claude-code - 💡(How to fix) Fix Agent tool: `isolation: "worktree"` creates worktree in session repo, not target repo, breaking parallel cross-repo work

Bug summary

When the main thread spawns a subagent with isolation: "worktree" and the subagent is briefed to work in a different repo than the session's primary working directory, the harness creates the worktree under the session's repo (e.g. <session-repo>/.claude/worktrees/agent-*), not the target repo. The subagent — having no useful files there — then cds into the target repo's main checkout and edits files there directly, without isolation.

For parallel subagents all targeting different repos, this appears to work (they don't conflict). But for parallel subagents that share a target repo, they clobber each other on the same files in the unisolated main checkout.

Reproduction

In a Claude Code session whose primary cwd is repo A:

Agent({
  description: "Edit repo B file",
  isolation: "worktree",
  prompt: "Edit src/auth.ts in d:/path/to/repoB to fix bug X."
})

The harness creates <A>/.claude/worktrees/agent-<id> but the agent's brief tells it to work in B. Inside the subagent:

1. Subagent runs pwd → reports the assigned worktree under repo A
2. Subagent has no relevant files there, sees the brief references directfn-clm (or whatever repo B is)
3. Subagent cds to d:/path/to/repoB (repo B's main checkout)
4. Subagent edits files there
5. Repo B's git status now shows uncommitted changes in its main checkout, on whatever branch the user happened to leave it on

If two such subagents target the same repo concurrently, they both edit the same files in the same checkout simultaneously. No conflict detection from the harness because the harness thinks each agent is isolated in its assigned worktree under repo A.

Real-world bite

Confirmed in a DirectFN session on 2026-05-31. Session cwd was directfn-admin. Two parallel Developer subagents were spawned for CLM (SCRUM-893 fix for a 2FA bypass, and SCRUM-899 fix for ~100 TypeScript errors). Both used isolation: "worktree". Both ended up editing src/lib/auth.ts in the directfn-clm main checkout simultaneously. The conflict surfaced when the user tried to git pull origin main && git cherry-pick <SCRUM-893-sha> to ship the first fix to Prod — the pull aborted because of 40 uncommitted files from the second subagent. Recovery required git stash --include-untracked + cherry-pick + git stash pop with auto-merge.

Proposed fix

Add an optional target_directory parameter to the Agent tool. When set with isolation: "worktree", the harness creates the worktree under <target_directory>/.claude/worktrees/agent-<id> and sets the subagent's initial cwd to that worktree. Default behavior (parameter omitted) is unchanged.

Agent({
  description: "Edit repo B file",
  isolation: "worktree",
  target_directory: "d:/path/to/repoB",
  prompt: "..."
})

This lets the main thread coordinate parallel cross-repo work safely. Multiple subagents targeting the same repo get distinct worktrees under that repo, fully isolated from each other and from the repo's main checkout.

Workaround currently in use

In CLAUDE.md + the persistent developer.md agent definition, the affected user has added a "Cross-repo worktree pattern" section instructing every Developer subagent to skip isolation: "worktree" and instead git worktree add a sibling working tree manually in the target repo, then clean up with git worktree remove. This works but is brittle (depends on every brief and every Developer reading and following the instruction). A harness-level fix would make the workaround unnecessary.

Why not "just spawn agents from the target repo's session"

For a session designed to coordinate cross-repo rollouts (e.g., shipping the same pattern to 5 repos in parallel), the user wants to drive the orchestration from one session — not bounce between 5 separate sessions, one per repo. The harness already supports the "spawn N parallel teammates" model well; this issue is specifically that the worktree-isolation knob doesn't honor cross-repo targets.