生活分享

Claude Code|讀懂 Hook 事件:輸入、輸出與退出碼

建立可重播事件的本機測試工具。Hook 教學最容易卡住的地方,常常不是腳本語法,而是沒有分清楚誰送入事件、腳本讀到什麼,以及輸出會由誰解讀。本篇建立一個能重播事件的小實驗室,先用固定 JSON 驗證腳本,再接到 Claude 的實際事件。最後你會有正常、拒絕、輸入錯誤及診斷訊息四種可辨認結果。

閱讀時間約 7 分鐘

LINE 分享
讀懂 Hook 事件:輸入、輸出與退出碼:文件、螢幕與完成記號的幾何插圖
圖片:Mokaair (© Mokaair)
本篇目錄
  1. 1. 從一次事件看完整資料流
  2. 2. 先建立最小事件讀取器
  3. 3. 比較四種可觀察的結果
  4. 4. PreToolUse 與 PostToolUse 不能混用
  5. 5. 接入一次真正的工具事件
  6. 6. 故障注入與修復
  7. 7. 為事件紀錄加上可核對的順序
  8. 8. 完成與延伸

Hook 教學最容易卡住的地方,常常不是腳本語法,而是沒有分清楚誰送入事件、腳本讀到什麼,以及輸出會由誰解讀。本篇建立一個能重播事件的小實驗室,先用固定 JSON 驗證腳本,再接到 Claude 的實際事件。最後你會有正常、拒絕、輸入錯誤及診斷訊息四種可辨認結果。

先讀 與。下載第 73 篇材料,在 starter 執行。需要 Node.js 22;只有最後的真實事件步驟需要 Claude 已登入。預估閱讀 20 分鐘、實作 45 分鐘。

從一次事件看完整資料流

從一次事件看完整資料流 → 先建立最小事件讀取器 → 比較四種可觀察的結果
從一次事件看完整資料流 → 先建立最小事件讀取器 → 比較四種可觀察的結果 · 圖片:Mokaair (© Mokaair)
閱讀完整文字說明

讀懂 Hook 事件:輸入、輸出與退出碼,以流程和文件圖形呈現教學重點。

Claude 準備使用工具或已完成工具時,可以依設定呼叫你的命令。事件資料送入命令的標準輸入,也就是 stdin;腳本將機器要讀的 JSON 放在標準輸出 stdout,把人要看的診斷放到 stderr。退出碼另外表示命令如何結束。這三個管道不能混在一起理解。

本課程的 hooks/replay.mjs 會讀取 fixture、補上目前工作目錄,再把 JSON 交給指定腳本。它只是測試驅動程式,沒有偽裝成 Claude 真的做過編輯。先完成這層測試,能把腳本邏輯與登入、模型決策或工具選擇等因素分開。

fixtures/pre-write.json:合成 PreToolUse 事件 · json
{
  "hook_event_name": "PreToolUse",
  "tool_name": "Write",
  "tool_input": { "file_path": "private/demo.txt" },
  "session_id": "synthetic-73"
}

fixture 沒有寫死作者電腦的絕對路徑。重播器會在執行時補上 cwd,並把 file_path 解析為這次練習的實際位置。如果把別人的事件完整照貼到自己電腦,裡面可能仍指向對方的資料夾,結果會讓你誤以為檔案不存在或規則失效。

先建立最小事件讀取器

打開 hooks/event.mjs。它只做三件事:讀完 stdin、解析 JSON、檢查最少必要欄位。這裡不宣稱驗證了官方事件的全部欄位,因為不同事件還有自己的要求。可共用的基礎檢查與個別事件語意應分開維護。

寫入 hooks/event.mjs · javascript
import { readFileSync } from 'node:fs';
export function readEvent() {
  const text = readFileSync(0, 'utf8').replace(/^\uFEFF/, '');
  const event = JSON.parse(text);
  if (!event || typeof event.cwd !== 'string'
      || typeof event.hook_event_name !== 'string') {
    throw new Error('event needs cwd and hook_event_name');
  }
  return event;
}
export function emit(value) {
  process.stdout.write(JSON.stringify(value) + '\n');
}

開頭去除 BOM 是為了讓不同文字編輯器存出的 UTF-8 fixture 更容易重播,不代表所有編碼都能自動轉換。若你用 UTF-16 儲存 JSON,應先改回 UTF-8,再排查欄位。遇到解析失敗時,不要先修改工具權限;那是不同層的問題。

比較四種可觀察的結果

先執行唯讀的 audit 重播。腳本只保存事件名稱、工具、工作階段識別碼與時間,故意不保存完整 tool_input。後者可能包含要寫入的內容或敏感資料;對確認事件有沒有觸發而言,通常不需要留下整段。

專案終端機:在 starter 重播兩種事件 · text
node hooks/replay.mjs audit fixtures/post-edit.json
node hooks/replay.mjs protect fixtures/pre-write.json

第一個命令成功時可能沒有 stdout,請看 run-data/events.jsonl 是否多一筆資料。第二個命令應輸出含有 deny 的 PreToolUse 決策,因為 fixture 指向受保護的假資料目錄。沒有畫面文字不一定失敗,有 JSON 也不一定成功;要對照該腳本的輸出約定。

情況可觀察結果代表的意義
audit 正常新增一筆 JSONL,退出碼 0腳本已記錄事件
protect 拒絕stdout 有 deny 決策請 Claude 阻擋對應工具操作
JSON 損壞stderr 說明解析問題腳本沒有拿到合法事件
格式化失敗PostToolUse 的 additionalContext原工具已完成,另回傳後續診斷

在 PowerShell 用 $LASTEXITCODE 看上一個外部命令的退出碼;Bash 用 echo $?。不要在檢查退出碼前先跑另一個命令,否則讀到的是後者的結果。若把成功訊息加進 stdout,記得它會破壞原本只含 JSON 的機器介面。

