Pass the context each specialist needs

Learning objective

Provide complete required task instructions and prior findings in subagent prompts; do not assume the parent’s history or memory is inherited.

Core idea

For an architect designing handoffs, the relevant question is what the receiving specialist actually gets. A non-fork subagent starts with its own system prompt and the Agent tool’s task prompt, not the parent’s conversation history, tool results, or system prompt. A coordinator that says “finish the comparison using our findings” can therefore omit the exact evidence the specialist needs.

Context isolation keeps intermediate work out of the main conversation, but it creates an explicit input responsibility. Put required instructions, prior findings, decisions, and unresolved questions in the delegation prompt. A specialist’s reusable role from 1.3.1 cannot supply this request’s missing evidence.

How it works

Build an assignment that stands alone

The Agent tool’s prompt carries the parent-to-subagent task input. It is distinct from AgentDefinition.prompt, which defines the specialist’s system prompt. The invocation should describe the requested decision, the relevant scope, the evidence already gathered, and the output criteria. Include concrete paths, error messages, and prior decisions where the work depends on them.

A synthesis specialist needs the earlier agents’ actual findings, not merely the fact that those agents finished. If a researcher found a retention clause and a second reviewer found an exception, pass both passages and their locations. “The researcher approved vendor A” removes the reasoning that synthesis must evaluate. See 1.3.4 for the structured evidence format.

The following illustrates an application-authored task prompt rather than an SDK configuration object:

Use the comparison-synthesizer agent to compare the supplied policies.
Decision: select the vendor whose documented retention fits 30 days.
Scope: the two supplied policy excerpts; do not infer missing clauses.
Prior findings:
- Vendor A's supplied clause states 30 days after closure.
- Vendor B's supplied clause states 90 days after closure.
- Neither reviewer found a backup-retention clause.
Evidence: [include the excerpts and their attribution records here].
Return: comparison, evidence for each finding, and unresolved gaps.
Do not treat missing backup evidence as a promise of deletion.

The retention numbers are hypothetical scenario inputs, not Claude service limits. Replace the bracketed evidence instruction with the actual records before dispatch. A prompt template with an unfilled evidence slot is not a complete handoff.

Anthropic’s research-system guidance recommends objectives, output formats, tool and source guidance, and task boundaries. Use those to make the assignment complete while allowing the specialist to choose an effective investigation strategy. Copying every parent turn adds volume without necessarily preserving the decisive inputs.

Distinguish supplied content from retrievable content

Passing a path tells the subagent where evidence can be read; it does not place the file’s contents in its prompt. A path-only assignment requires the file to exist in the execution environment and the specialist to have a suitable tool such as Read. If the specialist needs to synthesize a result without reopening documents, include the supporting content directly.

Anthropic’s research account also describes storing outputs as artifacts and returning lightweight references to avoid information loss and repeated copying. Use that pattern when the receiving agent can retrieve the artifact. For a concise synthesis handoff, include the decisive excerpts directly and identify the fuller artifact for additional investigation. A reference is useful only if it provides an executable retrieval path.

The SDK guide says the parent receives the subagent’s final report, while intermediate tool calls and results stay in the subagent’s conversation. Therefore, instruct a research specialist to put material needed downstream into that final report. Do not expect the coordinator to recover an unreported quote from the researcher’s private tool history automatically.

Only the task prompt crosses into a non-fork subagent, and only its final report crosses back.

Account for inheritance exceptions explicitly

A Claude Code fork inherits the parent’s conversation, system prompt, tools, and model at spawn time. That differs from a definition-based non-fork specialist. Fork mode is off by default in the Agent SDK and non-interactive Claude Code with -p; set CLAUDE_CODE_FORK_SUBAGENT=1 to enable it. Interactive Claude Code enables fork mode by default on v2.1.232 or later. See 1.3.7 for fork-based session design; here the implication is that your context assumption must identify both the enabled mode and the kind of invocation.

