Claude Code Hooks 完全解析:圍繞 Agent 的確定性控制層

什麼是 Claude Code hooks? Hooks 是使用者自訂的 shell 指令(外加 HTTP 端點、MCP 工具與模型提示詞),Claude Code 會在其生命週期的固定時間點自動執行:工具呼叫之前、編輯之後、工作階段開始時、Claude 完成回應時。¹ CLAUDE.md 給模型的是「大概會遵守」的指示,而 hooks 無論模型配不配合都會執行。在任何工作階段中輸入 /hooks,即可查看每個生命週期事件,以及綁定在其上的內容。 {.answer-block}

多數開發者使用 Claude Code 時仰賴兩層控制:權限限制 agent 可以做什麼,CLAUDE.md 描述它應該做什麼。Hooks 是第三層,也是唯一能保證任何事情的一層。以下依序說明:心智模型、目前文件記載的每個生命週期事件、精確的輸入/輸出契約、設定方式、五種可直接使用的模式,以及一套決策框架。所有 API 細節都已於 2026年7月1日 依官方 hooks 參考文件與指南逐一驗證——這個系統演進得很快,若本文與參考文件有出入,以參考文件為準。(剛接觸 Claude Code?建議從 5 分鐘安裝設定或 Claude Code 新手路徑開始。)

TL;DR: Hooks 從 stdin 接收 JSON,並以結束代碼或 stdout 的 JSON 回應。Exit 0 表示允許,exit 2 表示阻擋(在支援阻擋的事件上),而 exit 1——Unix 慣用的失敗代碼——什麼都擋不住,這是 hooks 最大的地雷。² 請在 settings.json 中以 PreToolUse、Stop 等事件名稱設定,並透過 matcher 篩選。凡是必須每次都發生的事,用 hooks;模型只需要知道的事,用 CLAUDE.md。

心智模型:圍繞非確定性核心的保證

編碼 agent 是一個機率性系統。要求它每次編輯後執行 Prettier,它會照做——大多數時候。當變更看起來微不足道、上下文拉得太長,或您的措辭稍有不同時,它可能就跳過這一步。CLAUDE.md、skills 與提示詞全都只是建議:品質很高、通常會被遵循,但永遠沒有保證。

Hooks 就是包覆在這個核心外的確定性外殼。官方定義是:「使用者自訂的 shell 指令、HTTP 端點或 LLM 提示詞,在 Claude Code 生命週期的特定時間點自動執行」,提供「對 Claude Code 行為的確定性控制,確保某些動作一定會發生,而不是仰賴 LLM 自行決定是否執行」。³ 格式化工具在每次編輯後觸發。指令防護會評估每一次 Bash 呼叫。完成閘門會檢查每一次結束。

這種強制力是真實的,不是裝飾:PreToolUse hooks 會在任何權限模式檢查之前觸發,因此回傳 permissionDecision: "deny" 的 hook,即使在 bypassPermissions 模式或 --dangerously-skip-permissions 之下也能阻擋工具。反過來則不成立——回傳 "allow" 的 hook 無法放寬設定中的 deny 規則。Hooks 可以把政策收得比權限更緊,但永遠無法將其放鬆。⁴

生命週期:所有 hook 事件

截至 2026年7月1日,參考文件共記載 30 個 hook 事件。¹ 它們分為三種節奏:每個工作階段一次(SessionStart、SessionEnd)、每回合一次(UserPromptSubmit、Stop、StopFailure),以及 agentic 迴圈內的每次工具呼叫(PreToolUse、PostToolUse)。其餘事件則在特定條件下觸發——設定變更、上下文壓縮、子代理、MCP 互動。

這些事件大多用不到。幾乎所有正式環境的設定都是由五個事件組成:PreToolUse、PostToolUse、UserPromptSubmit、SessionStart 與 Stop。其餘的存在,是為了您哪天需要它們的時候。

契約:輸入 JSON,輸出結束代碼或 JSON

