Hooks 配置与失败策略

设置执行类型、工作目录、matcher、超时和 failClosed，并理解多来源合并。

This page has not been translated into English yet. The original Chinese version is shown below.

Hooks 通过 stdin 接收 JSON，通过 stdout 返回事件对应的 JSON。配置文件中的 version 使用正整数 1，hooks 把事件名映射到定义数组。

项目示例

在项目 .cursor/hooks.json 中注册已经存在的脚本：

{
  "version": 1,
  "hooks": {
    "beforeShellExecution": [
      {
        "command": ".cursor/hooks/check-command.sh",
        "matcher": "curl|wget|nc ",
        "timeout": 30,
        "failClosed": true
      }
    ]
  }
}

项目 hook 从项目根运行；用户 ~/.cursor/hooks.json 从 ~/.cursor 运行。因此同一脚本的相对路径不能在两种配置中照抄。项目 hooks 需要 trusted workspace。

执行选项

字段	作用
type	默认 command，另支持 prompt
command	命令脚本路径或 shell 字符串
timeout	秒；未设置使用平台默认值
matcher	正则过滤；空字符串或 * 匹配全部
failClosed	默认 false，控制崩溃、超时、无输出等失败
loop_limit	stop/subagentStop 的每脚本续跑上限，Cursor 默认 5；null 不设上限

Prompt hooks 用 prompt 表达条件，返回 ok 和可选 reason；$ARGUMENTS 替换为输入 JSON，缺省时把输入追加到提示。可用 model 覆盖默认评估模型。云端当前只支持 command hooks。

失败行为

退出 0 时解析输出；退出 2 阻止动作；其他退出码默认记录错误并放行。权限类 hook 返回无效 JSON 或不匹配事件 schema 的响应时，即使 failClosed 为 false 也会阻止动作。

failClosed 为 true 时，崩溃、超时、非零失败和无输出也阻止动作。不要把“默认 fail-open”误解为任意错误输出都会放行，也不要把权限事件的行为套到所有观察事件。

多来源合并

顺序为 Enterprise、Team、Project、User，所有匹配 hook 都运行。权限合并始终 deny 高于 ask 高于 allow；user_message 与 agent_message 拼接。其他字段（例如 followup_message）以后来的响应为准，因此低优先级来源可能覆盖这些字段。

Enterprise 系统文件在 macOS 的 /Library/Application Support/Cursor/hooks.json、Linux/WSL 的 /etc/cursor/hooks.json、Windows 的 C:\ProgramData\Cursor\hooks.json。Team hooks 从 dashboard 分发，详细见云端与团队。