CCDV-F 7.3 — Hooks as safety controls

Where a hook sits in the tool loop

Claude

Harness

Hook

Tool

Requests Bash(rm -rf …)

PreToolUse with tool_input

Exit 2 · deny + reason

Blocked, with the reason

Tries a safe alternative

Allowed — tool runs

PreToolUse runs between the model asking and the tool running — the only point at which an action can still be stopped.

What a hook actually is

A hook is a handler you configure to run at a named point in the agent's lifecycle. It receives JSON describing what is about to happen — the session id, the working directory, the event name, and for tool events the tool_name and the tool_input — and it answers by exit code and by JSON on standard output. Handlers can be a shell command, an HTTP endpoint, a tool on an MCP server, or a prompt or subagent evaluated by a model.

The crucial property is that a hook is ordinary code. It runs whether or not the model is having a good day, its decision does not depend on how the request was phrased, and you can unit-test it. That is what makes it the right instrument for preventing destructive actions, and it is the comparison every exam item about hooks is drawing.

Control	Runs	Decides by	Good for
An instruction in the prompt or `CLAUDE.md`	When the model attends to it	Model judgement	Style, conventions, preferences
A permission allow/deny rule	Every matching tool call	Configured patterns	Broad policy on named tools and commands
A hook	Every matching event	Your code, on the actual input	Context-dependent safety checks, audit, blocking
Sandboxing	Every command	Filesystem and network isolation	Enforcement that does not depend on command text

Blocking a destructive action

PreToolUse is the event that can stop something. A hook blocks by exiting with status 2, and it should also return JSON naming the decision and the reason so the model learns why and can try something else. Exit 0 means the hook has no objection and normal permission handling continues; any other exit status is a non-blocking error and the action proceeds.

A `PreToolUse` hook that refuses a destructive commandbash

#!/bin/bash
# .claude/hooks/block-destructive.sh — receives the event JSON on stdin.
COMMAND=$(jq -r '.tool_input.command')

case "$COMMAND" in
  *"rm -rf"*|*"DROP TABLE"*|*"git push --force"*)
    # Tell the model why, then block. Exit 2 is the blocking signal.
    jq -n '{hookSpecificOutput: {
              hookEventName: "PreToolUse",
              permissionDecision: "deny",
              permissionDecisionReason:
                "Destructive command blocked by policy hook."}}'
    exit 2 ;;
esac

exit 0   # No objection — normal permission flow applies.

Hooks are configured in settings, with a matcher selecting which events reach them. A matcher of Bash fires only for the Bash tool, Edit|Write for either of two tools, and anything containing regular-expression characters is treated as a pattern — mcp__.*__.* reaches every tool provided by an MCP server. All matching hooks run in parallel.

Wiring it up in settingsjson

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-destructive.sh",
            "timeout": 10,
            "statusMessage": "Checking command safety..."
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/audit.sh" }
        ]
      }
    ]
  }
}

Exit status	Meaning	Effect on the action
`0`	Success; JSON on stdout is read	Proceeds under normal permission handling
`2`	Blocking error	Blocked on events that support blocking, with the reason passed back
Anything else	Non-blocking error	The action proceeds — the hook failed open
Timed out	Cancelled, output discarded	On `PreToolUse` it does not block

Worked example · Stopping a migration agent from dropping a production table

A platform team lets an agent run schema migrations in a staging environment. During one run it proposes a command that would drop and recreate a table — correct for staging, catastrophic if the connection string ever points at production.

Choose the enforcement point. A rule in the project instructions already said “never drop tables”. It had been followed until the day it was not, which is the nature of advice.
Match narrowly. A PreToolUse hook matches the Bash tool and inspects tool_input.command for destructive SQL verbs.
Decide on context, not just text. The hook reads the target host from the environment. Against staging it allows the command; against anything else it denies.
Explain the refusal. The denial reason tells the model the environment is not permitted, so it proposes a reversible migration instead of retrying the same command.
Fail closed. If the hook cannot determine the environment, it denies. A blocked staging migration costs a few minutes; the alternative does not.
Record it. A PostToolUse hook appends every executed migration, with the session id, to an audit file.

