Hooks 配置与失败策略

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

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 分发，详细见云端与团队。