PreToolUse

PreToolUse 在 Hawa Code 创建工具参数后和处理工具调用之前运行。这是拦截和控制工具执行的关键时机。

核心功能

• 拦截工具调用：在工具实际执行前进行检查和干预
• 允许、拒绝或询问：可以自动批准、阻止工具，或提示用户确认
• 修改工具输入：在执行前修改工具的参数
• 添加上下文：向 Hawa Code 注入额外的上下文信息

Matcher

PreToolUse 支持在 工具名称 上进行匹配，包括：

• 单一匹配：匹配单个属性，例如 “Edit”。
• 多个匹配：使用竖线 | 分隔多个属性，例如 “Edit|Write”。
• 通配符匹配：使用 * 进行通配匹配，例如 “mcp__memory__.“、”mcp__.*__write.“、”mcp__.__write.|Edit”

入参

属性	描述
session_id	当前会话 ID
transcript_path	历史对话记录 JSON 文件路径
cwd	调用 Hook 时候工作路径
permission_mode	当前权限模式：default、plan、acceptEdits、dontAsk 或 bypassPermissions
hook_event_name	PreToolUse
tool_name	当前处理的工具名称
tool_input	工具入参
tool_use_id	调用工具的 ID

入参示例：

{
  "session_id": "abc123",
  "transcript_path": "/home/user/.hcode/projects/.../xxxx.jsonl",
  "cwd": "/home/user/my-project",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm clear"
  }
}

出参

属性	描述
continue	如果为 true 当前工具会允许执行，如果为 false 当前工具会被阻止执行
stopReason	当工具被阻止执行的时候，stopReason 会发送给 LLM
systemMessage	在 CLI 终端显示的警示消息，不会发送给 LLM
suppressOutput	如果 suppressOutput 为 true 时 systemMessage 才会在 CLI 终端显示
hookSpecificOutput.hookEventName	PreToolUse
hookSpecificOutput.permissionDecision	deny 工具被阻止执行，ask 工具必须需要用户确认才可以执行，allow 工具直接执行不需要用户确认
hookSpecificOutput.updatedInput	被修改的入参，工具执行的时候会使用修改后的入参

出参示例：

{
  "continue": true, 
  "stopReason": "有风险不能执行", 
  "suppressOutput": true, 
  "systemMessage": "这个脚本是有分析的，如果没有忽略此警告消息", 
  "hookSpecificOutput": {
      "hookEventName": "PreToolUse",
      "permissionDecision": "ask",
      "permissionDecisionReason": "脚本有风险，应该重点核实，小心确认！",
      "updatedInput": {
        "command": "npm install"
      }
  }
}

返回码

如果 hook command 执行返回码如果不等于 1 ，continue 会设置为 false，同时标准错误输出会设置为 stopReason

配置

基础配置

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "./security-check.sh",
            "timeout": 30,
            "statusMessage": "Checking...",
            "async": false
          }
        ]
      }
    ]
  }
}

参数说明

参数	类型	说明	默认值
matcher	string	正则表达式匹配工具名称	必填
type	string	hook 类型：command/prompt/`	必填
command	string	要执行的命令（command 类型）	-
timeout	number	超时时间（秒）	600
statusMessage	string	自定义加载消息	-
async	boolean	是否异步运行	false

匹配器模式示例

// 匹配特定工具
"matcher": "Bash"

// 匹配多个工具（正则表达式）
"matcher": "Edit|Write"

// 匹配所有 MCP 工具
"matcher": "mcp__.*"

// 匹配特定 MCP 服务器的工具
"matcher": "mcp__memory__.*"