Spawning Subagents and Passing Context

What you need to know

Spawning: the Task tool

A coordinator spawns a subagent by calling a tool: the Task tool. Two consequences follow:

• If the coordinator's allowedTools does not include "Task", it cannot delegate, however clearly its system prompt tells it to. It will do the work itself.
• Spawning is a tool call like any other, so it shows up in the loop and in hooks.

Defining subagents: AgentDefinition

Each subagent type is described by an AgentDefinition:

options = ClaudeAgentOptions(
    allowed_tools=["Task", "Read", "Grep"],   # "Agent" in current releases
    agents={
        "synthesis": AgentDefinition(
            description="Combines research findings into a structured draft.",
            prompt="You merge findings. Keep every claim's source.",
            tools=["Read"],
        ),
    },
)

Subagents inherit nothing you do not pass

A non-forked subagent starts with a fresh context. It does not receive the coordinator's conversation history, earlier tool results, or another subagent's output, and nothing is shared between one invocation and the next. The only bridge is the prompt the coordinator writes for it.

So when the synthesis subagent writes a generic report that cites none of the search results, the likeliest cause is simple: nobody put the search results in its prompt.

What to put in a subagent's prompt

• Complete findings from earlier agents, not a one-line paraphrase. The synthesis subagent needs the search results and document analysis themselves.
• Structure that separates content from metadata, so attribution survives: each finding with its source URL or document name, page, and date.
• The goal and quality criteria, not a script. "Find evidence on recycling capacity in the EU since 2023; prefer primary sources; flag conflicts" lets the subagent adapt. "Run these five queries in order and summarise the top three results" breaks the moment the topic does not fit the script.

{"findings": [
  {"claim": "EU recycling capacity grew 40% in 2024",
   "source": "https://example.org/report-2025", "page": 12,
   "published": "2025-03-10"}
]}

Parallel spawning

To run independent subagents at the same time, the coordinator emits several Task calls in one response. Emitting one per turn makes them run one after another: two tasks of 15 and 20 seconds take 35 seconds in sequence and about 20 in parallel.

Fork-based sessions

For exploring two divergent approaches from the same analysis, a fork copies the conversation so far into a new, independent branch (lesson 1.7). A fork is the exception to "starts fresh": it inherits the history up to the fork point.

In the exam

Look for these symptoms: a coordinator that does all the work itself (missing Task tool), a synthesis that ignores earlier findings (findings not passed), lost citations (metadata not structured), slow runs (Task calls spread across turns), or rigid subagents (procedural prompts). Claims that subagents "automatically share memory" or "inherit the parent's history" are wrong.

Check your understanding

Apply it: Write Whitfield's synthesis task

{"question": "...", "findings": [
  {"claim": "...", "source": "URL or document name",
   "location": "page or section", "published": "YYYY-MM-DD",
   "from": "web_search | document_analysis"}],
 "gaps": ["subtopics with no findings"]}