Hooks & Guardrails

1 · Signs and locks

▶ Watch: the hook that said no · 3 min

This whole module grows out of one distinction, so let's state it properly. When you write a rule in CLAUDE.md, you are writing a request in English to a system that reads English. "Never delete files without asking." Claude reads that rule at the start of every session, and it follows the rule almost every time. Almost. The rule competes for attention with everything else in a busy context window, and on a long afternoon, in a long session, "almost every time" is what you get.

For most rules, that is completely fine. Style preferences, naming conventions, tone: if one in fifty sessions drifts, nothing terrible happens and you correct it. But some rules are not preferences, and for those, a miss is not a style problem. It is an incident. The whole module rests on telling these two kinds of rules apart:

A hook is a small script that the Claude Code software itself runs at fixed moments, automatically, every time, whether the model is having a good day or not. The sign on the door works on almost everyone. The lock works on everyone. This module is about installing locks.

2 · The moments a hook can fire

A hook attaches to a lifecycle event: a named moment in a session where Claude Code pauses and runs your script before continuing. Learn these as moments in a story, because that is what they are:

The one to internalize first is PreToolUse, because it is where the power is. It fires in the gap between "Claude wants to do X" and "X happens." Your script gets told exactly what Claude is about to do, and it gets a veto.

3 · Anatomy of a hook

A hook has two parts: a script, and a registration that tells Claude Code when to run it. People get this wrong constantly, so plant the flag early: hooks are registered in settings.json. There is no hooks folder. A script sitting in a folder that nothing points to is a doorbell nobody wired up.

Part one: the registration

Here is a complete, real registration:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "./scripts/check-command.sh" }
        ]
      }
    ]
  }
}

Read it from the outside in. PreToolUse is the moment. The matcher narrows it: this hook only cares about Bash tool calls, so file reads and edits skip it entirely. And the command is the script to run. That is the whole wiring.

Part two: the script

This is the actual command blocker from this module's demo, and it is deliberately boring:

#!/bin/bash
# check-command.sh: refuse destructive shell commands
input=$(cat)
if echo "$input" | grep -qE "rm -rf|--force|push.*main"; then
  echo "Blocked: destructive command. Archive instead of deleting." >&2
  exit 2
fi
exit 0

The verdict: exit codes

Two things carry all the meaning:

• The input. The script receives the details of what Claude is about to do on standard input, as JSON, so it can inspect the actual command.
• The exit code. Exit 0 means proceed. Exit 2 means block, and whatever the script printed to standard error gets handed back to Claude as feedback.

That feedback channel is why the message says what to do instead. Claude reads "archive instead of deleting" and proposes exactly that on its next attempt. A good block message is not just a wall; it is a redirect. For richer control, a hook can print JSON to standard output instead (deciding to allow, deny, or ask, with a reason attached), but exit codes cover most real uses and are where to start.

4 · Four hooks worth stealing

These four patterns cover most of what teams actually deploy. The map first, then each one in turn:

The command blocker

A PreToolUse hook on Bash, and about ten lines of script: read the proposed command, grep it for destructive patterns like rm -rf, a force push, or a push straight to main, and exit 2 with a message that points at the archive instead. (For anyone new to terminals: rm -rf is the delete command with every safety removed. It erases a folder and everything inside it, forced, no confirmation, no trash can, no undo. One wrong path and months of work vanish in under a second.) Every team's first hook, and rightly so, because it converts the scariest failure mode into a non-event.

The secret scanner

Before any file gets written, scan the content for things that look like credentials: sk-ant, AKIA, BEGIN PRIVATE KEY, connection strings. Block on a match. This is the hook that makes "we never commit secrets" true instead of aspirational:

input=$(cat)
if echo "$input" | grep -qE "sk-ant-|AKIA[A-Z0-9]{16}|BEGIN.*PRIVATE KEY"; then
  echo "Blocked: this write contains something that looks like a credential." >&2
  exit 2
fi
exit 0

The audit log

