Rubric
Contents — domains, guide and mocks

Subagent invocation and context passing

CCAR-F 1.310 min read · checked 21 September 2026

Task statementConfigure subagent invocation, context passing, and spawning

Defining a subagent

In the Agent SDK a subagent is an AgentDefinition: a description that tells the coordinator when to use it, a prompt that becomes its system prompt, and optionally tools to restrict what it can do and model to override the model. The description matters more than it looks — the coordinator chooses subagents by matching the task against descriptions.

Two specialised subagents, one read-onlypython
options = ClaudeAgentOptions(
    allowed_tools=["Read", "Grep", "Glob", "Agent"],   # the coordinator can spawn
    agents={
        "doc-analyst": AgentDefinition(
            description="Analyses supplied documents and extracts cited findings.",
            prompt="Extract claims with their source file and page. Never speculate.",
            tools=["Read", "Grep", "Glob"],            # read-only
        ),
        "synthesiser": AgentDefinition(
            description="Combines findings from other agents into one report.",
            prompt="Merge findings. Preserve every source attribution you are given.",
            tools=["Read"],
        ),
    },
)

Only description and prompt are required. Current documentation lists further optional fields — among them disallowedTools, skills, mcpServers, maxTurns, effort and permissionMode — but the exam's focus is the four above. If you leave tools out, the subagent inherits every tool available to subagents, so restricting it is a deliberate least-privilege choice, not a formality. Subagents can also be written as Markdown files in .claude/agents/; programmatic definitions win when the names clash.

What a subagent can see

A subagent's context starts fresh. It receives its own system prompt and the prompt string it was spawned with — not the coordinator's conversation history, not earlier tool results, not the coordinator's system prompt. If the synthesis agent needs the web search results and the document analysis, the coordinator has to put them in its prompt.

The spawn prompt is the only bridge

Reaches the subagent

  • Its own prompt (its system prompt)
  • The prompt string it was spawned with
  • Its tool definitions (all, or the tools subset)
  • Project CLAUDE.md, when settings load it

Never reaches it

  • The coordinator's conversation history
  • Tool results the coordinator already saw
  • The coordinator's system prompt
  • Anything a sibling subagent found
  • Its own earlier runs, unless resumed
Nothing flows from coordinator to subagent except the prompt string. Nothing flows back except the subagent's final message — its intermediate tool calls stay in its own context.

The return path is just as narrow. When a subagent finishes, the coordinator receives the subagent's final message as the result of the spawning tool call — not the files it read or the searches it ran. That is the point of a subagent: it can explore widely while the coordinator's context grows only by the summary. It also means a subagent should be told what its final message must contain, because that message is all anyone will see.

Passing context well

Pass complete findings, not a pointer to them. And keep content separate from metadata: when handing results to a synthesis agent, use a structured format that carries source URLs, document names and page numbers alongside each claim. Flattening everything into prose is how attribution gets lost between agents.

Findings passed with their provenancejson
[
  { "claim": "Cooling accounts for roughly 40% of facility energy",
    "source": "https://example.org/report-2025.pdf", "page": 12 },
  { "claim": "Water use rose year on year",
    "source": "internal/esg-summary.docx", "page": 3 }
]

Rewriting a spawn prompt

Weak — refers to invisible contexttext

Write the final report from
the research so far.

Strong — self-contained brieftext

Goal: a 2-page briefing on data-
centre water use for the ESG board.

Findings (JSON, with sources):
[ ...12 claims from 3 agents... ]

Rules:
- Use only these findings.
- Keep every source and page.
- Flag claims that conflict.

Return: markdown report, then a
list of gaps you noticed.
The weak prompt points at context the subagent cannot see. The strong one carries the findings, the goal and what “done” looks like.

Running subagents in parallel

To run subagents concurrently, the coordinator emits several spawn calls in a single response rather than one per turn. Independent subtasks then finish in roughly the time of the slowest, not the sum of all of them.

Parallel spawn, message by message

Coordinator
Analyst A
Analyst B
Synthesiser
Step 1: Coordinator to Analyst A: Contract A + what to extract
Step 2: Coordinator to Analyst B: Contract B + what to extract
Step 3: Analyst A to Coordinator: Final JSON only
Step 4: Analyst B to Coordinator: Final JSON only
Step 5: Coordinator to Synthesiser: Both JSON lists + format
Step 6: Synthesiser to Coordinator: Cited report
Both analysts are spawned from the same coordinator response, so they run side by side. The synthesiser only learns what the coordinator hands it.

Coordinator prompts should state research goals and quality criteria rather than step-by-step procedures. A subagent told what good looks like can adapt to what it finds; one given a rigid script cannot.

