What
- A new tool,
SubagentHandback, lets a subagent send its final report straight to the agent (or main thread) that spawned it, as its one and only last tool call. It isn't a progress-update channel — it can only be called once, requires a non-empty message, and only works when the agent has an active "handback contract" with a recorded recipient. - Long reports are compacted or summarized before delivery, and get safety-review framing (blocked/refused/unavailable) attached.
- The subagent's completion result now carries a
handbackpayload (and ahandbackInterimvariant), and the finalize step computes whether the handback was sent, flagged, or withheld, appending a message to the result accordingly. - Async subagents can now explicitly hand control back to a specific owning agent (tracked as
handbackRecipient) rather than only running to completion or being polled. - For subagents running in "auto" mode, this mechanism is what actually counts as the final answer: plain trailing text is discarded unless delivered through
SubagentHandback. The feature is off by default, controlled by theCLAUDE_CODE_SENDMESSAGE_HANDBACKenvironment variable or an internal rollout gate. - Depending on the handback outcome (
send,flagged, orwithheld), the step that classifies a sub-agent's final output is skipped or has its text discarded, so results aren't double-processed.
Why This gives subagents a reliable, explicit way to report back to whatever spawned them, instead of relying on trailing text that might get lost, mis-parsed, or double-classified — useful for orchestration flows where a parent agent needs a clean, single final report from a subagent it dispatched.
Names in the bundleSubagentHandback
Documented inclaude-code/agent-sdk/typescript
The entry above is what we published on the day. These lines were added later, as Anthropic's own pages caught up, and they sit beside the original rather than replacing it.
Added since
A small documentation edit on Create custom subagents touched a line naming SubagentHandback after this was published.
The second filter applies to subagents running in the background. Apart from `Agent` and `ExitPlanMode`, which follow the first filter's conditions wherever the subagent runs, a background subagent keeps every MCP tool but only these built…sub-agents see the edit
Confirmed since
Anthropic's documentation has since written up SubagentHandback, on Hooks reference.
| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | The subagent's final text blocks, or, for a subagent whose report goes through `SubagentHandback`, a short note about that hand-back in their place |hooks see the edit
One source agreesOne thing we can check says the same as this entry.
Anthropic's documentation agrees
Anthropic's documentation has since written up SubagentHandback, on Hooks reference.