Claude Code Subagents Sharing a Worktree? Serialize Writes

If two Claude Code subagents appear to switch into the same worktree, stop parallel writes before trying to repair Git state. A fresh upstream report describes concurrent worktree-isolated subagents changing one another's working directory and isolation identity. Older reports describe adjacent failures where a subagent's Git commands or file writes landed in the parent checkout.

These reports do not prove that every parallel Claude Code session is unsafe. They do justify a narrow containment rule: if a live agent's repository root changes, two agents claim the same worktree, or the isolation guard names another active agent's path, serialize all writers until you can verify every checkout.

Do not start with git reset, git checkout, git stash -u, or worktree deletion. Those commands can erase or entangle the exact uncommitted changes you are trying to recover.

Match the Failure

The current reports cover related but distinct symptoms:

The newest report is specifically about concurrent subagents in Claude Code 2.1.223. It says the failure occurred four times across two dispatch rounds and also affected a read-only subagent's guard identity. That is evidence for a bounded safety response, not proof of a universal runtime defect or a particular root cause.

Contain the Session Before You Touch Git

First, stop dispatching new subagents. Ask every running agent to stop before its next file write, Git command, formatter, or test that can update snapshots. If your client supports interrupting a task safely, interrupt agents that cannot acknowledge the pause.

Then choose one active writer. Let every other agent remain read-only or idle until that writer has finished and a human has reviewed its tree. Serialization removes the concurrency condition described in the fresh report. Repeating pwd in several still-concurrent writers does not.

While containment is active:

• do not follow a guard message into another agent's worktree;

• do not let any agent run a relative-path edit;

• do not switch branches in the parent checkout;

• do not stash untracked files;

• do not remove a worktree because it looks abandoned;

• do not commit a combined diff until ownership is clear.

If the parent checkout already contains unexpected changes, preserve it in place. Recovery comes after inventory.

Build a Read-Only Worktree Inventory

From the parent checkout, list Git's registered worktrees:

git worktree list --porcelain
git status --short --branch

Copy each exact worktree path from the first command. For every path, run these read-only checks manually:

git -C /absolute/path/to/worktree rev-parse --show-toplevel
git -C /absolute/path/to/worktree status --short --branch
git -C /absolute/path/to/worktree diff --stat
git -C /absolute/path/to/worktree diff --cached --stat

Record four facts for each live agent:

Do not infer ownership from a branch name alone. Read the diff and compare it with the task each agent was assigned. A correct-looking temporary branch can still coexist with edits in the wrong checkout.

Add a Fail-Fast Root Check

For the one serialized writer, make the expected worktree path explicit. Run this gate immediately before each write group and before every Git operation:

expected_root=/absolute/path/to/the/assigned/worktree
actual_root="$(git rev-parse --show-toplevel)"

if [ "$actual_root" != "$expected_root" ]; then
  printf 'unsafe repository root: expected %s, got %s\n' "$expected_root" "$actual_root" >&2
  exit 70
fi

git status --short --branch

Use an absolute path that you already verified. Do not derive expected_root from the current directory after the failure starts.

This check is a tripwire, not a fix. The fresh report says identity changed during concurrent work, so a check at session start cannot guarantee the root stays correct. Keep writers serialized and re-run the gate at each boundary.

For file edits, also require every target path to begin with the verified worktree root. If Claude Code's isolation guard rejects that verified path while naming another live agent's path, stop the writer. Do not work around the guard and do not move the write to the other tree.

Recover Changes One Tree at a Time

After all competing agents have stopped, recover one checkout at a time:

1. Review unstaged and staged diffs in the parent checkout.

2. Review each registered worktree with explicit git -C commands.

3. Match every changed file to the agent task that was supposed to own it.

4. Preserve unexpected files before any branch switch or worktree cleanup.

5. Run the relevant tests from the verified root.

6. Let a human review the final diff before committing.

If one task's changes landed in two trees, do not solve that by committing both. Choose the intended tree, compare the file contents, and move only the reviewed changes through your normal patch or review workflow.

If ownership is ambiguous, stop. A delayed commit is cheaper than silently combining two agents' work.

Test Parallelism in a Disposable Repository

Do not reproduce this failure in a repository with valuable uncommitted work. Use a disposable repository with two tiny, disjoint files and no credentials.

For each subagent, record its assigned root and require it to run the root check before editing. Dispatch no more than two agents. While they run, poll the parent and child checkouts with git worktree list --porcelain and git status --short --branch.

The test passes only if:

• every agent keeps a unique root for the whole run;

• each file changes only in its assigned worktree;

• the parent branch and working tree remain unchanged;

• no guard message names another live agent's path;

• the resulting commits contain only the assigned file.

One clean run does not prove the bug is gone. Repeat after a Claude Code update only when release notes or issue activity indicate that worktree isolation changed.

Keep the Safety Boundary Narrow

Claude Code's official worktree documentation describes separate worktrees as the isolation boundary for parallel sessions and subagents. The upstream reports describe cases where observed behavior did not match that contract. Until the affected version and fix status are clear, use the smallest operational change that removes the reported risk: one writer at a time.

Do not disable Git protections, grant broader file access, or tell agents to ignore isolation errors. Those changes weaken the boundary without repairing session identity.

For a related but different guard failure, see Claude Code worktree says the command is too complex. For a broader view of when agent skills, MCP, and CLI boundaries differ, read Agent Skills vs MCP vs CLI.

Monitor the Upstream Reports With Aident Loadout

Use a read-only upstream check before re-enabling concurrent writers. Give Claude Code or Codex the canonical setup instruction:

Follow https://aident.ai/SETUP.md

Then use this prompt:

Check my Aident Loadout account authentication and Vault status. Search the staging capability catalog for a connected read-only GitHub issue-search Action, inspect its current schema, and preflight it. If the estimate is free, return the state, updated time, comment count, reaction count, title, and URL for anthropics/claude-code issues 84685, 52958, and 55708. Do not comment, edit, close, label, publish, install, change files, start OAuth, or run a Git write.

Success is measurable: authentication and Vault checks complete; discovery, schema inspection, and preflight succeed; the three issue records return; and no GitHub or repository write occurs. Set up Aident Loadout and monitor Claude Code worktree isolation.

Sources

• Claude Code issue 84685: concurrent subagents can share worktree identity

• Claude Code issue 52958: a worktree-isolated agent can drift into the parent checkout

• Claude Code issue 55708: subagent Git operations can affect the parent checkout

• Anthropic documentation: run parallel Claude Code sessions with worktrees

• Git documentation: git-worktree

Refresh this guide when issue 84685 changes state, Anthropic documents the isolation contract more precisely, or a Claude Code release passes the disposable two-agent canary without root drift.