After every tool call, append one line to a log file: timestamp, tool, what it did. It never blocks anything; it just remembers. Unremarkable until the day someone asks "what exactly did the AI change last Tuesday?", at which point it is the most valuable file in the repo. Your compliance colleagues will receive this hook the way other people receive gifts.

The auto checker

After a file changes, run the formatter or the test suite and feed failures back. This one turns "please remember to run the tests" from a CLAUDE.md request into a thing that simply happens.

One warning that applies to all four: hooks make Claude wait

Hooks run synchronously. When one fires, everything stops until the script finishes: Claude proposes an action, your script runs, and only when it exits does the action proceed. One slow hook does not feel slow once. It feels slow four hundred times.

Do the arithmetic on a real afternoon. A busy session makes something like 40 file writes. A secret scanner that greps the content takes about a twentieth of a second, so all 40 checks together cost two seconds, spread so thin nobody ever notices them. Now replace that grep with a call to some external scanning service that takes 10 seconds per check. Same afternoon, same 40 writes, and the session now contains almost seven minutes of pure waiting, served ten seconds at a time to a person trying to work. That person will blame the assistant. Nobody ever blames the hook.

• Keep the script itself fast. A grep, a pattern match, a file append. A network call inside a hook is a seven minute afternoon waiting to happen.
• Scope with matchers. The secret scanner watches Write and Edit only, so the hundreds of reads and searches in a session never pay for it.
• The audit log is the working exception. It watches everything on purpose, and stays invisible anyway, because appending one line to a file costs nearly nothing.

5 · Shared hooks are a trust boundary

Commit settings.json to the shared repo and consider what one file now governs. Five consultants. Every session any of them opens. Every command any of those sessions proposes, all day, for the life of the engagement. That is a great deal of authority for one small file in a git repo. And it cuts in two directions, because the same commit that protects everyone also hands everyone the ability to edit the protections. Both edges matter, so take them one at a time.

The payoff: protection that distributes itself

Every teammate who pulls the repo inherits the same locks, automatically:

• The destructive command that gets blocked on your machine gets blocked on all five machines.
• New joiners are protected on day one, before they know there is anything to be protected from.
• Nobody has to remember to be careful. The protection needs no training, no memory, and no goodwill.

This is the first layer of the governance model the course assembles at the end: rules that enforce themselves, distributed through git like any other code.

The exposure: the locks are editable

But notice what you just built: a file that controls what five people's AI sessions can and cannot do, editable by anyone with push access. Play out how that goes wrong, without anyone meaning harm:

• A helpful teammate "simplifies" settings.json and quietly weakens a matcher.
• A Friday afternoon cleanup commit deletes the secret scanner entry entirely.
• Five people's sessions lose a protection nobody remembers relying on, and nothing announces the change.

The rule that protects the rules

Hook changes get reviewed like code changes, because they are code changes, with higher blast radius than most. Concretely:

• Any pull request touching settings.json or anything in scripts/ gets a second set of eyes. Every time, no exceptions for small diffs.
• For rules that even the repo must not be able to weaken, use the enterprise managed settings layer, the IT installed policy file. It sits above every repo and cannot be overridden from below.

6 · Case study: the repo with no locks

The setup

Back to the five consultant team at the regional health plan. By this point in their story, the second brain is humming: the skills are discoverable (the folder moved to the right address, the descriptions got rewritten to fire), sessions find the right files on the first search, and every consultant runs Claude Code against the shared repo all day. Five people, dozens of tool calls each per session, every one of those calls able to read, write, and run commands. And the number of hooks in the repo: zero. Everything that happens is governed by good manners and nothing else. For months, good manners held. Then one ordinary week showed the team what they had been trusting to luck.

Monday: one tidy up away from data loss

A consultant wraps a workstream and asks their session to clean out the old draft folders. Claude reaches for rm -rf. In this repo, nothing stands between that proposal and the disk:

• No hook inspects the command. It runs the moment the consultant approves, and approving tidy ups is a reflex.
• Anything uncommitted, and anything git was told to ignore, has no second copy. Client source files in data/raw/ fall in exactly that category.
• The CLAUDE.md rule "never modify data/raw" was in the window the whole time. It is a sign, and this was the afternoon the sign got skimmed.

