Subagents in the SDK changedagent-sdk/subagents
Nearest release: v2.1.304, published under an hour before upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 19 Oct 2026 19:49 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 19 Oct 2026 20:07 UTC.
Upstream edited
Recorded here
Lines+30added
Lines−3removed
From line
158
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits24to this page, all time
#### Choose whether Claude waits for subagents ### Forked subagents
The whole hunk
from line 158, old and new numbered
/
from line 158
158158
159159In the Python SDK, multi-word field names such as `disallowedTools` and `mcpServers` keep their camelCase spelling to match the wire format rather than following Python's snake\_case convention. See the [`AgentDefinition` reference](/docs/en/agent-sdk/python#agentdefinition) for details.
160160
161Subagents run in the background by default. An Agent tool call that omits the [`run_in_background`](/docs/en/sub-agents#run-subagents-in-foreground-or-background) input launches a background subagent, and Claude sets `run_in_background: false` when it needs the result before continuing. Set the `background` field to `true` to force background execution for a specific agent regardless of what Claude requests. Before Claude Code v2.1.198, the background default was rolling out gradually, and an Agent tool call that omitted `run_in_background` could run the subagent synchronously.
161#### Choose whether Claude waits for subagents
162162
163Subagents can also spawn subagents of their own. To limit how deep that nesting goes, how many subagents run at once, and how much a query spends, see [Cap subagent depth, concurrency, and spend](#cap-subagent-depth-concurrency-and-spend).
163By default, a subagent your main agent spawns [runs in the background](/docs/en/sub-agents#run-subagents-in-foreground-or-background). The Agent tool result has `status: "async_launched"`, and the report arrives in a later turn.
164164
165Claude waits when its next action needs the report: the call blocks and returns `status: "completed"`. To make that choice yourself:
166
167* **In your prompt**: ask Claude to wait, such as "run the test-runner agent and wait for it"
168* **In the definition**: set `background` to `true` to keep that agent in the background
169
165170### Filesystem-based definition (alternative)
166171
167172You can also define subagents as markdown files in `.claude/agents/` directories. See the [Claude Code subagents documentation](/docs/en/sub-agents) for details on this approach. Programmatically defined agents take precedence over filesystem-based agents with the same name.
from line 222
217222```
218223
219224This bypasses automatic matching and directly invokes the named subagent.
225
226### Forked subagents
227
228A [fork](/docs/en/sub-agents#fork-the-current-conversation) is a subagent that copies the conversation so far instead of starting fresh. From Claude Code v2.1.302, Claude can start forks in your application with nothing configured, by calling the Agent tool with `subagent_type: "fork"`.
229
230To stop Claude from starting forks, add an [`Agent(fork)` deny rule](/docs/en/agent-sdk/permissions#allow-and-deny-rules):
231
232<CodeGroup>
233 ```python Python theme={null}
234 options = ClaudeAgentOptions(
235 # Deny only the fork subagent type; other subagents still run
236 disallowed_tools=["Agent(fork)"],
237 )
238 ```
239
240 ```typescript TypeScript theme={null}
241 const options = {
242 // Deny only the fork subagent type; other subagents still run
243 disallowedTools: ["Agent(fork)"]
244 };
245 ```
246</CodeGroup>
220247
221248### Dynamic agent configuration
222249
No line in this hunk matches that.