1.5 Agent SDK Hooks

Lesson 1.4 told you that for high-stakes requirements you need code, not just prompts. This lesson shows you the specific machinery Claude gives you to run that code at precisely the right moment: hooks. If enforcement was the 'why,' hooks are the 'how.'

A hook is a piece of your own code that Claude runs automatically at a defined point in the agent's lifecycle — for instance, 'right before any tool runs' or 'right after a tool returns.' You don't call the hook yourself; you register it, and Claude fires it at that moment, every time, without fail. Think of hooks like the sensors and interlocks on a factory line: a light barrier that halts the press before a hand can reach in, or an inspection station that stamps every part as it passes. They're not part of the product being made — they're guarantees wired into the line itself.

That 'every time, without fail' is the whole point. Because a hook is your code firing at a fixed point, it behaves deterministically — exactly what Lesson 1.4 said high-stakes work demands. The exam focuses on two moments in particular (just before a tool runs, and just after), one decision rule for choosing between them, and one classic mistake about timing. Let's build all three up carefully.

The single most important thing about these two hooks is WHEN they fire, because that determines what they can and cannot do. Everything else follows from timing.

A PreToolUse hook fires BEFORE the tool runs. At that instant the action hasn't happened yet — so this is your one chance to stop it. You can block it outright, or redirect it somewhere else. A PostToolUse hook fires AFTER the tool has already run. The action is done; you can't un-ring that bell. What you CAN do is reshape the result before the model sees it. The mental test is simple: if you want to PREVENT something, you must act before it happens (PreToolUse); if you want to TIDY UP what came back, you act after (PostToolUse).

Here's where the classic exam mistake lives. Suppose you need to block refunds over $500. A tempting answer is 'use a PostToolUse hook to check the amount.' But PostToolUse fires AFTER process_refund has already executed — the $500 is already gone. By the time your hook looks at the amount, it's too late. Blocking MUST happen in PreToolUse. This timing trap is tested directly, so let the factory analogy anchor it: the safety interlock has to stop the press BEFORE it comes down, not file a report afterwards.

Let's see each hook's signature use case, starting with PostToolUse. Its job is normalization — turning the messy, inconsistent data that different tools return into one clean shape before the model has to reason about it.

Picture an agent wired to three different backend tools. One returns timestamps as Unix epoch numbers (1719792000), another as ISO-8601 strings (2024-07-01), a third as numeric status codes (2 instead of 'shipped'). If all that heterogeneity reaches the model, it has to waste effort decoding three formats and may slip up. A PostToolUse hook intercepts each tool's output and rewrites it into a single consistent shape — every timestamp as ISO-8601, every status as a readable word — so the model sees clean, uniform data.

Crucially, this is a DETERMINISTIC transformation, which is exactly why it belongs in a hook and NOT in the prompt. You could write 'always convert timestamps to ISO-8601' in the system prompt, but that's a sign again — probabilistic, occasionally ignored, and it burns tokens every turn. A hook does the conversion in code, every single time, invisibly. Format-wrangling is a job for a hook, not a request to the model.

PreToolUse is the enforcement hook — it's where Lesson 1.4's 'lock' actually gets built for tool calls. Because it fires before execution, it can inspect what the model is about to do and decide: allow it, block it, or redirect it.

This is how you implement compliance rules deterministically: a refund over $500 → block and route to human escalation; a transfer_funds call → block unless an AML check has passed; a discount over 20% → redirect into a manager-approval queue. In each case the model proposes the action, the PreToolUse hook intercepts it before it can run, and your code has the final word — the same model-proposes/code-disposes principle from Lesson 1.1, now realised as a concrete hook.

How does a hook communicate its decision back to Claude? Two ways, and you pick ONE, not both. The simplest is exit codes: exit 0 means 'fine, carry on'; exit 2 means 'BLOCK this.' There's a subtle gotcha the exam likes: exit code 1 does NOT block — only exit 2 does. (Exit 1 is treated as an ordinary, non-blocking error.) The alternative is to exit 0 and print a small JSON object like {"decision":"block","reason":"…"} for richer control. Use exit codes alone, or JSON alone — never mix them.

PreToolUse and PostToolUse are the two the exam drills, but they're part of a much larger family. Claude can fire hooks at many lifecycle moments — and knowing the families exist marks you as someone who understands the system, not just two events.

Two details connect back to earlier lessons. First, hooks can be scoped to a subagent — defined in that subagent's own configuration so they only fire while it's active, then clean up when it finishes. Second, a neat consequence: a 'Stop' hook (which fires when an agent finishes its turn) automatically becomes a 'SubagentStop' hook when it's attached to a subagent — because that's the event that actually fires when a subagent completes. You don't have to special-case it; Claude does the right thing.

Every 1.5 trap is a confusion about timing or layer — using the wrong hook direction, expecting a prompt to do a hook's deterministic job, or fumbling the exit codes. Anchor on 'before blocks, after reshapes' and they dissolve.

• •Blocking in the wrong place. ✗ Using a PostToolUse hook to block an action. ✓ It already ran — block in PreToolUse.
• •Prompting where a hook is needed. ✗ Relying on a system-prompt instruction for a 100%-compliance requirement. ✓ Use a hook — prompts are probabilistic.
• •Transforming in the model instead of in code. ✗ Asking the model to convert every timestamp to ISO-8601. ✓ Do it deterministically in a PostToolUse hook.
• •Wrong exit code. ✗ Returning exit 1 expecting it to block. ✓ Only exit 2 blocks; exit 1 is a non-blocking error.

You now understand what a hook is, why timing decides its power, PostToolUse for normalization, PreToolUse for enforcement, the exit-code mechanics, and the wider lifecycle. As always, the surest way to cement it is to build both — and to feel the timing trap by deliberately putting the block in the wrong place.

Hooks are the precision instrument of enforcement. With them, you've now seen the full toolkit Domain 1 gives you for shaping agent behaviour: the loop you control (1.1), teams you coordinate (1.2–1.3), and guarantees you enforce (1.4–1.5). The remaining two lessons turn to how you STRUCTURE the work itself — decomposition (1.6) and managing state across sessions (1.7).