Spawning Subagents: the Task/Agent Tool, AgentDefinition and Fresh Context

1.The spawning tool, and why the coordinator must be allowed to call it

A coordinator doesn't start subagents by magic. It makes a tool call. The exam guide calls this the Task tool. The current Agent SDK documentation calls the same thing the Agent tool, and its samples list "Agent" in the coordinator's allowed tools. The name you see depends on the version, but the rule is the same: the tool that spawns subagents has to be available to the coordinator. If it isn't, subagent definitions just sit there, because Claude has no way to delegate to them.

In the SDK sample below, allowed_tools is commented as the auto-approve list. "Agent" appears in it next to the read-only tools, and the agents map then defines what can be spawned. The two go together: agents says which subagents exist, and the spawning tool is how Claude actually calls one. You don't even need a custom definition to delegate. Claude can use a general-purpose subagent through the same tool.

            # Auto-approve these tools
            allowed_tools=["Read", "Grep", "Glob", "Agent"],
            agents={
                "code-reviewer": AgentDefinition(
                    # description tells Claude when to use this subagent
                    description="Expert code review specialist. Use for quality, security, and maintainability reviews.",

The reverse also holds. Claude Code's documentation gives denying the spawning tool as the way to switch delegation off completely. So whether that tool is permitted is the single switch that decides whether a coordinator can fan out at all.

Once the tool is available, how the coordinator emits the calls decides whether subagents run in parallel or one after another. Subagents can run concurrently, and the documentation's promise is that independent subtasks then finish in the time of the slowest one rather than the sum of all of them. That promise only holds when the coordinator emits multiple Task tool calls in a single response. If it spawns one subagent, waits for the result, then spawns the next in a later turn, the work is serialised and the parallel benefit is gone. Anthropic's research system is built on exactly this: the lead agent analyses the query, develops a strategy, and spawns subagents to explore different aspects simultaneously. A code review that needs a style check, a security scan and a coverage report is the same shape. Three spawning calls in one coordinator response, not three turns.

What goes into each of those prompts matters as much as when they are sent. Research is open-ended and path-dependent, and Anthropic's engineering team is explicit that you can't hardcode a fixed path for exploring a complex topic. So a coordinator prompt that lists step-by-step procedural instructions ("search for X, then open the first three results, then extract Y") locks the subagent into a route the coordinator guessed in advance. The stronger pattern is to state the research goal, the scope, and the quality criteria the answer must meet, and let the subagent decide how to get there. That is what gives it the flexibility to pivot or follow a tangential lead as the investigation unfolds. Procedural steps belong in the subagent's system prompt only when the task really is mechanical, such as running a fixed test command.

Sources123

2.AgentDefinition: description, system prompt and tool restrictions

Each subagent type is an AgentDefinition, passed under agents in the query options. Two fields are required, and they do different jobs. The description is read by the coordinator to decide when to delegate. The prompt is the subagent's system prompt, which shapes how it behaves once it is running. A strong prompt doesn't help if the description never makes the coordinator reach for the subagent in the first place.

Tool restrictions are how you give each subagent only the power its role needs. The documentation's example is a doc-reviewer that only has Read and Grep, so it can analyse files but can't change them. The default goes the other way, and this catches people out: if you leave out tools, the subagent gets every tool available to subagents. It does not get none. The test-runner below is given Bash on purpose, because running tests is its job.

                "test-runner": AgentDefinition(
                    description="Runs and analyzes test suites. Use for test execution and coverage analysis.",
                    prompt="""You are a test execution specialist. Run tests and provide clear analysis of results.

Focus on:
- Running test commands
- Analyzing test output
- Identifying failing tests
- Suggesting fixes for failures""",
                    # Bash access lets this subagent run test commands
                    tools=["Bash", "Read", "Grep"],
                ),

Sources1

3.Fresh context: the prompt string is the only way in

When the coordinator calls the spawning tool, the input is small. It has a short description, the prompt, and optionally a subagent type and a model. The documentation describes prompt as the task for the agent to perform. The subagent starts its own conversation, and nothing from the coordinator's history is added to it. The files the coordinator read, what the user said three turns ago, and earlier subagents' results are all missing from its context unless the coordinator writes them into this prompt.

{
    "description": str,  # A short (3-5 word) description of the task
    "prompt": str,  # The task for the agent to perform
    "subagent_type": str | None,  # The type of specialized agent to use
    "model": "sonnet" | "opus" | "haiku" | "fable" | None,  # Model override for this agent

Isolation works in both directions. The subagent's intermediate tool calls and results stay inside the subagent, and only its final message goes back to the parent. That is why subagents are useful: a research subagent can read dozens of files and the coordinator gets a short summary instead of all that text. It also means nothing carries over between spawns. Each new subagent starts clean, so if a later subagent needs an earlier one's output, the coordinator has to pass it along in the prompt. Anthropic's workflow cookbook puts it plainly: each subagent sees only the prompt it is given.

State this as a rule, because the exam does: subagent context must be explicitly provided in the prompt. A subagent does not automatically inherit the parent's context, and there is no shared memory between invocations. Spawning the same subagent type twice gives you two unrelated conversations; the second one has no idea what the first one found. The only exception the documentation names is a fork, which deliberately starts from a copy of an existing conversation. For an ordinary spawn, assume the subagent knows nothing you have not typed into its prompt.

This is what context passing looks like in a real pipeline. In Anthropic's research system, each search subagent performs its own web searches and returns its findings to the lead agent, which synthesises them. When the lead agent then hands the report to a synthesis or citation agent, it passes all the findings along, because that agent cannot see the searches that produced them. The practical rule for a coordinator is to include the complete findings from prior agents directly in the next subagent's prompt: the actual web search results, the actual document analysis outputs, not a one-line reference to "the research above". A reference to something outside the prompt points at nothing.

How you lay that context out matters for attribution. If you paste findings as one undifferentiated block of text, the synthesis subagent loses track of which claim came from which source, and the final report cannot be attributed properly. Use a structured format that separates content from metadata: each finding carries its extracted text as one field and its provenance (source URL, document name, page number) as separate fields, whether that is JSON, a simple list of records, or clearly labelled blocks. The research system's final stage exists precisely so that every claim can be attributed to its source, and that is only possible if the metadata survived every hop between agents. Strip it at any one handoff and no later agent can recover it.

Sources4153

4.Forking a session: divergent approaches from one analysis baseline

Fresh-context spawning is the normal case, but sometimes you want the opposite: several agents that all start from the same expensive analysis and then diverge. The SDK's session options handle that. A session has an ID you capture from the result message. Passing that ID as resume appends new turns to the same stored history, which is right for follow-up work like "now implement the refactoring you suggested". Forking a session, via the fork_session (Python) or forkSession (TypeScript) option alongside resume, branches a new independent session from that point instead, leaving the original untouched.

    async for message in query(
        prompt="Now implement the refactoring you suggested",
        options=ClaudeAgentOptions(
            resume=session_id,
            allowed_tools=["Read", "Edit", "Write", "Glob", "Grep"],
        ),
    ):

The fork-based pattern for exploring divergent approaches goes like this. First, run one session that does the shared analysis, such as reading the auth module and mapping its dependencies, and capture its session ID. Then fork that session once per approach you want to try: one branch attempts a JWT migration, another keeps sessions server-side, a third explores a hybrid. Each fork begins with the complete baseline analysis already in its context, so none of them repeats the reading, and because each is an independent branch, none of them pollutes the others or the original. Compare the branches, keep the winner, and the baseline is still there if you want a fourth attempt. This is the same idea as the subagent documentation's note that a subagent's conversation starts fresh unless it is a fork: a fork is the one way to hand an agent a shared starting point without retyping it into a prompt.

Sources671

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.A subagent can see the coordinator's conversation, so it already knows what was discussed.Why is that wrong?

   A subagent starts a new conversation. What reaches it is its own system prompt plus the task prompt the coordinator writes, so context has to be passed in explicitly.

   Covered in Fresh context: the prompt string is the only way in

2. 2.A detailed, accurate prompt field is what makes the coordinator choose a subagent.Why is that wrong?

   The coordinator reads the description to decide when to delegate. The prompt only shapes behaviour once the subagent is running.

   Covered in AgentDefinition: description, system prompt and tool restrictions

3. 3.Leaving tools out of an AgentDefinition gives the subagent a safe, minimal tool set.Why is that wrong?

   When tools is omitted, the subagent inherits every tool available to subagents. To restrict it, list the tools you want or use disallowedTools.

   Covered in AgentDefinition: description, system prompt and tool restrictions

4. 4.Spawning three independent subagents one per turn gets the same speed-up as spawning them together.Why is that wrong?

   The parallel benefit comes from subagents running concurrently, which needs the coordinator to emit the spawning calls in a single response. One call per turn serialises the work.

   Covered in The spawning tool, and why the coordinator must be allowed to call it

5. 5.The most reliable research subagent prompt is a precise step-by-step procedure.Why is that wrong?

   Open-ended research is path-dependent and cannot be hardcoded in advance. Prompts that state goals and quality criteria let the subagent adapt as it discovers things; step lists lock it into a guessed route.

   Covered in The spawning tool, and why the coordinator must be allowed to call it

6. 6.To try two alternative implementations from the same analysis, resume the session twice.Why is that wrong?

   Resume appends to one history, so the second attempt would see the first. Fork branches an independent session from the shared baseline for each alternative and leaves the original intact.

   Covered in Forking a session: divergent approaches from one analysis baseline