Subagent Failures in Parallel Runs

A git worktree doesn't contain your gitignored verify script. All three parallel lanes hit that. Guards we put in prompts, and how we check results.

PR: This article contains a placement for an affiliate program we plan to join (a learning service). Our verdicts do not depend on payouts.

Running subagents in parallel brings failures you never see with one agent. We reproduced the worktree trap locally, then list the guards we put in prompts and how we check what comes back. Environment: Linux, git 2.47.3, Claude Code 2.1.301, on 2026-10-16.

Parallel limits by tool are compared in Claude Code vs Cursor vs Codex in Practice.

The worktree has no verify script

A subagent with isolation: worktree runs in a temporary git worktree, branched by default from your default branch rather than the parent session’s HEAD (https://code.claude.com/docs/en/sub-agents, checked 2026-10-16). Our verify.sh lived in a gitignored .claude/, and a worktree only has committed files:

$ git worktree add -q ../wt -b lane1
$ ls -a ../wt
.  ..  .git  .gitignore
$ ls ../wt/.claude
ls: cannot access '../wt/.claude': No such file or directory

All three parallel lanes hit this. Calling the main checkout’s script from a worktree can end up verifying the main checkout. We now copy the script into each lane or pass the target path explicitly.

Handover notes split per worktree

The main checkout’s handover note said “phase 0, not started” while the worktree was 39 commits ahead. Start every session with git worktree list. Once, a squash merge replaced a 396-line task file with the worktree’s stale 266-line copy. Meta files are now edited on the main checkout only.

Designing the notes themselves: agent memory design.

Guards in every prompt

• No git commit --amend.
• Name both the main and worktree paths and say “don’t touch main.” (Without it, main did get dirtied.)
• Write findings to a file, not just the report.

For race-sensitive refactors, add a frozen zone (functions listed as file:line), the one allowed mechanical replacement, and “if unsure, stop with BLOCKED.” Since then, no subagent has stepped outside its scope.

Added tests don’t count until breaking the code makes them fail: green tests.

Build in parallel, test in series

One night, seven agents worked on seven PRs for about ten hours. Builds ran in parallel; tests went one at a time behind a mkdir lock, which fails if the directory exists:

until mkdir .test.lock 2>/dev/null; do sleep 0.2; done
run-tests; rmdir .test.lock

Three lanes started together ran strictly one after another in our test (each start followed the previous end within 0.01 s). Expected test count = main’s executed tests + the sum each lane added.

Check results mechanically

• Diff the set of test function names before and after.
• Read the diffstat from git merge --ff-only; an unexpected Bin 0 -> N bytes shows up there first.
• When a subagent says “can’t do it as specified,” verify yourself. Don’t let it implement an alternative.

Then verify against git, not the self-report.

For splitting a large deletion refactor into ordered steps, see Deleting Thousands of Lines in a Refactor.

Estimates run optimistic

Our plan estimates were 20–25% optimistic every time. Pad parallel schedules up front.

Summary

• Worktrees lack gitignored files; give each lane its verify script.
• Edit meta files on main only; run git worktree list at session start.
• Add-only tests, no amend, explicit paths, BLOCKED when unsure.
• Verify returns with test-name sets and the diffstat.