Home › Study guides › CCAR-F › Domain 1 › Lesson 1.3

CCAR-F · Domain 1 · 27% of the exam · Lesson 1.3 · 21 min read

Spawning subagents: the Task tool, context passing and forking

How a coordinator spawns subagents with the Task tool, why "Task" must be in allowedTools, what an AgentDefinition holds, and how findings reach a subagent.

Written against task statement 1.3 of the official CCAR-F exam guide (Version 1.0, effective July 2026). An independent resource, not affiliated with Anthropic; the practice questions are written from scratch.

1.3.1 How does a coordinator actually start a subagent?

Picture a research manager with a small team. A client asks for a report on where solid-state batteries for electric cars stand today. She does not do all the reading herself. She writes a brief for a researcher who will search the web and another for an analyst who will read the regulatory documents. Later she briefs a writer who will pull both sets of findings together. Notice three habits. Delegating is an ACT, not a wish: she hands a brief to a specific person. Each person knows only what the brief says, not what is in her head. And she hands out the two independent briefs at the same time rather than waiting for one to finish.

A multi-agent research system built with the Claude Agent SDK (software development kit: Anthropic's library for building agents) works the same way. Its manager is the coordinator, a Claude agent (Claude working in a loop, calling tools until the job is done) whose job is to delegate. The helpers it starts are subagents, each a separate agent with its own conversation.

Like any agent, the coordinator can act only through tools: it writes a structured request, and the software around it carries the request out. So starting a subagent is a tool call, made with a tool the exam guide calls the Task tool. The subagent knows only what the coordinator wrote into that call's prompt. And because one reply can hold several tool calls, the coordinator can start several subagents at once.

1.3.2 Delegation is a tool call: the Task tool and allowedTools

Here is the fact that makes everything else fall into place: the coordinator does not "have" subagents in any built-in sense. It has a tool. You describe the subagent types in the agents option, one of the settings you pass when you start the coordinator. The coordinator starts one by calling the Task tool with two key inputs: which type to run and the prompt to give it. The SDK then runs the subagent as its own separate agent and hands its final message back to the coordinator as the tool result, just as any tool returns its answer. Claude decides WHEN to delegate and what to say; the SDK does the spawning.

Because it is a tool call, the ordinary rules of tools apply. The coordinator picks a subagent type the way it picks any tool, by reading its description. And it can call the Task tool only if its configuration allows it. This is the configuration rule the exam tests: the coordinator's allowedTools list (allowed_tools in Python), the tools it is allowed to use, must include "Task". A coordinator with four well-defined subagents and no "Task" in that list does the research itself. No prompt wording fixes that, because the fault is in the configuration, not in the model's willingness.

In our research system the coordinator's allowedTools includes "Task", and its agents option defines four types: web-search, document-analysis, synthesis (findings in, argued narrative out) and report, which produces the final cited document. Only the coordinator needs "Task"; the workers do their jobs with their own tools.

1.3.3 Describing each worker: the AgentDefinition

The coordinator chooses subagents the way it chooses tools, so each subagent needs what a tool needs: a description that says when to use it, and a definition of what it can do. In the SDK that bundle is the AgentDefinition. You write one per subagent type and file it under the type's name in the agents option. Three fields carry the weight.

Memorise the three fields and their jobs. The definition accepts more (a model override, disallowedTools, maxTurns and others), but the exam asks about description, system prompt and tool restrictions.

Notice who reads what. The coordinator reads the description, so it is advice about WHEN to delegate. The subagent reads the prompt as its system prompt, the standing instructions it follows on every task. Its standards live there: how to judge a source, what shape findings take, what to do when evidence conflicts. The tools list is enforced, not requested: a tool you leave out is not in the subagent's session at all. A document-analysis subagent given ["Read", "Grep"] cannot search the web even if it wants to. It is safe because of how it is built, not because it was asked nicely.

Here is the shape for two of the four types. Look at the three comments: the description is aimed at the coordinator, the prompt at the subagent, and tools keeps each worker inside its job.

from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Task"],                 # "Task": the coordinator may spawn
    agents={
        "web-search": AgentDefinition(
            description="Finds current web sources on a topic. Use for any recent-events question.",  # read by the COORDINATOR
            prompt="You are a research searcher. Return each finding with its URL and the date you retrieved it.",  # the SUBAGENT's system prompt
            tools=["WebSearch", "WebFetch"],        # restriction: search and read, never write
        ),
        "document-analysis": AgentDefinition(
            description="Extracts claims and figures from long documents. Use when a document is already in hand.",
            prompt="You are a document analyst. Quote exactly and record the document name and page for every claim.",
            tools=["Read", "Grep"],                 # cannot search the web at all
        ),
    },
)

