Subagent Invocation and Context Passing

What you need to know

Lesson 1.2 is the shape of the system. This lesson is the wiring: how the coordinator actually starts a subagent and what it puts in that call.

The Task tool

The Task tool is how a coordinator spawns a subagent. That is the name in exam guide v0.2. Current Claude Code renamed it to Agent. Task still works as an alias, and the Agent SDK emits Agent in tool-use blocks. On the exam, answer Task. In current code, expect Agent.

The coordinator's allowedTools must include "Task" or "Agent". Without that name, the coordinator cannot spawn anyone. It is a gate, not a preference.

An AgentDefinition has three fields:

Description. What the subagent does. The coordinator uses this to decide when to call it.
System prompt. The instructions that subagent follows.
Tool restrictions. Which tools it may use, scoped to its role.

What has to be in the prompt

A subagent receives only the text the coordinator writes into its prompt. Three rules decide whether that handoff works.

Pass prior findings in full. If synthesis needs search results and document analysis, both go into the synthesis prompt, complete. Synthesis cannot look up the earlier results.
Keep the claim separate from its source. A finding needs the content and the metadata: source URL, document name, page number. Content alone leaves the next agent with nothing to cite.
State the goal, not the procedure. Tell the subagent what to achieve and what good looks like. A step-by-step script keeps it from changing approach when the input is unexpected.

Structured metadata

Each finding should carry its source. When synthesis receives this object, it has what it needs to cite the report.

{
  "findings": [
    {
      "claim": "Solar panel efficiency rose 25% in the last 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"
    }
  ]
}

Parallel and sequential calls

Independent subagents should be several Task calls in one coordinator response. One call per turn makes the second agent wait for no reason. If search and document analysis do not need each other's output, spawn both at once.

The exam is testing latency. For independent work, look for an option that says the calls happen in a single response or at the same time.

fork_session

fork_session starts an independent branch from a shared baseline. After the coordinator has read a codebase or framed a problem, it can fork to try two approaches. Each fork continues on its own. It does not see the other fork's results, and a change in one does not land in the other.

Example: after reading a codebase, fork to compare two testing strategies. --resume is the CLI flag for continuing a named session, with a matching resume option in the SDK. fork_session is the SDK option (forkSession in TypeScript) and --fork-session on the CLI.

Fork is a branch. Resume continues the same line of work. Use fork to compare approaches from one starting point. Use resume to carry on with the same investigation.

Worked example: missing citations

Three agents: web search, document analysis, and synthesis. Search returns URLs and titles. Document analysis returns page references. The coordinator sends the claims and the analysis text to synthesis and leaves out the URLs, document names, and page numbers.

Synthesis writes a clear summary with no sources. Changing its prompt does not help: it cannot cite a URL it was never given. The coordinator has to pass the structured metadata with every finding.

Exam traps

Assume a subagent can see the coordinator's history or another agent's output
Each subagent starts with the prompt it is given. Prior findings, source URLs, and constraints have to be written into that prompt.
Blame synthesis when the report has no citations
Synthesis can cite only the sources it was given. If the coordinator passed claims without URLs, document names, and page numbers, there is nothing to cite.
Call independent subagents one turn at a time
Independent work should be several Task calls in one coordinator response. Waiting a turn between them only adds latency.
Treat fork_session and --resume as the same control
Resume continues the same session. Fork branches from a shared start so the branches do not see each other. In the SDK you set both: resume names the session, fork_session says branch instead of append.

Practice scenario

A synthesis agent writes a report where several claims have no source. Web search returns results with URLs, titles, and snippets. Document analysis returns analysis with page references. Both specialists are working. What most likely caused the missing citations?

Option AGive the synthesis agent the web search tool so it can rerun the queries and check sources itself.Option BThe coordinator passes the claims without structured metadata — source URLs, document names, and page numbers are left out.Option CThe synthesis system prompt never says to cite sources, so the report summarises the research with no attribution.Option DWeb search returns a format the synthesis agent cannot parse, so URLs and titles are dropped during synthesis.

Build exercise

Implement context passing with structured metadata

What you will learn

Why allowedTools must include Task or Agent before a coordinator can spawn
How a finding keeps the claim separate from its source
Why a missing citation is a handoff bug
How to spawn independent subagents in one response
How fork_session differs from a parallel Task call

Step 1
Put Task or Agent on the coordinator
Create a coordinator whose allowedTools includes Task, or Agent, its current name.
Why: That entry is the gate for spawning. Without it, the coordinator cannot invoke a subagent. The exam treats this as a hard requirement.
You should see: A query call whose options.allowedTools lists Agent or Task, plus subagent definitions under options.agents.
Step 2
Define web search and document analysis
Give each subagent a description, a system prompt, and a tool list limited to its job.
Why: The exam checks the three AgentDefinition fields: description, system prompt, and tool restrictions.
You should see: Two definitions. Search can search. Document analysis can read files. Neither has the other's tools.
Step 3
Separate the claim from its source
Each finding needs the claim plus source_url, document_name, page_number, and confidence.
Why: Unsourced synthesis is the attribution failure. The coordinator passed text and dropped the metadata.
You should see: A Finding type with claim and analysis, and metadata fields source_url, document_name, page_number, confidence, and retrieved_by.
Step 4
Pass both result sets intact
Put the full findings arrays from search and document analysis into the synthesis prompt.
Why: Stripping metadata before synthesis is the bug the exam is pointing at. The coordinator must pass the structured output, not only the claim text.
You should see: The synthesis prompt contains the complete findings array. No source field is summarised away.
Step 5
Check that every claim cites a source
Read the synthesis report and confirm each factual claim has a URL and a page number.
Why: If a claim has no citation, look at what was passed. The synthesis prompt cannot invent a URL it never received.
You should see: Every factual claim in the report has a citation with a source URL and a page number.
Step 6
Spawn the two research agents in one response
Have the coordinator emit both Task calls together, then wait for both before synthesis.
Why: Search and document analysis do not depend on each other. Calling them on separate turns adds latency. The exam wants both calls in a single coordinator response.
You should see: One coordinator turn contains two Task tool calls. Synthesis starts after both results are back.

Sources

Claude Agent SDK overview — Anthropic
Agent SDK: work with sessions — Anthropic
MCP specification — Anthropic / MCP