Subagent Invocation & Context
Subagents get only what the coordinator writes into their prompt. Learn the Task/Agent tool, structured metadata passing, and why parallel spawning cuts latency.
The Task tool (renamed Agent in Claude Code v2.1.63) is the mechanism that lets a coordinator spawn subagents. There is a hard gate: the coordinator's allowedTools must include "Task" (or its current alias). Without it, the coordinator physically cannot spawn subagents no matter how carefully they are defined. Each subagent is described by an AgentDefinition with a description, a system prompt, and tool restrictions.
Isolated context windows
Subagents run in isolated context windows. They get only what the coordinator writes into their prompt - nothing else. A synthesis subagent cannot retroactively fetch the web-search or document-analysis results; it can only use what the coordinator explicitly includes. This shapes every design decision in multi-agent work.
Three rules for effective context passing
- 1Pass complete prior findings. Include all relevant output from previous agents in full - a downstream agent cannot retrieve what it was not given.
- 2Separate content from metadata using structured data. Keep the claim decoupled from its source URL, document name, page number, confidence, and originating agent.
- 3Write goal-oriented prompts. Tell subagents the objective and quality criteria, not a rigid step-by-step procedure. Goals let subagents adapt; procedures constrain them.
{
"findings": [
{
"claim": "Solar panel efficiency rose about 25% over the decade",
"source_url": "https://example.com/solar-report",
"document_name": "Annual Solar Industry Report 2024",
"page_number": 14,
"confidence": "high",
"retrieved_by": "web_search_agent"
}
]
}If a synthesis agent produces unsourced claims even though the research agents returned properly sourced results, the root cause is the coordinator stripping metadata before passing content along. The synthesis agent cannot cite sources it never received. Fix the coordinator's context passing, never the synthesis agent's prompt.
Flattening results into plain prose so the source URL, page number, and confidence are lost. The synthesis agent then cannot cite anything - and "fixing" its prompt won't recover data it never got.
prompt = "Solar efficiency rose ~25% last decade."Pass structured findings that keep each claim decoupled from its metadata, so attribution survives the handoff.
prompt = json.dumps({
"claim": "Solar efficiency rose ~25%",
"source_url": url, "page_number": 14,
"confidence": "high",
})Parallel spawning vs. sequential invocation
When a coordinator needs several subagents for independent tasks, it should emit multiple Task tool calls in a single response so they run in parallel. Invoking them one per turn adds unnecessary latency. On the exam, answer choices mentioning "single response" or "simultaneously" signal the correct parallel pattern.
# CORRECT: independent subagents spawned in one response (parallel).
coordinator.respond(tool_calls=[
Task(agent="web_search", prompt=f"Research solar. Context: {ctx}"),
Task(agent="web_search", prompt=f"Research wind. Context: {ctx}"),
Task(agent="doc_analysis", prompt=f"Analyze filings. Context: {ctx}"),
])
# WRONG: one subagent per turn adds latency for independent work.
# for topic in topics:
# coordinator.respond(tool_calls=[Task(...)]) # sequentialInvoking each independent subagent in its own turn, one after another. The tasks don't depend on each other, so the sequential round trips just stack up latency.
for t in topics:
coordinator.respond([Task(agent="web_search", ...)])Emit all the Task calls in a single response so independent subagents run in parallel. On the exam, "single response" / "simultaneously" signals this pattern.
coordinator.respond([
Task(agent="web_search", prompt=solar),
Task(agent="web_search", prompt=wind),
])These are opposites. fork_session creates an independent branch from a shared baseline for divergent exploration - changes in one fork do not affect others. --resume continues one specific named session along the same investigation line. Confusing the two is a recurring exam trap (see lesson 1.7).
| Trap | Reality |
|---|---|
| Subagents inherit the coordinator's history | No - context is strictly isolated; pass everything explicitly. |
| Blame the synthesis agent for missing citations | Root cause is the coordinator passing content without metadata. |
| Use sequential calls for independent tasks | Adds latency - emit parallel Task calls in one response. |
| fork_session equals --resume | Opposite purposes: fork diverges, resume continues. |
How the exam will try to trick you
The distractors below look right under time pressure — learn the tell.
- The trap
A subagent can reach back for the coordinator's history or another subagent's output when it needs it.
Correct answerEvery piece of information must be explicitly included in the subagent's prompt by the coordinator.
Why: Subagents run in isolated context windows - there is nothing to reach back to.
- The trap
The synthesis agent's prompt is to blame when its claims come out unsourced.
Correct answerThe coordinator passed content without structured metadata (source URLs, document names, page numbers).
Why: A synthesis agent can only cite sources it was given; fixing its prompt cannot recover data it never received.
- The trap
Invoke independent subagents sequentially, one per turn.
Correct answerSpawn them in parallel with multiple
Taskcalls in a single coordinator response.Why: Sequential round trips add latency with no benefit when the tasks do not depend on each other.
- The trap
Treat
fork_sessionand--resumeas interchangeable ways to keep going.Correct answerfork_sessionbranches for divergent exploration;--resumecontinues one named session.Why: They serve opposite purposes - forking diverges from a baseline while resuming continues the same line.
Key takeaways
- The Task/Agent tool must be in the coordinator's allowedTools or it cannot spawn subagents at all.
- Subagents have isolated context windows and get only what the coordinator writes into their prompt.
- Pass complete prior findings and keep structured metadata (source, page, confidence) intact.
- Attribution failures are coordinator context-passing bugs, not synthesis-agent bugs.
- Spawn independent subagents in parallel (multiple Task calls in one response) to cut latency.
- fork_session branches for divergent exploration; --resume continues one named session.
Frequently asked questions
How does a Claude coordinator invoke a subagent?+
Through the Task tool (renamed Agent in Claude Code v2.1.63), which must be listed in the coordinator's allowedTools. Each subagent is defined by an AgentDefinition specifying its description, system prompt, and tool restrictions, and receives its context through the prompt the coordinator writes.
How do you pass context to a Claude subagent?+
Explicitly, in the subagent's prompt. Because subagents run in isolated context windows, the coordinator must include all relevant prior findings in full and keep structured metadata (source URLs, document names, page numbers, confidence) separate from the claims so the subagent can attribute them.
Should independent subagents run in parallel or sequentially?+
In parallel. The coordinator should emit multiple Task tool calls in a single response so independent tasks execute simultaneously. Sequential invocation - one subagent per turn - adds latency with no benefit when the tasks do not depend on each other.