hooks-configuration

Claude Code 钩子配置

关于配置和开发 Claude Code 钩子的专业知识，可用于自动化工作流并强制执行最佳实践。

何时使用此技能

在以下情况下使用此技能……	在以下情况下使用其他方案……
配置钩子生命周期事件（PreToolUse、PostToolUse 等）	编写与钩子无关的通用 shell 脚本
阻止危险命令或强制执行模式	设置 CI/CD 管道（使用 CI 工具）
编辑后自动格式化文件	配置与钩子无关的 Claude Code 设置
在会话或子 Agent 启动时注入上下文	编写独立的自动化脚本
设置 PermissionRequest 自动批准/拒绝	直接通过 settings.json 管理项目权限
开发用于基于判断进行决策的提示词钩子或 Agent 钩子	构建 MCP 服务或自定义工具集成

核心概念

什么是钩子？ 钩子是用户定义的 shell 命令，会在 Claude Code 生命周期的特定时刻执行。与依赖 Claude“决定”是否运行某项操作不同，钩子可以提供确定且有保障的执行。

为什么使用钩子？

• 自动强制执行代码格式规范
• 在危险命令执行前将其阻止
• 在会话开始时注入上下文
• 记录命令以便审计追踪
• 在任务完成时发送通知

Hook 生命周期事件

事件	触发时机	主要使用场景
SessionStart	会话开始或恢复	环境设置、上下文加载
SessionEnd	会话终止	清理、状态持久化
UserPromptSubmit	用户提交提示词	输入验证、注入上下文
PreToolUse	工具执行前	权限控制、阻止危险操作
PostToolUse	工具完成后	自动格式化、日志记录、验证
PostToolUseFailure	工具执行失败后	重试决策、错误处理
PermissionRequest	Claude 请求使用某个工具的权限	无需用户提示即可自动批准或拒绝
Stop	主 Agent 完成响应	通知、Git 提醒
SubagentStart	子 Agent（Task 工具）即将启动	修改输入、注入上下文
SubagentStop	子 Agent 完成	按任务进行完成情况评估
WorktreeCreate	通过 EnterWorktree 创建新的 Git worktree	Worktree 设置、安装依赖
WorktreeRemove	会话退出后移除 worktree	清理、未提交更改提醒
TeammateIdle	Agent 团队中的队友进入空闲状态	为队友分配其他任务
TaskCompleted	共享任务列表中的任务标记为完成	任务验收前的验证关卡
PreCompact	上下文压缩前	备份对话记录
Notification	Claude 发送通知	自定义提醒
ConfigChange	Claude Code 运行时设置发生更改	审计配置更改、验证

Stop 与 SubagentStop 的区别：当主 Agent 完成一轮响应时，Stop 会在会话级别触发。当单个子 Agent（通过 Task 工具启动）完成时，SubagentStop 会触发。会话级通知使用 Stop；按任务设置质量关卡则使用 SubagentStop。

有关每个事件的完整架构、示例和超时建议，请参阅 .claude/rules/hooks-reference.md。

配置

文件位置

Hook 在设置文件中配置：

• ~/.claude/settings.json - 用户级（在所有位置生效）
• .claude/settings.json - 项目级（提交到仓库）
• .claude/settings.local.json - 本地项目级（不提交）

Claude Code 会合并所有文件中匹配的 Hook。

Frontmatter Hooks（技能和命令）

也可以在技能和命令的 frontmatter 中通过 hooks 字段直接定义 Hook：

---
name: my-skill
description: A skill with hooks
allowed-tools: Bash, Read
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "echo 'Pre-tool hook from skill'"
          timeout: 10
---

基本结构

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "your-command-here",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

匹配模式

• 精确匹配："Bash" - 精确匹配 "Bash" 工具
• 正则表达式："Edit|Write" - 匹配任一工具
• 通配符："Notebook.*" - 匹配名称以 "Notebook" 开头的工具
• 所有工具："*" - 匹配所有内容
• MCP 工具："mcp__server__tool" - 指定 MCP 服务工具

输入/输出架构摘要

钩子通过 stdin 接收 JSON，其中包含常见字段（session_id、transcript_path、cwd、permission_mode、hook_event_name）。特定事件的字段包括 PreToolUse 的 tool_name 和 tool_input、PostToolUse 的 tool_response，以及 SubagentStart 的 subagent_type/subagent_prompt。

退出代码：0 = 允许，2 = 阻止（向 Claude 显示 stderr），其他 = 非阻塞错误。

JSON 响应因事件而异：PreToolUse 使用包含 permissionDecision 的 hookSpecificOutput；Stop/SubagentStop 使用 decision/reason；SubagentStart 使用 updatedPrompt；SessionStart 使用包含 additionalContext 的 hookSpecificOutput。

详细的钩子架构和示例，请参阅 REFERENCE.md。

常见钩子模式

阻止危险命令（PreToolUse）

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

