--- name: hook-skill description: Claude Code Hook 开发专家。当需要创建、调试、配置 Hook 时触发。触发词：创建 hook、写 hook、hook 配置、stop hook、pre tool use、post tool use、session start。 --- # Hook 开发 创建和配置 Claude Code Hooks，用于在特定事件时执行自定义逻辑。 ## Hook 基础 ### 什么是 Hook？ Hook 是在 Claude Code 执行过程中特定时机自动触发的脚本或命令。可以用于： - 验证和拦截工具调用 - 自动批准特定操作 - 添加上下文信息 - 实现循环执行 - 通知和日志记录 ### 10 种 Hook 事件 | 事件 | 触发时机 | 常见用途 | |-----|---------|---------| | **PreToolUse** | 工具执行前 | 验证、拦截、修改输入 | | **PostToolUse** | 工具执行后 | 验证结果、触发后续 | | **PermissionRequest** | 权限对话框显示时 | 自动批准/拒绝 | | **UserPromptSubmit** | 用户提交 prompt 时 | 添加上下文、验证 | | **Stop** | Claude 完成响应时 | 实现循环、强制继续 | | **SubagentStop** | Subagent 完成时 | 链式触发、验证完成 | | **PreCompact** | 压缩操作前 | 保存状态 | | **SessionStart** | 会话开始时 | 加载上下文、初始化 | | **SessionEnd** | 会话结束时 | 清理、保存状态 | | **Notification** | 通知时 | 自定义通知 | ### Exit Code 含义 | Exit Code | 含义 | 效果 | |-----------|------|------| | **0** | 成功 | 继续执行，stdout 可返回 JSON | | **2** | 阻止 | 阻止操作，stderr 反馈给 Claude | | **其他** | 非阻止错误 | 显示警告，继续执行 | ## 配置结构 ### hooks.json 格式 ```json { "hooks": { "EventName": [ { "matcher": "ToolPattern", "hooks": [ { "type": "command", "command": "your-command-here", "timeout": 60 } ] } ] } } ``` ### 字段说明 - **matcher**：工具名匹配模式（仅 PreToolUse、PostToolUse、PermissionRequest） - 精确匹配：`Write` - 正则匹配：`Edit|Write`、`Notebook.*` - 匹配所有：`*` 或省略 - **type**：`command`（bash 命令）或 `prompt`（LLM 评估） - **command**：要执行的命令 - **timeout**：超时时间（秒），默认 60 ### 环境变量 - `$CLAUDE_PROJECT_DIR`：项目根目录 - `$CLAUDE_PLUGIN_ROOT`：插件根目录（插件 Hook 专用） - `$CLAUDE_ENV_FILE`：环境变量文件（仅 SessionStart） ## Hook 输入（stdin JSON） ### 通用字段 ```json { "session_id": "abc123", "transcript_path": "/path/to/transcript.jsonl", "cwd": "/current/directory", "permission_mode": "default", "hook_event_name": "PreToolUse" } ``` ### PreToolUse 输入 ```json { "hook_event_name": "PreToolUse", "tool_name": "Write", "tool_input": { "file_path": "/path/to/file.txt", "content": "file content" }, "tool_use_id": "toolu_01ABC123..." } ``` ### Stop 输入 ```json { "hook_event_name": "Stop", "stop_hook_active": true // 是否已被 Stop hook 继续过 } ``` ### UserPromptSubmit 输入 ```json { "hook_event_name": "UserPromptSubmit", "prompt": "用户的 prompt 内容" } ``` ### SessionStart 输入 ```json { "hook_event_name": "SessionStart", "source": "startup" // startup | resume | clear | compact } ``` ## Hook 输出（JSON） ### PreToolUse 控制 ```json { "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "allow", // allow | deny | ask "permissionDecisionReason": "原因", "updatedInput": { } // 可选：修改输入 } } ``` ### Stop 控制 ```json { "decision": "block", // block = 阻止停止，继续执行 "reason": "告诉 Claude 为什么要继续" } ``` ### UserPromptSubmit 控制 ```json { "decision": "block", // 可选：阻止 prompt "reason": "阻止原因", "hookSpecificOutput": { "hookEventName": "UserPromptSubmit", "additionalContext": "添加的上下文" } } ``` ### SessionStart 控制 ```json { "hookSpecificOutput": { "hookEventName": "SessionStart", "additionalContext": "启动时添加的上下文" } } ``` ## 常用模式 ### 1. 实现循环执行（Stop Hook） ```bash #!/bin/bash # stop-loop.sh - 阻止停止，让 Claude 继续 HOOK_INPUT=$(cat) STOP_ACTIVE=$(echo "$HOOK_INPUT" | jq -r '.stop_hook_active // false') # 检查状态文件 if [ -f ".loop-status.json" ]; then CURRENT=$(jq -r '.current // 0' .loop-status.json) MAX=$(jq -r '.max // 5' .loop-status.json) if [ "$CURRENT" -lt "$MAX" ]; then # 更新计数 jq ".current = $((CURRENT + 1))" .loop-status.json > .tmp && mv .tmp .loop-status.json # 阻止停止 echo "继续执行 ($((CURRENT + 1))/$MAX)" >&2 exit 2 fi fi exit 0 ``` ### 2. 自动批准文档文件读取 ```python #!/usr/bin/env python3 import json import sys input_data = json.load(sys.stdin) tool_name = input_data.get("tool_name", "") tool_input = input_data.get("tool_input", {}) if tool_name == "Read": file_path = tool_input.get("file_path", "") if file_path.endswith((".md", ".txt", ".json")): output = { "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "allow", "permissionDecisionReason": "文档文件自动批准" } } print(json.dumps(output)) sys.exit(0) sys.exit(0) ``` ### 3. 添加时间上下文（SessionStart） ```bash #!/bin/bash # session-start.sh echo "当前时间: $(date '+%Y-%m-%d %H:%M:%S')" echo "项目目录: $CLAUDE_PROJECT_DIR" # 如果有 CLAUDE_ENV_FILE，设置环境变量 if [ -n "$CLAUDE_ENV_FILE" ]; then echo "export PROJECT_START_TIME=$(date +%s)" >> "$CLAUDE_ENV_FILE" fi exit 0 ``` ### 4. 验证 Bash 命令（PreToolUse） ```python #!/usr/bin/env python3 import json import sys import re input_data = json.load(sys.stdin) tool_name = input_data.get("tool_name", "") tool_input = input_data.get("tool_input", {}) if tool_name != "Bash": sys.exit(0) command = tool_input.get("command", "") # 危险命令检查 dangerous_patterns = [ (r"\brm\s+-rf\s+/", "禁止删除根目录"), (r"\bsudo\b", "禁止使用 sudo"), ] for pattern, message in dangerous_patterns: if re.search(pattern, command): print(message, file=sys.stderr) sys.exit(2) sys.exit(0) ``` ### 5. Prompt 类型 Hook（LLM 评估） ```json { "hooks": { "Stop": [ { "hooks": [ { "type": "prompt", "prompt": "评估 Claude 是否应该停止。检查：1. 所有任务是否完成 2. 是否有错误需要处理。返回 JSON: {\"decision\": \"approve\" 或 \"block\", \"reason\": \"原因\"}", "timeout": 30 } ] } ] } } ``` ## 调试 ### 基本调试 ```bash # 查看 Hook 执行详情 claude --debug # 检查 Hook 配置 # 在 Claude Code 中运行 /hooks ``` ### 常见问题 1. **Hook 不触发** - 检查 matcher 是否正确（大小写敏感） - 检查 hooks.json 语法 - 运行 `/hooks` 查看注册状态 2. **命令找不到** - 使用绝对路径 - 检查执行权限 `chmod +x script.sh` 3. **JSON 解析失败** - 确保输出是有效 JSON - 检查引号转义 ## 安全注意 - Hook 以当前用户权限运行 - 始终验证和清理输入 - 使用引号包裹变量：`"$VAR"` - 检查路径遍历：`..` - 敏感文件要跳过：`.env`、`.git/` ## 创建 Hook 的步骤 1. **确定事件** - 选择合适的 Hook 事件 2. **设计逻辑** - 确定输入输出和处理逻辑 3. **编写脚本** - Python 或 Bash 4. **配置 hooks.json** - 添加到配置文件 5. **测试** - 使用 `--debug` 调试 6. **设置权限** - `chmod +x` ## 参考 官方文档：`site:code.claude.com hooks`