Subagent Invocation, Context Passing & Spawning

Spawning a subagent is like handing a brief to a contractor who has never seen your project: they get only what you write in the brief. No shared inbox, no shared memory."

A coordinator delegates by calling the Task tool (also used as Agent in Anthropic's Managed Agents docs). Subagent context is never auto-inherited - every fact the subagent needs must be written into the prompt the coordinator sends. D1.2 owns orchestration strategy (when to fan out, how to synthesize); this file owns the mechanics of invocation, configuration, and context passing.

1. What Task 1.3 is testing

Task 1.3 is the "plumbing" companion to D1.2's "architecture" questions. Where D1.2 asks should I use multi-agent?, 1.3 asks how do I actually wire the spawn, the config, and the data handoff so the subagent succeeds?

The official bullets, grouped:

Area	Bullet
Spawning mechanism	The `Task` tool spawns subagents; coordinator's `allowedTools` must include `"Task"` (Managed Agents docs: `"Agent"`)
Context isolation	Subagent context must be explicitly provided in the prompt — no auto-inheritance of history, system prompt, prior messages, other subagents' results, or shared memory
Configuration	`AgentDefinition`: `description` (drives selection), system prompt, per-subagent tool restrictions
Forking	Fork-based session management for divergent exploration from a shared baseline (cross-ref D1.7)
Passing findings	Include complete prior-agent findings directly in the subagent's prompt
Attribution	Structured data formats to separate content from metadata (URLs, doc names, page numbers)
Parallelism	Spawn parallel subagents via multiple `Task` calls in one coordinator response
Prompt style	Specify goals + quality criteria, not step-by-step procedures

2. The `Task` tool — the spawning mechanism

A coordinator does not "create" a subagent through some side channel. It calls a tool, exactly like calling get_weather or search. That tool is the Task tool. The subagent runs its own agentic loop and returns a result that arrives back in the coordinator's context as a tool_result.

Task is just a tool. If it is not in allowedTools, the coordinator literally cannot delegate. The capability does not exist for that agent.

Coordinator agentic loop
   │
   ├── emits tool_use: Task(subagent="web_search", prompt="...")
   │        │
   │        └── subagent runs its OWN loop → returns final text
   │
   └── tool_result(Task) appended to coordinator context → coordinator reasons on

2.1 Naming: `Task` vs `Agent`

The exam may use either term — they refer to the same delegation mechanism:

Surface	Tool name	Where seen
Claude Code / Agent SDK framing	`Task`	`allowedTools` includes `"Task"`
Managed Agents docs	`Agent`	coordinator's `allowedTools`/toolset includes `"Agent"`

Exam trap: A coordinator that "can't seem to delegate" or "ignores its subagents" most often has Task/Agent missing from allowedTools. Adding more subagent definitions does nothing if the coordinator lacks the tool to invoke them.

# Coordinator must be granted the delegation tool
coordinator = AgentDefinition(
    description="Researcher: decomposes queries and delegates to specialists.",
    prompt="You are a researcher. Delegate to specialists and synthesize.",
    tools=["Task"],      
)

3. Context is NOT inherited — the central rule

A subagent starts effectively blank. Spawning it does not carry over anything from the coordinator. The exam tests this from many angles, so memorize the full list of what is not shared.

Does the subagent automatically get…?	No — unless passed in the prompt
The coordinator's conversation history	❌
The coordinator's system prompt	❌
Prior messages / earlier turns	❌
Results from other subagents	❌
Shared memory / global state	❌
Its own prior invocations (call #1 → call #2)	❌

If a subagent needs to know it, the coordinator must write it into the prompt. The prompt is the only channel.

3.1 Why this is the right design

Isolation is a feature: it keeps each subagent's context lean and high-signal. The cost is that the coordinator becomes responsible for explicitly packaging every relevant fact.

Trap - misdiagnosing incomplete subagent output. When a subagent returns something thin or off-target, the first diagnostic question is "did the coordinator pass enough context?" — not "is the subagent broken?" The default exam answer for an under-informed subagent is fix the context passing, not retrain/replace the subagent.

# WRONG — assumes the subagent "remembers" the earlier search agent's output
Task(subagent="synthesis", prompt="Now synthesize the findings.")

# RIGHT — the coordinator hands over the actual findings
Task(subagent="synthesis", prompt=f"""
Synthesize a cited answer to: "{question}".
Findings from prior agents are below. Use ONLY these.
{search_findings_json}
{doc_analysis_findings_json}
""")

3.2 Repeated invocations are independent too

If the coordinator calls the same web_search subagent twice, the second call knows nothing about the first. To build on prior work, the coordinator must re-inject the relevant earlier output into the second prompt. (Managed Agents threads retain history within one persistent subagent thread — see D1.2 §5 — but a fresh Task spawn does not.)

4. AgentDefinition configuration

Each subagent type is declared by an AgentDefinition. Three fields matter for 1.3:

Field	Purpose	Exam emphasis
`description`	What the subagent is for	Drives coordinator selection — the coordinator reads descriptions to decide which subagent fits a subtask
System prompt (`prompt`)	Defines the subagent's role/behavior	The subagent's only standing instructions (it does NOT inherit the coordinator's system prompt)
Tool restrictions (`tools`)	Scopes capabilities per role	Least privilege per agent (see D1.2 §12)

web_search = 
    AgentDefinition(
        description="Searches the public web; returns sources with URLs, titles"
                "Use for current events and external evidence. NOT for internal",  
        prompt="You are a web research specialist. Return structured findings: "
               "each claim with its source URL, title, and publication date.",
        tools=["web_search", "web_fetch"],     # scoped to its role
    )

synthesis = 
    AgentDefinition(
        description="Combines findings from other agents into a cited answer. "
                "Does NOT search or fetch — operates only on provided findings.",
        prompt="You are a synthesis specialist. Reconcile and cite the findings you are given. "
           "Preserve every source attribution.",
        tools=[],                              # no search tools → cannot misuse them
)

4.1 `description` is the selection mechanism

The coordinator picks subagents by reading their description fields, the same way an LLM picks a tool by reading its description.

A vague description ("analyzes things") causes misrouting; a precise one with "use this when… / not for…" boundaries routes reliably.

Exam trap:

If the coordinator keeps sending work to the wrong specialist, the fix is usually sharpen the description (and tool scoping), not add a routing classifier or hard-code the pipeline.

4.2 Tool restrictions enforce specialization

Giving a synthesis agent web-search tools invites it to "just search instead of synthesizing." Restricting tools=[] makes the role boundary structural, not advisory. This is the per-agent application of least privilege from D1.2 §12.

5. Fork-based session management

Forking creates independent branches from a shared analysis baseline so multiple divergent approaches can be explored without re-doing the shared groundwork.

Shared baseline (e.g. completed codebase analysis)
        │
   fork_session ─┬─→ Branch A: try testing strategy X
                 ├─→ Branch B: try testing strategy Y
                 └─→ Branch C: try refactor approach Z
        │
   Compare branch outcomes; pick the winner

Concept	Meaning
`fork_session`	Creates an independent branch from a shared session/analysis state
Use case	Compare divergent approaches (two testing strategies, two refactors) that share one expensive analysis
Benefit	Each branch reasons from the same baseline; branches don't pollute each other

5.1 Forking vs spawning a fresh subagent:

	Fresh `Task` spawn	`fork_session`
Starting context	Blank (only the prompt)	Inherits the shared baseline at the fork point
Best for	New, independent subtask	Divergent exploration from common groundwork

Exam trap:

Forking is not the same as parallel fan-out. Fan-out splits different subtasks; forking explores alternative approaches to the same subtask from a shared baseline. And forking is not --resume (continuing one named session) — see D1.7.

6. Passing complete findings into the subagent prompt

The coordinator must put complete prior findings directly in the subagent's prompt. The classic case is the research pipeline: the web-search agent and document-analysis agent each return findings, and the coordinator must hand both sets to the synthesis agent verbatim — synthesis cannot fetch them itself.

# Coordinator aggregates upstream outputs, then injects them whole
synthesis_prompt = f"""
GOAL: Produce a cited answer to "{question}". Coverage target: all major subtopics.

WEB SEARCH FINDINGS:
{web_findings}

DOCUMENT ANALYSIS FINDINGS:
{doc_findings}

Use ONLY the findings above. Cite every claim to its source. Flag any subtopic
with no supporting evidence as a coverage gap.
"""
Task(subagent="synthesis", prompt=synthesis_prompt)

Exam trap:

"Have the synthesis agent re-run the searches itself to get the data" is wrong — it duplicates work, violates separation of concerns (D2.3), and discards the upstream agents' results. The coordinator carries the findings forward.

7. Structured data to preserve attribution

When passing findings between agents, separate content from metadata using a structured format. Metadata = source URLs, document names, page numbers, publication dates. If findings are flattened into prose, attribution is lost during synthesis (cross-ref D5.6 on provenance).

{
  "claim": "Global solar capacity grew 24% in 2024.",
  "evidence_excerpt": "...added 24% year-over-year...",
  "source": {
    "type": "web",
    "url": "https://example.org/solar-2024",
    "title": "Solar Capacity Report 2024",
    "published": "2025-01-15"
  }
}

{
  "claim": "The methodology used a 5-year historical window.",
  "evidence_excerpt": "We model on 2019–2023 data.",
  "source": {
    "type": "document",
    "doc_name": "DCF_Model_Methodology.pdf",
    "page": 7
  }
}

Why structured	Effect
Content separated from metadata	Synthesis agent can quote the claim and keep the citation
Survives the handoff	Attribution isn't compressed away (D5.6)
Enables conflict annotation	Conflicting stats keep their distinct sources (D5.6)

The synthesis agent can only cite what arrives structured. Prose-only findings arrive citation-free.

8. Parallel spawning: multiple `Task` calls in ONE response

To run subagents in parallel, the coordinator emits multiple Task tool calls in a single response — the same way parallel tool use works. Spreading the calls across separate turns serializes them.

ONE coordinator response:
   tool_use: Task(subagent="search", prompt="subtopic: solar")
   tool_use: Task(subagent="search", prompt="subtopic: wind")
   tool_use: Task(subagent="search", prompt="subtopic: geothermal")
        ↓ all three run concurrently; results return together

Pattern	Result
Multiple `Task` calls in one assistant response	Parallel execution (correct for independent subtasks)
One `Task` call per turn, across turns	Serial execution (slower; only needed for dependent steps)

Exam trap: "Emit one Task call, wait for the result, then emit the next" is the serial anti-pattern when the subtasks are independent. Parallelism requires batching the calls into a single response. (Dependent subtasks — schema-then-API — do belong in sequence; see D1.2 §6 on what is parallelizable.)

9. Coordinator prompts: goals + criteria, not procedures

Write coordinator (and delegation) prompts that specify research goals and quality criteria, not step-by-step procedural instructions. Over-prescription removes the subagent's ability to adapt to what it discovers.

Procedural (weaker)	Goal + criteria (stronger)
"Run query X, then query Y, then summarize the top 3 hits."	"Find authoritative, recent evidence on . Cover all major subtopics. Prefer primary sources; flag gaps."
"Call search exactly twice."	"Search until coverage is sufficient across the listed subtopics."

GOAL: Comprehensively research "impact of AI on creative industries."
QUALITY CRITERIA:
  - Cover music, writing, film, AND visual arts (not just one).
  - Every claim cited to a source with a date.
  - Note any subtopic lacking strong evidence as a gap.
DECOMPOSITION: You decide the subtopics and how many search agents to spawn.

State the destination and the bar for "good." Let the subagent choose the route. Procedural micromanagement caps quality at whatever the author anticipated.

This pairs with D1.2's narrow-decomposition trap: a goal that names the full scope ("music, writing, film, AND visual arts") guards against the coordinator under-decomposing.

10. Decision / heuristics table

Situation	Do this
Coordinator can't delegate at all	Add `"Task"` (or `"Agent"`) to `allowedTools`
Subagent output is thin / off-target	First suspect: coordinator didn't pass enough context
Coordinator routes work to wrong specialist	Sharpen each `AgentDefinition.description`; scope tools
Synthesis agent needs prior findings	Inject complete findings into its prompt (don't make it re-fetch)
Need attribution to survive synthesis	Pass findings as structured content + metadata
Independent subtasks, want speed	Emit multiple `Task` calls in ONE response (parallel)
Dependent subtasks (A feeds B)	Sequence the `Task` calls across turns
Explore divergent approaches from shared analysis	`fork_session` from the baseline (D1.7)
Subagent over-using a tool outside its role	Remove that tool from its `AgentDefinition.tools`
Want adaptive, high-quality subagent work	Prompt with goals + criteria, not procedures

11. Common exam anti-patterns

Anti-pattern	Why it's wrong	Better
Assuming subagents inherit coordinator history	No auto-inheritance — prompt is the only channel	Explicitly pass needed context
Coordinator missing `Task`/`Agent` in `allowedTools`	Delegation capability literally absent	Grant the delegation tool
Blaming the subagent for thin output	Usually a context-passing failure	Audit what the coordinator sent
Making synthesis re-run searches	Duplicates work; discards upstream results	Carry findings forward in the prompt
Passing findings as flat prose	Source URLs/pages/dates lost	Structured content + metadata
One `Task` per turn for independent work	Serializes parallelizable work	Batch `Task` calls in one response
Vague `AgentDefinition.description`	Coordinator misroutes	Precise "use when / not for" descriptions
Giving every subagent every tool	Cross-specialization misuse (D2.3)	Scope `tools` per role
Step-by-step procedural delegation prompts	Caps adaptability and quality	Goals + quality criteria
Confusing `fork_session` with fan-out or `--resume`	Different mechanisms	Fork = divergent branches from shared baseline (D1.7)

12. Scenario-Based Questions

Q1. Coordinator can't delegate

A coordinator agent is supposed to call specialized subagents but the logs show it never invokes any of them and instead tries to do everything itself. What is the most likely cause?

A. The subagents have weak system prompts B. The coordinator's allowedTools does not include Task (or Agent) C. The subagents are missing fork_session D. The coordinator's max_tokens is too low

Answer

B. Spawning happens through the Task/Agent tool. If it isn't in allowedTools, the coordinator has no mechanism to delegate and falls back to doing the work itself.

Q2. The naming question

Anthropic's Managed Agents docs and the Agent SDK framing sometimes use different names for the delegation tool. Which pair refers to the same mechanism?

A. Task and fork_session B. Agent and Resume C. Task and Agent D. Delegate and Spawn

Answer

C. The spawning tool is Task in the Agent SDK framing and Agent in the Managed Agents docs — the same delegation capability under two names.

Q3. Thin subagent output

A synthesis subagent returns a vague, uncited answer. Before changing anything else, what is the first thing to check?

A. Whether the synthesis agent's model is large enough B. Whether the coordinator passed the prior agents' findings into the synthesis prompt C. Whether fork_session was enabled D. Whether the synthesis agent has web-search tools

Answer

B. Subagents inherit no context automatically. Thin output usually means the coordinator didn't package the findings into the prompt — the synthesis agent had nothing to synthesize.

Q4. What's NOT inherited

A coordinator spawns a subagent. Which of the following does the subagent receive automatically?

A. The coordinator's full conversation history B. The coordinator's system prompt C. Results from previously run subagents D. None of the above — only what is written into its prompt

Answer

D. Subagents do not inherit history, system prompt, prior messages, other subagents' results, or shared memory. The prompt is the sole channel.

Q5. Routing to the wrong specialist

The coordinator keeps sending document-analysis work to the web-search subagent. What is the most effective first fix?

A. Add a deterministic routing classifier in front of the coordinator B. Hard-code the full pipeline so no selection is needed C. Sharpen each subagent's AgentDefinition.description (with use/don't-use boundaries) and scope their tools D. Give both subagents all tools so it doesn't matter

Answer

C. The coordinator selects subagents by reading their description. Precise descriptions with boundaries — plus tool scoping — fix misrouting without over-engineering.

Q6. Parallel spawning

You want three search subagents to run concurrently. How should the coordinator invoke them?

A. Emit one Task call, wait for the result, then emit the next, across three turns B. Emit three Task tool calls in a single coordinator response C. Use fork_session three times D. Set disable_parallel_tool_use: true

Answer

B. Parallel subagents are launched by emitting multiple Task calls in one response. Spreading them across turns serializes them.

Q7. Preserving attribution

The synthesis agent's report loses all source citations. The upstream agents found good sources. What design change fixes this?

A. Tell the synthesis agent to "remember to cite" B. Pass findings as structured data separating content (claims) from metadata (URLs, doc names, pages, dates) C. Give the synthesis agent its own web-search tool D. Increase the synthesis agent's max_tokens

Answer

B. Attribution is lost when findings are flattened to prose. Structured findings carry source metadata through the handoff so the synthesis agent can cite each claim.

Q8. Fork-based exploration

A team has completed an expensive codebase analysis and now wants to compare two different refactoring approaches without redoing that analysis. What mechanism fits?

A. --resume on the analysis session B. fork_session to branch from the shared analysis baseline into two divergent explorations C. Parallel fan-out of unrelated subtasks D. A single subagent doing both refactors sequentially

Answer

B. Forking creates independent branches from a shared baseline, ideal for exploring divergent approaches that share one piece of groundwork (cross-ref D1.7).

Q9. Procedural vs goal-based prompts

Which delegation prompt produces the most adaptable, highest-quality subagent behavior?

A. "Run query A, then query B, then summarize the first three results." B. "Call the search tool exactly twice and stop." C. "Find authoritative, recent evidence covering all major subtopics; cite every claim; flag gaps. You decide the queries." D. "Do your best."

Answer

C. Coordinator prompts should specify goals and quality criteria, not step-by-step procedures, so the subagent can adapt to what it discovers. A and B over-prescribe; D under-specifies.

Q10. Re-invoking the same subagent

The coordinator calls the web_search subagent a second time and expects it to remember what it found on the first call. What actually happens?

A. The second call automatically has the first call's context B. The second call is independent and knows nothing of the first unless the coordinator re-injects that info C. The subagent shares memory across invocations by default D. The second call inherits the coordinator's full history

Answer

B. A fresh Task spawn carries no memory of prior invocations. To build on earlier work, the coordinator must pass the relevant prior output into the new prompt.

Q11. Synthesis re-running searches

To get the data it needs, an engineer proposes having the synthesis subagent run the web searches itself instead of receiving findings from the search agent. Why is this the weaker design?

A. It duplicates work, violates separation of concerns, and discards the search agent's results B. It is faster and therefore always preferred C. Synthesis agents cannot run any tools D. It automatically preserves attribution

Answer

A. The coordinator should carry the search agent's findings forward into the synthesis prompt. Making synthesis re-search duplicates effort, blurs roles (D2.3), and throws away upstream results.

Q12. Tool over-use by a specialist

A synthesis agent that should only combine findings keeps calling a web-search tool instead. What is the cleanest structural fix?

A. Add "please do not search" to the system prompt and hope it complies B. Remove the search tool from the synthesis agent's AgentDefinition.tools C. Give it more tools so it has options D. Switch it to fork_session

Answer

B. Tool restrictions in the AgentDefinition make the role boundary structural rather than advisory. Removing the tool prevents the misuse outright (least privilege per agent).

Q13. Dependent subtasks

A coding workflow must design a database schema before implementing the API that depends on it. How should the coordinator spawn these subagents?

A. Both Task calls in one response for parallelism B. Sequentially — spawn the schema task, await its result, then spawn the API task with the schema in its prompt C. Fork both from a shared baseline D. Give the API agent the Task tool so it spawns the schema agent itself

Answer

B. Parallel spawning is for independent subtasks. When B depends on A's output, sequence the calls and pass A's result into B's prompt.

Q14. Selection mechanism

On what basis does a coordinator decide which subagent to invoke for a given subtask?

A. Alphabetical order of subagent names B. The description field of each AgentDefinition C. Whichever subagent has the most tools D. A separate routing model that must always be configured

Answer

B. The coordinator reads each subagent's description to choose the right specialist — analogous to how an LLM selects a tool from its description (D2.1). Precise descriptions drive reliable routing.

Memory hooks

Task (a.k.a. Agent) is the spawn tool — it must be in allowedTools or no delegation happens.
Nothing is inherited. The prompt is the only channel into a subagent.
Thin subagent output? Suspect the coordinator's context passing first, not the subagent.
AgentDefinition = description (drives selection) + system prompt + tool restrictions.
Carry findings forward into the prompt — don't make the synthesis agent re-fetch.
Structured content + metadata = attribution survives the handoff.
Parallel = many Task calls in ONE response; serial = one per turn (only for dependencies).
fork_session = divergent branches from a shared baseline (≠ fan-out, ≠ --resume; see D1.7).
Delegation prompts: goals + quality criteria, never step-by-step procedures.
Repeated invocations of the same subagent are independent — re-inject prior output.

Subagent Invocation, Context Passing & Spawning

1. What Task 1.3 is testing

2. The Task tool — the spawning mechanism

2.1 Naming: Task vs Agent

3. Context is NOT inherited — the central rule

3.1 Why this is the right design

3.2 Repeated invocations are independent too

4. AgentDefinition configuration

4.1 description is the selection mechanism

4.2 Tool restrictions enforce specialization

5. Fork-based session management

5.1 Forking vs spawning a fresh subagent:

6. Passing complete findings into the subagent prompt

7. Structured data to preserve attribution

8. Parallel spawning: multiple Task calls in ONE response

9. Coordinator prompts: goals + criteria, not procedures

10. Decision / heuristics table

11. Common exam anti-patterns

Memory hooks

2. The `Task` tool — the spawning mechanism

2.1 Naming: `Task` vs `Agent`

4.1 `description` is the selection mechanism

8. Parallel spawning: multiple `Task` calls in ONE response