Configure subagent invocation, context passing, and spawning

This statement is the mechanical half of 1.2: how a coordinator actually spawns and feeds subagents in the Claude Agent SDK.

The Task tool and allowedTools

Subagents are spawned with the Task tool. A coordinator that cannot see it cannot delegate, no matter how good its prompt is — so allowedTools on the coordinator must include the spawning tool. This is a favorite exam detail: a stem describes a coordinator that "keeps doing the work itself instead of delegating", and the correct answer is the missing allowedTools entry, not a prompt rewrite.

Task is the guide's spelling and the one to answer with. In the shipping SDK the tool was renamed to Agent (Claude Code v2.1.63) — current releases emit "Agent" in tool_use blocks while still reporting "Task" in the system:init tool list, which is why real detection code matches both.⁶ So on the exam: the missing-Task option is the credited one. In your own code: list "Agent", or the coordinator you build from this page will reproduce the exact bug this page teaches you to diagnose.

AgentDefinition

Each subagent type is declared as an AgentDefinition with three parts:⁷

Part	What it holds	Why it carries weight
description	How the coordinator recognizes when this subagent applies	It is doing selection work — write it as a routing signal, not a label
System prompt	The subagent's role, output contract and quality bar	None of the coordinator's reasoning is inherited, so this is the only place the role is stated
Tool restrictions	Least privilege for that role	A synthesis agent that cannot search cannot wander off and start researching

Context must be explicit

Because subagents have isolated context, complete findings from prior agents must be included directly in the subagent's prompt. If the synthesis subagent needs the web-search results and the document-analysis output, the coordinator pastes them in. There is no ambient state and no shared scratchpad by default, and nothing carries between two invocations of the same subagent type unless you deliberately arrange it. Two mechanisms in the shipping SDK do arrange it — resuming a subagent by its agentId, which restores its full history, and the memory field, which gives it a persistent notes directory of its own — but neither is what the guide means by context passing, and neither removes the requirement to put the other agents' findings in the prompt.⁶

That makes the format of passed context load-bearing. Use structured data that separates content from metadata — source URL, document name, page number, retrieval timestamp — as distinct fields rather than prose. Attribution survives the handoff, and the synthesis agent can cite precisely instead of guessing which claim came from which source.

Parallelism and prompt style

To run subagents concurrently, the coordinator must emit multiple Task tool calls in a single response.⁸ Spreading them across separate turns serializes them and multiplies latency — and repeatedly signals to the model that one-at-a-time is the expected shape.

Finally, coordinator prompts should specify research goals and quality criteria, not step-by-step procedures. Procedural scripts freeze the plan at design time and remove exactly the adaptability you spawned subagents to get. Say "every claim must carry a source URL and no sector may be unaddressed"; do not say "first call search with these five queries".

Fork-based context passing

Everything above passes context forward by writing it into a prompt. Fork-based session management is the complementary mechanism: rather than re-serializing a baseline into each new unit's prompt, fork_session branches from a session that already holds it, so every branch starts from the identical shared analysis baseline.⁹ It is the one case where a divergent exploration does not need its context pasted in — it inherits it by construction.

That makes it the right choice when the baseline is expensive and the branches genuinely start from the same place: map a codebase once, then explore two approaches from it. It is the wrong choice when the branches need different slices of context, which is ordinary prompt-level context passing. (1.7 covers the operational decision between resuming, forking and restarting.)

const agents: Record<string, AgentDefinition> = {
  'web-search': {
    description:
      'Finds current public sources for ONE assigned subtopic. Use when the query needs recent or external information.',
    prompt:
      'You research a single assigned subtopic. Return JSON only: ' +
      '{ findings: [{ claim, sourceUrl, sourceTitle, retrievedAt }] }. ' +
      'Do not synthesize across subtopics; that is another agent\'s job.',
    tools: ['WebSearch', 'WebFetch'],
  },
  'document-analysis': {
    description:
      'Extracts claims from supplied documents. Use when the coordinator has PDFs or files rather than web sources.',
    prompt:
      'Analyze only the documents provided. Return JSON: ' +
      '{ findings: [{ claim, documentName, pageNumber }] }.',
    tools: ['Read', 'Grep'],
  },
  synthesis: {
    description:
      'Combines findings supplied in the prompt into a cited narrative. Never gathers new information.',
    prompt:
      'You synthesize ONLY the findings given to you. Cite every claim with the ' +
      'sourceUrl or documentName/pageNumber attached to it. Flag contradictions explicitly.',
    tools: [], // least privilege: cannot search, cannot wander
  },
};

const coordinatorOptions = {
  agents,
  // Without the spawning tool the coordinator cannot spawn ANY subagent.
  // "Task" is the guide's spelling; the shipping SDK renamed it to "Agent"
  // in Claude Code v2.1.63, so real code lists "Agent" here.
  allowedTools: ['Task', 'Read', 'Write'],
  systemPrompt: coordinatorSystemPrompt,
};

// Coordinator builds the synthesis prompt from prior agents' raw outputs.
const synthesisPrompt = [
  'Synthesize the findings below into a report on: ' + topic,
  '',
  'Quality criteria: every claim cites its source; no sector unaddressed;',
  'contradictions between sources are surfaced, not averaged.',
  '',
  'FINDINGS (JSON — content and metadata are separate fields):',
  JSON.stringify(
    {
      webFindings: webSearchResult.findings,   // { claim, sourceUrl, sourceTitle, retrievedAt }
      docFindings: docAnalysisResult.findings, // { claim, documentName, pageNumber }
      sectorsAssigned: enumeratedSectors,
    },
    null,
    2,
  ),
].join('\n');

// Spawn synthesis via the Task tool with the FULL context inline —
// it inherits nothing from this conversation.

## Delegation

When two or more subtasks are independent (different files, different modules,
different source types), emit ALL of their Task calls in the SAME response so
they execute in parallel. Only serialize when a subtask genuinely needs a
previous subtask's result as input.

Each Task prompt must be self-contained: the subagent inherits none of this
conversation. Include the goal, the exact scope assigned to it, the output
format, and any findings from earlier agents it needs to do its job.