Cursor Hooks 鉤子

你是 Cursor Hook 設計顧問，幫我設計一個短小、可除錯、失敗語義清晰的 hook。

【角色】
你知道 Cursor hook 解決什麼、掛哪個事件、載入位置、失敗語義怎麼寫（放行 / 警告 / 阻斷）。

【輸入】
- 想在什麼時機自動檢查什麼：___
- 觸發事件：___
- 不透過該警告還是阻斷：___
- 個人用還是全 repo：___

【工作流程】
1. 確認適合用 hook（而非 skill 或人工）
2. 選觸發事件和載入位置
3. 設計短小的檢查邏輯
4. 寫對失敗語義

【輸出規範】
▌一、是否適合用 hook
▌二、觸發事件 + 載入位置
▌三、檢查邏輯（短小版）
▌四、失敗語義 + 處理

【硬約束】
- hook 必須短、可除錯、失敗明確
- 敏感路徑 / 危險命令預設阻斷 + 人工確認
- 全 repo 的 hook 影響所有人，謹慎
- 避免頻繁誤報
- 不確定的機制標註需查官方文件
- 給的設計可直接用

Hooks（鉤子，在固定事件上自動執行的指令碼）讓你用 custom scripts 觀察、控制和擴充套件 Cursor agent loop。官方文件說明，hooks 是 spawned processes（派生程序，獨立啟動的子程序），透過 stdio（標準輸入輸出）雙向傳遞 JSON，在 agent loop 的指定階段前後執行。

1. Hooks 能做什麼

官方列出的典型用途：

• Edit 後執行 formatter。
• 記錄 analytics events。
• 掃描 PII（Personally Identifiable Information，個人可識別資訊）或 secrets。
• Gate risky operations，例如 SQL writes。
• 控制 subagent，也就是 Task tool execution。
• 在 session start 注入 context。

flowchart TD
  Event["Agent event"] --> Hook["Hook process"]
  Hook --> Observe["Observe"]
  Hook --> Block["Block"]
  Hook --> Modify["Modify behavior"]
  Observe --> Agent["Agent loop continues"]
  Block --> Deny["Deny / ask"]
  Modify --> Agent

Cloud agents 也會執行 repo hooks。Enterprise plans 下，它們還會執行 team hooks 和 enterprise-managed hooks。

2. Agent 和 Tab 事件

Hooks 同時支援 Cursor Agent 和 Cursor Tab，但事件不同。

官方把 Agent 和 Tab 分開，是因為 Tab 的 inline completions 更偏自動補全，Agent 更偏使用者指令驅動。兩個入口應該能使用不同策略。

3. 設定路徑

建立 hooks.json。

User 示例：

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

Project 示例：

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

Project hooks 從 project root 執行，所以路徑用 .cursor/hooks/...。Cursor 會 watch hooks config files 並自動 reload。

4. Command-based hooks

Command hooks 是預設型別。指令碼從 stdin 接收 JSON input，並透過 stdout 返回 JSON output。

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

Exit code 行為：

5. Prompt-based hooks

Prompt hooks 用 LLM 判斷自然語言條件，適合不想寫指令碼的 policy enforcement。

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

官方說明：

• 返回結構化 { ok: boolean, reason?: string }。
• 使用 fast model 做快速判斷。
• $ARGUMENTS 會自動替換為 hook input JSON。
• 如果沒有 $ARGUMENTS，hook input 會自動追加。
• 可用 model 欄位覆蓋預設 LLM model。

6. 適合和不適合

適合 hooks：

• 低延遲、明確、可自動判定的檢查。
• 格式化、審計、記錄、只讀安全 gate。
• 組織需要統一執行的檢查。

不適合 hooks：

• 複雜產品判斷。
• 需要大量上下文和人工審閱的任務。
• 失敗後會造成生產副作用的自動化。
• 沒有記錄和回復的攔截邏輯。

7. 驗收清單

上線 hook 前檢查：

• hooks.json 放在正確作用域。
• Project hooks 使用 project-root 相對路徑。
• 指令碼可執行。
• stdin JSON 和 stdout JSON 都能被獨立測試。
• exit code 2 的 deny 行為可驗證。
• 非 0 / 2 的 fail-open 風險可接受。
• 安全類 hook 有記錄。
• Cloud Agent / team / enterprise hooks 的作用域清楚。

本章自檢

完成本章後，用這 3 個問題檢查自己是否真正理解：

1. Agent hooks 和 Tab hooks 的事件為什麼要分開？
2. User hooks 和 Project hooks 的指令碼執行目錄有什麼差異？
3. Command hook 返回 exit code 2 和其它非零 exit code 有什麼不同？

透過標準：你能寫出一個 beforeShellExecution hook，攔截網路命令，並說明失敗時是否 fail-open。

官方來源

• Cursor Hooks —— 官方說明 hook 機制、事件、設定、command hooks、prompt hooks 和示例。
• Third Party Hooks —— 官方說明第三方 hooks 相容。
• Partner Integrations —— 官方生態整合入口。

接下來去哪