Subagent Invocation and Context Passing

Official Exam Guide Objectives

Task 1.3: Configure subagent invocation, context passing, and spawning.

Knowledge of

• The Task tool as the mechanism for spawning subagents, and the requirement that allowedTools must include "Task" for a coordinator to invoke subagents
• That subagent context must be explicitly provided in the prompt—subagents do not automatically inherit parent context or share memory between invocations
• The AgentDefinition configuration including descriptions, system prompts, and tool restrictions for each subagent type
• Fork-based session management for exploring divergent approaches from a shared analysis baseline

Skills in

• Including complete findings from prior agents directly in the subagent's prompt (e.g., passing web search results and document analysis outputs to the synthesis subagent)
• Using structured data formats to separate content from metadata (source URLs, document names, page numbers) when passing context between agents to preserve attribution
• Spawning parallel subagents by emitting multiple Task tool calls in a single coordinator response rather than across separate turns
• Designing coordinator prompts that specify research goals and quality criteria rather than step-by-step procedural instructions, to enable subagent adaptability

What You Need to Know

Task Statement 1.3 covers the mechanics under 1.2's architecture: how a coordinator actually spawns a subagent, and what has to travel alongside the request for the result to be worth anything. 1.2 gave you the shape; this is the wiring, and wiring is where most multi-agent systems come apart.

The Task Tool

The Task tool is how a coordinator spawns subagents (the exam guide v0.2 uses this name). It names a concrete API mechanism in the Claude Agent SDK rather than delegation in the abstract, which is why the exact term matters. Claude Code as it ships today (v2.1.63, June 2026) calls the same mechanism Agent, retains Task as a working alias, and the Agent SDK writes Agent into its tool-use blocks. Give "Task tool" as the exam answer and expect Agent in anything written this year.

One setting gates the whole pattern: the coordinator's allowedTools must include "Task" (or "Agent", its current name in Claude Code). The gate is binary and does not degrade gracefully. Omit it and there is no route by which the coordinator reaches a subagent — the definitions can be flawless and every one of them is unreachable, and no prompt compensates for an absent capability.

Each subagent is defined by an AgentDefinition that specifies three things:

1. Description — the summary the coordinator reads when working out whether this is the subagent the current task calls for.
2. System prompt — the standing instructions the subagent runs under.
3. Tool restrictions — the tools it is permitted, narrowed to its role rather than inherited wholesale from the coordinator.

Context Passing: The Make-or-Break Detail

Context passing is where most multi-agent systems fall over, for the reason 1.2 established: a subagent receives its prompt and nothing else. Three rules follow.

Rule 1: Include complete findings from prior agents. Where synthesis depends on both the search results and the document analysis, both go into its prompt in full. Condensing them first to economise on tokens throws away exactly the detail synthesis was going to build on, and the agent has no way to recover it, because nothing retained the original.

Rule 2: Use structured data formats that separate content from metadata. A finding is a claim together with its provenance — source URL, document name, page number. Forward the claim alone and the claim arrives intact while the ability to attribute it does not.

The exam pattern built on this: a synthesis agent emits a report full of unsourced claims while search and document analysis are both behaving correctly. The cause sits in the handoff — content travelled, provenance did not — and the synthesis agent had nothing citable to work from, so no instruction to cite could have rescued it.

Rule 3: Design coordinator prompts that specify goals, not procedures. State the objective and what a good result looks like rather than the steps for producing one. A goal leaves room to adapt when the situation differs from the one you pictured; a procedure followed faithfully into an unanticipated case yields a confidently wrong result, because nothing licensed the subagent to depart from it.

Structured Metadata Format

Content and provenance need to stay bound together as the finding moves between agents. A workable shape:

{
  "findings": [
    {
      "claim": "Grid-scale battery storage costs fell 40% between 2020 and 2025",
      "source_url": "https://example.com/storage-costs",
      "document_name": "Global Energy Storage Outlook 2025",
      "page_number": 22,
      "confidence": "high",
      "retrieved_by": "web_search_agent"
    }
  ]
}

Attribution rides along with each claim, so the synthesis agent can cite without being separately briefed on where anything originated. retrieved_by earns its place too: when a claim turns out to be wrong, it identifies which subagent produced it.

Parallel Spawning

When a coordinator needs to invoke multiple subagents for independent tasks, it should emit multiple Task tool calls in a single response rather than invoking them one at a time across separate turns.