1.3.4 A subagent knows only what you tell it

Now the habit that catches almost everyone the first time. Suppose web-search has returned twelve findings on solid-state batteries and document-analysis has extracted eight claims. The coordinator spawns the synthesis subagent with the prompt "Synthesise the findings above into a narrative". The synthesis subagent replies that it has no findings, or worse, invents some. What happened?

Nothing "above" exists for the synthesis subagent. A subagent starts with a fresh conversation. It does not see the coordinator's history, system prompt or tool results, and nothing carries over automatically from one invocation to the next. The only content that passes from parent to subagent is the prompt written into the spawning call. It is the manager's brief again: the writer knows only what is on the page she hands over. So the coordinator must write the COMPLETE findings from search and analysis directly into the synthesis prompt: not a pointer to them, and not a two-line summary that throws the evidence away.

Second question: in what form? Pasted as a paragraph of prose, the sources blur. By the time the report subagent writes "analysts expect commercial cells by 2028", nobody can say which article or page said so. The fix is a structured format that separates content from metadata: the claim itself kept apart from the facts ABOUT the claim, such as where it came from. Each finding becomes a record with one field for the claim and separate fields for the source URL, document name, page number and retrieval date. Attribution then survives every handoff, because it travels as data rather than as a phrase a rewriter can drop. Here is one finding as a JSON record (a common text format for data):

{
  "content": "Pilot production of sulfide-electrolyte cells begins in 2027",
  "source_url": "https://example.org/battery-outlook-2026",
  "document": "Battery Outlook 2026",
  "page": 14,
  "retrieved": "2026-09-28"
}

Third question: how much to prescribe? It is tempting to write the brief as a procedure: "First list the findings, then group by manufacturer, then write three paragraphs." Resist it. A subagent is an agent, and its value is that it adapts to what it finds. Anthropic's research-system team found that each brief needs an objective, an output format, guidance on tools and sources, and clear boundaries, and that good heuristics beat rigid rules. So the coordinator states the GOAL ("explain where solid-state batteries stand for passenger cars and what blocks mass production"). It adds the QUALITY CRITERIA ("every claim carries its source; disagreements between sources are named, not averaged"). The method is left to the subagent.

1.3.5 Spawning in parallel: several Task calls in one response

Back to the manager handing out two briefs at once. The web search and the document analysis do not depend on each other, so the analyst need not wait for the searcher. A coordinator gets the same effect from a basic property of tool use: a single reply from Claude can contain more than one tool request (a tool_use block). If those requests are Task calls, the SDK starts all of those subagents, and they work at the same time. Independent subtasks then finish in the time of the slowest rather than the sum of all.

This is not a small effect. Anthropic's own research system has its lead agent start three to five subagents in parallel rather than one after another. Together with parallel tool calls inside each subagent, that change cut research time by up to 90 percent on complex queries.

The distinction the exam draws is precise: parallel spawning means several Task calls in ONE coordinator response, not one call per turn. A coordinator that spawns web-search, waits for the result, and only then spawns document-analysis runs them one after another, even though both are subagents. Parallel is right only for independent work. Synthesis needs the findings of the other two, so the coordinator spawns it in a later turn, once those results are back and can be written into its prompt.

Whether the coordinator actually does this depends on how you brief the coordinator itself. Instructions that read "search, then analyse, then synthesise" tend to be followed one step per turn. Instructions that state the research goal and the quality bar, and say that independent research should be launched together, work better. They let the coordinator spot the independent pieces and emit those Task calls in one response. Goals and criteria, not procedures, are what let an agent adapt, at every level.

1.3.6 Forking a session: two approaches from one baseline

One more situation from the manager's week. Research and analysis are done, and she wants the report tried two ways: as a chronological narrative and as a thematic comparison. She does not want the researchers to work twice. She wants one shared baseline and two branches from it.

