What a hook actually is
A hook is a shell command the harness runs when a specific event fires. It is configured in settings.json, it gets the event payload on stdin, and its exit code and output decide what happens next - the command can let the action through, surface a warning, or block it. That is the whole point: a hook is real code on your machine, not a request you are hoping the model honors.
This distinction matters more than it first appears. An instruction in your CLAUDE.md is a strong suggestion the agent usually follows. A hook is a guarantee. When the cost of forgetting is high - a destructive command, an unlinted commit, a missing environment variable - you want the guarantee, not the suggestion.
Hook versus instruction: where the line is
The useful rule is simple. If something must happen every single time with no exceptions, it belongs in a hook. If it is guidance, taste, or a default the agent can reasonably override in context, it belongs in an instruction. Stuffing non-negotiables into prose just means they hold most of the time, which is the same as not holding.
The non-negotiables worth a hook are usually short and boring:
- Lint and format after every edit. Run the formatter and linter on the file the agent just touched, so style never drifts and you are not reviewing whitespace.
- Block destructive git commands. Catch a
git push --forceto a protected branch or agit reset --hardbefore it runs, not after. - Set up the environment on directory change. Load the right Node version, source the right env, or warm a cache when the working directory moves - so the agent is never operating in a half-configured shell.
Notice what these have in common: each is mechanical, has an unambiguous correct answer, and is annoying to get wrong. That is exactly the shape of work you hand to deterministic code instead of judgment.
The common event points
You do not need to learn every hook event to be effective - a handful carry most of the weight:
- After an edit or write. The workhorse. Fire your formatter, linter, or type-check against the file that just changed and feed real diagnostics straight back to the agent.
- Before a tool runs. The gatekeeper. Inspect a command before execution and block the dangerous ones - this is where destructive-command guards live.
- On stop. The session is wrapping up. A good place to run the full check suite or confirm working state is clean before you walk away.
- On prompt submit. Inject fresh context or a reminder at the moment you send a message, so the agent is never working from a stale picture.
Safe by default beats clever
The most common way hooks go wrong is being too aggressive. A hook that hard-blocks on every lint warning, or fails the whole turn because a formatter touched an unrelated file, teaches you to disable it - and a disabled guard protects nothing. The saner posture is warn loudly, block rarely: reserve hard blocks for genuinely irreversible or destructive actions, and let everything else pass through with a visible message the agent can act on.
Keep them small, too. A hook should do one obvious thing and exit fast. The moment a hook grows its own config, branching, and edge cases, it becomes a thing you have to debug at the worst possible time - mid-session, when you just wanted to ship. If a job is big enough to need real logic, it is usually better off as a scoped subagent or a plain script the agent calls on purpose. Hooks are guardrails, not a place to build an application.
How this fits into a project that holds up
Plain hooks are a general Claude Code primitive - anyone can write them, and a few good ones are part of any setup worth trusting. Treating determinism as a deliberate layer rather than an afterthought is one of the core Claude Code best practices: decide on purpose what the agent is free to interpret and what it is not.
That is the thinking claudesetup bakes in. Core ships the project foundation - the substrate, the conventions, and context handoff - in one command. The Pro tier adds the full enforcement rig: tuned, safe-by-default enforcement hooks, a local integrity gate, governed decision records, and red-team review, for teams that want the guarantees wired in rather than assembled by hand. Either way you start with hooks that warn before they block, and you own every line.