One subagent per coordinator turn gains nothing when the tasks have no dependency on each other. Where search and document analysis are independent, making the second wait on the first simply adds the first one's latency to the total — and the penalty grows with every subagent added to the chain.

Latency awareness is what the exam is probing, and the phrasing gives it away: options mentioning "in a single response" or subagents running "simultaneously" are describing the parallel pattern.

fork_session

fork_session creates independent branches from a shared analysis baseline. Once the coordinator has done the costly groundwork — read the codebase, established what the problem actually is — a fork explores a different direction from that point without paying for the groundwork again.

Take a coordinator that has finished reading a project and wants to weigh two testing strategies against each other. From the branch point each side proceeds alone: neither observes what the other found, and work done on one has no effect on the other.

fork_session is not the same as --resume. Resume picks up a specific named session and carries the same line of work forward. Fork opens a new independent branch. The exam tests the pair directly, and intent is the reliable way to keep them apart: fork to compare alternatives from a common origin, resume to continue a single line of investigation.

Practical Example: Attribution Failure

A multi-agent research system has three agents: web search, document analysis, and synthesis. Search hands back well-sourced results carrying URLs and titles. Document analysis hands back detailed findings carrying page references. Neither is misbehaving.

The coordinator forwards the substance of both to synthesis and drops everything else — claims and analysis text arrive, source URLs, document names and page numbers do not. Synthesis returns a clear, well-organised summary that cites nothing at all.

Rewriting the synthesis prompt cannot repair this, and the point is worth being firm about: no amount of insistence produces source information that was never delivered. Granting it tool access is no better, since that has it re-run retrieval the other two agents already completed. The repair belongs at the coordinator, which has to forward structured findings with source URL, document name and page number intact.

Deep Dive

Current state: "Task" is the exam answer, "Agent" is what current tooling emits

Sourcecode.claude.com › subagentsfetched 2026-07-30

AgentDefinition — the four fields that matter most

Beyond the three fields already covered (description, system prompt, tool restrictions), the SDK's AgentDefinition has a precise required/optional split. (The published table carries further optional fields — disallowedTools, skills, memory, mcpServers, initialPrompt, maxTurns, background, effort, permissionMode — but the four below are the ones the exam objectives touch.) description and prompt are required; tools and model are optional: "description | string | Yes | Natural language description of when to use this agent ... prompt | string | Yes | The agent's system prompt defining its role and behavior ... tools | string[] | No | Array of allowed tool names ... model | string | No | Model override for this agent." Note the field is named prompt, not systemPrompt.

Omitting tools is a meaningful default, not an error: "Omit tools: the subagent gets every tool available to subagents. List tools: the subagent gets only those." A subagent with no tools field is not restricted — it is maximally permissive within what subagents can access.

model accepts aliases: "an alias such as 'fable', 'opus', 'sonnet', 'haiku', 'inherit', or a full model ID. Defaults to main model if omitted" — so a cheaper or faster model can be assigned per-subagent role without hardcoding a model ID.

Sourcecode.claude.com › subagentsfetched 2026-07-30

Three ways to define a subagent, and which wins on a name clash

The SDK supports three creation paths: "Programmatically: use the agents parameter in your query() options ... Filesystem-based: define agents as markdown files in .claude/agents/ directories ... Built-in general-purpose: Claude can invoke the built-in general-purpose subagent at any time." If a programmatic definition and a filesystem definition share a name, the programmatic one wins: "Programmatically defined agents take precedence over filesystem-based agents with the same name."

Sourcecode.claude.com › subagentsfetched 2026-07-30

How Claude picks which subagent to invoke

Subagent selection is not purely explicit routing by the coordinator's code — Claude itself decides based on the definition: "When you define subagents, Claude determines whether to invoke them based on each subagent's description field." A well-written description therefore functions like a tool description: the primary signal for automatic delegation. The coordinator (or user) can also override this and name a subagent directly: "You can also explicitly request a subagent by name in your prompt, for example 'Use the code-reviewer agent to...'"

Sourcecode.claude.com › subagentsfetched 2026-07-30

Context isolation, precisely

"A subagent's context window starts fresh, with no parent conversation, but isn't empty. The only content you pass from parent to subagent is the Agent tool's prompt string" — the subagent does not receive the parent's conversation history, tool results, or system prompt unless the coordinator writes them into that one prompt string. Within a run, "each subagent runs in its own fresh conversation. Intermediate tool calls and results stay inside the subagent; only its final message returns to the parent" — so a subagent's exploratory tool calls (dozens of file reads, search queries) never bloat the coordinator's context; only the distilled final message does.