The SDK gives you exactly that through sessions. A session is the saved conversation of one agent run: prompts, tool calls, tool results and replies. Every run ends with a result message that carries its session_id. Pass that id back as resume and the next run continues the same conversation, with all of its context. Pass it as resume together with fork_session=True (forkSession: true in TypeScript) and something different happens. The SDK creates a NEW session that starts with a copy of the original's history and then goes its own way. The fork gets its own session id, and the original is left untouched.

For our system, the baseline is the coordinator session in which web-search and document-analysis have already returned their findings. Branch A forks it to write a chronological narrative; branch B forks it to write a thematic comparison of manufacturers. Neither reruns a search, both start from identical evidence, and the original stays available to fork again. In the code, the two lines that matter are the two fork_session=True options pointing at the same resume id.

baseline_id = research_result.session_id           # from the finished run's result message

async for message in query(
    prompt="Synthesise the findings as a chronological narrative.",
    options=ClaudeAgentOptions(resume=baseline_id, fork_session=True),   # branch A: new id
):
    ...
async for message in query(
    prompt="Synthesise the findings as a thematic comparison of manufacturers.",
    options=ClaudeAgentOptions(resume=baseline_id, fork_session=True),   # branch B: another new id
):
    ...

1.3.7 The exam traps

Every mistake here comes from one of three misunderstandings. People treat delegation as something other than a tool call, assume a subagent sees what the coordinator saw, or run one at a time what could run together. The exam presents a misbehaving system and asks for the fix.

• ✗ Defining the subagents and expecting the coordinator to use them. ✓ Put "Task" in the coordinator's allowedTools. Delegation is a tool call, and prompt wording cannot stand in for a tool the configuration leaves out.
• ✗ Telling the synthesis subagent to "use the findings above". ✓ Paste the complete findings from web-search and document-analysis into its Task prompt. A subagent starts fresh; there is no "above".
• ✗ Passing findings as a summary paragraph. ✓ Pass structured records with the content in one field and the source URL, document name and page number in their own fields, so attribution survives every handoff.
• ✗ Spawning web-search, waiting, then spawning document-analysis. ✓ Emit both Task calls in one coordinator response; they are independent and run at the same time. Spawn synthesis, which needs their results, in a later turn.
• ✗ Writing the subagent brief as a numbered procedure. ✓ State the research goal, the quality criteria, the output format and the boundaries, and let the subagent adapt its method to what it finds.
• ✗ Rerunning the whole research to try a second report structure. ✓ Fork the session that holds the analysis baseline once per approach; each fork starts with the same history and leaves the original intact.

1.3.8 Put it together: spawn, pass, parallelise, fork

You now hold every piece: the Task tool and its configuration, the AgentDefinition, the Task prompt as the subagent's whole world, parallel spawning, and the session fork. The fastest way to make the context rule stick is to watch a subagent fail without it.

With the plumbing in hand, the rest of the domain builds on it. Workflow enforcement (1.4) guarantees that synthesis cannot start before the findings exist, and hooks (1.5) are the code that can inspect or block a Task call at the moment it is made. Task decomposition (1.6) is deciding which subagents to define and which pieces are independent enough to spawn together. Session management (1.7) goes deeper into resuming and forking, including what a session does and does not preserve.

Key takeaways

• ✓ A coordinator spawns a subagent by calling the Task tool; the SDK runs a separate agent loop and returns the subagent's final message as the tool result.
• ✓ "Task" must be in the coordinator's allowedTools for it to delegate; prompt wording cannot stand in for the missing tool.
• ✓ Each subagent type is an AgentDefinition: a description the coordinator reads to decide when to delegate, a system prompt for the worker, and a tools list that restricts what it can do.
• ✓ A subagent inherits none of the coordinator's context and no memory from earlier invocations; the complete findings it needs must be written into its Task prompt.
• ✓ Pass findings as structured records with content and metadata (source URL, document name, page number) in separate fields so attribution survives every handoff.
• ✓ Spawn independent subagents in parallel by emitting several Task calls in one coordinator response, and brief them with goals and quality criteria, not step-by-step procedures.
• ✓ Fork a session with resume plus fork_session=True to explore two approaches from one shared analysis baseline while the original stays unchanged.

Check your understanding

4 questions written for this lesson, then one from the CCAR-F question bank on the same topic. Every answer option is explained, including the ones you did not pick. Nothing is stored.

Sources

• Subagents in the SDK
• Work with sessions
• Configure permissions
• Claude Code subagents
• How tool use works
• How we built our multi-agent research system
• The CCAR-F exam guide, summarised