1.5 Agent SDK Hooks

What You Need to Know

Agent SDK hooks inject deterministic behaviour into an otherwise probabilistic system. They sit right at the boundary between the model’s decisions and the real world, intercepting tool calls and results to enforce business rules and normalise data. Remember the enforcement spectrum from 1.4? Hooks are how you implement its programmatic side in practice.

Two Types of Hooks

The Agent SDK provides hooks at two points in the tool execution lifecycle:

PostToolUse hooks run after a tool executes but before the model processes the result. They intercept tool results and transform them before the model sees them. The model receives clean, normalised data regardless of which tool produced it.

PreToolUse hooks (sometimes described as tool-call interception) run before a tool executes. They intercept the outgoing tool call and can block it, modify it, or redirect it to an alternative workflow. The tool never runs if the hook decides to block it.

What each hook returns. In the Agent SDK a PreToolUse hook answers with a permissionDecision of allow, deny, ask or defer, plus an optional updatedInput that rewrites the tool’s arguments before it runs. A PostToolUse hook can set updatedToolOutput to replace what the model sees, for built-in and MCP tools alike. The older updatedMCPToolOutput covered MCP tools only and is deprecated. One thing neither field changes: by the time PostToolUse fires the tool has already run, so blocking there stops the loop but does not undo the side effect. (Agent SDK hooks guide, checked September 2026.)

PostToolUse Hooks: Data Normalisation

Different MCP tools return data in different formats. A customer database might return Unix timestamps (1710489600). An order management system might return ISO 8601 dates (“2024-03-15T12:00:00Z”). A status API might return numeric codes (200, 404, 500) while another returns strings (“active”, “cancelled”, “pending”).

Without normalisation, the model has to interpret these mixed formats on every single iteration. That breeds inconsistency. It might parse a Unix timestamp correctly one time and misread it the next.

A PostToolUse hook solves this by normalising all formats before the model processes them:

Unix timestamps → ISO 8601 dates
Numeric status codes → human-readable strings
Currency values → consistent decimal format with currency code
Date strings in various regional formats → a single standard format

The model receives clean, consistent data every time, regardless of which tool or backend system produced it.

PreToolUse Hooks: Policy Enforcement

PreToolUse hooks are the implementation mechanism for the prerequisite gates described in 1.4. They intercept outgoing tool calls before execution and apply business rules:

Use case: Refund threshold enforcement. A hook intercepts all calls to process_refund. If the refund amount exceeds $500, the hook blocks the call and redirects to a human escalation workflow. The refund tool never executes — the hook prevents it before it can run.

Use case: Compliance prerequisite gates. A hook intercepts calls to transfer_funds. If the required anti-money laundering (AML) check has not been completed for this session, the hook blocks the call and returns an error message directing the agent to complete the AML check first.

Use case: Manager approval workflow. A hook intercepts calls to approve_discount for discounts above 20%. The hook pauses execution and routes the request to a manager approval queue. Only after manager approval does the tool execute.

The Decision Framework

This framework is the core mental model for the exam:

Requirement	Mechanism	Guarantee
Must be followed 100% of the time	Hooks	Deterministic
Preferred but occasional deviation is acceptable	Prompts	Probabilistic

If the business would lose money from a single failure → use a hook. If the business would face legal risk from a single failure → use a hook. If it is a formatting preference or style guideline → prompt-based guidance is fine.

The exam consistently presents prompt-based solutions as distractors for scenarios requiring deterministic enforcement. The decision is not about whether prompts are “good enough” — it’s about whether the consequence of a single failure justifies deterministic guarantees.

Hooks vs Prompts: Side-by-Side Comparison

Scenario: International transfers must pass AML checks.

Prompt approach: “Always complete AML verification before processing international transfers.” Works 95% of the time. The 5% failure rate means some transfers skip AML checks — a regulatory violation.
Hook approach: A PreToolUse hook blocks transfer_funds until aml_check returns a pass. Works 100% of the time. No transfer can execute without AML verification.

Scenario: Responses should be formatted in markdown.

Prompt approach: “Format all responses using markdown with headers and bullet points.” Works most of the time. Occasional plain-text responses are not a business risk.
Hook approach: Unnecessary overhead. Formatting preferences do not require deterministic enforcement.

