PostToolUse Hook

PostToolUse

PostToolUse 在工具成功执行后立即触发，支持使用与 PreToolUse 相同的匹配器值。

常见匹配器

  • Task - Subagent 任务
  • Bash - Shell 命令
  • Glob - 文件模式匹配
  • Grep - 内容搜索
  • Read - 文件读取
  • Edit - 文件编辑
  • Write - 文件写入
  • WebFetch、WebSearch - Web 操作

配置方式

在设置文件中配置 Hooks：

  • ~/.hcode/settings.json - 用户级设置
  • .hcode/settings.json - 项目级设置

基本结构

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "your-command-here"
          }
        ]
      }
    ]
  }
}

matcher：用于匹配工具名称的模式，区分大小写

  • 简单字符串：精确匹配，如 Write 仅匹配 Write 工具
  • 正则表达式：支持 Edit|Write 或 Notebook.* 等模式
  • 通配符：使用 * 匹配所有工具，也可使用空字符串 "" 或省略 matcher

hooks：模式匹配时执行的 hooks 数组

  • type：Hook 执行类型，"command" 表示执行 bash 命令
  • command：要执行的 bash 命令
  • timeout：（可选）hook 执行超时时间（秒）

插件 Hooks 中的 PostToolUse

示例插件 hook 配置：

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

输入参数

tool_input 和 tool_response 的具体格式取决于工具类型。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.hcode/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PostToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "file content"
  },
  "tool_response": {
    "filePath": "/path/to/file.txt",
    "success": true
  },
  "tool_use_id": "toolu_01ABC123..."
}

字段说明

字段 类型 说明
session_id string 会话唯一标识符
transcript_path string 对话 JSON 文件的完整路径
cwd string 调用 hook 时的当前工作目录
permission_mode string 当前权限模式："default"、"plan"、"acceptEdits"、"dontAsk" 或 "bypassPermissions"
hook_event_name string 固定为 "PostToolUse"
tool_name string 被执行的工具名称（如 Write、Edit、Bash 等）
tool_input object 工具的输入参数（因工具而异）
tool_response object 工具的响应结果（因工具而异）
tool_use_id string 工具调用的唯一标识符

注意：tool_input 和 tool_response 的具体格式取决于工具类型。

输出参数 / 决策控制

PostToolUse hooks 可在工具执行后向 Hawa Code 提供反馈。

  • "block"：阻止后续操作，并使用 reason 提示 Hawa Code
  • undefined：不执行任何操作，reason 被忽略
  • "hookSpecificOutput.additionalContext"：为 Hawa Code 添加额外上下文
{
  "decision": "block" | undefined,
  "reason": "决策说明",
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "提供给 Hawa Code 的额外信息"
  }
}

字段说明

字段 类型 说明
decision string | undefined "block" 表示阻止并提示原因，undefined 表示不执行任何操作
reason string 决策的解释说明
hookSpecificOutput object hook 特定的输出信息
hookSpecificOutput.hookEventName string 固定为 "PostToolUse"
hookSpecificOutput.additionalContext string 为 Hawa Code 添加的额外上下文信息

退出码行为

简单退出码

Hooks 通过退出码、stdout 和 stderr 传达状态：

  • 退出码 0：成功，stdout 显示给用户
  • 退出码 2：阻止错误，向 Hawa Code 显示 stderr（工具已执行），格式为 [command]: {stderr}
  • 其他退出码：非阻止错误，stderr 中显示

PostToolUse 特定的退出码 2 行为

Hook 事件 行为
PostToolUse 向 Hawa Code 显示 stderr（工具已执行）