Command hooks 從 stdin 接收 JSON,並透過結束代碼、stdout 與 stderr 回應。(HTTP hooks 以 POST 主體接收相同的 JSON,並透過回應主體作答。)²

每個事件都會傳遞一組共同的信封欄位——session_id、transcript_path、cwd 與 hook_event_name,多數事件還帶有 permission_mode——再加上各事件專屬的欄位。針對 Bash 指令的 PreToolUse hook 會收到:

{
  "session_id": "abc123",
  "transcript_path": "/home/user/.claude/projects/.../transcript.jsonl",
  "cwd": "/home/user/my-project",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": { "command": "npm test" }
}

其他事件則替換尾端欄位:UserPromptSubmit 帶有 prompt,SessionStart 帶有 source(startup/resume/clear/compact),Stop 帶有 stop_hook_active 與 last_assistant_message。在子代理內觸發的 hooks 還會額外收到 agent_id 與 agent_type。²

結束代碼

三種結果:²

• Exit 0——成功。Claude Code 會解析 stdout 中的 JSON 輸出欄位。對多數事件而言,stdout 只會進入除錯日誌;但對 UserPromptSubmit、UserPromptExpansion 與 SessionStart,純文字 stdout 會被加入為 Claude 看得到的上下文。
• Exit 2——阻擋性錯誤。Stdout(包括任何 JSON)會被忽略;stderr 會作為錯誤訊息回饋給 Claude。「阻擋」的具體含義取決於事件。
• 其他任何結束代碼——非阻擋性錯誤。對話紀錄會顯示 <hook name> hook error 通知,執行則繼續進行。

最後一點值得加粗強調:exit 1 什麼都擋不住。文件對此有直接警告——即使 1 是 Unix 慣用的失敗代碼,Claude Code 仍將 exit 1 視為非阻擋性錯誤並繼續執行。政策類 hooks 必須 exit 2。²

Exit 2 在各事件上的效果:²

其餘事件都無法阻擋。PostToolUse 與 PostToolUseFailure 會把 stderr 顯示給 Claude(工具已經執行完畢);SessionStart、Notification、SessionEnd、CwdChanged、FileChanged、PostCompact、SubagentStart 與 Setup 只會把 stderr 顯示給使用者;StopFailure、InstructionsLoaded、MessageDisplay 與 PermissionDenied 則完全忽略結束代碼——對 PermissionDenied 而言,唯一的控制桿是 JSON 的 retry: true。²

JSON 輸出

若需要比「阻擋或沉默」更精細的控制,請以 exit 0 結束,並將一個 JSON 物件印到 stdout。先講一條規則:結束代碼或 JSON,兩者擇一,絕不並用——JSON 只在 exit 0 時才會被處理,exit 2 會將其捨棄。⁵

通用欄位適用於每個事件:continue: false 會讓 Claude 完全停止(並向使用者顯示 stopReason),suppressOutput 會在對話紀錄中隱藏 stdout,systemMessage 會向使用者顯示警告,terminalSequence 則會發出允許清單內的終端機逸出序列(桌面通知、視窗標題、響鈴)。決策欄位則因事件而異:⁵

有兩個細節常讓人踩坑。第一,PreToolUse 是頂層 decision 模式的例外:它在歷史上曾使用頂層 decision/reason,但這些欄位在此事件上已棄用("approve"/"block" 對應到 "allow"/"deny");請改用 hookSpecificOutput.permissionDecision。⁵ 第二,當多個 PreToolUse hooks 意見不一時,優先順序為 deny > defer > ask > allow。⁵

設定:settings.json、matcher 與作用範圍

Hook 設定分為三層巢狀結構:選擇一個事件,加入一個 matcher 群組來篩選觸發時機,再定義一個或多個要執行的 hook handler。⁶

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "/path/to/lint-check.sh" }
        ]
      }
    ]
  }
}

