Claude Code hooks：事件、範例與運作方式

Claude Code hook 事件

官方參考文件列出了 30 多個事件，下面是大多數 hook 會用到的幾個；matcher 可以把 hook 限定在特定的工具、檔案或來源上。

hook 要放在哪裡

Claude Code hook 範例，一步一步來

把每段設定放到設定檔的 hooks 鍵下；如果檔案裡已經有 hooks 物件，就把事件當作同層的鍵加進去，不要整個取代。執行 /hooks 確認 Claude Code 已經載入。你也可以直接請 Claude 幫你寫 hook。

1. Claude 需要你時收到桌面通知

   在 ~/.claude/settings.json 加入一個 Notification hook。這裡在 macOS 上用的是 osascript；Linux 上用 notify-send，Windows 上用 PowerShell。

   {
     "hooks": {
       "Notification": [
         {
           "matcher": "",
           "hooks": [
             {
               "type": "command",
               "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
             }
           ]
         }
       ]
     }
   }

2. 自動格式化 Claude 編輯的每個檔案

   一個比對 Edit|Write 的 PostToolUse hook，用 jq 從 stdin 的 JSON 讀出被編輯檔案的路徑，再對它執行 Prettier。把它放進 .claude/settings.json，整個團隊就都能共用。

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

3. 阻擋危險指令

   一個針對 Bash 的 PreToolUse hook 會執行這支腳本。結束代碼 2 會阻擋這次呼叫，寫到 stderr 的內容會成為給 Claude 的回饋，讓它調整方向。結束代碼 0 表示不做決定，照一般權限流程處理。

   #!/bin/bash
   # .claude/hooks/block-drop-table.sh，作為 Bash 的 PreToolUse hook 執行
   INPUT=$(cat)
   COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')
   
   if echo "$COMMAND" | grep -q "drop table"; then
     echo "Blocked: dropping tables is not allowed" >&2  # 會成為給 Claude 的回饋
     exit 2                                               # 2 = 阻擋這個動作
   fi
   
   exit 0  # 不做決定：照一般權限流程處理

4. 讓 Claude 持續工作到任務完成

   一個 prompt 類型的 Stop hook 會問模型是否全部完成。如果回答是 ok: false，Claude 會把 reason 當作下一個指示繼續工作。這就是經典的 Stop hook 範例。

   {
     "hooks": {
       "Stop": [
         {
           "hooks": [
             {
               "type": "prompt",
               "prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}."
             }
           ]
         }
       ]
     }
   }

來源：Claude Code 文件，Automate actions with hooks

hook 如何決定接下來發生什麼

• 輸入：每個 hook 都會從 stdin 收到 JSON 格式的事件，例如工具名稱和 tool_input、工作階段 ID 以及 cwd。
• 結束代碼 0：沒有異議。對少數事件（例如 SessionStart 和 UserPromptSubmit），一般的 stdout 會加入 Claude 的上下文。
• 結束代碼 2：在事件允許的情況下阻擋。stderr 會依事件不同，回傳給 Claude 或顯示給你。
• stdout 輸出 JSON：更精細的控制，例如帶有權限決定的 hookSpecificOutput、用來改寫工具輸入的 updatedInput，或 additionalContext。
• 其他結束代碼：通常視為不阻擋的錯誤，除非 hook 設定了 onFailure: "block"。
• 同一事件下比對到的多個 hook 會平行執行。

command、prompt、agent 和 HTTP 類型的 hook

hook、skill 與 CLAUDE.md 的差異，以及其他注意事項

• CLAUDE.md 和 skill 是 Claude 通常會遵守的指示；hook 則每次都會執行。任何絕不能跳過的事情都應該放進 hook。
• PostToolUse 無法撤銷已經執行的動作；要阻止它，請用 PreToolUse。
• Stop 在 Claude 每次結束回覆時都會觸發，不只是在任務結束時，而且使用者中斷時不會觸發。
• hook 本身不能執行斜線指令，也不能呼叫工具；它們只能透過結束代碼、stdout、stderr 或 JSON 回傳資訊。
• "disableAllHooks": true 會關閉 hook；但受管 hook 仍會執行，除非受管設定也把它們關掉。
• hook 只作用於你本機的 Claude Code 環境。涵蓋所有 Claude 產品的組織層級檢查是另一項功能：Claude inference hooks。
• 用 PreToolUse hook 過濾測試輸出，也是減少 token 用量最有效的方法之一。

hook 讓 Claude Code 守規矩，Crewmark 讓它持續工作。

hook 是讓無人看管的 agent 變得安全的關鍵：格式化、測試和防護規則每次都會執行。Crewmark 把 Claude Code、Codex、DeepSeek Harness 或 OpenCode 工作階段變成有職位、目標和工作時間的 AI 員工，並依心跳喚醒它，從看板上接手下一個 issue，同時載入你專案裡的 hook。

1. 把 hook 提交到儲存庫

   .claude/settings.json 裡的 hook 會像在你的工作階段中一樣，在員工的工作階段中載入，所以它的編輯會被格式化，有風險的指令會被阻擋。

2. 讓心跳啟動工作

   在工作時間內，員工每 15、30 或 60 分鐘在同一個對話中醒來一次；參見如何讓 Claude Code 主動工作。

3. 只回答需要你的問題

   它會在自己的 issue 下留言，需要你拍板時傳訊息給你。閱讀什麼是 AI 員工。

Claude Code hooks 常見問題