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

本篇目錄
Hook 教學最容易卡住的地方,常常不是腳本語法,而是沒有分清楚誰送入事件、腳本讀到什麼,以及輸出會由誰解讀。本篇建立一個能重播事件的小實驗室,先用固定 JSON 驗證腳本,再接到 Claude 的實際事件。最後你會有正常、拒絕、輸入錯誤及診斷訊息四種可辨認結果。
先讀 Hooks 入門Claude Code|建立第一個 Hook設定事件與條件,確認 Hook 實際觸發。本篇會建立第一個 Hook:Claude 使用檔案編輯工具後,將事件名稱與工具名稱寫入練習專案的本機紀錄。你會先人工測試腳本,再接上 PostToolUse,最後用真實編輯確認觸發。這個起點能分清楚「程式可跑」與「Claude 真的呼叫過它」。閱讀全文與實用案例Claude Code|Hooks 實用案例建立格式檢查、測試提示及通知流程。Hook 的價值來自可預測的觸發與可辨認的結果。本篇提供三個漸進用途:檔案編輯後檢查 JavaScript 語法、提醒完成前執行測試,以及在需要注意時留下本機通知紀錄。每個用途都有停止方式,並把檢查失敗與程式故障分開處理。閱讀全文。下載第 73 篇材料,在 starter 執行。需要 Node.js 22;只有最後的真實事件步驟需要 Claude 已登入。預估閱讀 20 分鐘、實作 45 分鐘。
從一次事件看完整資料流
閱讀完整文字說明
讀懂 Hook 事件:輸入、輸出與退出碼,以流程和文件圖形呈現教學重點。
Claude 準備使用工具或已完成工具時,可以依設定呼叫你的命令。事件資料送入命令的標準輸入,也就是 stdin;腳本將機器要讀的 JSON 放在標準輸出 stdout,把人要看的診斷放到 stderr。退出碼另外表示命令如何結束。這三個管道不能混在一起理解。
本課程的 hooks/replay.mjs 會讀取 fixture、補上目前工作目錄,再把 JSON 交給指定腳本。它只是測試驅動程式,沒有偽裝成 Claude 真的做過編輯。先完成這層測試,能把腳本邏輯與登入、模型決策或工具選擇等因素分開。
{
"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、檢查最少必要欄位。這裡不宣稱驗證了官方事件的全部欄位,因為不同事件還有自己的要求。可共用的基礎檢查與個別事件語意應分開維護。
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。後者可能包含要寫入的內容或敏感資料;對確認事件有沒有觸發而言,通常不需要留下整段。
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 已在工具完成之後,這時即使診斷不理想,也不能把先前的外部動作想成從未發生。要處理已寫入檔案的修復,必須另外明確執行並核對差異。
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "protected fixture directory"
}
}
不要把這個輸出 JSON 直接放到 settings.json。設定檔描述何時執行哪一個命令;上面的 JSON 是那個命令執行後回給 Claude 的決策。這個區別也能幫你排錯:沒有啟動命令時查設定,命令有啟動卻無效時再查輸入與輸出。
接入一次真正的工具事件
先閱讀 config/hooks.settings.json,確認命令只指向本練習的 hooks 腳本。本篇可用單次啟動載入這份設定,不必更改個人全域設定。啟動前記下 events.jsonl 的行數,讓你稍後能辨認新增的真實事件,而不把之前的人工重播算進去。
claude --settings config/hooks.settings.json
請在本專案 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 的只讀診斷腳本,遇到其他事件時明確報錯。接著可做只格式化變更檔案Claude Code|只處理變更檔案的格式化 Hook限制格式化範圍並避免事件重複執行。格式化 Hook 如果每次都掃描整個專案,可能改到與任務無關的檔案。本篇只處理 Write 或 Edit 剛完成的 JSON 練習檔,檢查路徑、解析內容,再在有必要時寫回。你會用連續重播確認第二次不再產生變更,也會驗證失敗時原始資料仍保留。閱讀全文、可停止的品質檢查Claude Code|建立可停止的品質檢查 Hook讓完成檢查能指出失敗並有清楚的退出機制。測試沒有通過時,Claude 應知道工作還有問題;但如果 Hook 每次都阻止結束,又可能陷入不停重試。本篇建立有次數邊界的 Stop 檢查,第一次失敗回報原因,重複觸發時停止遞迴,並把尚未完成的結果清楚交回讀者。閱讀全文與跨平台排錯Claude Code|跨平台 Hooks:中文路徑、逾時與遞迴排錯把 Hook 做成可測試、可停用、可移植的工具。Hook 在作者的資料夾能跑,不代表移到中文路徑、另一個 shell 或不同作業系統也正常。本篇建立一張環境矩陣,檢查路徑、編碼、換行、逾時與重複事件,最後寫出能停止並恢復正常工作的操作手冊。閱讀全文。每次新增事件先寫 fixture,再接入 Claude,會比較容易找到問題。
回 Claude Code 教學總目錄Claude Code 完整教學目錄:從入門到自動化依平台、程度與功能找到需要的教學,從 96 篇文章與共用練習專案逐步完成操作。這個教學中心把 Claude Code 分成 96 個可以獨立閱讀的小題目,從桌面、CLI、網頁與手機開始,再學 MD 規則、常用指令、Skills、MCP 與自動化。你可以依推薦路線循序學習,也可以直接搜尋正在遇到的功能、命令或檔名。目錄依目前公開狀態顯示可閱讀文章。閱讀全文
覺得這篇整理實用嗎?分享給需要的朋友
同主題延伸閱讀
生活分享
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 工作方法時,不能只挑成功那一次,也不能只看第一個答案有多快。本篇用固定案例、原始紀錄和一致判準,比較品質、重試、等待與人工整合時間,最後寫出有樣本數與限制的報告,而不是保證某個方法一定省錢。