Scenario: Refunds above $500 require human approval.

Prompt approach: “For refunds above $500, escalate to a human agent.” Works most of the time. A single failure means a large refund processed without approval.
Hook approach: Intercept process_refund, check the amount, block if above $500 and route to human escalation. Works 100% of the time.

Practical Example: Data Format Chaos

A customer support agent uses three MCP tools:

get_customer returns dates as Unix timestamps and status as numeric codes.
lookup_order returns dates as ISO 8601 strings and status as English strings.
check_shipping returns dates as “DD/MM/YYYY” and status as single-character codes (“S” for shipped, “P” for pending).

Without a PostToolUse hook, the model must interpret three different date formats and three different status representations on every iteration. Sometimes it correctly converts a Unix timestamp; sometimes it confuses the day/month order in “DD/MM/YYYY”; sometimes it misinterprets “P” as “processed” instead of “pending.”

With a PostToolUse hook, all tool results are normalised before the model sees them:

All dates → ISO 8601 (“2024-03-15T12:00:00Z”)
All status codes → human-readable strings (“shipped”, “pending”, “delivered”)

The model always receives consistent data, eliminating interpretation errors entirely.

Exam Traps

Practice Scenario

An agent occasionally processes international transfers without required compliance checks. The compliance team requires 100% enforcement of anti-money laundering (AML) checks before any international transfer is executed. The current system uses prompt instructions that work approximately 95% of the time. What is the correct approach?

A. Implement a PreToolUse hook that blocks the transfer_funds tool from executing until aml_check returns a verified pass result
B. Add detailed AML check instructions to the system prompt with examples of correct behaviour and explicit warnings about penalties for non-compliance
C. Add a PostToolUse hook that flags any completed transfer which skipped its AML check and queues it for manual review by the compliance team
D. Train the agent with few-shot examples demonstrating the correct AML verification workflow before every transfer

Answer & explanation

Correct: A

A — A PreToolUse hook intercepts the outgoing tool call before execution and physically blocks it until the AML check passes. This provides the deterministic 100% guarantee that regulatory compliance demands. No transfer can execute without verification.
B — Enhanced prompt instructions may improve the rate from 95% to 97-98% but cannot reach 100%. With AML regulations, even a single missed check can result in significant legal penalties. Probabilistic improvement is insufficient for regulatory requirements.
C — PostToolUse hooks run after execution. By the time the hook detects the missing AML check, the non-compliant transfer has already been processed. Regulatory compliance requires prevention, not post-hoc detection.
D — Few-shot examples improve accuracy but remain probabilistic. They cannot guarantee 100% compliance. Regulatory requirements for AML checks demand deterministic enforcement that only hooks can provide.

Sources

Claude Agent SDK Overview — Anthropic
Claude Agent SDK Hooks Documentation — Anthropic
Building with Claude API (Skilljar) — Anthropic

Exam Simulator

Five exam-style multiple-choice questions on Agent SDK Hooks. Pick an answer, then open the explanation.

Question 1

A. Add detailed AML check instructions to the system prompt with examples of correct behaviour and explicit warnings about penalties for non-compliance
B. Add a PostToolUse hook that flags completed transfers that skipped AML checks for manual review
C. Implement a PreToolUse hook that blocks the transfer_funds tool from executing until aml_check returns a verified pass result
D. Train the agent with few-shot examples demonstrating the correct AML verification workflow before every transfer

Answer & explanation

Correct: C

C is correct because a PreToolUse hook intercepts the outgoing tool call before execution and physically blocks it until the AML check passes. This provides the deterministic 100% guarantee that regulatory compliance demands. No transfer can execute without verification.
A is wrong because enhanced prompt instructions may improve the rate from 95% to 97-98% but cannot reach 100%. With AML regulations, even a single missed check can result in significant legal penalties. Probabilistic improvement is insufficient.
B is wrong because PostToolUse hooks run after execution. By the time the hook detects the missing AML check, the non-compliant transfer has already been processed. Regulatory compliance requires prevention, not post-hoc detection.
D is wrong because few-shot examples improve accuracy but remain probabilistic. They cannot guarantee 100% compliance. Regulatory requirements demand deterministic enforcement.

