Subagent Invocation and Context Passing

A subagent is a separate Claude conversation started by a parent agent to do a bounded piece of work. It has its own context window, its own system prompt and tool set, and it returns a single report when it finishes. Architects use subagents to keep the parent's context clean, to run independent work in parallel, and to apply specialised instructions or a cheaper model to subtasks. The exam tests whether you understand what crosses the boundary and what does not.

What a subagent inherits

Almost nothing, by design. A subagent starts with:

• the prompt the parent writes when invoking it;
• its own definition (system prompt, allowed tools, model);
• access to the same filesystem and MCP servers the parent is permitted to use, unless restricted.

It does not see the parent's conversation history, the parent's earlier tool results, or the user's original message unless the parent repeats them. When the subagent finishes, the parent receives only the final text report, not the subagent's transcript. This is what makes delegation cheap for the parent's context and also what makes a vague brief fail: the subagent cannot ask the parent what it meant.

Defining subagents in Claude Code

Claude Code stores subagent definitions as Markdown files with frontmatter in .claude/agents/ (project scope) or ~/.claude/agents/ (user scope). Project definitions take precedence when names collide.

---
name: security-reviewer
description: Reviews a diff for security issues. Use proactively after code changes touching auth or input handling.
tools: Read, Grep, Glob, Bash
model: sonnet
---
You are a security reviewer. Report findings as a numbered list with file paths and line numbers. Do not edit files.

The description field matters more than it looks: the parent model reads it to decide when to delegate automatically. Phrases such as "use proactively" influence that choice. tools restricts what the subagent can call; omitting it inherits the parent's tools. model lets a routine subtask run on a smaller model while the parent stays on a more capable one.

In the Agent SDK the same definitions are passed programmatically through the agents option, each with description, prompt, optional tools and model.

Passing context deliberately

Because the brief is the only lever, write it like a hand-off to a colleague who was not in the meeting:

1. State the goal and the done criterion. "Find every call site of parseConfig and report whether each handles a null return" beats "look at config parsing".
2. Include what you already know. Ruled-out hypotheses, relevant file paths, the user's constraints. Otherwise the subagent rediscovers them at your expense.
3. Point at files instead of pasting them. The subagent can read; a path costs a few tokens, a pasted file costs thousands in both contexts.
4. Specify the return shape. Ask for a short structured report. The parent will have to parse or relay it.
5. Keep the scope narrow. One subagent, one question. Several narrow subagents in parallel beat one broad one.

Context can also cross the boundary through the filesystem. A parent can write a brief or a data file, invoke the subagent with its path, and read the subagent's output file afterwards. This is the most robust pattern for large payloads and for chains of subagents.

Parallel fan-out and its costs

Subagents may run concurrently. Fan-out is ideal for independent research questions, per-module reviews or multi-file refactors. The costs are real: each subagent pays for its own system prompt and tool definitions, the parent cannot watch progress, and a subagent's mistakes arrive in the same confident tone as its findings. Verify what matters, especially anything the parent will act on.

Two rules of thumb from Anthropic's own tooling: do not delegate a check you could run yourself in a handful of tool calls, and never re-delegate an entire assignment to a single subagent, which just adds a lossy hop.

The orchestrator-worker view

At the API level there is no special subagent object. An orchestrator is one messages array; each worker is another, started fresh with a brief. Structured output on the worker's final message makes the handback machine-readable. Everything above about briefs and return shapes applies identically.

Exam focus

• A subagent has its own context window and receives only the prompt it is invoked with; it does not inherit the parent's conversation.
• The parent receives only the subagent's final report, never its transcript or intermediate tool results.
• Claude Code subagent files live in .claude/agents/ (project) and ~/.claude/agents/ (user); project definitions win on name conflicts.
• The description frontmatter drives automatic delegation; tools restricts capability; model can downgrade cost per subtask.
• Pass large context by file path, not by pasting; specify the return shape in the brief.
• Delegation suits independent, parallelisable or context-heavy work, not quick lookups you could do inline.