Claude Hooks: Deterministic Guardrails for Tool Calls

1.Why a guardrail belongs in a hook, not in the prompt

Suppose an agent can run shell commands and edit files, and you never want it to run rm -rf or overwrite a .env file. You could write that rule into the system prompt or CLAUDE.md. Claude would usually follow it. But an instruction in context is something the model weighs against everything else it is reading, and 'usually' is not a safety control.

A hook moves the rule out of the model and into code that the harness runs. Anthropic's tips describe hooks as a way to deterministically run logic at points in the agent lifecycle. The Agent SDK documentation puts the safety use first in its list of what hooks are for: they can block dangerous operations before they run, like destructive shell commands or unauthorized file access. The same list also covers auditing every tool call, sanitizing inputs and outputs, and requiring human approval for sensitive actions like database writes.

The split to remember: the prompt shapes what Claude *tries* to do, and the hook decides what is actually *allowed* to happen. A hook doesn't need the model to agree with it.

Sources12

2.Which events can stop an action, and which only see it

Claude Code emits many hook events, but not all of them can serve as a guardrail. What matters is when an event fires compared with the action it describes. PreToolUse and PostToolUse both fire on every tool call in the agentic loop (EndConversation calls skip both). Only PreToolUse fires *before* execution, and the hooks reference says plainly that it can block the call. PostToolUse fires after a tool call succeeds. By then the file is already written or the command has already run, so a PostToolUse hook suits formatting, logging or audit work, not prevention.

A handful of other events are also documented with a blocking or modifying role. The table below keeps to that wording.

Sources32

3.How a hook resolves: event, matcher, if condition, handler

Configuring a hook takes three choices: an event to respond to (such as PreToolUse), a matcher group that filters when it fires (such as 'only for the Bash tool'), and one or more handlers to run on a match. At runtime Claude Code works through the same chain in order. The event fires with a JSON payload such as { "tool_name": "Bash", "tool_input": { "command": "rm -rf /tmp/build" } }. The matcher checks the tool name. An optional if condition narrows the match further using permission-rule syntax. The handler runs, and Claude Code acts on what it returns.

In the reference example below, the matcher limits the hook to Bash, and "if": "Bash(rm *)" means the script only starts for rm commands, not for every shell call.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

The type field picks the kind of handler. There are five documented types, and they differ in where the guardrail logic actually runs.

Sources34

4.Where a guardrail is configured decides who it protects

A hook only protects the sessions that load it, so where you put it is part of the design. The hooks reference lists these locations:

A guardrail the whole team relies on belongs in .claude/settings.json, committed to the repo. If the organization has to enforce it, managed policy settings are the place. Managed policy can also lock the setup down: the reference describes a managed configuration in which user, project, local and plugin hooks are all blocked, apart from plugins that managed settings force-enable. HTTP handlers can be restricted as well. When allowedHttpHookUrls is defined, Claude Code runs an HTTP hook only if its URL matches the merged allowlist.

Sources3

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.A PostToolUse hook that detects rm -rf in the command can stop the deletion.Why is that wrong?

   PostToolUse fires only after the tool call has succeeded, so the deletion has already happened. Prevention needs PreToolUse, which fires before the call executes and can block it.

   Covered in Which events can stop an action, and which only see it

2. 2.Putting a guardrail hook in .claude/settings.local.json shares it with everyone who works on the project.Why is that wrong?

   The local settings file is project-scoped but not shareable. It is gitignored when Claude Code saves a setting to it. For a team-wide hook, commit it in .claude/settings.json, or use managed policy settings to enforce it across the organization.

   Covered in Where a guardrail is configured decides who it protects