claude-code - 💡(How to fix) Fix Worktree isolation: Edit-tool path validation + drift-detection in task-notification payload

1. Problem

When Claude Code spawns multiple agents in parallel via Task(isolation: "worktree"), each agent gets its own git worktree on disk. Each worktree has its own HEAD (under .git/worktrees/<name>/HEAD), but the refs database is shared with the common repo: refs/heads/<branch> is a single entry visible from every worktree, so a git checkout issued against any worktree's .git/worktrees/<name> moves only that worktree's HEAD — including the meta-root's worktree when an agent's CWD has drifted there. Two failure modes:

(1) Edit-tool path drift. An agent's Edit/Write call with an absolute file_path that happens to fall inside the meta-root checkout (e.g. an unqualified path that the agent inferred from session context) lands in the meta-root working tree, not the worktree. The agent's diff appears empty in the worktree; the meta-root accumulates uncommitted leakage from concurrent agents.

(2) Branch-checkout drift. An agent running git checkout <branch> from a CWD that has drifted to the meta-root (or via an explicit git -C <meta-root>) moves the meta-root's HEAD, displacing whatever other agents (or the operator) had checked out there. With N concurrent agents, HEAD can move N times during a single fan-out.

Concrete evidence from a single recent fan-out run in our orchestration framework:

• Incident 1 — Edit calls landed at meta-root; the agent caught its own divergence and re-applied in the worktree.
• Incident 2 — meta-root branch switched to a different feature branch mid-fan-out, displacing the operator's uncommitted in-progress work.
• Incident 3 — 6 test files leaked into the meta-root working tree from a sibling agent; recovered via git stash.

Prior workarounds we have shipped at the orchestration layer:

• Pre-dispatch prompt clause embedded in every parallel-worker spawn that instructs the agent to keep edits and git operations inside $PWD. Soft constraint; LLM-orchestrator subagents still violate on long procedures.
• Pre-dispatch file-touch overlap detection that refuses parallel dispatch when briefs declare overlapping file-touch sets. Catches cross-worker file collisions but not worker-vs-meta-root path drift.
• A post-fan-out capture/verify guard (shell script) that snapshots the meta-root HEAD
  • branch + working-tree hash before spawn and checks for drift after every agent completes. Post-hoc only; surfaces drift after agents complete, but cannot prevent mid-flight work loss.

2. Requested platform changes

Request A: Edit-tool path validation against worktree root

When the Agent SDK's Edit tool is invoked from inside an agent that was spawned with isolation: "worktree", the tool MUST reject any file_path whose canonicalized absolute form is not path-boundary-contained within the agent's worktree root — i.e. after realpath-resolution, the file_path must be the worktree root itself or a descendant of it on a path-component boundary. String-prefix matching is insufficient: a naive startswith check would incorrectly accept a sibling worktree at /tmp/wt-other/file.py when the root is /tmp/wt, contradicting the rejection of sibling worktrees in the behavior matrix below. Equivalent safe forms in stdlib include Path(file_path).resolve().is_relative_to(Path(worktree_root).resolve()) or an explicit parents-chain walk; the contract is path-component containment, not character-prefix containment. The rejection should be a structured error (e.g. WORKTREE_PATH_VIOLATION) carrying the offending path and the worktree root so the agent's diagnostic surface can recover or surface the violation.

Behavior matrix:

Notes:

• The same gate SHOULD apply to Write and NotebookEdit (parallel tools that mutate paths).
• The gate SHOULD NOT apply to Read, since cross-tree reads are intentional (the prompt clause already directs agents to use absolute Read paths instead of cd).
• Bash is outside scope of this request — see Request B for the drift-detection signal that closes the Bash surface programmatically.

Request B: Drift-detection field in Agent task-notification payload

When an Agent completes (the parent receives the task-notification message), the payload SHOULD include a boolean meta_root_state_drift field. The field is true iff any of:

• the meta-root's HEAD ref differs from its state at agent-spawn time;
• the meta-root's working-tree dirty state changed during the agent's lifetime;
• the meta-root's branch HEAD changed during the agent's lifetime.

This lets orchestrators detect drift programmatically without each orchestrator having to reimplement the same git rev-parse + working-tree hash dance in a shell script. Once the field exists, our (and every other orchestrate-style framework's) local capture/verify guard can be deprecated and replaced with a single payload read.

3. Why prompt-only fixes are insufficient

Our coding convention for LLM pipeline design captures the structural limit:

"DO NOT silently fall back to X" or "MUST invoke subprocess Y" in an agent spec is a soft constraint: an LLM-orchestrator subagent will still violate when the procedure has many steps.

The agents observed in the evidence above had the Scope Guard prompt clause in their spawn prompts and still drifted. The platform-side fix in Request A makes the violations structurally impossible, not socially discouraged.

4. Compatibility / migration

• Request A is backward-compatible for agents that do not use isolation: "worktree".
• Request A may break workflows that intentionally write outside the worktree; we believe the right behavior is to fail loud and force the workflow author to make the cross-tree write explicit (e.g. via a new escape-hatch flag), but the request is open to Anthropic on the exact escape mechanism.
• Request B is purely additive (new optional field); orchestrators that don't read it see no behavior change.

5. Out of scope (acknowledged)

• A cd / git checkout PreToolUse hook for Bash. We considered this as a local workaround and rejected it: it cannot reach the Edit/Write surface that dominates the evidence above, and the CWD-based agent-identity heuristic is bypassed precisely when drift has already happened. Bash surface drift remains observable through Request B's meta_root_state_drift signal.
• Per-tool sandboxing beyond path validation (e.g. capability tokens, syscall filters). Out of scope for this request; the path-validation approach is the minimal change that closes the documented evidence.