Whetstone.
Security, guardrails and Claude CodeHooks, and Claude Code as an operating surface
Module 4, Lesson 321 min

Hooks, and Claude Code as an operating surface

Two small domains to close on. Claude Code Operation is 3.1% and Claude Hooks is 1.0%, so this is a working-level lesson, not a manual. Know what the things are and where they sit.

Claude Code, in the amount the exam wants

Claude Code is an agentic coding tool that operates in your terminal against your actual repository. You drive it in natural language, it reads and edits files, runs commands, and works through multi-step tasks with the codebase as its context rather than a pasted snippet.

The operational facts worth holding: it works against real files in a real working directory, it is configured per-project as well as globally, and it is interactive by default but scriptable.

The one architectural fact that carries the most weight:

That framing is worth memorising verbatim, because the natural assumption is the other one. Almost every vendor SDK you have used is a transport wrapper. This is the agent.

Hooks: the deterministic interception point

You already know this pattern under another name. A line in CONTRIBUTING.md saying “always run the formatter before you commit” is a request; a pre-commit hook is a fact about what happens. Nobody who has maintained a repository believes those two are equivalent, and nobody expects the wording of the CONTRIBUTING.md line to close the gap.

A hook is a configured command that fires at a defined point in the agent’s lifecycle. Around tool use, around edits, at session boundaries. You configure it in settings; you do not ask for it in a prompt.

The single property that matters, and the only thing worth a whole percent of an exam:

A hook is not a decision the model makes.

You can write “always run the linter after editing” in your project instructions. It will mostly happen. Mostly is a probability, and on current models a more forcefully worded version of that instruction is actively worse, because they overtrigger on emphatic language.

A hook that fires on the edit event runs the linter. Full stop. No negotiation, no context window, no chance the instruction got crowded out by three thousand lines of file content.

Why this lands in the security module

Because it is the same distinction as the previous lesson, one layer down.

Guardrails are enforcement because they sit outside the model and can veto. Hooks are enforcement because they sit outside the model’s decision-making and fire regardless. Prompt instructions shape behaviour. Hooks and guardrails constrain it.

If you want a single sentence to carry out of the whole security half of this course: anything that has to be true cannot live in the context, because everything in the context is negotiable.

Practice

Try it yourself

Quiz

Hooks versus instructions

You want to guarantee that a formatter runs after every file edit, every time, with no exceptions. What do you reach for?

  1. AA line in the project instructions telling the agent to run the formatter after editing
  2. BA more forceful line, with CRITICAL and MUST in it
  3. CA hook that fires on the edit event and runs the formatter
  4. DA custom tool the model can choose to call
Show answer

Correct answer: C — A hook that fires on the edit event and runs the formatter

A hook fires deterministically on an event; the model does not decide whether it runs. Option 1 is the tempting answer because instructions do usually work and are much easier to write. The word in the question is guarantee, and an instruction is a probability while a hook is a control-flow fact. Option 2 is worse than option 1 on current models, which overtrigger on forceful language.

Quiz

The Agent SDK

What is the relationship between Claude Code and the Agent SDK?

  1. AThe Agent SDK is Claude Code as a library: the same agent harness, callable from your own code
  2. BThe Agent SDK is a lighter, unrelated wrapper over the Messages API transport
  3. CClaude Code is built on the Agent SDK but exposes a strict subset of its features
  4. DThey are alternative names for the same CLI, one internal and one public
Show answer

Correct answer: A — The Agent SDK is Claude Code as a library: the same agent harness, callable from your own code

The Agent SDK is Claude Code as a library. That framing is the one to carry: the loop, the tool handling and the harness you interact with through the CLI are the thing you get programmatically. Option 2 is the tempting answer because most vendor SDKs are exactly that, a thin client over an HTTP API, so it is the shape you expect by default. Here the SDK is the agent, not the transport.

Recall

What a hook is

One definition and one property. The property is the whole reason this concept is worth a percent of an exam, so an answer that only defines the mechanism is half an answer.

What is a Claude Code hook, and what does it give you that a prompt instruction cannot?

Reveal answer

A hook is a configured command that fires deterministically at a defined point in the agent's lifecycle, such as before or after a tool call. The property it has is that it is not a decision the model makes: it runs whether the model wanted it to or not, which makes it usable as enforcement rather than encouragement.

Recall

Hooks as the guardrail pattern

This card asks you to join two lessons together rather than to retrieve a fact. If the link comes back as one sentence, you have it.

Why do hooks belong in the security domain rather than only the tooling domain?

Reveal answer

Because they are the enforcement half of the encouraged-versus-enforced distinction, applied to an agent. A hook sits outside the model's decision-making and can inspect or block at a defined interception point, which is the same structural property that makes an external check a guardrail while a system-prompt rule is only encouragement.

Do

Sort your own rules

Ten minutes, one scratch file, no configuration changes. A sorting exercise rather than a setup exercise, and the useful output is a disagreement between what you believed and what is true.

  • Open the project instructions for a repository you work in. List every rule containing the word always or never.
  • For each one, write down what actually happens today when the agent skips it, and how you would find out that it had.
  • Mark each rule as encouragement or enforcement, honestly. A rule the model can decline is encouragement however forcefully it is worded.
  • For any rule you marked encouragement but needed to be enforcement, name the lifecycle event a hook would fire on instead.
Done whenYou have at least one rule that you believed was enforced and have now written down as encouragement, and you can name the event it would need to hang off.
Sign in to track your progress →