Sourcecode.claude.com › subagentsfetched 2026-07-30

Parallel subagents: isolation is what makes the speed-up safe

"Multiple subagents can run concurrently, so independent subtasks finish in the time of the slowest one rather than the sum of all of them" — the latency benefit behind "emit multiple Task tool calls in a single response." This is only safe because subagents have separate context windows in the first place: each one "runs in its own fresh conversation", so two subagents working the same corpus cannot corrupt each other's state or each other's context budget. The docs' own illustration is the high-volume, low-signal read: "a research-assistant subagent can explore dozens of files without any of that content accumulating in the main conversation" — exactly the web-search-plus-document-analysis shape used in this lesson's build exercise.

Sourcecode.claude.com › subagentsfetched 2026-07-30

fork_session — exact mechanics

fork_session (TypeScript: forkSession) is a boolean option used alongside resume — the sessions guide shows it as fork_session=True / forkSession: true, and the SDK reference documents it as "when resuming with resume, fork to a new session ID instead of continuing the original session." What forking actually does: "creates a new session that starts with a copy of the original's history but diverges from that point. The fork gets its own session ID; the original's ID and history stay unchanged. You end up with two independent sessions you can resume separately." That is the mechanism behind "comparing two testing strategies or refactoring approaches from a shared codebase analysis" — the shared baseline is the copied history at the fork point, and each branch is independently resumable afterward.

Sourcecode.claude.com › sessionsfetched 2026-07-30

Quick Reference

Exam Traps

Practice Scenario

Build Exercise

Implement Context Passing with Structured Metadata

Difficulty: Intermediate (2/4)

50 minutes

1. Create a coordinator agent with Task (or Agent) in its allowedTools

Why: Task is the hard gate for subagent spawning (renamed Agent in current Claude Code v2.1.63; Task still works as an alias). Without it in allowedTools, the coordinator cannot invoke any subagent. The exam tests this as a binary requirement — it is not optional or configurable at runtime.

You should see: A query() call whose options include allowedTools explicitly containing Agent (or Task) alongside any other tools the coordinator needs directly, plus the subagent definitions under options.agents.

2. Define two subagents: a web search agent that returns results with source URLs and titles, and a document analysis agent that returns analysis with page references

Why: Each subagent needs scoped tool access matching its role. The exam tests whether you define subagents with proper AgentDefinition fields: description, system prompt, and tool restrictions.

You should see: Two AgentDefinition objects, each with a description, system prompt, and restricted tool set. The web search agent has search tools only; the document analysis agent has file reading tools only.

3. Design a structured output format that separates content from metadata: each finding includes claim, source_url, document_name, page_number, and confidence

Why: The exam specifically tests the attribution failure pattern: when a synthesis agent produces unsourced claims, the root cause is that the coordinator passed content without structured metadata. Separating content from metadata is the fix.

You should see: A TypeScript interface or JSON schema defining the Finding type with both content fields (claim, analysis) and metadata fields (source_url, document_name, page_number, confidence, retrieved_by).

4. Pass complete structured results from both subagents to a synthesis subagent, preserving all metadata

Why: This is the critical step the exam targets. Stripping metadata before passing to the synthesis agent is the root cause of attribution failures. The coordinator must pass the full structured output, not just the claim text.

You should see: The coordinator passes the complete findings array (with all metadata intact) to the synthesis agent prompt. No metadata fields are stripped or summarised away.

5. Verify that the synthesis agent can attribute every claim in its output to a specific source with URL and page number

Why: This verification step confirms the context passing worked. If any claim lacks attribution, trace back to whether the metadata was actually passed — do not blame the synthesis agent prompt.

You should see: A synthesis report where every factual claim includes a citation with source URL and page number. No orphaned claims without attribution.

6. Refactor the coordinator to spawn both research subagents in parallel using multiple Task tool calls in a single response

Why: The exam tests latency awareness. Sequential spawning of independent subagents wastes time. Parallel spawning via multiple Task tool calls in a single coordinator response is the correct pattern for independent tasks.

You should see: Both the web search and document analysis subagents invoked simultaneously via parallel Task tool calls, with the coordinator waiting for both to complete before proceeding to synthesis.

Sources

