Hooks

选择事件与配置位置

支持的时机包括会话开始、提交提示、工具调用前后、权限处理、上下文压缩前后与停止。配置中的事件名称如 SessionStart、PreToolUse 和 PostToolUse 区分大小写。

全局配置读取 ~/.acecode/hooks.json 与 ~/.codex/hooks.json；项目配置读取当前受信任工作区中的 .acecode/hooks.json 与 .codex/hooks.json。各个已加载来源会合并，而非只保留一个文件。

目前支持 command 处理器。prompt、agent 与 async 类型不会按其他产品的实现自动运行，而会显示跳过或诊断信息。总开关 features.hooks 可以关闭这套兼容生命周期 Hooks；旧版启动钩子另有兼容行为。

配置一个工具调用检查

下面以 Bash 工具调用前运行本地检查脚本为例。先在项目中准备并自行验证脚本，然后把定义合并到项目 Hooks 文件。

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "python ./hooks/check_tool.py",
        "commandWindows": "py ./hooks/check_tool.py",
        "timeout": 30
      }]
    }]
  }
}

import json
import sys

request = json.load(sys.stdin)
# 在这里检查 request 中的事件和工具参数。
# 退出码 0 且不输出内容，表示检查通过且不附加行为。
sys.exit(0)

命令从标准输入接收一条 UTF-8 JSON 事件。timeout 的单位是秒；Windows 可以单独配置 commandWindows。需要阻止操作或添加上下文时，应使用该事件支持的结构化输出，不能给所有事件套用同一种返回对象。

审核、启停与排错

1. 进入设置 > 钩子并刷新发现结果，TUI 也可用 /hooks 查看。
2. 检查来源路径、命令、匹配条件和诊断。
3. 对确认可信的待审核项执行信任操作。
4. 触发一次对应的小操作，核对实际结果。

新的非托管 Hook 处于待审核状态时会被跳过。定义改变后需要重新审核；受管理策略控制的 Hook 会显示相应限制。可以禁用或重新启用普通 Hook，但重新启用不能替代尚未完成的信任审核。

Hook 没有执行时，先看开关、项目是否受信任、事件和 matcher 是否匹配。脚本失败时检查解释器、工作目录、退出码及超时。不要通过反复放宽工具权限来解决脚本本身的错误。