Resumption also differs from launching another agent with the same name. The SDK guide states that a resumed subagent retains its own conversation history. To continue it across query() calls, preserve the main session_id, use the top-level resume option, and include the prior agentId in the follow-up prompt. Each query() starts a separate session by default. See 1.2.4 for using resumption to repair a synthesis gap.

Persistent memory is another explicit configuration. Claude Code’s subagent memory field accepts user, project, or local scopes and supplies a persistent memory directory. It is not an automatic copy of the parent’s conversation. The documented locations are ~/.claude/agent-memory/<name-of-agent>/, .claude/agent-memory/<name-of-agent>/, and .claude/agent-memory-local/<name-of-agent>/, respectively. Disabling auto memory through autoMemoryEnabled or CLAUDE_CODE_DISABLE_AUTO_MEMORY makes the field ineffective.

Project instructions can also load through CLAUDE.md; they are distinct from the parent’s conversational findings. The SDK inheritance table describes project CLAUDE.md loading through settingSources. TypeScript Agent SDK v0.3.271 or later supports AgentDefinition.omitClaudeMd to omit user, project, and local CLAUDE.md files while retaining managed policy files; Python’s AgentDefinition lacks this field. Neither loaded instructions nor persistent memory establish that this request’s evidence is present. Keep the required task inputs explicit even when those supporting mechanisms are enabled.

Key distinctions and trade-offs

Complete context versus complete transcript: Completeness means supplying everything needed for this task. It does not require copying irrelevant exploratory turns. Preserve the question, decisive evidence, constraints, and open gaps.

Fresh invocation versus resumption: Reusing an agent definition gives the next invocation the same role. Resuming the particular agent gives it its own prior history. A repeated name is not a transcript identifier.

Evidence content versus an evidence address: A supplied passage is available for immediate reasoning. A URL or file path requires retrieval. Choose based on the receiving agent’s tools and the amount of content it needs, rather than treating both as equivalent context.

Passing full findings costs more prompt space than passing a conclusion, but supports review and synthesis. Artifact references reduce copying while adding a retrieval dependency. Decide which content must arrive directly before choosing the shorter handoff.

Architecture / decision scenario

A multi-agent research coordinator has web-search findings from one agent and document-analysis findings from another. It launches a non-fork synthesis specialist with “Use both agents’ results to recommend a vendor.” The synthesis role is well defined, but the task prompt includes neither result. The parent knows the evidence; the specialist does not.

You replace that assignment with the exact comparison question, the relevant findings from each researcher, supporting excerpts, attribution records, and the unresolved backup-retention gap. You ask the specialist to compare the policies against the same requirement and return an explicitly qualified conclusion. The evidence enters through the Agent tool’s prompt, not by presumed shared history.

One report is too large to embed. You include its decisive passages directly and provide a file path to the complete artifact. Because the specialist has Read and the file exists in its environment, the path supports further inspection. You do not substitute a path to a file available only in another worker’s environment.

For a follow-up, you choose either to pass the findings again to a fresh specialist or deliberately resume the identified prior agent in its session. You do not use “same specialist name” as a substitute for that choice. The resulting recommendation can be reviewed against evidence actually supplied or retrieved.

Common exam traps

• Assuming a non-fork subagent inherits the parent’s conversation or tool results.
• Confusing AgentDefinition.prompt with the Agent tool’s task prompt.
• Passing a conclusion while omitting the findings needed to evaluate it.
• Treating a source path as already-read source content.
• Assuming another invocation with the same name resumes prior history.
• Generalizing the fresh-context rule to forks and configured persistent memory.

Where the exam guide differs

What to remember

Construct non-fork assignments as self-contained inputs. Include required instructions and prior findings, and make artifact retrieval possible when you pass references. Forking, resumption, and persistent memory have explicit semantics; none makes missing task evidence safe to assume.

Knowledge check

References

• Anthropic, Subagents in the SDK
• Anthropic, Create custom subagents
• Anthropic, How we built our multi-agent research system
• Anthropic, Claude Certified Architect – Foundations Exam Guide