Hooks 排障与动态插件

Hook 没有触发、触发后失败、返回值未生效是不同问题。先在 Customize > Hooks 和 Hooks output channel 检查配置、执行记录和错误。

加载与路径

Cursor 监视 hooks.json 并在保存后重新加载；仍未加载时重启。项目脚本路径相对于项目根，用户脚本相对于 ~/.cursor，脚本还需要具备执行权限。

matcher 匹配对象由事件决定：shell 匹配整条命令，subagent 匹配类型，通用工具匹配 tool type。把文件 glob 当作 afterFileEdit 的 matcher 不会按预期筛选路径。

响应不生效

按事件检查输出字段：preToolUse 的 ask 当前不被执行，subagentStart 的 ask 被当作 deny，sessionStart 的 continue:false 不阻止创建。无效 JSON 在权限事件中会阻止动作，而其他失败默认可能放行；具体见失败策略。

输入中的 conversation_id 在多轮中稳定，generation_id 每条用户消息变化；model_id、model_params 可能缺省。transcript_path 可能为 null，不要未经检查就读文件。

可用环境变量

workspaceOpen

打开工作区及每次文件夹变化时触发，零文件夹窗口跳过。它在 desktop 和 CLI 运行，位于 Agent 会话之外，因此输入不带 conversation_id、generation_id、model、session_id 或 transcript_path。

脚本可返回绝对插件目录列表：

{
  "pluginPaths": ["/absolute/path/to/workspace-plugin"]
}

适合按工作区选择插件。输入仍有 hook_event_name、cursor_version、workspace_roots、user_email；不要要求必须存在会话字段才处理该事件。