放置位置決定作用範圍:~/.claude/settings.json 適用於您的所有專案,.claude/settings.json 是專案範圍且可提交至版本控制,.claude/settings.local.json 是專案範圍但被 gitignore 排除,並且套用標準的設定優先順序——受管理原則優先於 local,local 優先於專案,專案優先於使用者。⁹ Hooks 也可以隨外掛(hooks/hooks.json)以及 skill 或 agent 的 frontmatter 一起提供,而企業管理員可以強制施行使用者無法覆寫的受管理 hooks。⁶

Matcher 依其字元內容進行判定:"*"、"" 或省略 matcher 會匹配所有內容;只包含字母、數字、_、-、空格、逗號與 | 的值,會被視為精確字串或清單(Bash、Edit|Write);其他任何值都會成為未錨定的 JavaScript 正規表示式,因此 Edit.* 會同時匹配 Edit 與 NotebookEdit——若您指的就是單一工具,請用 ^Edit$ 加以錨定。Matcher 區分大小寫,且每個事件依自己的欄位進行匹配:工具事件用工具名稱,SessionStart 用 source,SubagentStart 用 agent 類型,Notification 用通知類型。⁶ 若要在工具事件上做更精準的篩選,每個 handler 的 if 欄位可接受一條權限規則,例如 "Bash(git *)"——但它只是盡力而為(遇到無法解析的指令時會直接放行),因此需要硬性保證時,請使用權限規則而非 if。⁶

Handler 共有五種類型:command(shell)、http(POST 端點)、mcp_tool、prompt(單回合模型評估),以及 agent(具備 Read/Grep/Glob 存取權的子代理;實驗性功能)。預設逾時:command/http/mcp_tool 為 600 秒(UserPromptSubmit 降為 30 秒、MessageDisplay 降為 10 秒),prompt 為 30 秒,agent 為 60 秒——可透過 timeout 針對個別 hook 覆寫。⁶ 所有匹配的 hooks 會平行執行,完全相同的 handler 會去除重複,而 $CLAUDE_PROJECT_DIR 會將指令碼指向您的專案根目錄。

使用 /hooks 進行驗證:這是一個唯讀的瀏覽介面,顯示每個事件、其已設定的 hooks,以及各自來自哪個設定檔。要修改任何內容,請直接編輯 JSON(或請 Claude 代勞)。要暫時停用全部 hooks,請設定 "disableAllHooks": true。⁶

五種模式

以下皆為通用化的最小範例。hooks 教學為其中幾種建構了更完整的正式環境版本,而 Apple 開發的 Hooks 則將它們應用於 iOS 工具鏈。

1. 編輯後自動格式化(PostToolUse)

直接取自官方指南——Claude 碰過的每個檔案都會被格式化,沒有例外:³

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }
        ]
      }
    ]
  }
}

依您的技術堆疊需求,將指令換成 ruff format、gofmt 或 swiftformat。

2. 阻擋危險指令(PreToolUse,exit 2)

#!/bin/bash
# .claude/hooks/guard-bash.sh — register on PreToolUse, matcher "Bash"
command=$(jq -r '.tool_input.command // empty')
case "$command" in
  *"rm -rf"* | *"git push --force"* | *"DROP TABLE"*)
    echo "Blocked: matches a destructive pattern. Propose a safer alternative." >&2
    exit 2 ;;
esac
exit 0

Exit 2 會阻擋該次呼叫,並將 stderr 回饋給 Claude,讓它調整方向而非盲目重試。等效的 JSON 寫法——附帶理由的 permissionDecision: "deny"——效果相同,還保留了成長空間:可改用 "ask"(升級交由人類決定)或 updatedInput(改寫指令)。⁵

3. 工作階段開始時注入上下文(SessionStart)

SessionStart hook 的純文字 stdout 會直接成為 Claude 看得到的上下文——不需要 JSON:¹

#!/bin/bash
# .claude/hooks/session-context.sh — register on SessionStart
echo "Current branch: $(git branch --show-current)"
echo "Recent commits:"
git log --oneline -5
echo "Uncommitted files: $(git status --porcelain | wc -l | tr -d ' ')"
exit 0

