docs/design/2026-07-21-headless-fork-subagents.md
An explicit subagent_type: "fork" request is currently honored only when
Config.isInteractive() is true. Headless callers such as qwen --prompt,
the TypeScript SDK, and CI runners silently execute a fresh
general-purpose subagent instead. The requested and effective context modes
therefore differ, and the child does not receive the parent conversation.
Fork availability is independent of the presentation surface. A top-level fork request always uses the existing fork construction path, which copies the parent's history and cache-safe generation configuration.
Headless forks run through the existing background-agent registry even when
run_in_background is omitted or false. Forks are detached by definition, and
the registry gives non-interactive callers the lifecycle they need:
task_started and terminal task notifications;subagent_type: "fork" is recorded in events, metadata, and
subagent telemetry;Interactive fork behavior remains unchanged.
A fork request from a nested subagent is still unsupported, but it now fails
with an explicit tool error instead of silently running a fresh
general-purpose subagent.
This change reuses the current full-history fork behavior. It does not add
partial history selection such as fork_turns; that can be introduced
separately without blocking correct headless inheritance.
task_started event and
verifies that it exposes subagent_type: "fork".run_in_background: false.qwen --prompt --output-format stream-json check uses a parent
marker that is absent from the fork directive and verifies that the child
can still recover it from inherited history.