feat(sdk): add subagent conversation forking

[Thushanth Bengre (thushanth-bengre-langchain)]

Closes #4668.

Adds ForkedSubAgent, a subagent spec that inherits the parent's effective conversation history and exact system prompt instead of only seeing the task description — useful when a subagent is delegated deep into an investigation and shouldn't have to re-derive context the parent already gathered.

mode="fork" is required rather than optional on ForkedSubAgent, since SubAgent.system_prompt is also optional — making both optional would let the two specs collapse into the same shape and get silently misrouted between forking and isolated behavior.

Reconstructs history using the same summarization-cutoff logic as isolated subagents (now shared via a common helper), drops the parent's still-unresolved trailing tool-call message so the forked prefix matches what was actually cached, and mirrors in a fresh memory middleware instance when memory= is configured. Experimental, flagged as such in the docstrings.

Note: #4668 proposed a per-call fork: bool flag on the task tool; this implements the capability as a spec-level ForkedSubAgent type instead. A per-call flag can be layered on as a follow-up if the tool-level ergonomics are wanted.

[open-swe]

Open SWE Review found 2 potential issues.

Open in Web • View Open SWE trace

[open-swe]

Open SWE Review found 2 potential issues.

Open in Web • View Open SWE trace

[Mason Daugherty (mdrxy)]

Closes #4668 — with a shape difference worth noting:

• Add fork option to the task tool so subagents can inherit parent conversation history #4668 proposed: per-call fork: bool on the task tool, gated by an allow_fork middleware flag.
• This PR: a separate ForkedSubAgent spec with required mode="fork" — forking is a property of the subagent definition, not a per-call flag. mode is required so the two specs can't collapse into the same shape and get silently misrouted.

Same underlying capability: forked subagent gets the parent's effective history (same summarization-cutoff logic as isolated subagents) plus the task description. Isolated-by-default is unchanged.

Ninaad R. Rao (@NinaadRao) — if the per-call fork= flag itself matters beyond the capability, that can be layered on as a follow-up.

Unaffected related issues: #1359, #2440, #3838, #2512.

(Also editing the PR description to include the Closes #4668 line.)

[Mason Daugherty (mdrxy)]

• Forks probably shouldn't run prompt-producing middleware. Today a fork builds its middleware stack like any other subagent. MemoryMiddleware, SkillsMiddleware, and any profile extras each append to the system prompt. But then _ForkSystemMessageMiddleware runs last and replaces the whole thing with the captured parent message. So that work happens on every call and is thrown away every time. Since a fork's prompt is definitionally the parent's captured prompt, I think we can skip prompt-producing middleware at fork construction and set the captured message as the fork's static prompt?
• A forked spec with system_prompt should raise, not silently drop it. The Never annotation only helps typed users; at runtime _resolved_declarative_spec filters the key out, so ForkedSubAgent(system_prompt="You are a SQL expert...") runs without complaint and the prompt is silently discarded (the kind of misrouting required mode="fork" seems to be designed to prevent). A ValueError in _validate_subagent_mode (or a sibling validator) would make bad config loud.
• Reject duplicate subagent names. The context leak Open SWE flagged is currently avoided only because subagents_by_name and subagent_graphs both happen to resolve duplicates last-write-wins. That agreement is incidental: a ValueError on duplicate names removes the whole class of bug instead of relying on two maps staying in lockstep.

[open-swe]

Open SWE Review found 1 potential issue.

Open in Web • View Open SWE trace

[Thushanth Bengre (thushanth-bengre-langchain)]

• Forks probably shouldn't run prompt-producing middleware. Today a fork builds its middleware stack like any other subagent. MemoryMiddleware, SkillsMiddleware, and any profile extras each append to the system prompt. But then _ForkSystemMessageMiddleware runs last and replaces the whole thing with the captured parent message. So that work happens on every call and is thrown away every time. Since a fork's prompt is definitionally the parent's captured prompt, I think we can skip prompt-producing middleware at fork construction and set the captured message as the fork's static prompt?
• A forked spec with system_prompt should raise, not silently drop it. The Never annotation only helps typed users; at runtime _resolved_declarative_spec filters the key out, so ForkedSubAgent(system_prompt="You are a SQL expert...") runs without complaint and the prompt is silently discarded (the kind of misrouting required mode="fork" seems to be designed to prevent). A ValueError in _validate_subagent_mode (or a sibling validator) would make bad config loud.
• Reject duplicate subagent names. The context leak Open SWE flagged is currently avoided only because subagents_by_name and subagent_graphs both happen to resolve duplicates last-write-wins. That agreement is incidental: a ValueError on duplicate names removes the whole class of bug instead of relying on two maps staying in lockstep.

• Fixed — forks now skip building MemoryMiddleware/SkillsMiddleware at construction instead of computing then discarding them.
• Fixed — a forked spec with system_prompt set now raises ValueError in _validate_subagent_mode
• Fixed — duplicate subagent names now raise ValueError before anything gets compiled

[open-swe]

Open SWE Review found 1 potential issue.

Open in Web • View Open SWE trace

[open-swe]

Open SWE Review found 1 potential issue.

Open in Web • View Open SWE trace