這種做法適合動態狀態。靜態慣例應放在 CLAUDE.md——官方文件本身也建議,不需要指令碼的上下文就放在那裡。¹

4. Stop 上的完成閘門

Stop 在 Claude 完成回應時觸發。阻擋它可以強制 agent 持續工作,直到滿足特定條件為止:

#!/bin/bash
# .claude/hooks/stop-gate.sh — register on Stop
input=$(cat)
if [ "$(echo "$input" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # already continuing because of this hook; don't loop forever
fi
if ! npm test --silent > /tmp/stop-gate.log 2>&1; then
  jq -n '{decision: "block", reason: "Tests are failing. Fix them before finishing. Log: /tmp/stop-gate.log"}'
fi
exit 0

stop_hook_active 的檢查很重要:Claude Code 對 Stop hook 設有連續 8 次阻擋的硬性上限,而一個從不檢查自己是否已觸發續行的閘門,很快就會把額度全部燒光。⁷ 若想採取較柔性的引導,可回傳 hookSpecificOutput.additionalContext 取代 decision: "block"——同樣能讓對話繼續,但屬於有標記的回饋而非 hook 錯誤。至於一次性的條件,內建的 /goal 指令就是一個工作階段範圍、基於提示詞的 Stop hook,完全不需要設定。¹

5. 分派器:單一進入點,多個小型 hooks

註冊十個 hooks,意味著十筆 settings.json 項目,會在不同機器與專案之間逐漸失去同步。替代方案:每個事件只註冊一個分派器,再依慣例路由。

#!/bin/bash
# .claude/hooks/dispatch.sh — register once per event you care about
input=$(cat)
event=$(echo "$input" | jq -r '.hook_event_name')
dir="$CLAUDE_PROJECT_DIR/.claude/hooks/$event"
[ -d "$dir" ] || exit 0
for hook in "$dir"/*.sh; do
  [ -x "$hook" ] || continue
  echo "$input" | "$hook" || exit $?
done
exit 0

現在,新增一道防護只需在 .claude/hooks/PreToolUse/ 裡對新檔案 chmod +x——settings.json 完全不必更動,每支指令碼都小到能獨立測試,而且第一個 exit 2 會向外傳播。有一點要注意:分派器會把 Claude Code 原本平行執行的工作序列化,因此最適合結束代碼型的 hooks——會輸出 JSON 的 hook 應維持獨立註冊,因為 stdout 必須恰好包含一個 JSON 物件。⁵

Hook、CLAUDE.md、skill 與 memory 該怎麼選

四種機制,四種職責:

失誤模式在兩個方向上都會發生。把慣例編成 hooks,換來的是一堆脆弱的指令碼,強制執行著一句指引就能處理好的事。把政策寫成 CLAUDE.md 的文字,換來的是 agent 在最要命的那一天強制推送到 main。判斷標準:模型忽略這件事一次,代價是什麼?只是小麻煩→CLAUDE.md。會釀成事故→hook。

Hooks 做不到的事

誠實列出限制,全部出自官方文件:⁷

• Hooks 無法呼叫工具或斜線指令。Command hooks 只會說 stdout、stderr 與結束代碼這三種語言——僅此而已。透過 additionalContext 回傳的上下文會以純文字形式注入。
• PostToolUse 無法復原。工具已經執行完畢。預防要靠 PreToolUse。
• Stop 在每次回應結束時都會觸發,而不是只在「任務完成」時,且使用者中斷時永遠不會觸發(API 錯誤則改為觸發 StopFailure)。閘門邏輯必須容忍任務中途的停止。
• PermissionRequest 在 headless(-p)模式下不會觸發。自動化的權限決策請改用 PreToolUse。
• PreToolUse 看不到以 @ 引用的檔案。在提示詞中透過 @ 拉進來的檔案不涉及任何工具呼叫;要保護路徑不被這條途徑存取,請使用 Read 的 deny 規則。¹
• 平行的 updatedInput 是非確定性的。當多個 PreToolUse hooks 改寫同一個工具的參數時,最後完成的那個勝出。每一種改寫都應交由單一 hook 負責。
• 逾時會取消 hook。Command hooks 預設 600 秒(UserPromptSubmit 為 30 秒、MessageDisplay 為 10 秒);一個因逾時而失效的緩慢閘門,等於沒有執行的閘門。
• 輸出上限為 10,000 個字元——超出的部分會寫入檔案,並以預覽取代。
• Hooks 以您的完整使用者權限執行。參考文件自己就這樣警告:它們「可以修改、刪除或存取您的使用者帳號能存取的任何檔案。將 hook 指令加入設定之前,請先審查並測試所有指令」。⁸ 請為變數加上引號、使用絕對路徑、避開敏感檔案。
• 一個壞掉的 hook 會拖累每個工作階段,直到修好為止。除錯可用對話紀錄檢視(Ctrl+O)、claude --debug-file /tmp/claude.log,或在工作階段中使用 /debug;一個經典的陷阱是 shell profile 在啟動時輸出文字,污染了 hook 的 JSON 輸出。⁷

常見問題

什麼是 Claude Code hooks?

Hooks 是使用者自訂的指令——shell 指令碼、HTTP 端點、MCP 工具或模型提示詞——由 Claude Code 在特定的生命週期時間點自動執行。³ 它們從 stdin 接收事件 JSON,並以結束代碼或 JSON 回應:阻擋工具呼叫、注入上下文、改寫參數、讓 agent 持續工作。與 CLAUDE.md 的指示不同,無論模型行為如何,它們每次都會執行。

PreToolUse hooks 與權限有什麼差別?

權限規則是宣告式的:由 Claude Code 自行評估的靜態 allow/deny/ask 模式。PreToolUse hooks 則是可程式化的:由您的程式碼檢視完整的工具輸入後做出決定。Hooks 在權限模式檢查之前觸發,因此 hook 的 "deny" 即使在 bypassPermissions 模式下也依然有效——但 hook 的 "allow" 無法覆寫設定中的 deny 規則。⁴ 凡是模式能表達的,就用權限規則;當決策需要邏輯、外部狀態或改寫輸入時,才動用 hook。

Hooks 在 headless(-p)模式下能運作嗎?

可以——但有一個文件記載的例外:PermissionRequest hooks 在非互動模式下不會觸發,因此自動化的權限決策應放在 PreToolUse。⁷ Headless 模式還解鎖了一個互動式工作階段會忽略的選項:permissionDecision: "defer",它會暫停工具呼叫,讓外層包裝的程序(Agent SDK 應用程式、自訂 UI)收集輸入後,再恢復工作階段。⁵

為什麼我的 hook 有執行,卻什麼都擋不住?

幾乎都是違反了契約。Exit 1 不會阻擋——只有 exit 2 會,而且僅限支援阻擋的事件。² JSON 決策只在 exit 0 時才會被解析——一支印出 {"decision": "block"} 卻以 exit 2 結束的指令碼,其 JSON 會被直接捨棄。此外,matcher 區分大小寫——bash 永遠不會匹配 Bash。請先用 /hooks 確認註冊狀態,再將範例 JSON 透過管線送進指令碼測試,並檢查 echo $?。⁷

資料來源

已於 2026年7月1日 依官方文件驗證。Hooks API 在 Claude Code v2.1.x 各版本之間已有實質變動(新事件、新欄位、matcher 語意),因此請將版本敏感的細節視為「截至本文日期為止」的資訊。

本站相關文章:Claude Code 指南的 hooks 章節提供包含 prompt 與 agent hooks 在內的完整系統視角;hooks 教學提供五個附完整設定的正式環境實作;Apple 開發的 Hooks 示範應用於 iOS 的模式;若您尚未安裝 Claude Code,請從快速入門開始。