SubagentStop Hook
Agent SDKDefinition
An Agent SDK lifecycle hook that fires at the **child→parent boundary** — the precise moment a subagent finishes its task and hands its result back to the orchestrator. Unlike the [Stop hook](/glossary/stop-hook), which is an inward-facing gate on a single agent's own final response, SubagentStop is an outward-facing interface contract: it intercepts what crosses from a subagent's isolated context into the parent session.
Example Usage
In a parallel fan-out pipeline, three subagents each return structured data. SubagentStop fires once per subagent as it completes — three times total, in completion order — validating each result against the expected schema before the orchestrator merges them into a unified report.
Why It Matters for the CCA-F Exam
The CCA-F exam tests candidates on the Stop vs. SubagentStop distinction. If a question involves a multi-agent pipeline where one agent spawns others and must validate what they return, SubagentStop is the answer. If the question involves a single agent's final response quality, it is the Stop hook.
In Depth
SubagentStop fires once per subagent completion, at the seam between two agents' contexts. To understand why this boundary matters, recall that a subagent runs in a completely isolated context window — its internal tool calls and reasoning never reach the parent directly. When the subagent finishes, it emits one structured result that crosses the boundary. SubagentStop intercepts that crossing before the result enters the orchestrator's context as a tool_result block.
This hook position is architecturally distinct from Stop in two ways:
- Scope: Stop fires within a *single* agent's own turn, gating that agent's final response. SubagentStop fires at the *boundary between two agents*, gating what travels from child to parent.
- Frequency in fan-out: In a parallel pipeline where the orchestrator spawns N subagents, SubagentStop fires N times — once per subagent, in the order they finish. Stop would only fire once for the main orchestrator's own output.
Productive uses of SubagentStop:
- Schema validation in parallel pipelines: Fan out to three subagents (pricing, specs, compliance). SubagentStop validates each result against its schema before the orchestrator runs the merge step. Malformed data is rejected at the boundary, not discovered mid-merge.
- Security filtering: A subagent that called external tools might embed sensitive data in its result. SubagentStop can strip or redact that content before it enters the parent's context window, preventing data leakage across the context isolation boundary.
- Format normalization: Canonicalize result shapes so the orchestrator's merge logic can assume a uniform structure regardless of which subagent produced the data.
- Result enrichment: Append provenance metadata — which subagent, from what input, at what time — before the result is stored in the orchestrator's context.
- Partial-failure handling: Substitute a safe default when a subagent's result is incomplete, rather than propagating a null that the orchestrator must detect later.
SubagentStop does *not* fire per tool call inside the subagent — if the subagent made ten tool calls internally, SubagentStop fires exactly once when the whole subagent finishes. To intercept individual tool calls inside a subagent, configure PreToolUse or PostToolUse in that subagent's own AgentDefinition.
How It's Tested & Common Confusions
- Hook identification in multi-agent scenarios: given a diagram of orchestrator + subagents, identify which hook fires at the orchestrator-subagent boundary
- Frequency clarification: confirm SubagentStop fires once per subagent completion, not per tool call within the subagent
- Contrast with Stop: scenario where both hooks could be relevant — the question tests whether candidates can pinpoint the correct scope
- Use-case matching: given a list of requirements (validate subagent schema, gate main agent output, block a tool call), map each to the correct hook
- Pipeline integrity: questions about preventing a malformed subagent result from corrupting a merge step
Frequently Asked Questions
If I have three subagents running in parallel, does SubagentStop fire once (for all three) or three times (once per subagent)?
SubagentStop fires independently for each subagent as it completes. In a parallel fan-out of three subagents, SubagentStop fires three times — once per subagent, in the order they finish. Each invocation receives only that subagent's result, not the results of the others.
Can SubagentStop prevent a subagent's result from reaching the orchestrator entirely?
Yes. SubagentStop can raise an error or return a null/empty result, effectively blocking the subagent's output from propagating. The orchestrator then receives an error or empty response for that subagent slot, which it must handle gracefully — typically via a fallback or retry path.
Does SubagentStop have access to the subagent's internal tool call history, or only its final output?
SubagentStop primarily receives the subagent's final result — the output it produced for the parent. Depending on the SDK implementation, the event may also include metadata about the subagent's session (tool calls made, token count), but the hook's primary input is the final response, not a full transcript of the subagent's internal reasoning.