Stop Hook
Agent SDKDefinition
An Agent SDK lifecycle hook that runs when the agent reaches an end_turn stop condition. Can inspect the final response and decide whether to allow the stop or inject additional instructions to continue the loop. Used for output validation and quality gates.
Example Usage
Use a Stop hook to verify the agent produced a complete response before allowing end_turn, injecting a prompt to continue if the response is incomplete.
Why It Matters for the CCA-F Exam
Stop hooks appear on the exam in quality-assurance and output-validation scenarios. If a question describes ensuring an agent's final response meets a structural requirement before it is delivered, the Stop hook is the correct mechanism. Key differentiator: Stop fires on `end_turn`, not on tool calls — if the scenario involves tool interception, it is not a Stop hook scenario.
In Depth
The Stop hook occupies a fundamentally different position in the agent lifecycle than the tool-interception hooks. It does not fire during a tool call at all — it fires when the agent itself decides it is done: specifically, when the model emits end_turn as its stop_reason, signalling it has no more tool calls to make and intends to deliver its final response.
This is the last checkpoint before the agentic loop hands control back to the caller. The Stop hook receives the agent's full proposed final response and can do one of two things: let the turn end, or force the loop to continue by injecting additional instructions into the conversation.
The power of Stop hooks comes from that second option. A common pattern: the Stop hook runs an automated quality check — does the final response mention a required section? Does it contain a valid JSON block? Does it cite at least two sources? If the check fails, the hook does not let end_turn complete. Instead, it injects a follow-up message such as "Your response is missing the cost estimate. Please add it before finishing." The agent receives this as a new user message and continues the loop.
This creates a self-correcting feedback loop that is entirely invisible to the end user. From their perspective, the agent simply produced a higher-quality response. Under the hood, the Stop hook may have forced one or two additional reasoning turns.
Stop hooks are especially valuable for:
- Completeness gates: Verify required sections, fields, or references are present
- Format enforcement: Check that the response is valid JSON, matches a schema, or follows structural rules
- Length guardrails: Prevent responses that are too short (likely truncated) or excessively verbose
- Compliance checks: Run a policy filter on the final text before it leaves the system
Compared to PreToolUse and PostToolUse, the Stop hook operates at the response level, not the tool level. There is no "tool" involved — the agent has completed its work and the hook is the final quality arbiter. Compared to SubagentStop, the Stop hook governs the main agent's own turn, not a child subagent's result.
One critical design constraint: Stop hooks that always force continuation risk creating infinite loops. Always include a maximum iteration count or a convergence condition. If the hook has already injected corrections twice, allow end_turn on the third attempt regardless of output quality — otherwise a flawed quality check can trap the agent indefinitely. See Agent SDK Hooks: PostToolUse & Interception for implementation guidance on loop guards.
How It's Tested & Common Confusions
- Scenario identification: given a description of an agent producing incomplete responses, identify which hook can force a second pass
- Stop_reason linkage: connect
end_turnstop_reason to the Stop hook's trigger condition - Anti-patterns: recognize that a Stop hook that always injects continuation instructions creates an infinite loop
- Hook ordering: confirm that Stop fires after all tool calls are complete, not during them
- Subagent distinction: differentiate Stop (main agent's turn) from SubagentStop (child subagent's turn)
Frequently Asked Questions
Does the Stop hook fire on every stop_reason, or only end_turn?
The Stop hook fires specifically when the agent reaches `end_turn` — meaning it has completed its reasoning and produced a final response. It does not fire on `tool_use` (the agent is still mid-loop awaiting tool results), `max_tokens` (truncation, not a voluntary stop), or `pause_turn` (server-side tool pause awaiting resumption).
Can a Stop hook access the full conversation history, or just the final message?
Hook implementations vary by SDK, but the Stop hook typically receives the final assistant response and may have access to the full message history depending on how the hook context is surfaced. In Claude Code's shell-hook model, the hook receives the final response text via stdin. In Agent SDK callback mode, the event includes the complete turn context.
What is the risk of using a Stop hook for quality gating?
The primary risk is infinite loops: if the quality check is flawed or the agent cannot satisfy the requirement, the hook keeps forcing continuation indefinitely. Always set a maximum number of continuation attempts. A secondary risk is latency — each forced continuation adds a full model inference turn, increasing cost and response time.