Study notes · 3.9% of the exam

1.3 Configure subagent invocation, context passing, and spawning

Configure subagents with `AgentDefinition`, enable spawning through the Task tool in `allowedTools`, pass complete structured context in the prompt, spawn in parallel with multiple Task calls in one response, and use session forks to branch from a shared baseline.

Key points

1
Subagents are spawned through the Task tool (shown as Agent in current SDK releases and in tool_use blocks; the exam guide and older versions call it Task). The coordinator's allowedTools must include it, otherwise defined agents are never invoked.
2
Define subagents programmatically with the agents option: each AgentDefinition has a description (when Claude should pick it), a prompt (its system prompt and behaviour), an optional tools list, and optional model. Filesystem definitions in .claude/agents/ are an alternative; programmatic ones take precedence on name clashes.
3
The description is what the coordinator matches tasks against, so write it as "use for ..." with concrete triggers. A one-word description produces unreliable selection; naming the agent in the prompt forces explicit invocation but removes dynamic choice.
4
Omitting tools inherits every tool available to subagents. To make an analysis agent read-only, list ["Read", "Grep", "Glob"]; a tool left out is simply absent from the subagent's session, with no prompt or error. Prompt rules like "never modify files" are not a capability boundary.
5
Subagent context must be provided explicitly. A subagent receives its own system prompt, the Task prompt string, CLAUDE.md content and its tool definitions; it does not receive the parent's conversation history, tool results or system prompt, and it does not share memory with other invocations.
6
Pass complete findings from prior agents directly in the prompt, for example the web-search results and document-analysis outputs handed to the synthesis subagent. "Synthesize the findings above" delivers nothing.
7
Use structured data formats that separate content from metadata (source URL, document name, page number, publication date) when passing context between agents, so attribution and citations survive synthesis.
8
Parallel subagents are spawned by emitting multiple Task tool calls in a single coordinator response; independent subtasks then complete in about the time of the slowest one. Spawning one per turn serialises the work regardless of concurrency limits.
9
Coordinator prompts should specify research goals and quality criteria (source count, source diversity, citation requirements) rather than step-by-step procedures, so the coordinator can judge whether findings are sufficient and adapt which subagents it invokes.
10
forkSession: true (Python fork_session=True) with resume creates a new session seeded with a copy of the original history while the original stays unchanged. Use two forks to explore divergent approaches (for example two refactoring strategies) from a shared, still-valid analysis baseline.
11
Forks branch conversation history, not the filesystem, and they are not the mechanism for parallel subagents. Sequential resumes of one session contaminate each exploration with the previous one's conclusions.
12
Cap growth with maxTurns per agent, the concurrency and spawn-depth environment variables, and maxBudgetUsd; the parent may summarise a subagent's final message, so ask for verbatim output if it must be preserved.

Read the source

Test yourself on 1.3 Configure subagent invocation, context passing, and spawning

Ten questions, with the answer and explanation after each one.