# Block rm -rf /
if echo "$COMMAND" | grep -Eq 'rm\s+(-rf|-fr)\s+/'; then
    echo "BLOCKED: Refusing to run destructive command on root" >&2
    exit 2
fi

exit 0

编辑后自动格式化（PostToolUse）

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

if [[ "$FILE" == *.py ]]; then
    ruff format "$FILE" 2>/dev/null
    ruff check --fix "$FILE" 2>/dev/null
elif [[ "$FILE" == *.ts ]] || [[ "$FILE" == *.tsx ]]; then
    prettier --write "$FILE" 2>/dev/null
fi

exit 0

提醒使用内置工具（PreToolUse）

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

if echo "$COMMAND" | grep -Eq '^\s*cat\s+[^|><]'; then
    echo "REMINDER: Use the Read tool instead of 'cat'" >&2
    exit 2
fi

exit 0

在会话开始时加载上下文（SessionStart）

#!/bin/bash
GIT_STATUS=$(git status --short 2>/dev/null | head -5)
BRANCH=$(git branch --show-current 2>/dev/null)

CONTEXT="Current branch: $BRANCH\nPending changes:\n$GIT_STATUS"
jq -n --arg ctx "$CONTEXT" '{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": $ctx
  }
}'

其他模式（子 Agent 注入、桌面通知、审计日志记录、自动批准、工作树设置、任务门控），请参阅 REFERENCE.md。

基于提示词和基于 Agent 的钩子

钩子有四种类型：command（Shell 脚本，退出代码）、http（HTTPS 端点）、prompt（单轮大模型调用）和 agent（多轮且可使用工具）。确定性规则使用 command；基于判断的决策使用 prompt/agent。添加 async: true 可实现即发即弃；添加 once: true 可让钩子在每个会话中只运行一次。

基于提示词和基于 Agent 的钩子适用于 PreToolUse、PostToolUse、PostToolUseFailure、PermissionRequest、Stop、SubagentStop、TaskCompleted、UserPromptSubmit。其他所有事件仅支持 command 钩子。

有关钩子类型详情、CLAUDE_ENV_FILE 和配置示例，请参阅 REFERENCE.md 和 .claude/rules/prompt-agent-hooks.md。

处理被阻止的命令

当 PreToolUse 钩子阻止某条命令时：

情况	操作
钩子建议了替代方案	使用建议的工具/方法
替代方案不可行	请用户手动运行命令
用户说“继续”	仍然会被阻止——请说明原因并提供命令，让用户手动执行

重要：用户权限无法绕过钩子。重试被阻止的命令仍会失败。

确实需要执行命令时：

1. 解释需要该命令的原因
2. 说明考虑过哪些替代方案，以及它们为何不可行
3. 提供要由用户手动运行的准确命令
4. 让用户决定

超时指南

自 Claude Code 2.1.50 起，钩子的默认超时为 600s（10 分钟）。设置显式超时可说明意图并避免出现“Hook cancelled”错误：

钩子类型	建议超时	用途
SessionStart	120–300s	测试、代码检查工具、依赖项检查
SessionEnd	60–120s	日志记录、清理、状态保存
Stop / SubagentStop	30–60s	Git 状态检查、快速验证
PreToolUse	10–30s	快速验证
PostToolUse	30–120s	日志记录、通知
PermissionRequest	5–15s	保持快速响应，提供良好体验

后台子 Shell 模式（推荐用于耗时钩子）

当钩子需要执行耗时任务（日志记录、API 调用），又不希望阻塞时，可在后台子 Shell 中运行：

#!/bin/bash
# Exits instantly; slow work continues in background
(
  echo "$(date): Session ended" >> ~/.claude/session.log
  # Any other slow work...
) &>/dev/null &
exit 0

这样做的原因：( ) 会创建子 Shell，& 会在后台运行，&>/dev/null 可避免 stdout/stderr 导致阻塞，exit 0 会立即返回成功。

最佳实践

领域	要点
脚本	使用 cat 读取 stdin；使用 jq 解析；为所有变量加引号；以 2 退出以阻止，以 0 退出以允许；通过 stderr 输出消息；保持在 5 秒以内
配置	使用 $CLAUDE_PROJECT_DIR 设置可移植路径；明确指定超时时间；优先使用具体匹配器，而非通配符；启用前先测试
安全	验证所有输入；使用绝对路径；避免直接使用 .env / .git/；部署前进行审核

调试

错误	原因	修复方法
Hook 已取消	超出超时时间	添加 "timeout" 字段，或使用后台子 shell 模式
Hook 失败	脚本错误	检查退出代码；添加错误处理
找不到命令	缺少脚本	确认脚本路径和权限
权限被拒绝	脚本不可执行	chmod +x ~/.claude/script.sh

使用 /hooks 验证注册情况，使用 claude --debug 查看详细日志，并通过 echo '{"tool_input":{"command":"..."}}' | bash your-hook.sh 手动测试。检查 $? 获取退出代码。插件 Hook 文档请参阅 hooks/README.md。