Subagents in the SDK changedagent-sdk/subagents
Nearest release: v2.1.238, published an hour before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+9added
Lines−24removed
From line
19
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits24to this page, all time
### Context isolation ### Parallelization ### Specialized instructions and knowledge ### Tool restrictions
The whole hunk
from line 19, old and new numbered
/
from line 19
1919
2020## Benefits of using subagents
2121
22### Context isolation
22Because subagents are separate agent instances, delegating work to them gives you four benefits:
2323
24Each subagent runs in its own fresh conversation. Intermediate tool calls and results stay inside the subagent; only its final message returns to the parent. See [What subagents inherit](#what-subagents-inherit) for exactly what's in the subagent's context.
24* **Context isolation**: each subagent runs in its own conversation, which starts fresh unless the subagent is a [fork](/docs/en/sub-agents#fork-the-current-conversation). Either way, intermediate tool calls and results stay inside the subagent; only its final message returns to the parent. A `research-assistant` subagent can explore dozens of files without any of that content accumulating in the main conversation. The parent receives a concise summary, not every file the subagent read. See [What subagents inherit](#what-subagents-inherit) for exactly what's in the subagent's context.
25* **Parallelization**: multiple subagents can run concurrently, so independent subtasks finish in the time of the slowest one rather than the sum of all of them. During a code review, you can run `style-checker`, `security-scanner`, and `test-coverage` subagents simultaneously instead of sequentially.
26* **Specialized instructions and knowledge**: each subagent can have a tailored system prompt with specific expertise, best practices, and constraints. A `database-migration` subagent can have detailed knowledge about SQL best practices, rollback strategies, and data integrity checks that would be unnecessary noise in the main agent's instructions.
27* **Tool restrictions**: subagents can be limited to specific tools, reducing the risk of unintended actions. A `doc-reviewer` subagent might only have access to Read and Grep tools, ensuring it can analyze but never accidentally modify your documentation files.
2528
26**Example:** a `research-assistant` subagent can explore dozens of files without any of that content accumulating in the main conversation. The parent receives a concise summary, not every file the subagent read.
27
28### Parallelization
29
30Multiple subagents can run concurrently, so independent subtasks finish in the time of the slowest one rather than the sum of all of them.
31
32**Example:** during a code review, you can run `style-checker`, `security-scanner`, and `test-coverage` subagents simultaneously instead of sequentially.
33
34### Specialized instructions and knowledge
35
36Each subagent can have tailored system prompts with specific expertise, best practices, and constraints.
37
38**Example:** a `database-migration` subagent can have detailed knowledge about SQL best practices, rollback strategies, and data integrity checks that would be unnecessary noise in the main agent's instructions.
39
40### Tool restrictions
41
42Subagents can be limited to specific tools, reducing the risk of unintended actions.
43
44**Example:** a `doc-reviewer` subagent might only have access to Read and Grep tools, ensuring it can analyze but never accidentally modify your documentation files.
45
4629## Create subagents
4730
4831### Programmatic definition (recommended)
from line 177
194177
195178## What subagents inherit
196179
197A subagent's context window starts fresh, with no parent conversation, but isn't empty. The only content you pass from parent to subagent is the Agent tool's prompt string, so include any file paths, error messages, or decisions the subagent needs directly in that prompt.
180Unless the subagent is a [fork](/docs/en/sub-agents#fork-the-current-conversation), its context window starts fresh, with no parent conversation, but isn't empty. The only content you pass from parent to subagent is the Agent tool's prompt string, so include any file paths, error messages, or decisions the subagent needs directly in that prompt.
198181
199182A subagent that has the [`SendMessage`](/docs/en/tools-reference) tool starts with a list of the other named agents running in the session, so it knows which names it can send messages to. Claude Code adds the list to the subagent's first turn automatically. A [fork](/docs/en/sub-agents#fork-the-current-conversation) doesn't get the list because it inherits the parent conversation instead. The list requires Claude Code v2.1.206 or later.
183
184The table below lists what a non-fork subagent's context contains and what it leaves out.
200185
201186| The subagent receives | The subagent doesn't receive |
202187| :------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------- |
No line in this hunk matches that.