Subagent Invocation & Context Passing

Spawning a subagent is not like calling a function — Claude does not automatically inherit the coordinator's context. You must explicitly provide every piece of information the subagent needs. This lesson covers how to invoke subagents, structure their prompts, and run them in parallel.

The Task Tool

The Task tool spawns subagents. The coordinator's allowedTools array must include "Task" — without it, the coordinator cannot delegate. AgentDefinition objects configure each subagent's description, system prompt, and tools array. Tool restrictions matter here: a research subagent should not have access to mutating tools like process_refund.

Explicit Context Passing

The single most common subagent failure is omitting context. Subagents inherit nothing — not the user's question, not prior subagent findings, not the conversation history. Every relevant fact must appear in the subagent's prompt. Use structured formats to pass complex context:

Research goal: [exact user question]
Prior findings:
  - [Subagent A's key claim, with source URL]
  - [Subagent B's caveat about temporal data]
Quality criteria:
  - Cite at least 3 sources
  - Distinguish established findings from contested ones
  - Note publication dates for time-sensitive claims

Parallel Spawning Saves Wall-Clock Time

If three subagents have independent subtasks, spawning them sequentially across three coordinator turns triples the latency. Instead, the coordinator should emit multiple Task tool calls in a single response. The agent SDK runs them in parallel and returns all results before the coordinator's next turn.

Structured Output From Subagents

When subagents return findings, require structured formats: source URL, document name, relevant excerpt, publication date. This makes it possible for the coordinator to do real synthesis (resolving conflicts, attributing claims) rather than just concatenating text.

Skills to Develop

1. Write subagent prompts that include goals and quality criteria — not procedural steps. Let the subagent figure out the "how".
2. Pass complete prior findings explicitly when one subagent depends on another's output.
3. Spawn parallel subagents in a single coordinator response when subtasks are independent.
4. Restrict each subagent's allowedTools to its role — a research subagent doesn't need write access.