Dispatch contract for spawning parallel agents covering worktree collisions, scope overflow, and silent exits. Use when fanning out concurrent agents or authoring a lead prompt.
Dispatch contract for spawning parallel agents covering worktree collisions, scope overflow, and silent exits. Use when fanning out concurrent agents or authoring a lead prompt.
user-invocable
false
allowed-tools
Read, Glob, Grep, TodoWrite
model
opus
created
"2026-04-21T00:00:00.000Z"
modified
"2026-08-07T00:00:00.000Z"
compatibility
claude-code
reviewed
"2026-07-05T00:00:00.000Z"
Parallel Agent Dispatch
Conventions that apply every time more than one agent runs in parallel. Prevents
the top failure modes observed across real multi-agent sessions: dirty-worktree
cross-contamination, context overflow mid-task, and silent exits that require
manual salvage from orphan branches.
Supporting material is split across references/ by the path that needs it;
REFERENCE.md is the index. Sections below link the specific file.
Using the implicit team + teammate spawn for coordinated parallel work
A simple background task with no parallel siblings
Running worktree-isolated parallel implementation across repos/features
A read-only inline subagent that does not write to disk
Coordinating parallel investigation or audit swarms
The work fits in the current session without forking
Dispatch from the Main Thread When Possible
Agent and other parallel-spawn tools may be absent from a sub-agent's sandbox
even when available in the main conversation, so designing a fan-out from inside
a coordinating sub-agent risks silent degradation to sequential execution.
Default: dispatch from the main conversation — the full tool surface is
guaranteed.
Sub-agent orchestrator: only when the team's outputs need not feed back
into the main thread. Brief it to verify tool availability up front and report
sequential fallback as a first-class outcome (agent-teams → "Sub-Agent
Caveat").
The Three Pillars
1. Worktree Preflight
Before spawning, the orchestrator must verify:
Check
Rationale
Main working tree is clean (git status --porcelain empty)
Prevents numbering collisions in parallel doc writes
If any check fails, refuse to dispatch and report the blocker. Do not
"clean up" uncommitted user work — surface it and ask.
Target-branch preflight (#1969).isolation: "worktree" auto-names the
branch; renaming onto a fixed conventional target name another session's
worktree already holds is refused only at the end-of-task rename, deep into
the run (real case: two sessions both reached PR-open → duplicate-PR
reconcile). Before dispatching — or as the agent's first step — check the
name is free (git branch -a --list "$target", git worktree list,
git ls-remote --heads origin "$target"); any hit ⇒ another session may own
this task — stop and reconcile, not race to a duplicate PR
(.claude/rules/concurrent-session-pr-check.md). Mitigation: push via
explicit refspec (git push origin HEAD:$target) instead of renaming. See
references/worktree-hazards.md → Target-branch preflight.
Transient worktree leaks (#1319). While a wave runs, a file a child wrote
inside its worktree can briefly appear in the parent as an untracked entry
at the same relative path, then vanish when the child commits. Do not stash,
restore, or commit untracked parent files during a wave; wait for the child's
completion, then let its branch reclaim the file. /git:coworker-check raises
worktree_leak_suspected for this — run it before every parent-side commit.
cwd-reset leaking git writes (#1480). Distinct from the transient leak: an
agent thread's bash cwd resets between calls and can land on the main repo root,
so a git-write agent's bare commands mutate main instead of its worktree.
Brief every git-write agent: pin the root once
(git rev-parse --show-toplevel → $WORKTREE) and prefix every call with
git -C "$WORKTREE" …; forbid bare git checkout -B / git rebase --autostash
until inside the worktree. After the agent returns, run the post-run main-repo
integrity check (see references/worktree-hazards.md → cwd-reset
guardrail) —
a changed branch or new dirty state is silent main-repo mutation.
GIT_DIR/GIT_WORK_TREE export leak (#1692 sibling). A worktree reporting
core.bare = true (fatal: this operation must be run in a work tree) is
shared-checkout corruption — STOP and report it; never "work around" it by
exporting GIT_DIR/GIT_WORK_TREE, which override git -C so every later
git call (and any git-shelling test/hook subprocess) targets the shared common
config, breaking all sibling worktrees at once. A subprocess that must run
git in a sandbox neutralizes inherited env first:
env -u GIT_DIR -u GIT_WORK_TREE git -C "$dir" …. See
references/worktree-hazards.md → GIT_DIR-export leak.
Nested-repo workspaces — isolation: "worktree" isolates the outer repo (#1838).
The harness worktrees the session's repo, not the repo the agent was told to
edit. In a nested-repo / portfolio layout the target files live in an independent
nested repo that is absent from that worktree, so the agent's only path to
them is the shared checkout — which the Edit-tool isolation guard correctly
blocks. Detect it before dispatch: git -C <target-dir> rev-parse --show-toplevel
≠ git rev-parse --show-toplevel. When they differ, either create the nested
repo's worktree explicitly off its own origin/main and point the agent there, or
brief the agent to do so as its first step. See
references/worktree-hazards.md → Nested-repo isolation
for detection script and rules.
2. Scope Budget (per-agent prompt rules)
Every agent prompt must declare:
File scope: exclusive write paths (glob or explicit list). Out-of-scope
discovery → stop and report (see agent-teams).
Read budget: soft cap on files examined (default "≤10 files per hop, ≤3
hops before returning").
Output budget: expected length of the return summary — discourages echoing
full file contents when a diff or line reference will do.
These budgets prevent the "agent hit context limits" and "prompt too long"
failure modes — without them an agent exhausts its window on exploration and
truncates its deliverable.
Orchestrator-only files. Even with disjoint write scopes, shared files must
be excluded from every agent's write-path under an ### Orchestrator-only files
heading in the brief: the blueprint manifest (ID registry), the feature tracker,
top-level plan/roadmap docs, build manifests, justfile/Makefile, and local
task-queue stores. Last-writer-wins silently destroys earlier work on these. See
references/brief-templates.md for the full
template and evidence.
Pre-allocated IDs. The shared-counter snapshot must expand into explicit
per-agent ID assignment in each brief ("Use WO-012; others claim WO-013/014").
"Pick the next free ID" is a race under parallelism. Applies to any shared
monotonic identifier (ADR, migration, PRP).
Wave splits for exclusive locks. An agent needing an exclusive lock (Ghidra
project lock, shared git index, migration lock, taskwarrior bulk ops,
single-writer caches) cannot share a wave with another lock-contender. Dispatch
it alone, or pre-compute its artefacts so downstream agents are read-only. See
exclusive-lock-dispatch.
Every parallel agent must end its run with a structured ## Result summary as
its final message, regardless of success or failure (status / branch / pr /
commits / worktree, plus Scope delivered, Deferred, Issues encountered, and
Orchestrator action needed). Include the schema verbatim in every dispatched
agent's prompt under a heading like ### Return contract (mandatory) — agents
follow concrete schemas more reliably than prose. Copy the full schema from
references/dispatch-contract.md → Return Contract schema;
for the failure-mode → schema-field rationale, see
references/dispatch-contract.md → Failure modes.
Orchestrator edits needed must be verbatim patches, not prose (literal CMake
blocks, full justfile recipes, literal doc paragraphs), and the agent writes the
final prose for any docs update its slice requires. See
references/brief-templates.md → Verbatim patches.
Loud-failure contract (never surrender silently)
A dispatched agent that hits a wall must say so loudly. The dominant failure
shape (issue #1422)
is an agent that runs 50–200 tool calls, thrashes against hooks, then emits a
one-word final message — Terminal., Done., Stopped. — with no PR URL and
no blocked list. That is indistinguishable from success to the orchestrator,
so the harness reads "no changes", cleans up the worktree, and the work is lost.
Tie the escalation to the Return Contract's status field:
Outcome
The agent must return
Success
PR URL plus one summary metric (test/line delta) — status: success
Partial blocker
Push the WIP, open a draft PR, return its URL plus an explicit "what's blocked" list — status: partial
Total blocker
Explain exactly what blocked it, which tools were denied, what it tried — status: failed. Never a bare Terminal. / Done. / Stopped.
The one-sentence contract to paste into every brief: "Your final message is
the only thing I can act on — a one-word summary loses all your work. On any
blocker, push what you have, open a draft PR, and tell me exactly what stopped
you." Optional enforcement: a SubagentStop hook that flags sub-~20-char or
bare-surrender final messages (see hooks-plugin).
The same contract, expressed as workflow primitives
A harness does not replace this contract; it turns what prose can only request
into what a runtime enforces:
Here (prose)
Workflow primitive
The ## Result schema pasted into each brief
a JSON Schema on the agent() call — validated, so a one-word surrender cannot parse
"every returned summary parsed" (Orchestrator Checklist)
parallel() — the barrier that line already assumes
When fanning out agents to bulk-edit content covered by a regression script, the
brief must include the script as the agent's own final verification step.
Exit 0 means ship; non-zero means fix-and-re-run inside the same agent's budget —
shifting validation from commit-time to edit-time.
Treating the script as advisory defeats the purpose — the regression lands in
the agent's diff and the agent already has the context to fix it. See
references/brief-templates.md → Bulk-edit self-verification
and .claude/rules/regression-testing.md.
Closed-list mechanical batches need a completion manifest, not just a
self-report. A refactor agent assigned a fixed list (symbols to delete, files
to touch) must emit a machine-checkable manifest of what it completed — and
never trust that manifest alone: re-run the authoritative checker (knip /
build / test) afterward and diff against the assignment. A truncated or
optimistic summary reads as success even when the batch fell short (issue
#1601: a ~23-symbol
batch completed only ~5, invisible until knip was re-run). Cap the per-agent
batch so an early stop costs little. See
references/brief-templates.md → Refactor-brief template.
5. Reviewer-agent verification (verify-then-fix)
Self-attestation is unreliable. For high-stakes dispatches (PR "ready to merge",
security audits, shared-state mutations), spawn a separate reviewer agentafter the worker reports done and before trusting it. The reviewer runs in
its own worktree, ideally a different model, receives the claim and branch (not
the reasoning trace), and re-derives a verdict from the diff. On a flag, fix
inline or dispatch a follow-up worker — do not close on the worker's self-claim.
Agents push their own commits in the normal case — worktree isolation plus
per-agent branches makes this safe and keeps the lead context lean. The lead
pushes instead only for: web sandbox sessions (CLAUDE_CODE_REMOTE=true,
where teammates may hit TLS errors on push — see agent-teams), cross-agent
dependencies where Phase 1 commits must land as a single merge base for Phase
2, and explicit user instruction ("I'll push manually").
Handling a Missing Return
If an agent exits without emitting the Return Contract, treat it as a silent
stall, not a success. Before deciding, discriminate empty vs dirty
worktree:
Dirty / commits present → the agent did the work; salvage it
(commit/push the WIP, open the PR) rather than re-dispatching.
Empty / trivial diff → nothing to salvage; resume or re-dispatch.
Do not report the parent task complete until every spawned agent has produced
a Return Contract (or been explicitly accounted for). Two causes leave the work
intact: a pre-commit hook blocking git commit, or a rate-limit cut-off after
the implementation but before the StructuredOutput call (issue
#1491).
An implementer can finish its work (clean commit + tree) then go idle
emitting only an idle_notification — the work isn't lost, the communication
is (intermittent; siblings can deliver fine). Not a failure signal: run the
empty-vs-dirty check above, then SendMessage the named agent to resend the
Return Contract (read-only, so the #1546 caveat below does not apply). Never
respawn — a fresh agent lacks context and can't take the branch. Prevention:
implementers SendMessage the report to the lead as their final act. See
references/failure-recovery.md → Idle without report.
Killing a Thrashing Agent Preserves Its Worktree
TaskStop does not discard the agent's work — its worktree stays on disk
with every uncommitted change intact, making TaskStop a recovery
affordance. When an agent is thrashing (high Bash:Edit ratio with a rising
error rate on hook-blocked Bash calls), killing it early and salvaging beats
waiting for a silent give-up. Then decide from the worktree state:
Worktree state
Decision
Substantive diff vs origin/main
Salvage — finish in the parent session, commit, push, open the PR
Empty / trivial diff, or wrong design
Restart — git worktree remove <path> first, then re-dispatch
[1m] parents running six or more concurrent subagents can hit Server is temporarily limiting requests partway through a wave (distinct from your account
usage limit; varies by time of day). "It worked with N agents yesterday" is not
a guarantee. Start conservative, then scale up:
Agent profile
Safe starting concurrency
Heavy (installs / builds / long tool chains)
2–3
Light (read-only analysis, single-file edits)
up to 5
Prefer sequential waves of small batches over one big fan-out beyond ~4
heavy agents, and treat the rate-limit signal as backoff-and-retry, not task
failure — re-dispatch rejected agents with backoff and reduced concurrency.
When the burst killed agents at startup, the dead worktrees leave empty
branch refs behind: git worktree prune and delete them before the retry, or
each agent's git switch -c <branch> collides with the leftover ref.
See references/failure-recovery.md → Concurrent rate-limit recovery
and .claude/rules/skill-fork-context.md.
Skill-less agentType for Read-Only Fan-Out
For read-only / structured-output fan-out — classification, verification, audit
sweeps where each agent reads files and emits a result, nothing more —
dispatch a Skill-less agentType rather than general-purpose. A
general-purpose subagent carries the Skill tool, which injects a
skill_listing attachment (~88k chars / ~22k tokens) plus a
deferred_tools_delta (~3k tokens) before its first tool call; add file reads
and a forced StructuredOutput schema and that ~25k fixed tax pushes the
subagent over its window (Prompt is too long, 40–100% batch failures — issue
#1549). Agents
without the Skill tool receive no skill_listing injection at all.
Fan-out need
agentType
Why
Read-only classify / verify / audit
agents-plugin:review
Read/Glob/Grep, no Skill tool → no skill_listing tax; its review system prompt does not interfere given an explicit rubric + schema
Read plusWrite (e.g. emit a report file)
agents-plugin:docs
Same Skill-less lean tool set, with write capability
Genuinely needs the skill catalog or broad Bash (gh/task filing)
general-purpose
The ~25k tax is only worth paying when the catalog is actually used
Preserve agents-plugin:review's lean, no-Skill tool set when reaching for it
as a fan-out building block. See
references/dispatch-contract.md → Skill-less agentType;
sibling authoring guidance is in custom-agent-definitions.
Composition with agent-teams
agent-teams covers the implicit-team / SendMessage / TaskUpdate mechanics; this
skill adds the dispatch-time contract that applies to both team and non-team
fan-out. When both apply, follow both — the out-of-scope protocol from
agent-teams slots into the Issues encountered / Deferred sections here.
SendMessage-resume of a completed worktree-isolated agent does not
re-enter that agent's worktree — the resumed run executes in the
orchestrator's main checkout, so the resume loses worktree isolation;
resuming several file-mutating agents this way runs them concurrently in the
main checkout and tangles branch state (issue
#1546).
Continuation
Safe to SendMessage-resume?
Do instead
Read-only / single-checkout follow-up
Yes — no worktree to re-enter
Resume freely
Parallel file-mutating agent that must stay in its worktree
No — resume runs in the main checkout
Re-dispatch a fresh Agent with isolation: "worktree"
Resuming a workflow: resumeFromRunId re-runs succeeded worktree agents
Workflow({resumeFromRunId})'s "completed agent() calls return cached
results" holds for ordinary agents but not for isolation: "worktree"
ones: a worktree agent that already succeeded is re-executed on resume,
re-firing its outward side effects — an agent that opened a PR opens a
duplicate (PR #1858 dup of #1857; issue
#1868). Opposite
failure to the SendMessage case above (there the resume loses its worktree;
here it re-runs the whole agent).
So to retry a few failed worktree agents, do not resume the whole run —
re-dispatch only the failed agents in a fresh sequential pass (which
also dodges the burst rate limit), checking for an already-open PR first
(gh pr list --state all --search …, reading state/mergedAt per
.claude/rules/gh-json-fields.md). Non-worktree stages cache correctly. See
.claude/rules/agent-coworker-detection.md.
Quick Reference
Orchestrator Checklist
Working tree clean; no conflicting worktrees
Each agent has unique branch name and exclusive file scope
Each prompt includes file/read/output budgets
Each prompt includes the Return Contract schema verbatim
Each prompt mandates the loud-failure contract (no one-word surrenders)
Agents authorized to push their own commits (unless sandbox/dependency exception)
Every returned summary parsed; missing returns treated as stalls
Common Mistakes
Mistake
Correct Approach
Spawning agents from a dirty main tree
Commit or stash first; refuse to dispatch on dirty state
Scope described in prose, not glob
Explicit write-path list per agent
"Report back when done" with no schema
Include Return Contract verbatim in every prompt
Treating agent silence as success
No Return Contract = stall; investigate before reporting done
Respawning after an idle_notification with no report
Check the branch, then SendMessage the agent to resend the report (#2039)
Accepting a one-word final message (Terminal./Done.)
Mandate the loud-failure contract: push work, open a draft PR, explain
Centralizing pushes as a default
Agent pushes its own work; lead pushes only on sandbox/dependency exceptions
Related
REFERENCE.md — index over references/: dispatch contract, brief templates, failure recovery, worktree hazards
