Claude Code Hooks: Block, Format, and Gate Tool Calls

A hook is a handler attached to an event. Claude Code fires events at points in its lifecycle, and every handler registered for that event (and whose matcher fits) runs. The most used events are:

• PreToolUse: before a tool call runs. It can block the call, ask the user, or rewrite the call's input.
• PostToolUse / PostToolUseFailure: after a tool call succeeds or fails. The tool has already run.
• UserPromptSubmit: when you submit a prompt, before Claude sees it. It can block the prompt or add context.
• Stop: when Claude finishes a reply. It can send Claude back to keep working.
• SessionStart: on startup, resume, /clear, or after compaction. Its plain stdout is added to Claude's context.
• Notification: when Claude Code would notify you, for example when it needs a permission decision or has been idle.

The reference lists many more, including PermissionRequest, PreCompact, SubagentStop, ConfigChange, FileChanged, and SessionEnd.

Configuration nests three levels: the event name, a list of matcher groups, and for each group a list of handlers. For tool events the matcher is the tool name: Bash, Edit|Write, or a regular expression such as mcp__.*. Matchers are case-sensitive.

1{2  "hooks": {3    "PostToolUse": [4      {5        "matcher": "Edit|Write",6        "hooks": [7          { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }8        ]9      }10    ]11  }12}

Hooks can live in ~/.claude/settings.json (all your projects), .claude/settings.json (committed, shared with the team), .claude/settings.local.json (yours, not committed), managed policy settings, a plugin's hooks/hooks.json, or the frontmatter of a skill or subagent. Entries from different files are merged, not replaced. Run /hooks to browse every configured hook and see which file it came from.

A command hook receives one JSON object on stdin. Every event includes common fields such as session_id, transcript_path, cwd, permission_mode, and hook_event_name. Tool events add tool_name, tool_input, and tool_use_id; PostToolUse also adds tool_response. For a Bash call, tool_input.command holds the command text. For Edit and Write, tool_input.file_path holds the target file.

The hook answers through its exit code and, optionally, JSON on stdout:

• Exit 0: success. If stdout is a JSON object, Claude Code parses it for decisions. Plain-text stdout is added to Claude's context only for a few events, such as SessionStart and UserPromptSubmit.
• Exit 2: a blocking error. On events that can block, the action stops and stderr becomes the reason. For PreToolUse, Claude reads that reason and can change course.
• Any other code: a non-blocking error. The action continues and a hook-error notice appears in the transcript.

For finer control, exit 0 and print JSON. A PreToolUse hook sets hookSpecificOutput.permissionDecision to allow, deny, ask, or defer, with a permissionDecisionReason. Build that JSON with jq rather than string concatenation, so quotes in the reason do not break it:

1jq -n --arg reason "Edits to migrations/ need a human." '{2  hookSpecificOutput: {3    hookEventName: "PreToolUse",4    permissionDecision: "deny",5    permissionDecisionReason: $reason6  }7}'

Pick one style per hook. Exit 2 blocks even if the same hook also printed JSON that allows the action.

PreToolUse is the event for policy. It fires before the permission-mode check, in every mode, including bypassPermissions and --dangerously-skip-permissions. A hook that denies or exits 2 blocks the call in all of them, which is why teams use hooks for rules that must not depend on which mode someone picked.

This script refuses pushes that target main, or that run while main is checked out:

1#!/bin/bash2# .claude/hooks/block-main-push.sh3CMD=$(jq -r '.tool_input.command // empty')4 5case "$CMD" in6  *git*push*)7    BRANCH=$(git -C "$CLAUDE_PROJECT_DIR" rev-parse --abbrev-ref HEAD 2>/dev/null)8    if [[ "$CMD" == *" main"* || "$CMD" == *":main"* || "$BRANCH" == "main" ]]; then9      echo "Pushing to main is blocked. Push a feature branch and open a pull request." >&210      exit 211    fi12    ;;13esac14exit 0

The second guard comes from the official guide: it blocks edits to .env, package-lock.json, and anything under .git/.

1#!/bin/bash2# .claude/hooks/protect-files.sh3FILE_PATH=$(jq -r '.tool_input.file_path // empty')4for pattern in ".env" "package-lock.json" ".git/"; do5  if [[ "$FILE_PATH" == *"$pattern"* ]]; then6    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&27    exit 28  fi9done10exit 0

Register both, make them executable with chmod +x, and quote the project-dir variable:

1{2  "hooks": {3    "PreToolUse": [4      {5        "matcher": "Bash",6        "hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-main-push.sh" }]7      },8      {9        "matcher": "Edit|Write",10        "hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh" }]11      }12    ]13  }14}

PostToolUse fires after a tool succeeds. The tool has already run, so the hook cannot undo anything. It is the place for work that should follow every edit: formatting, a quick lint, a log line.