Takeaway: The hook did something no prompt could: it made a decision from information the model never sees — which database the connection actually points at — and enforced it in code.

The other events, and what they are for

Blocking is the headline, but the lifecycle has points for the rest of a safety story too. The documented set is large; a handful carry most of the safety work.

Event	Fires	Typical safety use
`PreToolUse`	Before a tool runs	Block destructive actions; require a condition to hold
`PostToolUse`	After a tool succeeds	Audit log, secret scanning, running a formatter or test
`UserPromptSubmit`	Before Claude processes a prompt	Screen input; add context; block a disallowed request
`SessionStart`	When a session starts or resumes	Load policy or environment; record who started it
`ConfigChange`	When configuration changes	Audit or block changes to settings during a session
`Stop`	When Claude finishes responding	Check the turn's outcome before it is presented

Where the hook is configured decides who can change it. Project settings are shared through version control; a local settings file is personal and not committed; managed policy settings are administered centrally and cannot be overridden by a user. A safety hook that matters to the organisation belongs in managed settings — otherwise the control is only as strong as the most impatient engineer's local configuration.

Choosing the right control

How should this rule be enforced?

A preference or convention
Instructionsguidance the model follows
A named tool or command
Permission ruleallow, ask or deny
Needs your logic or data
PreToolUse hookinspect, decide, exit 2
Must hold whatever the text says
Sandboxfilesystem and network isolation

Hooks are not a replacement for permissions or sandboxing. They are the layer for checks that need your own logic or your own data.

That last branch matters. The security documentation notes that a deny rule matches a command as written, so text-based matching can be evaded by an equivalent command spelled differently; for enforcement that does not depend on the wording, network and filesystem isolation is the stronger instrument. A hook reading tool_input has the same exposure, so treat pattern matching as a filter over an already-restricted environment, not as the wall itself.

Worked example · An audit trail nobody had to remember to write

A regulated team must be able to show, months later, exactly what an agent changed in a repository and who was driving. Developers were asked to record this by hand, and predictably it was patchy.

Pick the event. A PostToolUse hook matching Edit|Write fires after every successful file change.
Capture the facts. It writes the session id, the tool name, the file path and a timestamp to an append-only log.
Scan while you are there. The same hook greps the changed file for credential-shaped strings and raises a warning when it finds one.
Centralise it. The configuration ships as managed settings, so every session in the organisation has it and no local file can turn it off.
Keep it out of the way. It is non-blocking by design: an audit hook that fails should never stop work, which is the opposite of the choice made for the destructive-command hook.

Takeaway: Different events want opposite failure modes. A blocking safety hook fails closed; an observability hook fails open. Decide which one you are writing before you write it.

Traps the wrong answers are built from

Tempting but wrong	Do this instead
Relying on `CLAUDE.md` or the system prompt to forbid destructive commands	Enforce it with a `PreToolUse` hook, a deny rule or a sandbox.
Returning a non-zero exit code other than 2 to block an action	Exit `2`; every other non-zero status is a non-blocking error and the action proceeds.
Letting a safety hook crash or time out unhandled	Fail closed: deny when the check cannot complete, and test that path.
Blocking silently with no reason	Return `permissionDecisionReason` so the model can adapt rather than retry.
Keeping an organisation-wide safety hook in a personal settings file	Ship it as managed policy settings that users cannot override.
Treating string matching on commands as complete protection	Pair it with sandboxing, which does not depend on how the command is spelled.

You should now be able to

Explain what a hook is, what input it receives and how it returns a decision.
Write a PreToolUse hook that blocks a destructive action and explains why.
Choose the right lifecycle event for a given safety or audit requirement.
Configure matchers and pick the settings scope that makes a control enforceable.
Decide whether a hook should fail open or closed, and justify it.

Hooks as safety controls