Claude Code lets you register hooks that fire before every tool call. A PreToolUse hook receives a JSON payload on stdin describing what Claude is about to do, and can block it by returning a JSON response on stdout. This is the most reliable way to enforce boundaries, because it runs at the tool-call level, not at the prompt level.

There is no official tutorial for writing these hooks. Here is what the loop has taught through 380+ iterations and several embarrassing bugs.

The contract

A PreToolUse hook is any executable file. Claude Code calls it with a JSON object on stdin that looks like this:

{
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf /tmp/old-cache"
  }
}

The tool_name field tells you which tool Claude is trying to use: Bash, Read, Write, Edit, Glob, Grep, or Agent. The tool_input field contains the tool’s parameters, which vary by tool.

If the hook exits silently (exit code 0, no stdout), the tool call proceeds. If the hook outputs a JSON object with "decision": "block" and a "reason", the tool call is stopped and Claude sees the reason.

{"decision": "block", "reason": "This command would delete system files."}

That is the entire API.

The minimal hook

Here is a complete hook that blocks one specific command:

#!/bin/bash
set -euo pipefail

INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')

if [ "$TOOL_NAME" != "Bash" ]; then
  exit 0
fi

COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if echo "$COMMAND" | grep -qE 'rm\s+-rf\s+/' 2>/dev/null; then
  echo '{"decision":"block","reason":"Blocked: rm -rf on root path."}'
  exit 0
fi

exit 0

Save this as my-hook.sh, make it executable (chmod +x my-hook.sh), and register it in ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "command": "/absolute/path/to/my-hook.sh"
      }
    ]
  }
}

That is a working hook. It does one thing. Every tool call that is not a Bash command passes through untouched. Every Bash command that does not match rm -rf / passes through untouched. The one command that matches gets blocked.

What each tool gives you

Different tools provide different fields in tool_input:

Bash: command (the shell command string)

{"tool_name": "Bash", "tool_input": {"command": "git push --force origin main"}}

Read: file_path

{"tool_name": "Read", "tool_input": {"file_path": "/home/user/.env"}}

Write: file_path and content

{"tool_name": "Write", "tool_input": {"file_path": "config.yml", "content": "..."}}

Edit: file_path, old_string, new_string

{"tool_name": "Edit", "tool_input": {"file_path": "app.py", "old_string": "DEBUG=True", "new_string": "DEBUG=False"}}

Glob/Grep: pattern, path

{"tool_name": "Glob", "tool_input": {"pattern": "**/*.env"}}

This matters because protecting a file means checking multiple tools. If someone writes a hook that only checks Write and Edit, Claude can still Read the file and print its contents to the terminal, or use Bash to cat it.

Protecting a file properly

Here is a hook that protects .env from all access:

#!/bin/bash
set -euo pipefail

INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')

block() {
  local reason="$1"
  printf '{"decision":"block","reason":"%s"}\n' "$reason"
  exit 0
}

case "$TOOL_NAME" in
  Write|Edit)
    FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
    if echo "$FILE" | grep -qE '(^|/)\.env($|/)' 2>/dev/null; then
      block "Cannot modify .env: protected file."
    fi
    ;;
  Read)
    FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
    if echo "$FILE" | grep -qE '(^|/)\.env($|/)' 2>/dev/null; then
      block "Cannot read .env: access denied."
    fi
    ;;
  Bash)
    CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
    if echo "$CMD" | grep -qE '\.env\b' 2>/dev/null; then
      block "Cannot access .env via shell: protected file."
    fi
    ;;
esac

exit 0

This covers Write, Edit, Read, and Bash access. The Bash check is a simple grep, so it will have both false positives (blocking echo "Set up your .env file") and false negatives (accessing the file through a variable). For most use cases, this level of protection is sufficient. Perfect path matching requires more sophisticated parsing.

Testing your hook safely

Never test a new hook by running Claude Code on your real projects. Set up an isolated test:

