《Cursor文檔》-第三方鉤子

Cursor 支持加載第三方工具的鉤子，併兼容其他 AI 編程助手現有的鉤子配置。

Claude Code 鉤子¶

Cursor 可以加載並執行爲 Claude Code 配置的鉤子，讓您可以在兩個工具中使用相同的鉤子腳本。

要求¶

要啓用 Claude Code 鉤子兼容性：

1. 在 Cursor 設置 → 規則、技能、子智能體 → 包含第三方插件、技能和其他配置中，啓用第三方技能
2. 此功能必須已爲你的賬戶啓用

配置位置¶

Claude Code 鉤子會從以下位置加載 (按優先級排序) ：

優先級順序¶

當鉤子配置在多個位置時，將按以下優先級順序合併 (從高到低) ：

1. 企業版 鉤子 (託管部署)
2. 團隊 鉤子 (在儀表盤中配置)
3. 項目 鉤子 (.cursor/hooks.json)
4. 用戶 鉤子 (~/.cursor/hooks.json)
5. Claude 項目本地配置 (.claude/settings.local.json)
6. Claude 項目配置 (.claude/settings.json)
7. Claude 用戶配置 (~/.claude/settings.json)

來自所有來源的匹配鉤子都會運行。響應發生衝突時，合併時以優先級較高的來源爲準。

企業版託管的 鉤子 和儀表盤分發功能需要企業版方案。聯繫銷售瞭解更多。

Claude Code 鉤子格式¶

Claude Code 鉤子使用相似但略有不同的格式。Cursor 會自動將 Claude 鉤子名稱映射爲 Cursor 中對應的名稱。

Claude Code settings.json 示例：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Shell",
        "hooks": [
          {
            "type": "command",
            "command": "./hooks/validate-shell.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "./hooks/audit.sh"
          }
        ]
      }
    ]
  }
}

響應格式兼容性¶

Cursor 同時支持 Claude Code 的嵌套 hookSpecificOutput 響應格式和較早的扁平響應格式。爲 Claude Code 編寫的鉤子腳本無論採用哪種格式，均可在 Cursor 中正常運行。

PreToolUse 響應格式¶

嵌套格式 (Claude Code 風格) ：

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Blocked by policy",
    "updatedInput": { "command": "npm ci" }
  }
}

扁平格式 (Cursor 原生風格) ：

{
  "permission": "deny",
  "user_message": "Blocked by policy",
  "updated_input": { "command": "npm ci" }
}

兩種格式等效。嵌套的 permissionDecision 對應 permission，permissionDecisionReason 對應 user_message，updatedInput 對應 updated_input。

Stop / SubagentStop 響應格式¶

嵌套格式 (Claude Code 風格) ：

{
  "hookSpecificOutput": {
    "decision": "block",
    "reason": "Tasks incomplete, continue working"
  }
}

扁平格式 (Claude Code 舊版風格) ：

{
  "decision": "block",
  "reason": "Tasks incomplete, continue working"
}

Cursor 原生格式：

{
  "followup_message": "Tasks incomplete, continue working"
}

對於 Stop 和 SubagentStop 鉤子，decision 爲帶有 reason 的 "block" 時，會被視爲自動跟進，等同於在 Cursor 原生格式中提供 followup_message。

鉤子步驟映射¶

Claude Code 鉤子名稱會自動映射爲對應的 Cursor 鉤子名稱：

退出碼行爲¶

Cursor 和 Claude Code 鉤子均支持通過退出碼 2 阻止操作，從而確保在不同工具間共享鉤子時行爲一致：

#!/bin/bash
# 阻止危險命令
if [[ "$COMMAND" == *"rm -rf"* ]]; then
  echo '{"permission": "deny", "user_message": "Destructive command blocked"}'
  exit 2
fi
echo '{"permission": "allow"}'
exit 0

• 退出碼 0：鉤子執行成功，使用 JSON 輸出
• 退出碼 2：阻止該操作 (等同於 permission: "deny")
• 其他退出碼：鉤子執行失敗，操作仍會繼續執行 (失敗時放行)

從 Claude Code 遷移¶

如果您已有 Claude Code 鉤子，可以：

1. 繼續使用 Claude Code 配置文件：啓用第三方技能後，現有 .claude/settings.json 中的鉤子會自動生效
2. 遷移到 Cursor 格式：按照 Cursor 格式將鉤子複製到 .cursor/hooks.json，即可獲得完整功能支持

對應的 Cursor 格式：

{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "command": "./hooks/validate-shell.sh",
        "matcher": "Shell"
      }
    ],
    "postToolUse": [
      {
        "command": "./hooks/audit.sh"
      }
    ]
  }
}

支持的功能¶

在 Cursor 中使用 Claude Code 鉤子時，支持以下功能：

其他支持的功能：

工具名稱映射¶

Claude Code 工具名稱與 Cursor 工具名稱的映射如下：

限制¶

以下功能僅在使用 Cursor 原生格式時可用：

• subagentStart 鉤子 (Claude Code 僅支持 SubagentStop)
• 循環限制配置 (loop_limit)
• 通過儀表盤分發團隊/企業版鉤子

疑難排查¶

Claude Code 鉤子未加載

1. 確認已在 Cursor 設置中啓用“第三方技能”
2. 檢查 .claude/settings.json 文件是否爲有效的 JSON
3. Cursor 會監視配置文件並自動重新加載。如果鉤子仍未加載，請重啓 Cursor。

鉤子正在運行但未阻止操作

1. 確保鉤子腳本以退出代碼 2 退出，以阻止操作
2. 檢查 JSON 輸出格式是否符合預期的 schema
3. 在 Cursor 中查看 Hooks 輸出通道，獲取錯誤詳情

Cursor 與 Claude Code 的行爲差異

由於執行環境不同，二者的行爲可能存在差異。請在兩個工具中測試鉤子，以確保兼容性。

企業版鉤子部署¶

通過儀表盤使用託管的企業版鉤子並向團隊分發。