PreToolUse 與 PostToolUse 不能混用

PreToolUse 發生在特定工具動作之前,拒絕範例會使用 hookSpecificOutput 及對應事件名稱。PostToolUse 已在工具完成之後,這時即使診斷不理想,也不能把先前的外部動作想成從未發生。要處理已寫入檔案的修復,必須另外明確執行並核對差異。

protect.mjs 的預期 stdout:這是結果,不是設定檔 · json
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "protected fixture directory"
  }
}

不要把這個輸出 JSON 直接放到 settings.json。設定檔描述何時執行哪一個命令;上面的 JSON 是那個命令執行後回給 Claude 的決策。這個區別也能幫你排錯:沒有啟動命令時查設定,命令有啟動卻無效時再查輸入與輸出。

接入一次真正的工具事件

先閱讀 config/hooks.settings.json,確認命令只指向本練習的 hooks 腳本。本篇可用單次啟動載入這份設定,不必更改個人全域設定。啟動前記下 events.jsonl 的行數,讓你稍後能辨認新增的真實事件,而不把之前的人工重播算進去。

專案終端機:僅在這次 Claude 啟動載入練習設定 · text
claude --settings config/hooks.settings.json
Claude Code 對話框:要求一個明確的練習操作 · text
請在本專案 fixtures/demo.json 寫入 {"value":1}。
只修改這個練習檔,完成後指出寫入位置。

依你實際權限設定處理工具詢問。操作後檢查檔案真的存在,再查看事件 log 是否記錄 Write 或 Edit。若模型只回覆一段建議、沒有呼叫工具,PostToolUse 當然不會出現;若所用工具名稱不同,matcher 也可能不匹配。應記錄真正使用的工具名稱,再調整測試,不要單純把 matcher 放寬成所有事件。

故障注入與修復

先複製 pre-write.json,把最後一個大括號刪掉。執行重播應看到 JSON 解析錯誤,接著恢復字元、用相同命令重跑。第二個故障把 hook_event_name 改成 Stop,再送進 protect;應得到事件不符。這兩種失敗分別驗證資料格式與業務前提,不應被同一個空成功回覆吞掉。

再試一次把 audit 的 log 目錄暫時設成不可寫的位置,觀察 stderr 及退出碼。這個案例只在你建立的測試目錄進行,無需改作業系統重要資料夾權限。修復後確認沒有把半筆 JSON 留在正式紀錄,並說明哪些事件是在故障期間沒有保存。

為事件紀錄加上可核對的順序

同一次編輯可能產生多個事件,不能只靠記錄行數推定有幾次使用者操作。重播時一次送入一個固定事件,記下命令與對應輸出,再進入 Claude 的實際工作階段。如此才能分辨腳本解析問題和產品事件沒有觸發的問題。

若紀錄中只看到完成事件而沒有前置事件,先檢查兩者的設定位置及 matcher,不要推定前置防護已運作。每個要依賴的事件都需要自己的觸發證據。

完成與延伸

交付時保存四種輸入、每次 stdout/stderr/退出碼,以及真實觸發前後的 log 差異。合成事件可重播,是腳本測試成功;真實 Claude 工具產生了紀錄,才是設定和執行鏈一起通過。兩者都重要,但驗證了不同東西。

完成判準是你能從症狀判斷問題在設定、輸入、事件語意、腳本或輸出通道,並能用一個最小案例重現。若登入過期或當前平台沒有完成真實操作,保留文件與重播測試成果,把那一項標成待測,不改寫成已驗證。

小練習是增加一個只接受 PostToolUse 的只讀診斷腳本,遇到其他事件時明確報錯。接著可做、與。每次新增事件先寫 fixture,再接入 Claude,會比較容易找到問題。

覺得這篇整理實用嗎?分享給需要的朋友

LINE 分享

回總目錄

  • 生活分享

    Claude Code|建立第一個 mod:在 Claude Code 行程內數工具呼叫

    寫一個三檔案的 mod,用驗證器與測試確認它掛上的事件。文件把 mod 定義成多了入口檔的 plugin:入口檔叫 hooks module,Claude Code 在事件發生時呼叫裡面的函式,函式可以觀察、改寫或接手事件。

  • 生活分享

    Claude Code|Git Worktree 平行工作

    隔離多個任務的檔案與分支。Git Worktree 讓同一儲存庫擁有多個工作目錄,各自使用分支與檔案。本篇會把待辦篩選與文件整理分開,確認兩個 session 不會直接改到彼此的檔案,再把其中一個成果整合回主分支。你也會知道何時可以安全清理工作目錄。

  • 生活分享

    Claude Code|雙 Worktree 實作與衝突整合

    隔離兩項功能,最後完成整合與回歸。兩個 Claude 工作階段同時編輯專案,最容易出現的問題是互相改到同一份檔案,或各自測試通過、整合後卻失敗。本篇用兩個 Worktree 分別處理篩選預設值與介面文字,故意製造一次小衝突,再完成整合、驗證與清理。你不需要先啟用 Agent Teams。

  • 生活分享

    Claude Code|比較流程品質、用量與執行時間

    以同一資料集比較兩種工作方法。比較兩種 Claude 工作方法時,不能只挑成功那一次,也不能只看第一個答案有多快。本篇用固定案例、原始紀錄和一致判準,比較品質、重試、等待與人工整合時間,最後寫出有樣本數與限制的報告,而不是保證某個方法一定省錢。

資料來源

本文依據上方所列參考來源與標示之核對日期整理;票價、時刻、功能規格或服務條款可能變動,出發、預訂或購買前請至相關官方網站確認最新資訊。

生活分享