The formatter hook from the earlier example runs Prettier on each file Claude edits. With Prettier's defaults, ask Claude to add a line with single-quoted strings to a JavaScript file, and the file ends up with double quotes, without Claude being asked.

A PostToolUse hook can also feed information back. Exit 2 shows stderr to Claude, and the JSON field decision: "block" with a reason adds that reason next to the tool result. Both tell Claude something went wrong after the fact, for example that the file it just wrote fails type checking.

Slow work, such as a test suite, should not hold up every edit. Add "async": true to a command hook and it runs in the background. When it finishes, its additionalContext and systemMessage reach Claude on the next turn:

1{2  "hooks": {3    "PostToolUse": [4      {5        "matcher": "Write",6        "hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/run-tests.sh", "async": true }]7      }8    ]9  }10}

Async hooks cannot block anything. decision, permissionDecision, and continue have no effect, because the action they would control has already finished.

A Stop hook runs whenever Claude finishes a reply. If it exits 2, Claude keeps working and reads stderr as the reason. That turns "make sure tests pass" from a request into a gate:

1#!/bin/bash2# .claude/hooks/tests-must-pass.sh3INPUT=$(cat)4if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then5  exit 0   # already sent back once; let Claude stop6fi7 8cd "$CLAUDE_PROJECT_DIR" || exit 09LOG=$(mktemp)10if ! npm test --silent >"$LOG" 2>&1; then11  echo "Tests are failing. Fix them before finishing:" >&212  tail -n 30 "$LOG" >&213  exit 214fi15exit 0

The stop_hook_active check matters. It is true when Claude is already continuing because of a Stop hook, and without it a test that can never pass sends Claude around in circles. Claude Code also has its own limit: after eight consecutive blocks with no tool call in between, it overrides the hook and ends the turn. You can raise the cap with CLAUDE_CODE_STOP_HOOK_BLOCK_CAP.

SessionStart with the compact matcher solves a different problem. Compaction summarises the conversation and can drop details. Plain stdout from a SessionStart hook is added to Claude's context, so you can restore the essentials after every compaction:

1{2  "hooks": {3    "SessionStart": [4      {5        "matcher": "compact",6        "hooks": [{ "type": "command", "command": "echo 'Use pnpm, not npm. Current task: auth refactor.'; git log --oneline -5" }]7      }8    ]9  }10}

For instructions you want in every session, CLAUDE.md is simpler; this hook is for re-adding what compaction loses. See Claude Code Context Window for how compaction works.

Command hooks run with your full user permissions. They can read, change, or delete anything your account can. That cuts both ways: it is what makes them useful, and it is why a hook from someone else's repository deserves the same review as any script you are about to run.

The workspace-trust rules decide when repository hooks run:

• Interactive sessions hold back hooks from every settings file, including your own, until you accept the workspace trust dialog for the folder.
• claude -p and SDK sessions never show the dialog and treat the folder as trusted. Hooks committed in a repository's .claude/settings.json run even if you have never opened the folder before.

Before scripting claude -p over a repository you did not write, read its .claude/ settings, or run with --settings '{"disableAllHooks": true}'. Organisations can set allowManagedHooksOnly in managed settings so that only admin-approved hooks run.

When a hook misbehaves, test it outside Claude Code first by piping sample input into it:

1echo '{"tool_name":"Bash","tool_input":{"command":"git push origin main"}}' \2  | CLAUDE_PROJECT_DIR=$PWD .claude/hooks/block-main-push.sh3echo "exit: $?"

Then check the debug log. Start Claude Code with claude --debug and read ~/.claude/debug/<session-id>.txt, or choose the location with --debug-file <path>. Each command hook leaves a line with its event, command, exit status, and duration.

Use the simplest mechanism that holds. Permission rules are declarative and need no code; use them for fixed lists of allowed or forbidden tools, paths, and commands. Hooks are for checks that need logic, such as reading the current branch, parsing a file, or calling a service, and for actions that must always follow an event. CLAUDE.md is for conventions where judgment is fine and an occasional miss costs little.

They also combine. A deny rule on Read(./.env) plus a PreToolUse hook on Edit|Write plus the sandbox covers far more paths to a secret than any one of them alone.

In a scratch Git repository with a package.json and a test script:

1. Add block-main-push.sh and protect-files.sh from the PreToolUse section, run chmod +x on both, and register them in .claude/settings.json. 2. Pipe sample JSON into each script, as in the debugging section, and confirm exit: 2 for a push to main and for an edit to .env, and exit: 0 for git status. 3. Start Claude Code, run /hooks, and confirm both appear under PreToolUse from the project settings file. 4. Ask Claude to add a comment to .env, then to commit and push to main. 5. Add the Stop hook, break one test on purpose, and ask Claude to "rename a variable and finish".

Pass criterion: the .env edit and the push are both blocked with your messages shown; Claude offers a feature branch instead of pushing; the Stop hook sends Claude back once with the failing test output, and the turn ends after the fix or after the second stop.