Orchestrator V2: let delegate_task run a child in its own worktree

[dubonzi]

Problem

In Orchestrator V2 (#2829), delegate_task children always run in the parent thread's checkout.. There is no workspace parameter. Parallel implementation work needs one worktree per child, so an orchestrator creates them with git worktree add and tells each child to work there. The child's shell commands then run in the right worktree, but the child's thread is still bound to the parent's checkout.

We hit this orchestrating tickets with three Codex children (gpt-5.6-luna), each told to work in its own worktree:

• Each child's Codex session metadata has cwd and runtime_workspace_roots set to the parent's worktree, not the ticket worktree.
• The child passed the ticket worktree as workdir to its shell commands, so git status, tests and commits ran there.
• Its first apply_patch calls used relative paths. Those resolve against the thread binding, so the edits landed in the parent's checkout. The child's own worktree stayed clean, and its later shell commands didn't see the change.
• The parent found the stray diff only when a merge refused to overwrite uncommitted files. It saved the diff, restored its checkout, and checked whether the child was still writing there.

From then on, every delegated prompt had to say "use absolute paths for every edit", and the parent checked that its own checkout stayed clean after each child finished. That works until one prompt leaves the rule out.

t3_thread_launch with workspaceStrategy binds a thread to its own worktree correctly. But it makes a top-level thread that never wakes the launcher, so the orchestrator loses taskId, task_status and the completion notification. #15148 asks for that wake on t3_thread_launch. This proposal comes at the same tradeoff from the delegation side.

Proposal

An optional workspace field on delegate_task that takes the same shapes as t3_thread_launch's workspaceStrategy:

delegate_task({
  task: "Implement ticket 03 …",
  target: { providerInstanceId: "codex", model: "gpt-5.6-luna" },
  mode: "async",
  workspace: {
    type: "worktree",              // or "existing_worktree" | "root" | "inherit" (default)
    baseRef: "t3code/round-1",
    branch: "t3code/ticket-03",
    startFromOrigin: false,
  },
})

• The child's thread binding, provider cwd, and workspace or sandbox roots all point at that worktree. Relative edit paths resolve there.
• Everything else stays as it is: the child is owned by the parent, it wakes the parent on completion, and task_status/task_cancel work through its taskId.
• task_status returns the worktree path and branch, so the parent can review and merge.
• The default inherit keeps today's behavior.

Smallest useful version

existing_worktree only. The orchestrator already creates the worktrees itself, so T3 only needs to bind the child to a given path and branch. Creating and cleaning up worktrees can come later.

Related

• Opt-in completion wake for threads started with t3_thread_launch #15148: opt-in completion wake for t3_thread_launch, the same tradeoff from the launch side.
• Orchestrator V2: isolated / elastic compute for delegated workers #15516: isolated compute for delegated workers. A per-child worktree is the local, same-machine version of that isolation.

[juliusmarminge]

Note

Grok responding on behalf of Julius.

This landed in #19102: delegate_task now takes an optional isolation: "worktree", which starts the child in its own worktree from the parent's local commit (shared checkout stays the default, and uncommitted edits are not copied). Closing as resolved. Running a child in a different project is still tracked in #17415.