1.3 — Subagent Invocation and Context Passing

CCAR-F Domain 1 · Task 1.3

What You Need to Know

A coordinator is the agent that runs a multi-agent task and hands parts of it to subagents. Invocation is how it starts a subagent. Context passing is how it gives that subagent the information it needs.

The Task Tool

The Task tool is how a coordinator spawns subagents. It is the API mechanism that makes multi-agent orchestration work in the Claude Agent SDK.

Current state: Claude Code renamed it Agent in v2.1.63. The name Task still works as an alias.

The coordinator's allowedTools must include "Task" (or "Agent"). This is a binary gate. Without it, the coordinator cannot invoke any subagent.

Each subagent is defined by an AgentDefinition, which specifies:

1. Description: what the subagent does. The coordinator reads it to decide when to invoke.
2. System prompt: the instructions the subagent follows.
3. Tool restrictions: which tools the subagent can access, scoped to its role.

Context Passing

Subagents have isolated context. A subagent receives only what the coordinator writes into its prompt. Three rules follow:

Rule 1: Include complete findings from prior agents. A synthesis subagent cannot look up earlier results. If it needs web search results and document analysis output, the coordinator must pass both in full.

Rule 2: Use structured data that separates content from metadata. Content is the claim. Metadata says where it came from (source URL, document name, page number). When a coordinator compresses findings and drops the link between claim and source, attribution is lost.

Rule 3: Specify goals, not procedures. A coordinator prompt should tell a subagent what to achieve and which quality criteria to meet, not give step-by-step instructions.

Structured Metadata Format

{
  "findings": [
    {
      "claim": "Solar panel efficiency has increased 25% in the last decade",
      "source_url": "https://example.com/solar-report",
      "document_name": "Annual Solar Industry Report 2024",
      "page_number": 14,
      "confidence": "high",
      "retrieved_by": "web_search_agent"
    }
  ]
}

When Attribution Fails

If both research subagents return well-sourced work but the coordinator passes the content without the metadata, the synthesis subagent writes a proposal with no source attribution. Changing the synthesis prompt does not fix this. The coordinator must pass structured metadata alongside the content.

Parallel vs Sequential Spawning

When a coordinator needs several subagents for independent tasks, it should emit multiple Task tool calls in a single response. Sequential spawning means one subagent per coordinator turn and adds unnecessary latency.

Key Concept: Spawn independent subagents in parallel by emitting multiple Task tool calls in a single coordinator response.

fork_session

fork_session creates independent branches from a shared analysis baseline. After an initial analysis, a coordinator can fork the session to explore divergent approaches. After the branching point, each fork works independently.

fork_session is not the same as --resume. Resume continues a specific named session. Fork creates a new independent branch.

In the exam

Exam guide v1.0 uses the name Task tool. Answer "Task tool" even where current code shows Agent. When a synthesis agent's report has unsourced claims while the research subagents work correctly, the root cause is that the coordinator passed content without structured metadata.

Exam Traps

• Assuming subagents automatically have access to the coordinator's conversation history or other subagents' outputs
• Blaming the synthesis agent's prompt when claims lose their source citations
• Proposing sequential subagent invocation for tasks that can run independently
• Writing a subagent's prompt as an exact step-by-step procedure