Claude Code 使用指南

主题

事件类型 ​

Hook Event Types

Claude Code 提供了丰富的生命周期事件，你可以在这些事件触发时执行自定义逻辑。每个事件在特定时机触发，并通过 stdin 传入 JSON 格式的上下文数据。

事件总览 ​

事件触发时机可阻止典型用途
PreToolUse工具调用前✅安全检查、参数验证
PostToolUse工具调用后❌自动格式化、日志记录
StopAgent 完成时❌通知、清理
SubagentStop子 Agent 完成时❌子任务后处理
SessionStart会话开始时❌环境准备、日志
SessionEnd会话结束时❌清理、统计
TaskCompleted后台任务完成时❌通知、后续处理
UserPromptSubmit用户提交输入时✅输入预处理、过滤
ConfigChange配置变更时❌配置同步
PreCompact上下文压缩前❌保存关键信息
WorktreeCreate工作树创建时❌环境初始化

PreToolUse ​

触发时机：Claude 准备调用任何工具之前。

这是最常用的 Hook 事件，可以拦截并阻止工具调用。

传入参数 ​

json
{
  "hook_event": "PreToolUse",
  "tool_name": "Bash",
  "tool_params": {
    "command": "rm -rf /tmp/test",
    "description": "Delete test directory"
  },
  "session_id": "abc123"
}

返回值 ​

json
{
  "allow": false,
  "reason": "禁止执行 rm -rf 命令",
  "message": "检测到危险命令，已阻止执行"
}
  • allow: false 阻止工具调用
  • allow: true 或无返回值则允许
  • reason 显示给 Claude 的阻止原因

可匹配的工具名 ​

你可以在配置中指定只对特定工具触发：

工具名说明
BashShell 命令执行
Read读取文件
Write创建文件
Edit编辑文件
Glob文件搜索
Grep内容搜索
Agent子代理调用

配置示例 ​

json
{
  "hooks": {
    "PreToolUse": [
      {
        "tool": "Bash",
        "handler": {
          "type": "command",
          "command": "node .claude/hooks/check-bash-safety.js"
        }
      }
    ]
  }
}

PostToolUse ​

触发时机：工具调用完成后。

用于对工具执行结果进行后处理。

传入参数 ​

json
{
  "hook_event": "PostToolUse",
  "tool_name": "Write",
  "tool_params": {
    "file_path": "/project/src/app.ts",
    "content": "..."
  },
  "tool_result": {
    "success": true,
    "output": "File created successfully"
  },
  "session_id": "abc123"
}

典型用途 ​

  • 文件写入后自动运行格式化工具
  • 代码修改后自动运行相关测试
  • 记录所有文件操作日志

Stop ​

触发时机：Claude 完成当前任务并准备停止时。

json
{
  "hook_event": "Stop",
  "stop_reason": "end_turn",
  "session_id": "abc123",
  "total_cost": 0.045,
  "total_turns": 12
}

典型用途 ​

  • 发送任务完成通知（Slack、邮件）
  • 生成会话摘要
  • 清理临时文件

SubagentStop ​

触发时机：子 Agent 完成任务时。

json
{
  "hook_event": "SubagentStop",
  "agent_id": "agent_xyz",
  "agent_type": "general-purpose",
  "result": "Task completed successfully",
  "session_id": "abc123"
}

SessionStart ​

触发时机：新会话开始时（用户启动 Claude Code）。

json
{
  "hook_event": "SessionStart",
  "session_id": "abc123",
  "working_directory": "/project",
  "timestamp": "2026-03-11T10:00:00Z"
}

典型用途 ​

  • 检查开发环境是否就绪
  • 加载项目特定配置
  • 启动依赖服务

SessionEnd ​

触发时机：会话结束时（用户退出或超时）。

json
{
  "hook_event": "SessionEnd",
  "session_id": "abc123",
  "duration_seconds": 3600,
  "total_cost": 0.12,
  "timestamp": "2026-03-11T11:00:00Z"
}

典型用途 ​

  • 记录会话统计
  • 生成使用报告
  • 清理会话产生的临时文件

TaskCompleted ​

触发时机：通过 Tasks 系统创建的后台任务完成时。

json
{
  "hook_event": "TaskCompleted",
  "task_id": "task_123",
  "status": "completed",
  "result": "All tests passed",
  "session_id": "abc123"
}

UserPromptSubmit ​

触发时机：用户提交输入后、Claude 处理前。

可以修改或拦截用户输入。

json
{
  "hook_event": "UserPromptSubmit",
  "prompt": "请帮我删除所有日志文件",
  "session_id": "abc123"
}

返回值 ​

json
{
  "allow": true,
  "modified_prompt": "请帮我安全地清理超过30天的日志文件（先列出再确认）"
}

ConfigChange ​

触发时机：任何配置变更时。

json
{
  "hook_event": "ConfigChange",
  "changed_key": "model",
  "old_value": "claude-sonnet-4-6",
  "new_value": "claude-opus-4-6",
  "session_id": "abc123"
}

PreCompact ​

触发时机：上下文自动压缩之前。

json
{
  "hook_event": "PreCompact",
  "current_tokens": 180000,
  "max_tokens": 200000,
  "session_id": "abc123"
}

典型用途 ​

  • 在压缩前保存重要的上下文信息到文件
  • 记录压缩前的关键状态

WorktreeCreate ​

触发时机：创建 Git 工作树（用于 SubAgent 隔离）时。

json
{
  "hook_event": "WorktreeCreate",
  "worktree_path": "/tmp/claude-worktree-abc",
  "branch": "claude/task-123",
  "session_id": "abc123"
}

典型用途 ​

  • 在新工作树中安装依赖
  • 配置工作树特定的环境

事件过滤 ​

可以通过 tool 字段限制 Hook 只对特定工具生效：

json
{
  "hooks": {
    "PreToolUse": [
      {
        "tool": "Bash",
        "handler": { "type": "command", "command": "..." }
      }
    ],
    "PostToolUse": [
      {
        "tool": "Write",
        "handler": { "type": "command", "command": "..." }
      },
      {
        "tool": "Edit",
        "handler": { "type": "command", "command": "..." }
      }
    ]
  }
}

不指定 tool 字段则对所有工具生效。