Dispatching parallel agents

Iron Law

YOU MUST RESTRICT PARALLEL AGENTS TO READ-ONLY WORK ONLY.
YOU MUST PROVIDE EACH DISPATCHED AGENT WITH ITS OWN ISOLATED WORKTREE -- ONE WORKTREE PER AGENT.
No exceptions.

Violating the letter of this rule is violating the spirit of this rule.

Announce at start: "I am using the dispatching-parallel-agents skill to [describe what is being parallelized]."

---

The Team Lead Model

When dispatching parallel agents, the main agent acts as a team lead:

Role	Actor	Responsibilities
Manager	User / human	Receives validated, aggregated results. Never receives raw agent output directly.
Team lead	Main agent (you)	Orchestrates agents, tracks work status, validates and cross-checks all results, presents conclusions to the user
Team members	Subagents	Execute specific, isolated tasks. Return structured results to the team lead only.

What the team lead does between dispatch and presentation:

1. Collect all agent results before acting on any
2. Cross-check conflicts against source files directly
3. Aggregate findings into a coherent summary
4. Remove noise -- do not forward raw agent output upstream
5. Present conclusions to the user: "Agents found X. I verified Y at [file:line]. Conclusion: Z."

What the team lead never does:

• Forward a finding to the user without verifying it first
• Let two agents report contradictory findings without resolving the conflict
• Report "agents completed" without summarizing what was learned

See references/AGENT_CACHING.md for the agent response caching protocol (postmortem evidence format and scratch/ conventions).

---

Agent Type Selection

Before dispatching any agent, select the correct type. The wrong type wastes context and produces lower-quality output.

Task type	Correct agent	Wrong choice
Read-only research across 3+ files -- patterns, symbols, hypotheses	explore	general-purpose
Skill review (skill .md files)	skill-reviewer	general-purpose
Code review (code/config files)	code-quality-reviewer	general-purpose
Multi-step implementation with file modifications	general-purpose + worktree	explore
Build, test, or lint execution -- success/failure result only	task	general-purpose
Any read-only + write combination	Separate explore and general-purpose agents	One general-purpose for everything

Routing rule: Use the most constrained agent type that can complete the job. general-purpose can do everything -- which means it accumulates context, produces serial output, and contaminates findings with session assumptions for work that a constrained agent would complete faster and cleaner.

---

When to Parallelize

Dispatch agents in parallel when ALL of the following are true:

1. Tasks are independent -- no agent needs the output of another to start
2. Every agent has its own isolated worktree -- read-only and write agents alike
3. Each task has a single clear objective -- multi-part briefs produce noise

Good candidates for parallelization:

• Scanning multiple files for a pattern
• Confirming/denying multiple independent hypotheses simultaneously
• Researching 3+ unrelated topics at once
• Running multiple spec-compliance or code-quality reviews simultaneously

Do NOT parallelize:

• Tasks where Agent B needs Agent A's output
• Multiple write agents on the same files (race condition)
• Tasks requiring shared state or coordinated decisions

BEFORE DISPATCHING PARALLEL AGENTS, verify:

1. All tasks are truly independent -- no agent needs another agent's output to start
2. Return format is explicitly defined for every agent before dispatch
3. No more than 20 agents in flight unless CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS is raised (past the limit, dispatch fails with Concurrent subagent limit reached; it succeeds again once the running count drops below the limit)
4. Every agent has its own isolated worktree.
5. If dispatching a batch of agents to test a hypothesis (A/B test, multi-agent experiment): dispatch a design-review Skeptic FIRST before running the test agents. An unreviewed experiment design cannot guarantee it measures what it intends to measure.

[+] All met -> dispatch agents [-] Any unmet -> resolve the dependency, define the return format, or serialize the dispatch before proceeding

---

BEFORE PROCEEDING

1. All tasks are truly independent -- no agent needs another agent's output to start
2. Return format is explicitly defined for every agent before dispatch
3. No more than 20 agents in flight unless CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS is raised (past the limit, dispatch fails with Concurrent subagent limit reached; it succeeds again once the running count drops below the limit)
4. Every agent has its own isolated worktree.
5. If dispatching a batch of agents to test a hypothesis (A/B test, multi-agent experiment): dispatch a design-review Skeptic FIRST before running the test agents. An unreviewed experiment design cannot guarantee it measures what it intends to measure.

[+] All met -> dispatch agents [-] Any unmet -> resolve the dependency, define the return format, or serialize the dispatch before proceeding

---

Concurrency Rules

The Agent tool enforces two separate limits. The concurrent-subagent limit defaults to 20 agents running at once, configurable via the CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS environment variable (v2.1.217+); ultracode sessions are exempt. Dispatching past this limit fails immediately with the error Concurrent subagent limit reached, and the error tells Claude not to retry. The limit frees up as the running count drops below it. Separately, a session has a total cap of 200 subagents across its lifetime, configurable via CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION (v2.1.212+, any positive whole number, no upper bound, cannot be disabled). This cap is cumulative -- a finished subagent still counts against it -- and exceeding it fails with the error Subagent spawn limit reached. Within a single message, tool-use concurrency defaults to 10 parallel tool calls. None of these limits depend on account tier or model. (Workflow-tool agent() calls have a separate concurrency cap bound by available processor cores -- up to 16, fewer on machines with limited cores -- do not conflate it with the subagent limits above.)

