# Claude Code hooks explained: config structure, matchers, and a copy-paste PreToolUse guard

> Source: <https://dev.to/rulestack/claude-code-hooks-explained-config-structure-matchers-and-a-copy-paste-pretooluse-guard-58jj>
> Published: 2026-07-24 16:53:57+00:00

If you have only ever used Claude Code's permission prompts, hooks are the next layer down: deterministic shell commands (or HTTP endpoints, MCP tools, prompts, or subagents) that fire at fixed points in a session and can **block, allow, or reshape** what happens next. The feature is powerful, but the configuration has a few sharp edges that trip people up — especially the JSON your hook prints back, which changed and is easy to get wrong from memory.

This post walks through the current config structure, the two ways a hook reports a decision, and a copy-paste `PreToolUse`

guard that blocks recursive `rm`

.

Hooks live in a settings file (`.claude/settings.json`

for a project, `~/.claude/settings.json`

for your user). The shape is three levels of nesting, and naming them makes the rest of the docs click:

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

`PreToolUse`

) — the lifecycle point. Events fall into three cadences: once per session (`SessionStart`

, `SessionEnd`

), once per turn (`UserPromptSubmit`

, `Stop`

), and on every tool call (`PreToolUse`

, `PostToolUse`

).`"matcher": "Bash"`

) — a filter for `tool_name`

.`hooks`

array) — the thing that actually runs. There are five types: `command`

, `http`

, `mcp_tool`

, `prompt`

, and `agent`

.The `if`

field narrows further using permission-rule syntax — `Bash(rm *)`

here means "only spawn this handler when the Bash subcommand matches `rm *`

," so the script never even launches for `npm test`

. It holds exactly one rule; there is no `&&`

or `||`

, so multiple conditions mean multiple handlers.

A matcher that contains regex characters is tested with JavaScript's `RegExp.prototype.test`

, which succeeds on a match **anywhere** in the value. So:

`Edit`

also matches `NotebookEdit`

. If you mean only the `Edit`

tool, write `^Edit$`

.`mcp__<server>__<tool>`

. A bare `mcp__memory`

is treated as an exact string and matches `.*`

suffix: `mcp__memory__.*`

for every tool from the `memory`

server.If you want a handler to run on every occurrence of an event, omit the matcher or use `"*"`

.

This is where most confusion lives. A command hook communicates results through **exit codes and stdout**, and you choose *one* of two modes:

**Exit codes alone.** Exit `0`

means success and no decision (staying silent does **not** approve a call — it just lets the normal permission flow continue). Exit `2`

is a blocking error: Claude Code ignores stdout and feeds your **stderr** back to Claude as the reason. For `PreToolUse`

, exit 2 blocks the tool call.

**Exit 0 plus JSON on stdout.** For finer control, exit `0`

and print a JSON object. Claude Code only parses JSON on exit 0 — if you exit 2, any JSON is ignored. You must choose one approach per hook, not both.

`decision: "block"`

If you learned hooks a while ago, you probably remember a top-level `{"decision": "block"}`

. **That is deprecated for PreToolUse.** This event now returns its decision inside a

`hookSpecificOutput`

object with a required `hookEventName`

, and the field is `permissionDecision`

with four possible values: `allow`

, `deny`

, `ask`

, or `defer`

. (The old `"approve"`

/`"block"`

map to `"allow"`

/`"deny"`

.) Other events like `PostToolUse`

and `Stop`

still use the top-level `decision`

/`reason`

fields — so the format genuinely differs per event, and copying a `PostToolUse`

snippet into `PreToolUse`

won't work.Here is the correct current shape for a `PreToolUse`

deny:

```
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Recursive rm is blocked. Delete specific files instead."
  }
}
```

`rm`

Save this as `.claude/hooks/block-rm.sh`

and `chmod +x`

it. It reads the event JSON on stdin, pulls the Bash command with `jq`

, and denies anything with a recursive `rm`

:

``` bash
#!/usr/bin/env bash
# PreToolUse hook: deny recursive rm, stay silent otherwise.
# Requires jq on PATH.
input=$(cat)
command=$(printf '%s' "$input" | jq -r '.tool_input.command // ""')

if printf '%s' "$command" | grep -qiE '(^|[[:space:]])rm[[:space:]]+(-[a-z]*r|--recursive)'; then
  cat <<'JSON'
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Recursive rm is blocked by a project hook. Delete specific files instead."
  }
}
JSON
  exit 0
fi

# No decision: exit 0 with no output lets the normal permission flow decide.
exit 0
```

With the settings above, the `if: "Bash(rm *)"`

filter means the script only spawns for `rm`

commands (saving the process launch on unrelated calls), and the matcher keeps it scoped to Bash. When Claude tries `rm -rf /tmp/build`

, the hook prints the deny JSON, Claude Code blocks the call, and Claude sees the reason.

A note on paths: `${CLAUDE_PROJECT_DIR}`

is substituted by Claude Code to your project root, so the hook resolves no matter what the working directory is at call time. If your project path contains spaces, switch the handler to exec form (set `args`

) so each element is passed as one argument with no shell quoting.

Hooks are the deterministic guardrail layer. Two neighbors worth knowing:

`if`

filter is best-effort.`if`

filter fail open and run your hook anyway.Type `/hooks`

in Claude Code to open a read-only browser of everything you have configured, including which settings file each hook came from — a fast way to confirm your matcher is actually matching.

*I'm Rulestack — I build and maintain drop-in rule and hook packs for Claude Code, Cursor, and Codex. There's a Claude Code Hooks Pack of production-ready guardrails if you'd rather not hand-roll each one. I post working AI-coding tips on Bluesky at @ai-shop.bsky.social — follow along if this was useful.*