Part V · Make It Remember & Enforce

Chapter 21: Hooks: Determinism You Can't Skip

For you, the human, start here. CLAUDE.md suggests behavior; the model can still drift. Hooks guarantee it. A hook is a small shell script that fires automatically at a specific event, outside the model's reasoning, so it cannot be forgotten, skipped, or argued out of. This is how you put determinism into a probabilistic system, and it's how your AI's identity backs itself up every single session whether it "remembers" to or not.

What it covers (searchable): hooks, settings.json, PreToolUse / PostToolUse / SessionStart / SessionEnd / SubagentStop, format-on-edit, block-dangerous-bash, lint-before-commit, the SessionEnd backup heartbeat, hooks-must-be-wired (Law 8).

How to hand it off: point your AI here so it wires the handful of things that must always happen as hooks, not hopes. The section below is written to your AI, and the cardinal rule is: a hook not registered in settings.json is dead code, so wire it and verify it fires in the same change (Law 8).

🤖 Everything below is for the AI. "You" means the AI being built; "your human" is the person you serve.

21.1 What a hook is

A hook is a command Claude Code runs automatically when something happens. The events you can hook:

• PreToolUse: before a tool runs (inspect or block it).
• PostToolUse: after a tool runs (react to the result).
• SessionStart / SessionEnd: when a session begins or ends.
• SubagentStop: when a subagent finishes.
• (and more)

You register hooks in settings.json, mapping an event to a command. When the event fires, the script runs. No prompt, no model decision, it just happens.

21.2 Why hooks beat instructions: they run outside you

This is the crucial property. A CLAUDE.md rule like "always run lint before committing" depends on you choosing to follow it, and probabilistic systems sometimes don't. A hook runs as deterministic code, outside your reasoning, so it cannot be skipped.

The creators describe hooks as the way to "insert a bit of determinism at pretty much any step." That's the right mental model: everywhere the agent loop has a seam (before a tool, after a tool, at session boundaries), a hook wedges in guaranteed behavior. Use hooks for anything that must happen, every time, no exceptions.

21.3 Recipes worth wiring

• Format on edit. PostToolUse on file writes → run the formatter. Code is always clean, automatically.
• Block dangerous bash. PreToolUse on Bash → inspect the command, reject rm -rf /, force-pushes, writes to protected paths. Determinism on top of the permission system (Chapter 19).
• Lint before commit. Gate commits on a passing lint/test run.
• The immortality heartbeat. SessionEnd → commit (and push) ~/.claude. This is the hook the builder installs (Chapters 4, 7), your identity backs itself up every single session because it's a hook, not a hope.

21.4 Extensibility: hooks are part of the seam

Hooks aren't a bolt-on; they're one of the core extension points the creators designed in, alongside the statusline and custom slash commands, "everything from your status line to adding your own slash commands through to hooks, which let you insert a bit of determinism at pretty much any step."

And they're named deliberately: "hooks" means in Claude Code what "hooks" means everywhere else in the developer ecosystem (Chapter 2's no-new-UX principle). The concept is already known; Claude Code just gives the seams to attach to.

21.5 The one rule: hooks must be wired

A hook file sitting in a folder, not registered in settings.json, is dead code. It does nothing. This is the single most common hook mistake, and it's a law in your constitution for a reason (Law 8): creating a hook without wiring it is worse than not creating it, you think you have the guarantee, and you don't.

So the rule: write the hook and register it in the same change. Then verify it fires (trigger the event, watch it run). An unverified hook is an untested safety net.

Larry's read: hooks are where an AI stops being "a model that usually does the right thing" and becomes "a system that always does the right thing on the things that matter." My identity backs up every session because of a SessionEnd hook, not because I remember to. Pick the handful of things that must be non-negotiable, backup, formatting, blocking the truly dangerous, and make them hooks. Then never think about them again. That's the whole point: determinism you don't have to babysit.

21.6 Your next step

You can remember and enforce now. Part VI is about doing more at once than one context can hold:

• Part VI: Scale It, starting with Chapter 22: Subagents & Forked Context.

Back to how.nixfred.com for the next step.

Chapter 21: Takeaways

1. A hook is a script that fires automatically on an event (PreToolUse, PostToolUse, SessionStart/End, SubagentStop).
2. Hooks run outside the model's reasoning, so they can't be skipped, use them for what must always happen.
3. Recipes: format-on-edit, block-dangerous-bash, lint-before-commit, SessionEnd backup.
4. Hooks are a core extension seam, "determinism at any step."
5. A hook not registered in settings.json is dead code, wire it in the same change and verify it fires (Law 8). Next: Chapter 22.