Wednesday: nothing reads what gets written

Another consultant is building a small script that downloads monthly claims numbers from the client's reporting system. To log in, the script needs a credential: a long secret key the client issued, the digital equivalent of a password. The consultant asks Claude to save the connection settings in a file, and the file Claude writes has that credential pasted directly into it:

• No scanner looks at file content before it lands. The write succeeds instantly.
• One git push later, the credential is in the repo history on five machines, and scrubbing git history is an afternoon of work with a tool nobody enjoys.
• At a health plan, a leaked credential is not an oops. It is a reportable event with a form attached.

Friday: no answer to "what changed?"

The engagement partner reviews the client materials, notices a reworded risk statement, and asks a fair question: what exactly did the AI change in here this week?

• Git shows commits, and commits show who pushed, but nothing records what the AI sessions actually did tool call by tool call.
• The honest answer in the room is: nobody can say. In front of a client, that sentence costs more than any hook ever will.

Three scripts, three different sentences

Now replay the same week with this chapter's three hooks in place:

• The command blocker turns Monday into a non-event: the delete is blocked, the block message redirects, and the drafts move to an archive folder instead. Four seconds.
• The secret scanner turns Wednesday into a blocked write with an explanation, and the credential goes to an environment variable instead of git history.
• The audit log turns Friday's question into a one minute lookup: every tool call, timestamped, blocks included.

# .env  (gitignored, stays on this machine only)
CLAIMS_API_KEY=sk-live-4471-xxxx-xxxx

# settings.py  (committed, safe to share with anyone)
api_key = os.environ["CLAIMS_API_KEY"]

What it costs the team

Here is the part that makes hooks an easy sell in any governance conversation: the price of all three protections, for the people being protected, is nothing. Nobody changes how they work. Nobody remembers anything. Nobody even needs to know the hooks exist. Three small scripts, one settings file, one code review habit, and the team's worst week becomes three non-events. That is enforcement by mechanism: governance that does not depend on training, memory, or mood, and the first concrete layer of the governance model the course assembles at the end.

7 · Demo: watch the hooks get built, then build yours

▶ Watch the demo: building your guardrails · 4 min

The prompt pack: every demo prompt, cleaned and explained

The opening video showed one hook saying no. This demo builds all three, prompt by prompt: the command blocker (script, redirect message, and registration asked for in a single plain instruction), the secret scanner scoped to Write and Edit, and the audit log with no matcher at all. Then five tests run in a fresh session, and the last one is the keeper: the registration gets removed on purpose while the script stays put, and the destructive command sails straight through. Nothing teaches the wiring rule faster.

Then run the pack in your own repo. The prompt pack linked above holds every prompt from the demo, cleaned up and explained. Copied as is or rephrased in your own words, check what the demo checked as you go:

• An rm -rf request gets blocked, and Claude proposes a safer alternative on its own. The redirect is the block message doing its job.
• Saving a file with a fake key like sk-ant-test123 gets blocked by the scanner.
• logs/audit.log shows every tool call with a timestamp, blocks included.
• A plain file read runs untouched. Matchers are working when hooks stay out of the way.
• With the registration removed (script intact), the blocked command sails through. Put the registration back.

8 · Wrap-up: what you should be able to do cold

• Explain signs versus locks to a teammate, with one example of each done properly
• Name the lifecycle events and say which one can block, and why that one matters most
• Write the settings.json registration from memory: event, matcher, command
• Explain exit 0 versus exit 2, and why a block message should redirect, never just refuse
• Describe the four production patterns and what each protects against
• Make the case for hook changes getting code review, in one paragraph, to a skeptic
• Connect settings hooks to the exam's Agent SDK framing: intercept, gate, normalize

Readings

Claude Code docs on Hooks, including the hooks reference for events and JSON output (code.claude.com/docs), and the Agent SDK documentation on hooks for the TS 1.5 framing.

Take the Module 03 quiz →  then hit the Study App for Domain 1, lesson 1.5.