• Claude Agent SDK Overview — Anthropic
• MCP Specification — Anthropic / MCP
• Building with Claude API (Skilljar) — Anthropic
• Claude Agent SDK — Subagents — Anthropic
• Claude Agent SDK — Sessions — Anthropic

Appendix A — Build Exercise Step Hints

Progressive hints revealed by the "Stuck? Get a nudge" control on each step.

Step 1. Create a coordinator agent with Task (or Agent) in its allowedTools

Why: Task is the hard gate for subagent spawning (renamed Agent in current Claude Code v2.1.63; Task still works as an alias). Without it in allowedTools, the coordinator cannot invoke any subagent. The exam tests this as a binary requirement — it is not optional or configurable at runtime.

You should see: A query() call whose options include allowedTools explicitly containing Agent (or Task) alongside any other tools the coordinator needs directly, plus the subagent definitions under options.agents.

import { query } from "@anthropic-ai/claude-agent-sdk";

const result = query({
  prompt: "Research the topic and produce a fully cited report.",
  options: {
    systemPrompt: "You coordinate research by delegating to specialist subagents and synthesising their findings.",
    // "Task" in the exam guide; renamed "Agent" in Claude Code v2.1.63
    allowedTools: ["Agent", "Read"],
    agents: {
      "web-search": webSearchAgent,
      "doc-analysis": docAnalysisAgent,
      "synthesis": synthesisAgent
    }
  }
});

import asyncio

from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(
    system_prompt=(
        "You coordinate research by delegating to specialist subagents "
        "and synthesising their findings."
    ),
    # "Task" in the exam guide; renamed "Agent" in Claude Code v2.1.63
    allowed_tools=["Agent", "Read"],
    agents={
        "web-search": web_search_agent,
        "doc-analysis": doc_analysis_agent,
        "synthesis": synthesis_agent,
    },
)


async def main():
    async for message in query(
        prompt="Research the topic and produce a fully cited report.",
        options=options,
    ):
        print(message)


asyncio.run(main())

Step 2. Define two subagents: a web search agent that returns results with source URLs and titles, and a document analysis agent that returns analysis with page references

Why: Each subagent needs scoped tool access matching its role. The exam tests whether you define subagents with proper AgentDefinition fields: description, system prompt, and tool restrictions.

You should see: Two AgentDefinition objects, each with a description, system prompt, and restricted tool set. The web search agent has search tools only; the document analysis agent has file reading tools only.

// Keyed into options.agents as "web-search" and "doc-analysis"
const webSearchAgent = {
  description: "Searches the web for current information and returns results with source URLs and titles",
  prompt: "Search for information on the given topic. Return each finding as JSON with fields: claim, source_url, source_title, retrieved_date.",
  tools: ["WebSearch"]
};
const docAnalysisAgent = {
  description: "Analyses documents and returns findings with page references",
  prompt: "Analyse the provided documents. Return each finding as JSON with fields: claim, document_name, page_number, section.",
  tools: ["Read", "Grep"]
};

from claude_agent_sdk import AgentDefinition

# Keyed into options.agents as "web-search" and "doc-analysis"
web_search_agent = AgentDefinition(
    description=(
        "Searches the web for current information and returns results with "
        "source URLs and titles"
    ),
    prompt=(
        "Search for information on the given topic. Return each finding as JSON "
        "with fields: claim, source_url, source_title, retrieved_date."
    ),
    tools=["WebSearch"],
)
doc_analysis_agent = AgentDefinition(
    description="Analyses documents and returns findings with page references",
    prompt=(
        "Analyse the provided documents. Return each finding as JSON with "
        "fields: claim, document_name, page_number, section."
    ),
    tools=["Read", "Grep"],
)

Step 3. Design a structured output format that separates content from metadata: each finding includes claim, source_url, document_name, page_number, and confidence

Why: The exam specifically tests the attribution failure pattern: when a synthesis agent produces unsourced claims, the root cause is that the coordinator passed content without structured metadata. Separating content from metadata is the fix.

You should see: A TypeScript interface or JSON schema defining the Finding type with both content fields (claim, analysis) and metadata fields (source_url, document_name, page_number, confidence, retrieved_by).

interface Finding {
  claim: string;
  source_url: string;
  document_name: string;
  page_number: number | null;
  confidence: "high" | "medium" | "low";
  retrieved_by: string;
}

interface ResearchOutput {
  findings: Finding[];
  query: string;
  timestamp: string;
}

