- In short
- The hooks vs prompts framework is a single decision rule: use a hook when a rule must hold every single time, and a prompt when you only need probabilistic guidance. Hooks give deterministic guarantees in code; prompts shape behaviour the model can still reason around.
The framework in one question
Deciding between hooks vs prompts sounds like a tooling choice, but it is really a reliability choice, and it collapses to a single question: does this rule have to hold one hundred per cent of the time? If the honest answer is yes, you need a hook, because a hook is enforced by code the model cannot override. If an occasional miss is genuinely acceptable, a prompt is the lighter, cheaper instrument and usually the right one. Everything else in this framework is just elaboration on that one question.
The official guidance states the distinction plainly: hooks provide deterministic control over Claude Code's behaviour, ensuring certain actions always happen rather than relying on the model to choose to run them. A prompt, by contrast, is interpreted at runtime by a model that can be reasoned with, persuaded, or simply distracted across a long conversation. Both are legitimate; they are tuned for different stakes.
- Hooks vs prompts framework
- A decision rule for choosing an enforcement mechanism. Hooks deliver deterministic guarantees suited to rules that must never fail; prompts deliver probabilistic guidance suited to preferences and soft conventions the model can apply with judgement.
Deterministic versus probabilistic, concretely
A prompt lives inside the model's reasoning. When you write a guideline into a system prompt or a CLAUDE.md file, you are adding a strong influence on the model's choices, but it remains an influence and not a constraint. The model weighs it against everything else in context, and on most turns it follows it. The failure mode is statistical: across thousands of calls, a fraction will diverge, and you cannot predict which.
A hook lives outside the model's reasoning, in a shell command the runtime executes at a fixed lifecycle point. It does not weigh anything against context; it applies its rule and returns a verdict. The failure rate of a correctly written hook is effectively zero for the condition it checks, because the model is not in the loop for that decision. That is the entire trade: prompts are flexible and fallible, hooks are rigid and reliable.
Why a demo hides the difference
The framework is easy to state and surprisingly easy to get wrong in practice, and the reason is the demo. When you trial a strong prompt against a handful of cases, it almost always behaves the way a hook would, because the model is attentive and the context is short. That early success is exactly what lulls a team into treating a prompt as sufficient for a serious rule. The gap between guidance and guarantee is invisible at small scale; it only emerges in the long tail of real traffic.
What changes at scale is the diversity of inputs and the length of conversations. A guideline that holds cleanly in a three-turn test can be diluted across a forty-turn session, contradicted by an unusual user request, or quietly outweighed by competing instructions the model is also trying to honour. None of these failures reproduce reliably, which makes them maddening to debug and impossible to eliminate by editing the prompt. Designing for the tail rather than the demo is the mindset shift this knowledge point is really teaching, and it is why the reliability question has to be asked up front.
The cost-of-failure test
The cleanest way to apply the framework is to imagine the rule failing exactly once and ask what it costs. If a single breach means lost money, a regulatory violation, leaked data, or an irreversible deletion, the expected cost of even a small failure rate is unacceptable, and the rule must be deterministic. If a single breach just means a slightly less tidy commit message or a stylistic inconsistency, a prompt is entirely adequate and a hook would be over-engineering.
This is the same logic behind the high-stakes enforcement decision rule: stakes, not preference, decide the mechanism. It also explains why the two tools coexist happily in one agent. You might use a prompt to encourage a helpful tone and a concise style, while using a PreToolUse hook to guarantee that a payment never exceeds a limit. Neither could do the other's job well.
Using both together in one agent
A frequent misconception is that the framework forces an either-or choice, as though every agent were ruled by hooks or by prompts. Mature designs use both, deliberately and at the same time, because the two instruments are tuned for different layers of behaviour. Prompts shape the broad, judgement-rich texture of how an agent works: its tone, its preferences, the heuristics it applies when no hard rule is at stake. Hooks draw the small number of bright lines that must never be crossed, and they draw them in code.
Seen this way, the framework is less a fork in the road than a sorting exercise. You take each rule an agent should follow and drop it into one of two buckets according to its stakes, ending up with a thin layer of deterministic guarantees underneath a richer layer of probabilistic guidance. The art is in the sorting, not in picking a side. An architect who can look at a requirements list and confidently route each item to the right mechanism is demonstrating exactly the analyse-level competence this knowledge point assesses.
Why the two are not interchangeable
The headline exam trap here is treating hooks and prompts as interchangeable, with the specific sub-trap of using a prompt for a compliance requirement. They feel interchangeable because, in a demo, a well-written prompt often produces the same behaviour a hook would enforce. The difference only reveals itself at the tail of the distribution, on the rare input or the long conversation where the prompt quietly fails and the hook does not. Architecture decisions have to be made for that tail, not for the demo.
There is also a subtler error in the other direction: wrapping soft preferences in hooks. A hook that hard-fails on a style nit makes the agent brittle and annoying, blocking work for something that did not need a guarantee. The framework cuts both ways. Match deterministic enforcement to rules that must never fail, and leave probabilistic guidance to genuinely soft conventions. Analysing a requirement to find which category it belongs to is precisely the analyse-level skill this knowledge point assesses.
Worked example
A team is designing two safeguards for a coding agent and must choose a mechanism for each: never modifying .env files, and preferring British spelling in documentation.
Take the first safeguard. Editing a .env file could leak secrets or break production, and a single mistake is costly and hard to reverse. Run it through the framework: must it hold every time? Yes. Would one failure cause real harm? Yes. So this is a hook. A PreToolUse hook on the file-editing tools denies any write whose path targets a .env file, and that denial holds even if the model is convinced it has a good reason.
Now the second safeguard. Using American spelling in a doc is a minor inconsistency a reviewer can fix in seconds. Must it hold every time? Not really; an occasional miss is harmless. Would one failure cause harm? No. So this is a prompt. A line in CLAUDE.md asking for British spelling nudges the model effectively, and the rare slip costs nothing.
The instructive part is that the same agent uses both, each matched to its stakes. The compliance-grade rule is deterministic and unbypassable; the stylistic preference is probabilistic and lightweight. Reverse them and you get the worst of both worlds: a brittle agent that blocks on spelling and a leaky one that merely hopes to protect secrets. The framework exists to stop exactly that mismatch.
Run a few more candidate rules through the same two questions and the sorting becomes second nature. Never push directly to the main branch: must hold every time, and a breach is costly to unwind, so it is a hook. Prefer adding a short docstring to new functions: a miss is harmless and judgement-dependent, so it is a prompt. Always run the test suite before opening a pull request: a single skip can ship a regression, so it is a hook. The questions stay fixed while the rules change, which is what makes the framework portable across every agent you will design.
Common misreadings to avoid
Misconception
A sufficiently detailed prompt is a reasonable substitute for a hook when enforcing a compliance rule.
What's actually true
Misconception
Hooks are simply the better, stronger version of prompts and should be used for every rule.
What's actually true
The prompt-based hook: a deliberate hybrid
One refinement keeps the binary honest, and the exam can probe it. Claude Code supports more than one kind of hook. Alongside the command hooks this page has assumed, the official hooks reference defines a prompt-based hook (type: "prompt") that runs no shell command at all. When its event fires, Claude Code sends the hook input together with your instruction to a Claude model, using Haiku by default, and the model returns a structured JSON decision that Claude Code then applies automatically. The hook input is injected into your instruction through the $ARGUMENTS placeholder, and a literal dollar sign is escaped as \$.
That makes a prompt-based hook a genuine hybrid rather than a counter-example. It is still a hook in every structural sense: it is bound to a lifecycle event, it can be narrowed with a matcher, and its JSON verdict is enforced by the runtime rather than left to the main agent's discretion. What differs is where the decision is computed. The judgement itself comes from a model call, so a prompt-based hook is not the same hard, non-model guardrail a command hook gives you. For a rule that must hold with certainty, a deterministic command hook or an external validator is still the safer choice; a prompt-based hook fits best where you want event-driven, auto-applied control but the decision needs a little model judgement.
The lesson for the framework is that hook versus prompt is really a spectrum of enforcement, not a strict either-or. A free-form system prompt is the most flexible and the least guaranteed; a command hook is the most rigid and the most guaranteed; a prompt-based hook sits between them, packaging model judgement inside the deterministic plumbing of the hook system. Recognising that middle option, and remembering it still rides on a model call, is the kind of precise distinction an analyse-level question rewards.
How it shows up on the exam
Domain 1 carries 27% of the exam, and this knowledge point is where the deterministic-enforcement principle becomes an explicit choice. Questions present a rule and a context and ask which mechanism fits, or critique an existing design that used the wrong one. The most common credited answer recognises that a compliance or financial rule demands a hook, while the most common distractor offers a more elaborate prompt that still cannot guarantee the outcome.
You can answer almost every item by running the two-part test in your head: must it hold every time, and would one failure hurt? Two yeses point to a hook. A clear no on the first points to a prompt. Carrying that rule into compliance hook scenarios and hook pipeline design lets you justify the mechanism, not just name it, which is what evaluate-level questions reward. A final tell to watch for: when an option insists the prompt was simply not detailed or forceful enough, treat that as a signal the design is reaching for the wrong tool, because no amount of wording converts probabilistic guidance into a deterministic guarantee.
An architect is reviewing four proposed agent rules and wants to use prompts wherever a guarantee is genuinely unnecessary. Which rule is the best candidate for a prompt rather than a hook?
People also ask
When should I use a hook instead of a prompt?
Are Claude Code hooks deterministic?
Can prompts guarantee compliance?
Watch and learn
Official Anthropic Academy lessons first, then hand-picked walkthroughs. Videos load only when you press play.
Introducing hooks
Why watch: Framing when to reach for a hook versus a prompt is the deterministic-vs-probabilistic decision this KP teaches.
More videos for this concept
References & primary sources
Master this concept with Archie
Practice it inside an adaptive study session. Archie, your Socratic AI tutor, tracks your mastery with Bayesian Knowledge Tracing and schedules the perfect next review.