Docs: agent-sdk/subagents never mentions fork mode or the foreground/background precedence list

Status Open
Reported on v2.1.232
Maintainer reply None cached
Activity 0 comments · opened Aug 17, 2026

Subagents in the SDK describes foreground vs background as:

Two subagent behaviors changed in Claude Code v2.1.198: * Subagents run in the background by default. An Agent tool call that omits the run_in_background input launches a background subagent, and Claude sets run_in_background: false when it needs the result before continuing. Before v2.1.198, omitting run_in_background ran the subagent synchronously. […]

That is accurate for the SDK's own default, where fork mode is off. What the page never mentions is that fork mode exists at all — that it can be turned on in the SDK, that it has been the default in interactive sessions since 2.1.232, or that while it is on the run_in_background parameter is not in the Agent tool schema.

Run subagents in foreground or background carries the full precedence list and is the page that answers the question. A cross-link from the SDK page, or a single sentence naming fork mode, would be enough.

Context: I read the SDK page from an interactive CLI session and filed #85765 against it; it was closed as working-as-documented, with the precedence list linked in the close.

View original on GitHub ↗