1.3 Subagent invocation, context passing, and spawning
The Task tool
Subagents are spawned via the Task tool (Agent SDK subagents, custom subagents in Claude Code). A coordinator therefore must have "Task" in allowedTools — omit it and delegation silently cannot happen.
- TypeScript
- Python
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: COORDINATOR_PROMPT,
options: {
allowedTools: ["Task", "Read", "Grep"], // "Task" is mandatory for delegation
agents: {
"web-search": {
description: "Searches the public web for sources on an assigned subtopic.",
prompt: "You research one assigned subtopic. Return findings as structured claims with source URL and publication date.",
tools: ["WebSearch", "WebFetch"],
},
"doc-analysis": {
description: "Extracts data points and claims from provided documents.",
prompt: "You analyse supplied documents only. Never search the web.",
tools: ["Read", "load_document"],
},
synthesis: {
description: "Merges findings into a cited narrative.",
prompt: "You merge supplied findings. Preserve every claim-source mapping.",
tools: ["verify_fact"], // scoped cross-role tool, see Domain 2.3
},
},
},
})) {
// ...
}
from claude_agent_sdk import AgentDefinition, ClaudeAgentOptions, query
options = ClaudeAgentOptions(
allowed_tools=["Task", "Read", "Grep"], # "Task" is mandatory for delegation
agents={
"web-search": AgentDefinition(
description="Searches the public web for sources on an assigned subtopic.",
prompt="You research one assigned subtopic. Return findings as structured claims with source URL and publication date.",
tools=["WebSearch", "WebFetch"],
),
"doc-analysis": AgentDefinition(
description="Extracts data points and claims from provided documents.",
prompt="You analyse supplied documents only. Never search the web.",
tools=["Read", "load_document"],
),
"synthesis": AgentDefinition(
description="Merges findings into a cited narrative.",
prompt="You merge supplied findings. Preserve every claim-source mapping.",
tools=["verify_fact"], # scoped cross-role tool, see Domain 2.3
),
},
)
async for message in query(prompt=COORDINATOR_PROMPT, options=options):
...
An AgentDefinition carries the subagent's description (how the coordinator decides to use it), its prompt (system prompt), and its tool restrictions.
Context must be passed explicitly
Subagents inherit nothing. Include the complete findings from prior agents directly in the subagent's prompt:
- TypeScript
- Python
const synthesisPrompt = `
Synthesise the following findings into a cited report.
<web_findings>
${JSON.stringify(webFindings, null, 2)}
</web_findings>
<document_findings>
${JSON.stringify(docFindings, null, 2)}
</document_findings>
Preserve every claim -> source mapping. Annotate coverage gaps explicitly.
`;
synthesis_prompt = f"""
Synthesise the following findings into a cited report.
<web_findings>
{json.dumps(web_findings, indent=2)}
</web_findings>
<document_findings>
{json.dumps(doc_findings, indent=2)}
</document_findings>
Preserve every claim -> source mapping. Annotate coverage gaps explicitly.
"""
Use structured data formats that separate content from metadata — source URLs, document names, page numbers, publication dates — so attribution survives the handoff:
{
"claim": "Streaming revenue grew 14% YoY in 2025.",
"evidence": "…revenue rose 14 percent year over year…",
"source": { "type": "url", "value": "https://example.org/report", "published": "2026-02-11" },
"relevance": 0.91
}
Parallel spawning
Emit multiple Task tool calls in a single coordinator response. Spawning across separate turns serialises the work and forfeits the latency win.
Goal-oriented coordinator prompts
Specify research goals and quality criteria, not step-by-step procedure. Procedural prompts remove the adaptability that made a subagent worth spawning.
Fork-based session management
fork_session (Python) / forkSession (TypeScript) creates independent branches from a shared analysis baseline — the way to explore divergent approaches without re-paying for the shared exploration. See 1.7.
Quiz
- Question 1
The web search subagent returns 30 relevant articles and logs confirm it completed successfully. The coordinator then spawns the synthesis subagent, whose allowedTools and system prompt are both correct, and it returns a report stating that no sources were available on the topic. What is the defect?
- Question 2
Your coordinator delegates four independent subtopics to four subagents on every broad research task. Wall-clock time is roughly four times a single subagent run, although none of the four depends on another’s output. Traces show the coordinator emitting one Task call, waiting for its result, then emitting the next in the following turn. What change reduces the latency?
- Question 3
A 40-minute analysis pass over a corpus has finished and its findings are current. You now want to compare two synthesis strategies against that same baseline, without repeating the analysis and without either attempt seeing the other’s intermediate output. Which mechanism fits?
- Question 4
The synthesis subagent receives the search subagent’s findings as one concatenated block of article text. Its prose is coherent, but citations are regularly attached to the wrong article and some claims carry no source at all. What change fixes attribution?