Support `cwd` for `spawn_agent`

Open 💬 4 comments Opened Apr 22, 2026 by gndk

What variant of Codex are you using?

CLI

What feature would you like to see?

Add an optional cwd parameter to spawn_agent, including the MultiAgentV2 tool surface.

Parallel subagent workflows often need one worker per isolated checkout or worktree. Today a spawned
subagent inherits the parent session cwd, so callers must rely on prompt instructions such as “work in
this directory.” That is not a reliable boundary for tool execution, hooks, sandboxing, or git-root
checks.

A per-spawn cwd would let the orchestrator start each subagent in the checkout it owns.

Proposed API:

{
  "task_name": "worker_a",
  "message": "Implement the assigned slice.",
  "cwd": "/absolute/path/to/worktree"
}

Suggested semantics:

absolute paths are used as-is
relative paths resolve from the parent agent cwd
the child session starts with the requested cwd
reject a requested cwd that would grant access outside the parent’s sandbox
recompute the child file-system sandbox policy relative to the requested cwd when applicable

Additional information

Spawned agents are already created from a child Config, and session/tool execution already has a
cwd. This request is to expose a per-spawn cwd override on spawn_agent and validate/apply it before
the child session starts.

View original on GitHub ↗

4 Comments

PratikRai0101 · 4 months ago

Hey, I would like to work on this, I will open a draft PR for this.

Pimpmuckl · 3 months ago

That would be really useful for multi agent orchestration to not step on each other's toes!

wcy1231 · 3 months ago

Why this matters

cwd is often the subagent's ownership boundary, not just a shell convenience.

In multi-agent workflows, a parent/orchestrator agent may delegate work to workers that each own a different package, checkout, or worktree. Those locations can have different:

AGENTS.md instructions
skill discovery
repo-local config
hooks
git roots
sandbox assumptions

If the spawned agent only inherits the parent cwd, then prompt instructions like _"work in this directory"_ are not a reliable substitute for actually starting the child session there.

Worker/reviewer use case

This becomes especially important when subagents are used as real workers or reviewers, rather than short one-off helpers.

The orchestrator should be able to keep high-level context while starting each worker in the environment that defines its actual task boundary.

Suggested behavior

I agree with the proposed semantics:

add an optional per-spawn cwd
resolve relative paths from the parent cwd
validate the requested cwd against the parent sandbox
apply the cwd before the child session starts

This would make multi-agent workflows much more robust and would align instruction discovery, skill discovery, hooks, shell tools, and git behavior with the subagent's intended scope.

SanjoSolutions · 2 months ago

Implemented in https://github.com/SanjoSolutions/codex/tree/feature/worktree-backed-subagent-spawns

Usage prompt:

Do:

* Task A
* Task B
* Task C

in parallel using subagents. Spawn one subagent per task with `git_worktree`, each on a unique `agent/...` branch and sibling worktree. After they finish, review and merge their branches back into this workspace, resolving conflicts and running tests.

Or with this skill:

$do * Task A
* Task B
* Task C