Match the error text to the limit: Concurrent subagent limit reached means reduce the number of agents in flight or raise CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS; Subagent spawn limit reached means the session hit its 200-agent lifetime total. Run /clear to reset the total and start a new conversation with the full budget -- if work that can still spawn subagents survives the clear, such as a running workflow, the count carries over instead. A settings-file env block takes effect in the running session; a shell export only applies to sessions launched after it. Sending a follow-up message to an already-completed agent resumes it without spending a new spawn from the total. Workflow agent() calls do not count toward the session total -- workflows have their own per-run limit.

State your concurrency basis before dispatching: "Dispatching N agents in parallel -- [default 20-agent subagent limit / CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS raised to N]."

---

Isolation Rules

Each parallel agent MUST receive:

1. Isolated context -- never share your session history. Provide only what that agent needs.
2. A single objective -- one question, one file set, one hypothesis.
3. An explicit return format -- tell it exactly what to give back.
4. No knowledge of other agents -- agents do not know about each other.

Why isolation matters: Agents that share context inherit your biases and assumptions. Isolated agents search without your anchoring.

---

Aggregating Results

When parallel agents return:

1. Read all results before acting on any
2. Treat every finding as a hypothesis -- not a fact
3. Cross-check conflicting findings against the source files yourself
4. State what each agent found and what you verified:

   Agent 1 found: [X] -- verified by reading [file:line]
   Agent 2 found: [Y] -- conflicts with Agent 1 -- investigating
   

5. Do NOT propagate a finding to the user until you have verified it

---

Citation Verification

When any agent cites specific file names, page names, or resource paths as evidence, apply this gate before accepting any cited finding into synthesis:

1. For each cited resource not directly confirmed by a read or listing tool in the agent's own work: verify the resource yourself by reading or listing it directly.
2. Verification = the resource exists AND its content supports the claim.
3. If verification fails: REJECT the finding. Record: REJECTED: [resource] does not exist -- citation unverified. Do NOT re-dispatch the original agent for the same citation.
4. If verification passes: accept the finding. Note: VERIFIED: read [path] -- content confirms [claim].

Why: Agents -- especially when working with large archives or documentation sets -- frequently cite plausible-but-nonexistent resources. Treating citations as hypotheses and verifying them before synthesis prevents hallucinated evidence from reaching conclusions.

---

Worktree Requirement -- Every Dispatched Agent

When dispatching parallel agents -- read-only and write agents alike (e.g., multiple reviewers or implementers working on independent subsystems):

1. Create one worktree per agent BEFORE dispatching
2. Verify each worktree is gitignored: git check-ignore -q .worktrees || echo "NOT IGNORED"
3. Pass worktree path as the agent's working directory
4. After agents complete: review each write agent's diff independently before merging; for read-only agents, verify reported findings against source files before accepting them

See references/WRITE_AGENTS_SETUP.md for git commands and using-git-worktrees skill for full lifecycle.

---

Red Flags -- STOP

Pattern	Action
Two or more agents assigned to the same file or overlapping file sets	STOP. Reassign to non-overlapping sets or serialize the dispatch.
Dispatching agents without a defined return format	STOP. Define the exact return format for every agent before dispatching.
Acting on one agent's result before all agents have returned	STOP. Collect ALL results first, then aggregate and verify.
More than 20 concurrent agents dispatched without raising CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS	STOP. Confirm the environment variable is raised or reduce the batch size. Read the error text to identify which limit fired -- Concurrent subagent limit reached or Subagent spawn limit reached.
Forwarding agent output to the user without verifying it against source files	STOP. Cross-check every finding against source files before presenting conclusions.
Dispatching batch hypothesis-testing agents (A/B test, multi-agent experiment) without a prior Skeptic design review	STOP. Dispatch the design-review Skeptic first. Unreviewed experiment designs produce uninterpretable results.

---

Rationalization Prevention

Excuse	Reality
"These tasks are mostly independent"	Mostly = risk. Confirm independence before dispatching.
"I'll just have them both edit the file"	Race condition. One agent's changes will be overwritten. Use worktrees.
"I'll share my session context -- it's helpful"	It contaminates their search. They'll confirm your assumptions instead of testing them.
"One agent can do all this"	Sequential agents fill your context. Parallel agents preserve it.
"I don't need to verify -- the agent found it"	Findings are hypotheses. You verify before you propagate.
"I'll use general-purpose -- it can do everything"	general-purpose for read-only research wastes context and produces serial output. Use explore for research across many files.
"I'll run them sequentially -- parallel is harder to coordinate"	YOU MUST run independent tasks in parallel. Sequential dispatch wastes turns.
"The agents can share the same branch -- I'll merge their changes manually"	YOU MUST use an isolated worktree for every dispatched agent, read-only or write. Shared branches produce conflicts.
"I announced the tool calls in one turn, so they run in parallel"	Model Context Protocol (MCP) tool calls in a single assistant turn execute sequentially -- 17-second gaps per call are not parallel. Parallel execution requires separate Agent dispatch in a single message. Do not announce "in parallel" for same-turn tool call sequences.

---

Related Skills

• subagent-driven-development -- orchestration framework; parallel dispatch is a specialized case of subagent dispatch
• using-git-worktrees -- required for every dispatched agent, read-only and write alike; isolation guarantee
• execution -- work loop and commit rhythm that parallel dispatch operates within