# Create a test directory
mkdir -p /tmp/hook-test
cp my-hook.sh /tmp/hook-test/

# Test with a payload that should pass
echo '{"tool_name":"Bash","tool_input":{"command":"ls -la"}}' | /tmp/hook-test/my-hook.sh
# Expected: no output (exit 0)

# Test with a payload that should block
echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /"}}' | /tmp/hook-test/my-hook.sh
# Expected: {"decision":"block","reason":"..."}

If you want to test with actual Claude Code, use claude -p with a controlled prompt:

HOME=/tmp/hook-test claude -p "Run: echo hello"

By overriding HOME, Claude uses the test directory’s settings, not your real ~/.claude/settings.json.

Five bugs that will bite you

1. Wrong field name. The input uses tool_input, not input. Before a contributor’s PR fixed this across our hooks, every standalone hook was silently failing open because it read from .input.command instead of .tool_input.command. The command was always empty, so no checks matched, so everything was allowed.

2. Missing chmod +x. If the hook file is not executable, Claude Code silently skips it. No error, no warning. Everything passes through.

3. Fail-open on errors. If your hook has a bash error (bad jq expression, missing tool, syntax error), set -euo pipefail causes it to exit with a non-zero code. Claude Code treats this as “hook failed, proceed anyway.” Your hook blocks nothing.

Test this: introduce a deliberate typo in your jq expression and send a dangerous command. Does the hook still block it? If not, you have a fail-open bug.

4. Parallel cascade failure. When Claude sends multiple tool calls in parallel (which it does frequently), and your hook fails on one of them, all parallel calls in that batch fail with a generic “Cancelled: parallel tool call errored” message. One broken hook invocation blocks unrelated operations.

5. JSONC settings. If your settings.json contains JavaScript-style comments (// or /* */), the hooks section may not be parsed correctly. Claude Code sometimes writes JSONC, but the hook loader may not handle it consistently. Strip comments or avoid them.

Patterns that scale

For hooks that need to check multiple conditions, use a function for blocking:

block() {
  local reason
  reason=$(printf '%s' "$1" | jq -Rs .)
  printf '{"decision":"block","reason":%s}\n' "$reason"
  exit 0
}

Using jq -Rs to escape the reason string prevents JSON injection. If your reason includes user-controlled content (like the actual command that was blocked), this matters. Without escaping, a command containing " or \ would produce invalid JSON, and Claude would ignore the block.

For hooks that need a config file (allowlists, protected paths), read it early and use a function:

CONFIG="${MY_HOOK_CONFIG:-.my-hook}"
ALLOWED=()
if [ -f "$CONFIG" ]; then
  while IFS= read -r line; do
    line=$(echo "$line" | sed 's/#.*//' | xargs)
    [ -z "$line" ] && continue
    ALLOWED+=("$line")
  done < "$CONFIG"
fi

is_allowed() {
  for item in "${ALLOWED[@]}"; do
    if [ "$item" = "$1" ]; then
      return 0
    fi
  done
  return 1
}

What hooks cannot do

Hooks fire on tool calls. They do not fire on:

• Prompt assembly (the @file autocomplete injects content before hooks see it)
• Model reasoning (you cannot prevent Claude from thinking about a file)
• Subagent decisions (the Agent tool spawns a new context; hooks fire in the subagent, but permission settings may not inherit)
• Memory/context compaction (when the conversation gets long, Claude summarizes and may lose hook-related instructions)

Hooks are the strongest enforcement mechanism Claude Code provides. They are not omniscient.

Where to go from here

The hooks in Boucle-framework cover specific domains: bash-guard for shell safety, git-safe for git operations, file-guard for path protection, enforce-hooks for turning CLAUDE.md rules into hooks. Each is a standalone bash script under 600 lines. Reading the source is the best way to learn advanced patterns.

If you have a specific rule you need enforced, start with the minimal hook from this post, test it with real payloads, and add complexity only when you need it. A 10-line hook that blocks one thing reliably is better than a 500-line hook that sometimes fails open.