Configure subagent invocation, context passing, and spawning

Subagents are spawned through the built-in Task tool. When the coordinator wants to delegate work, it emits a Task tool call describing the subagent to run and the prompt to give it. The Agent SDK then launches that subagent, runs its own agentic loop to completion, and returns its final output back to the coordinator as the tool result.

The hard requirement to memorize: the coordinator can only spawn subagents if "Task" is present in its allowedTools. If Task is not allowed, the coordinator has no mechanism to delegate and will try to do everything itself in a single context, which defeats the entire coordinator-subagent architecture.

In the SDK you configure this on the top-level query, and you define the available subagent types in an agents map:

const result = query({
  prompt: 'Research the impact of AI on creative industries',
  options: {
    allowedTools: ['Task'],            // required to spawn subagents
    agents: {
      'web-search': { /* AgentDefinition */ },
      'doc-analysis': { /* AgentDefinition */ },
      'synthesis': { /* AgentDefinition */ }
    }
  }
});

In Claude Code the same subagents can also be declared as Markdown files in .claude/agents/ with YAML frontmatter (name, description, tools, model) plus a system-prompt body. Either way, the coordinator still needs Task in its allowed tools to invoke them.

This is the single most tested idea in this task statement. A subagent runs in its own isolated context window. It does not inherit the coordinator's conversation history, it cannot see what other subagents produced, and it shares no memory between separate invocations. Each Task call is effectively a fresh conversation seeded only by the prompt you hand it.

The practical consequence: if a piece of information is not written into the subagent's prompt, the subagent simply cannot access it. A synthesis subagent will not magically know the web search results or the document analysis output unless the coordinator copies those findings into the synthesis prompt. There is no ambient shared state.

This is intentional and beneficial. Isolation keeps each subagent's context lean and focused, avoids attention dilution from irrelevant history, and lets subagents run in parallel without interfering with one another. But it shifts responsibility onto the coordinator to be explicit and complete about what it passes down.

Each subagent type is configured with an AgentDefinition. The three fields you must know are the description, the system prompt, and the tools restriction (an optional model can also be set to trade cost for capability).

The description behaves like a tool description: it is what the coordinator reads when deciding which subagent fits the current need, so it should clearly state the subagent's purpose and when to use it. The prompt is the subagent's system prompt, establishing its role, behavior, and output expectations. The tools field scopes what the subagent may call, which prevents cross-specialization misuse (for example, a synthesis agent should not be able to run web searches).

agents: {
  'web-search': {
    description: 'Finds and extracts web sources. Use for locating articles, data, and current information.',
    prompt: 'You are a web research specialist. Return each finding as a claim with its source URL and publication date.',
    tools: ['WebSearch', 'WebFetch'],
    model: 'sonnet'
  }
}

Good descriptions and tight tool lists are how you get the coordinator to route work to the right subagent and how you keep each subagent reliable within its lane.

Because subagents inherit nothing, the coordinator must include the complete findings from prior agents directly in the next subagent's prompt. For the synthesis subagent, that means embedding the actual web search results and document analysis outputs, not a reference to them and not a vague summary that drops the numbers.

Critically, pass this context in a structured format that separates content from metadata. Every claim should travel with its provenance (source URL, document name, page number, publication date) so attribution survives the handoff. If you flatten findings into one prose blob, the synthesis agent loses the ability to cite sources and may misattribute or fabricate references.

{
  "claim": "Generative music tools cut demo production time by roughly 60%",
  "source_url": "https://example.com/music-ai-report",
  "document": "Sound and Tech Annual 2025",
  "page": 14,
  "published": "2025-03-01"
}

Keeping claim, source, and date in discrete fields (rather than merged into a sentence) is what lets a downstream agent preserve citations, distinguish well-supported claims from weak ones, and treat differing dates as temporal context rather than contradictions.

To run subagents in parallel, the coordinator emits multiple Task tool calls in a single assistant response. The SDK runs those spawned subagents concurrently and returns all their results together. This is the correct way to fan out independent work such as searching several source types at once.

If instead the coordinator emits one Task call per turn (spawn, wait for the result, then spawn the next in the following turn), those subagents run sequentially, one after another. That is the right shape only when a later subagent genuinely depends on an earlier one's output (for example, synthesis must wait for search and analysis to finish).

The exam framing is precise: parallelism comes from batching multiple Task calls in one response, not from any special flag or configuration. When independent subagents are forced across separate turns, you pay avoidable latency. When dependent steps are wrongly parallelized, you get incomplete inputs. Match the emission pattern to the actual dependency graph.

Design coordinator prompts (and the delegated subagent prompts) to specify research goals and quality criteria rather than step-by-step procedural instructions. Tell the subagent what a good result looks like and what to cover, not a rigid script of exact actions to take in order.

Goal-oriented delegation lets each subagent adapt its approach to what it actually discovers, which is the whole point of using an autonomous agent. Overly procedural prompts constrain the subagent to a fixed path and prevent it from adjusting when the material differs from what you anticipated. This mirrors the broader agentic principle: describe the destination and the standards, and let the model reason about the route.

For example, instruct a research subagent to "produce a well-sourced overview of AI's effect on music production, with at least three independent sources and publication dates for every statistic" rather than "first call WebSearch with query X, then fetch the top result, then extract paragraph two."

Session forking lets you explore divergent approaches from a shared analysis baseline. After a coordinator or agent has done expensive upfront work (say, mapping a codebase or gathering research), you can fork the session so each branch inherits that baseline but then diverges independently, without contaminating the original or each other.

In the SDK this is forkSession (also referred to as fork_session): when resuming a session, setting it creates a new branched session id that starts from the resumed state, leaving the original session untouched. That is different from a plain resume, which continues the same session in place.

query({
  prompt: 'Now refactor using strategy A',
  options: { resume: baselineSessionId, forkSession: true }
});

The canonical use is comparing two strategies from one baseline, for example forking a shared code-analysis session into one branch that tries an incremental refactor and another that tries a full rewrite, then comparing the outcomes. Session forking is covered more deeply under task 1.7; here the key point is that it is the mechanism for divergent exploration off a common starting context.