【学习笔记】Claude Code Hooks 详解

用户提交 prompt
  ↓
UserPromptSubmit hook → 注入额外上下文
  ↓
Claude 处理
  ↓
Claude 调用 Edit 工具
  ↓
PreToolUse hook → 检查是否允许编辑该文件
  ↓
Edit 执行
  ↓
PostToolUse hook → 自动格式化编辑后的文件
  ↓
Claude 完成回复
  ↓
Stop hook → 检查是否遗漏了什么

{
  "hooks": {
    "EventName": [
      {
        "matcher": "可选的匹配模式",
        "hooks": [
          {
            "type": "command",
            "command": "your-script.sh"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      },
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"Bash command executed\" >> /tmp/claude-commands.log"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "$HOME/scripts/check-protected-files.sh"
          },
          {
            "type": "prompt",
            "prompt": "Verify that the file being written follows project conventions."
          }
        ]
      }
    ]
  }
}

{
  "type": "command",
  "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",
  "args": [],
  "timeout": 30
}

{
  "type": "http",
  "url": "https://my-service.com/hooks/validate",
  "headers": {
    "Authorization": "Bearer ${API_TOKEN}"
  },
  "timeout": 10
}

{
  "type": "prompt",
  "prompt": "Analyze the tool call and determine if it follows project conventions. Block any destructive operations."
}

{
  "type": "mcp_tool",
  "server": "my-mcp-server",
  "tool": "validate-code"
}

{
  "type": "agent",
  "prompt": "Review the code changes and report any issues."
}

"Edit"              → 精确匹配 Edit 工具
"Edit|Write"        → 匹配 Edit 或 Write（管道分隔）
"Bash"              → 匹配所有 Bash 调用
"mcp__.*"           → 正则匹配所有 MCP 工具
省略 matcher 或 "*"  → 匹配所有支持 matcher 的事件

{
  "matcher": "Bash",
  "if": "Bash(rm *)",
  "hooks": [
    {
      "type": "command",
      "command": "echo 'Dangerous rm command blocked' >&2 && exit 2"
    }
  ]
}

{
  "matcher": "Edit",
  "if": "Edit(*.prod.*)",
  "hooks": [
    {
      "type": "prompt",
      "prompt": "This is a production config file. Verify the edit is safe."
    }
  ]
}

{
  "session_id": "abc-123",
  "cwd": "/path/to/project",
  "event": "PreToolUse"
}

{
  "tool_name": "Edit",
  "tool_input": {
    "file_path": "/path/to/file.ts",
    "old_string": "old",
    "new_string": "new"
  }
}

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Cannot edit production config files."
  }
}

{
  "decision": "block",
  "reason": "This task is incomplete; tests were not run."
}

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "Project uses TypeScript strict mode. All new files must include type annotations."
  }
}

{
  "description": "Automatic code formatting",
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

{
  "name": "my-plugin",
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh"
          }
        ]
      }
    ]
  }
}

---
name: deploy
description: Deploy to production.
disable-model-invocation: true
hooks:
  PostToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "${CLAUDE_SKILL_DIR}/scripts/log-deploy.sh"
---

## Deploy Steps

1. Run the build command
2. Deploy to server

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
FILE=$(jq -r '.tool_input.file_path')
case "$FILE" in
  *.production.*|*.prod.*)
    echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"Cannot edit production config files."}}'
    # 也可以直接把原因写到 stderr 并 exit 2；这里用 JSON 做结构化控制。
    exit 0
    ;;
esac
exit 0

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "cat \"${CLAUDE_PROJECT_DIR}/.claude/context/project-rules.md\""
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if the edited file has any obvious syntax errors or missing imports. If it does, report them."
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Verify that the task is fully complete. Check: 1) All requested changes are made. 2) No TODOs left. 3) Tests would pass. If incomplete, describe what's missing."
          }
        ]
      }
    ]
  }
}

/hooks

claude --debug

# 模拟 PreToolUse 事件
echo '{"tool_name":"Edit","tool_input":{"file_path":"test.ts"}}' | bash hooks/protect-files.sh

{
  "description": "GLM StatusLine lifecycle hooks",
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/bin/glm-statusline-install.js check",
            "timeout": 5
          }
        ]
      }
    ]
  }
}