Question 2

A customer support agent uses three MCP tools that return dates in different formats: Unix timestamps (1710489600), ISO 8601 strings (“2024-03-15T12:00:00Z”), and DD/MM/YYYY format (“15/03/2024”). The model sometimes confuses day/month order. What is the best solution?

A. Add instructions to the system prompt explaining the three date formats and how to interpret each one
B. Use only one MCP tool to avoid format inconsistency
C. Implement a PreToolUse hook that converts dates before sending them to the tools
D. Implement a PostToolUse hook that normalises all date formats to ISO 8601 before the model processes them

Answer & explanation

Correct: D

D is correct because PostToolUse hooks intercept tool results after execution but before the model processes them. Normalising all dates to ISO 8601 at this point ensures the model always receives consistent data regardless of which tool produced it.
A is wrong because relying on the model to correctly interpret three different date formats on every iteration introduces inconsistency. The model may correctly parse a format once and misinterpret it the next time.
B is wrong because restricting to one tool limits functionality. The correct approach is to normalise heterogeneous outputs, not to avoid using multiple tools.
C is wrong because PreToolUse hooks run before tool execution. Dates are in the tool results (after execution), not in the tool calls (before execution). The hook direction is wrong for this use case.

Question 3

Which statement correctly describes the difference between PostToolUse hooks and PreToolUse hooks?

A. PostToolUse hooks transform results after execution; PreToolUse hooks block or modify calls before execution
B. PostToolUse hooks run before tool execution; PreToolUse hooks run after
C. Both types run at the same point but PostToolUse handles data while PreToolUse handles errors
D. PostToolUse hooks only work with MCP tools; PreToolUse works with all tool types

Answer & explanation

Correct: A

A is correct because PostToolUse hooks run after a tool executes but before the model processes the result (correct for data normalisation). PreToolUse hooks run before a tool executes (correct for policy enforcement and blocking actions).
B is wrong because it reverses the direction. PostToolUse is after execution, not before. PreToolUse is before execution, not after.
C is wrong because the hooks run at different points in the lifecycle, not the same point. Their timing is the fundamental distinction.
D is wrong because both hook types can work with any tool type. The distinction is timing (before vs after execution), not tool compatibility.

Question 4

A developer implements a PostToolUse hook to block refunds above $500. Why is this approach flawed?

A. PostToolUse hooks cannot access the refund amount parameter
B. The refund has already executed by the time a PostToolUse hook fires
C. PostToolUse hooks are only available in the paid tier of the Agent SDK
D. PostToolUse hooks can only transform data, not block operations

Answer & explanation

Correct: B

B is correct because PostToolUse hooks run after tool execution. By the time the hook fires, the process_refund tool has already executed and the refund has been processed. For blocking actions, you need a PreToolUse hook that intercepts before execution.
A is wrong because PostToolUse hooks can access the full tool result, including parameters. The issue is timing, not data access.
C is wrong because this is not a pricing tier limitation. The issue is that PostToolUse hooks fundamentally run too late to prevent an action.
D is wrong because while PostToolUse hooks are typically used for transformation, the core issue is that they run after execution. Even if they could block, the action has already occurred.

Question 5

When should you use hooks instead of prompt instructions for enforcing a business rule?

A. When the rule is complex and requires multiple steps to verify
B. When the rule involves formatting preferences or output style guidelines that readers will notice
C. When the agent has access to more than 5 tools
D. When a single violation would cause financial loss, legal risk, or security breach

Answer & explanation

Correct: D

D is correct because the decision framework is based on consequences. Hooks provide deterministic guarantees (100% enforcement). Prompts provide probabilistic guidance. If a single failure would cause financial loss, legal risk, or security breach, only hooks provide the required level of assurance.
A is wrong because complexity of the rule does not determine the mechanism. Simple rules (block refunds above $500) may require hooks due to financial risk, while complex rules (follow a specific formatting convention) may only need prompts.
B is wrong because formatting preferences are explicitly low-stakes and appropriate for prompt-based guidance. Hooks would be unnecessary overhead.
C is wrong because the number of tools is irrelevant to the hooks vs prompts decision. The consequence of a single violation is the deciding factor.