Step 4. Pass complete structured results from both subagents to a synthesis subagent, preserving all metadata

Why: This is the critical step the exam targets. Stripping metadata before passing to the synthesis agent is the root cause of attribution failures. The coordinator must pass the full structured output, not just the claim text.

You should see: The coordinator passes the complete findings array (with all metadata intact) to the synthesis agent prompt. No metadata fields are stripped or summarised away.

// The prompt the coordinator embeds when it invokes the synthesis subagent;
// webSearchResults / docAnalysisResults are the structured findings the research subagents returned
const synthesisPrompt = `Synthesise the following research findings into a coherent report. Every claim MUST include a citation with source URL and page number.

Web search findings:
${JSON.stringify(webSearchResults.findings, null, 2)}

Document analysis findings:
${JSON.stringify(docAnalysisResults.findings, null, 2)}

Output a report where every factual claim links to its source.`;

import json

# The prompt the coordinator embeds when it invokes the synthesis subagent;
# web_search_results / doc_analysis_results are the structured findings the
# research subagents returned
synthesis_prompt = f"""Synthesise the following research findings into a coherent report. Every claim MUST include a citation with source URL and page number.

Web search findings:
{json.dumps(web_search_results["findings"], indent=2)}

Document analysis findings:
{json.dumps(doc_analysis_results["findings"], indent=2)}

Output a report where every factual claim links to its source."""

Step 5. Verify that the synthesis agent can attribute every claim in its output to a specific source with URL and page number

Why: This verification step confirms the context passing worked. If any claim lacks attribution, trace back to whether the metadata was actually passed — do not blame the synthesis agent prompt.

You should see: A synthesis report where every factual claim includes a citation with source URL and page number. No orphaned claims without attribution.

function verifyCitations(report: string, findings: Finding[]): string[] {
  const uncited: string[] = [];
  const claims = extractClaims(report);
  for (const claim of claims) {
    const hasCitation = findings.some(f =>
      report.includes(f.source_url) && report.includes(claim)
    );
    if (!hasCitation) uncited.push(claim);
  }
  return uncited;
}

def verify_citations(report: str, findings: list[dict]) -> list[str]:
    uncited = []
    for claim in extract_claims(report):
        has_citation = any(
            f["source_url"] in report and claim in report for f in findings
        )
        if not has_citation:
            uncited.append(claim)
    return uncited

Step 6. Refactor the coordinator to spawn both research subagents in parallel using multiple Task tool calls in a single response

Why: The exam tests latency awareness. Sequential spawning of independent subagents wastes time. Parallel spawning via multiple Task tool calls in a single coordinator response is the correct pattern for independent tasks.

You should see: Both the web search and document analysis subagents invoked simultaneously via parallel Task tool calls, with the coordinator waiting for both to complete before proceeding to synthesis.

const result = query({
  prompt: "Research the topic. Invoke the web-search and doc-analysis subagents in parallel — emit both Agent tool calls in a single response — then pass their complete structured findings to the synthesis subagent.",
  options: {
    allowedTools: ["Agent"],
    agents: { "web-search": webSearchAgent, "doc-analysis": docAnalysisAgent, "synthesis": synthesisAgent }
  }
});

for await (const message of result) {
  // Both Agent tool_use blocks arrive in one assistant message;
  // the SDK executes the two subagents concurrently
}

async for message in query(
    prompt=(
        "Research the topic. Invoke the web-search and doc-analysis subagents in "
        "parallel — emit both Agent tool calls in a single response — then pass "
        "their complete structured findings to the synthesis subagent."
    ),
    options=ClaudeAgentOptions(
        allowed_tools=["Agent"],
        agents={
            "web-search": web_search_agent,
            "doc-analysis": doc_analysis_agent,
            "synthesis": synthesis_agent,
        },
    ),
):
    # Both Agent tool_use blocks arrive in one assistant message;
    # the SDK executes the two subagents concurrently
    ...

Appendix B — Interactive Study Prompts

Two prompts to paste into Claude. B1 drills the judgement the exam actually measures; B3 reviews the code you wrote for the Build Exercise above. The exam simulator between them is the interactive quiz on this page.

B1. Concept Check — Discrimination Drill

B2. Exam Simulator

B3. Build Coach — Code Review

The Build Exercise and its hint ladder are already on this page. This prompt is for the one thing the page cannot do: review the code you actually wrote.