Claude Code Hooks：让 AI 编程有迹可循、可审计、可回滚

Most people use Claude Code like this: give an instruction, watch the result, undo if something went wrong.

That works. But it has a blind spot: you don’t know what the AI did until it’s already done it.

Claude Code’s Hooks system solves this. It lets you inject custom logic before and after every AI action — not just “allow or deny,” but a fully programmable interception layer.

What Hooks Are

Hooks are shell commands that Claude Code automatically executes when specific events occur.

Four hook events are currently supported:

Each hook can:

• Receive the full context of the tool call (tool name, parameters, results)
• Execute arbitrary shell commands
• Influence tool call behavior (PreToolUse can block execution)

Configuration

Hooks are configured in ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/pre-bash.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/post-write.sh"
          }
        ]
      }
    ]
  }
}

matcher accepts tool names (Bash, Write, Edit, Read, etc.) or * to match all tools.

Example 1: Blocking Dangerous Commands

The most common use case: prevent AI from executing high-risk operations.

~/.claude/hooks/pre-bash.sh:

#!/bin/bash
# Read the tool call JSON input
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""')

# Intercept dangerous patterns
DANGEROUS_PATTERNS=(
  "rm -rf /"
  "git push --force"
  "DROP TABLE"
  "chmod 777"
  "> /dev/sda"
)

for pattern in "${DANGEROUS_PATTERNS[@]}"; do
  if echo "$COMMAND" | grep -qi "$pattern"; then
    echo "Hook blocked: detected dangerous pattern '$pattern'" >&2
    # Exit code 2 = block tool execution and return error
    exit 2
  fi
done

exit 0

Hook exit codes determine behavior:

• 0 — allow execution
• 1 — log a warning but allow execution
• 2 — block execution, return error message to Claude

Example 2: Auto-Backup Before File Writes

Before AI writes to any file, back up the original:

~/.claude/hooks/pre-write.sh:

#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')

if [ -f "$FILE_PATH" ]; then
  BACKUP_DIR="$HOME/.claude/backups/$(date +%Y%m%d)"
  mkdir -p "$BACKUP_DIR"

  # Preserve directory structure in filename
  RELATIVE_PATH=$(echo "$FILE_PATH" | sed 's|/|_|g')
  cp "$FILE_PATH" "$BACKUP_DIR/${RELATIVE_PATH}.bak"

  echo "Backed up: $FILE_PATH -> $BACKUP_DIR" >&2
fi

exit 0

Even if AI corrupts a file, ~/.claude/backups/ always has that day’s version.

Example 3: Operation Audit Log

Record every Claude Code tool call for post-hoc review:

~/.claude/hooks/audit-log.sh:

#!/bin/bash
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // "unknown"')
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
LOG_FILE="$HOME/.claude/audit.log"

# Extract key parameters (avoid logging full file contents)
case "$TOOL_NAME" in
  "Bash")
    DETAIL=$(echo "$INPUT" | jq -r '.tool_input.command // ""' | head -c 200)
    ;;
  "Write"|"Edit")
    DETAIL=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
    ;;
  "Read"|"Glob"|"Grep")
    DETAIL=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.pattern // ""')
    ;;
  *)
    DETAIL=$(echo "$INPUT" | jq -r '.tool_input | to_entries[0].value // ""' | head -c 100)
    ;;
esac

echo "$TIMESTAMP | $TOOL_NAME | $DETAIL" >> "$LOG_FILE"
exit 0

Register this for all tools in PostToolUse:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [{ "type": "command", "command": "~/.claude/hooks/audit-log.sh" }]
      }
    ]
  }
}

By end of day, audit.log has a complete record of everything Claude did.

Example 4: Task Completion Notification

Push a notification when a long task finishes — no need to sit watching the screen:

~/.claude/hooks/notify-done.sh:

#!/bin/bash
INPUT=$(cat)
# Stop hook fires: Claude has finished one round of response

# Read webhook URL from environment variable
if [ -z "$FEISHU_WEBHOOK" ]; then exit 0; fi

curl -s -X POST "$FEISHU_WEBHOOK" \
  -H "Content-Type: application/json" \
  -d '{
    "msg_type": "text",
    "content": { "text": "Claude Code task complete" }
  }' > /dev/null

exit 0

Register this in the Stop hook. After a long compile or large-scale refactor, your phone gets a notification.

Combined: A Full Safety + Observability Config

Put everything together:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "~/.claude/hooks/pre-bash.sh" }]
      },
      {
        "matcher": "Write",
        "hooks": [{ "type": "command", "command": "~/.claude/hooks/pre-write.sh" }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [{ "type": "command", "command": "~/.claude/hooks/audit-log.sh" }]
      }
    ],
    "Stop": [
      {
        "matcher": "*",
        "hooks": [{ "type": "command", "command": "~/.claude/hooks/notify-done.sh" }]
      }
    ]
  }
}

This configuration gives you:

• Automatic blocking of dangerous commands
• Auto-backup before every file write
• Complete audit log of all operations
• Task completion push notifications

Hook Design Principles

1. Keep it fast

Every tool call triggers hooks. Slow hooks visibly degrade Claude Code’s response speed. Avoid network requests in hooks (exception: non-blocking Stop hooks).

2. Fail silently

Errors in hook scripts shouldn’t crash Claude Code. Add set +e to your scripts so that even if a hook fails, the main flow is unaffected.

3. Use stderr for diagnostic output

A hook’s stdout gets sent to Claude. stderr is for the user. All diagnostic messages go to stderr:

echo "debug: processing $FILE_PATH" >&2  # correct
echo "debug: processing $FILE_PATH"      # Claude will read this

4. Design for idempotency

The same operation triggered multiple times should produce the same result. In backup scripts, use timestamps in filenames to avoid overwriting.

Integrating with the Memory System

Hooks and the memory architecture work well together.

For example, automatically append agent operations to logs/ in PostToolUse:

#!/bin/bash
INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.tool_name')
DETAIL=$(echo "$INPUT" | jq -r '.tool_input | tostring' | head -c 100)
DAILY_LOG="./memory/logs/$(date +%Y-%m-%d)_ops.md"

echo "- $(date +%H:%M) [$TOOL] $DETAIL" >> "$DAILY_LOG"
exit 0

Every agent action automatically flows into memory, so the next session can review “what exactly happened last time.”

Hooks transform Claude Code from a “black box AI” into an observable, auditable, interruptible engineering tool.

From trusting — to verifying. That’s the right posture for using AI confidently in production.

Series: Claude Code in Practice · Related: Claude Code Memory Architecture · MCP in Practice