The guide also mentions fork-based sessions for exploring divergent approaches from a shared analysis baseline. That is covered in 1.7.

Traps the wrong answers are built from

Tempting but wrongDo this instead
Assuming a subagent knows what the coordinator knowsPass every finding and constraint it needs in its prompt.
Spawning subagents one per turn when the work is independentEmit several spawn calls in one coordinator response.
Flattening findings into prose between agentsPass structured claims with source, document and page.
Procedural step lists in coordinator promptsState goals and quality criteria so subagents can adapt.
Leaving the spawning tool out of the coordinator's allowed toolsInclude it ("Task" in the guide; "Agent" in current SDK code).

You should now be able to

  • Define subagents with descriptions, prompts and restricted tool sets.
  • Include the spawning tool in the coordinator's allowed tools.
  • Put complete prior findings directly in a subagent's prompt.
  • Pass context in a structured format that preserves attribution.
  • Spawn parallel subagents from a single coordinator response.

Practice questions

Original questions written for this lesson, in the exam’s style. Answer first, then open the reasoning — every option is explained, including why the wrong ones are tempting.

  1. Question 1

    A synthesis subagent produces a report that ignores most of the evidence gathered earlier. Logs show the coordinator spawned it with the prompt: “Write the final report from the research so far.”

    What is the most likely cause?

    1. AThe synthesis subagent runs on a model that is too small for the job.
    2. BThe synthesis agent lacks the web search tool it needs to gather data.
    3. CIt started fresh, so it never received the research in its prompt.
    4. DSubagents must be resumed rather than spawned to see earlier work.
    Show answer and reasoning
    1. AIncorrect. A larger model still cannot see findings that were never passed to it.
    2. BIncorrect. It does not need to search again; it needs the findings the others gathered.
    3. CCorrect. Subagent context starts fresh. “The research so far” refers to something it cannot see.
    4. DIncorrect. Resumption continues a subagent's own history, not the coordinator's.

  2. Question 2

    A coordinator needs results from four independent search subagents. How should it spawn them to minimise total time?

    1. AEmit four spawn calls in a single coordinator response.
    2. BSpawn one subagent, wait for its result, then spawn the next.
    3. CGive one subagent all four topics in a single long prompt.
    4. DHave each subagent spawn the next one when it has finished.
    Show answer and reasoning
    1. ACorrect. Multiple calls in one response let independent subagents run concurrently.
    2. BIncorrect. Sequential spawning makes total time the sum of all four.
    3. CIncorrect. That removes the parallelism and loads one context with everything.
    4. DIncorrect. Chaining serialises the work and bypasses the coordinator.

  3. Question 3

    A team defines three subagents with clear descriptions and passes them in agents. The coordinator's allowed tools are Read, Grep and Glob. In testing, the coordinator never delegates and does all the work itself.

    What should they check first?

    1. AWhether each subagent's model field names a supported model.
    2. BWhether the spawning tool is in the coordinator's allowed tools.
    3. CWhether the subagents' tools lists include Read and Grep.
    4. DWhether the coordinator's system prompt forbids doing work itself.
    Show answer and reasoning
    1. AIncorrect. A bad model value would fail when the subagent runs; it would not stop delegation being attempted.
    2. BCorrect. The guide says the coordinator's allowedTools must include the spawning tool ("Task"; "Agent" in current SDK code). Without it, spawn calls are not pre-approved, so an unattended run cannot delegate.
    3. CIncorrect. Subagent tool lists govern what a subagent can do once spawned, not whether the coordinator can spawn it.
    4. DIncorrect. A prompt instruction does not grant a tool the configuration withholds.

  4. Question 4

    Three analysis subagents each return findings with a URL and page number. The coordinator summarises their results in a paragraph and passes it to the synthesis subagent. The final report has almost no citations.

    What is the best fix?

    1. ATell the synthesis subagent to search again for the missing sources.
    2. BAdd a citation-checking subagent after the report is written.
    3. CGive the synthesis subagent the same system prompt as the analysts.
    4. DPass the findings as structured claims, each with source and page.
    Show answer and reasoning
    1. AIncorrect. Re-searching wastes the work already done and may find different sources.
    2. BIncorrect. It can detect missing citations but cannot recover provenance that was discarded upstream.
    3. CIncorrect. The problem is the input it received, not its instructions.
    4. DCorrect. Attribution was lost when the coordinator flattened findings into prose. Keeping claims and metadata together preserves it.

Practise every question in Domain 1 →

Sources

Drafted with AI assistance and checked against the sources above; expert review is in progress. Spotted an error? Tell us and it gets fixed, dated and listed on how this is written.