Hooks

Hooks 让你用自定义脚本观察、控制和扩展智能体循环。在项目级或用户级的 hooks.json 文件里定义 hooks，或从 Customize 通过插件安装。Hooks 是派生出来的进程，通过 stdio 用 JSON 双向通信。用 hooks 你可以：在编辑后运行格式化工具、为事件添加分析、扫描 PII 或密钥、把风险操作（如 SQL 写入）设为需要放行、控制子智能体（Task 工具）的执行、在会话开始时注入上下文。Cursor 还支持从 Claude Code 等第三方工具加载 hooks。

Hook 类别

按触发它们的事件分三类：

**Agent hooks（Cmd+K / Agent Chat）**在智能体会话期间触发：sessionStart / sessionEnd（会话生命周期）；preToolUse / postToolUse / postToolUseFailure（通用工具使用，对所有工具触发）；subagentStart / subagentStop（子智能体（Task 工具）生命周期）；beforeShellExecution / afterShellExecution（控制 shell 命令）；beforeMCPExecution / afterMCPExecution（控制 MCP 工具使用）；beforeReadFile / afterFileEdit（控制文件访问和编辑）；beforeSubmitPrompt（提交前验证提示）；preCompact（观察上下文窗口压缩）；stop（处理智能体完成）；afterAgentResponse / afterAgentThought（跟踪智能体回复）。

**Tab hooks（行内补全）**为自主的 Tab 操作触发：beforeTabFileRead（控制 Tab 补全的文件访问）、afterTabFileEdit（对 Tab 编辑做后处理）。

应用生命周期 hooks在任何智能体会话之外触发：workspaceOpen（Cursor 打开工作区以及每次工作区文件夹变化时触发，可以返回当前工作区要加载的额外插件路径）。这些独立的 hook 面让你对自主的 Tab 操作、用户指挥的 Agent 操作和工作区启动应用不同的策略。

云端智能体支持

云端智能体运行你仓库里基于命令的 hooks：如果项目根的 .cursor/hooks.json 里定义了 hooks，云端智能体会在工作期间拾取并运行它们；在 Enterprise 套餐上，云端智能体还运行通过网页控制台配置的团队 hooks 和企业托管 hooks。云端智能体有时在早期探索回合以只读环境开始，此时 hooks 不运行，要等智能体有可写环境后才开始。云端智能体运行的 hooks：beforeShellExecution、afterShellExecution、beforeReadFile、afterFileEdit、preToolUse、postToolUse、postToolUseFailure、subagentStart、subagentStop、beforeSubmitPrompt、preCompact、afterAgentResponse、afterAgentThought、stop。云端不可用的：sessionStart、sessionEnd、beforeMCPExecution / afterMCPExecution、beforeTabFileRead / afterTabFileEdit、workspaceOpen（原因分别是只读环境里 hooks 不加载、云端智能体没有编辑器生命周期的会话边界、MCP hook 时机不明确、Tab 补全是 IDE 功能、这是 IDE 生命周期 hook）。云端智能体从这些来源加载 hooks：项目 hooks（仓库里的 .cursor/hooks.json）、团队 hooks（Enterprise）、企业 hooks（Enterprise）；用户级 hooks（~/.cursor/hooks.json）不可用，因为云端智能体 VM 无法访问你本地的主目录配置。云端智能体只运行基于命令的 hooks，基于提示的 hooks 需要云端执行环境里没有的认证接线。

快速开始

创建 hooks.json 文件，可以放在项目级（<项目>/.cursor/hooks.json）或你的主目录（~/.cursor/hooks.json）；项目级 hooks 只适用于那个项目，主目录的 hooks 全局适用。用户 hooks（~/.cursor/hooks.json）示例：

{
  "version": 1,
  "hooks": {
    "afterFileEdit": [{ "command": "./hooks/format.sh" }]
  }
}

在 ~/.cursor/hooks/format.sh 创建脚本（读取输入、做点事、退出 0），并 chmod +x 使其可执行：

#!/bin/bash
# Read input, do something, exit 0
cat > /dev/null
exit 0

项目 hooks 从项目根运行，所以要用 .cursor/hooks/format.sh（而不是 ./hooks/format.sh）。Cursor 监视 hooks 配置文件并自动重新加载，你的 hook 在每次文件编辑后运行。

Hook 类型

hooks 支持两种执行类型：基于命令的（默认）和基于提示的（LLM 评估）。

基于命令的 hooks 执行 shell 脚本，通过 stdin 接收 JSON 输入并通过 stdout 返回 JSON 输出：

{
  "version": 1,
  "hooks": {
    "beforeShellExecution": [
      {
        "command": "./scripts/approve-network.sh",
        "timeout": 30,
        "matcher": "curl|wget|nc"
      }
    ]
  }
}

退出码行为：退出码 0 表示 hook 成功，使用 JSON 输出（对权限类 hooks（beforeShellExecution、beforeMCPExecution、beforeReadFile、beforeTabFileRead、subagentStart、preToolUse），无效 JSON 或不匹配预期的响应会被处理）；退出码 2 阻止该动作（等价于返回 permission: "deny"）；其他退出码表示 hook 失败，动作继续（默认失败时放行）。

基于提示的 hooks 用 LLM 评估自然语言条件，适用于无需自写脚本的策略强制：

{
  "version": 1,
  "hooks": {
    "beforeShellExecution": [
      {
        "type": "prompt",
        "prompt": "Does this command look safe to execute? Only allow read-only operations.",
        "timeout": 10
      }
    ]
  }
}

特点：返回结构化的 { ok: boolean, reason?: string } 响应；用快速模型做快速评估；$ARGUMENTS 占位符自动替换为 hook 输入 JSON（缺少该占位符时 hook 输入被自动追加）；可选的 model 字段覆盖默认的 LLM 模型。各事件的输入输出载荷字段和更多示例，以官方 Hooks 页为准。