Claude Code PreToolUse hook 回 defer 之後,claude -p 的行程去哪了:結束一輪、待決呼叫留在 transcript,resume 時 hook 會再被問一次,2.1.328 新增的 CLAUDE_CODE_DISABLE_DEFERRED_TOOL_RESUME 又關掉什麼
hook 回了 defer,那個 claude -p 的行程到底去哪了?
文件說它「暫停」。暫停這個詞很容易讓人想到一個行程停在半空中,等著誰按一下繼續。我直接拿本機的 2.1.330(11 月 20 日發布的版本)做了一次:掛一個 PreToolUse hook,只攔 Bash,永遠回 defer,然後請 Claude 跑一行 echo。
1 | claude -p "Run exactly one Bash command: echo DEFER_TEST_OK . Do nothing else." \ |
回來的 JSON,我節錄跟這件事有關的欄位:
1 | { |
行程的 exit code 是 0。is_error 是 false,result 是空字串,subtype 還寫著 success。
所以答案很無聊:它不是睡著,它結束了。呼叫端如果只看 exit code 或 is_error,會以為一切順利,而事情根本沒做完。唯一說實話的欄位是 stop_reason。
行程結束了,單據還在抽屜裡
打個比方,這個比方只負責幫你記住順序,不是機制本身。櫃檯人員拿到一張需要主管簽核的單子,主管不在。他不會抱著單子站在原地等,而是把單子放進抽屜、下班走人。隔天另一個人上班,打開抽屜,看到那張單子,再去問一次主管。
對上 Claude Code,三件事各有一個對應。文件寫的是:defer 會讓這一輪結束,結果帶著 stop_reason: "tool_deferred",而待決的工具呼叫留在 transcript 裡。這就是「單子放進抽屜」。接手的人是下一個 claude -p --resume <session-id> 行程。而它問主管的那一步,是同一個工具呼叫再觸發一次 PreToolUse。
這個結構順便解釋了兩個看起來奇怪的事。
第一,文件說 defer 沒有逾時、沒有重試上限。文件只說了沒有逾時;我的推論是行程都已經不在了,沒有東西在計時。單子躺在磁碟上的 session 裡,直到 cleanupPeriodDays 的清理把它掃掉,預設是 30 天。清理這件事我之前寫過一篇 cleanupPeriodDays 與 claude purge 各清什麼,這裡不重講,只需要知道「單子有保存期限」。
第二,文件說 defer 只在 -p 模式有效,而且那一輪只能有一個工具呼叫。互動模式下它只記一條警告然後忽略;同一輪有好幾個工具呼叫時也是警告加忽略,改走一般的權限流程。要有人在行程外面接著做後續,才有意義,所以只有「把 claude 當子行程跑」的整合方式用得到。這幾條我只讀了文件,沒有造出那兩種情況。
接回去的時候,同一個問題會再問一次
單子放進抽屜之後,我做了兩個實驗,想弄清楚「再問主管」是不是真的發生。
實驗 B:不帶任何 prompt,直接 claude -p --resume <session-id> --settings …,hook 仍然回 defer。結果又是 stop_reason: tool_deferred,deferred_tool_use.name 還是 Bash,而 hook 自己寫的 log 多了一行。同一個呼叫,hook 被再叫了一次。
實驗 C:把 hook 的模式檔改成 allow,同一個 session 再 --resume,一樣不帶 prompt。這次回來 stop_reason: end_turn,result 是「已執行完畢,輸出為 DEFER_TEST_OK。」,log 又多一行 mode=allow。沒有任何新的 prompt,那個 Bash 就被接回去跑完了。
放行時,hook 輸出的樣子是這樣:
1 | {"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}} |
把這兩個實驗放在一起,有一件事會變得很明確:第一次的 defer 沒有被記住。每次接回,hook 都是重新判斷。這意味著 hook 得是「問第二次也沒事」的寫法,不能假設它只會被叫一次。如果你的 hook 在第一次被問的時候發了一則通知、扣了一次額度、寫了一筆紀錄,接回時它會再做一遍。
文件還補了一個方向相反的細節:接回時如果答案還沒準備好,hook 可以再回一次 defer;而這時如果你同時帶了 prompt,Claude 會在沒有該工具結果的情況下直接回答 prompt,不去執行那個呼叫。所以文件的建議是,在 hook 回 allow 或 deny 之前,resume 都不要帶 prompt。我只實測了不帶 prompt 的兩次,帶 prompt 那條是文件原文。
另一個容易漏掉的:文件說用 -p 接回時,Claude Code 不會還原先前儲存的權限模式,會用一個新的 claude -p 起手的模式。如果原本那個 session 用過 --permission-mode 或 --dangerously-skip-permissions,接回時要再傳一次。這條我也沒有實測。
把 DISABLE 打開之後,單子被跳過了
最讓我意外的是 2.1.328 新加的那個環境變數。changelog 的原文是:Added CLAUDE_CODE_DISABLE_DEFERRED_TOOL_RESUME, which lets a host stop claude -p --resume and --continue from running a tool call that a hook deferred,發布日是 11 月 19 日。env-vars 文件的說明是設成 1 就在 -p 接回時跳過 deferred 的工具呼叫,還補了一句 Claude can still repeat the call,也就是 Claude 仍然有可能自己重做。
跳過是什麼意思,我拿兩個實驗去問。
實驗 D:另開一個 session,hook 對 echo DEFER_TEST_B 回 defer。然後帶著 CLAUDE_CODE_DISABLE_DEFERRED_TOOL_RESUME=1,不帶 prompt 去 --resume。行程 exit code 是 1,stderr 是:
1 | Error: Input must be provided either through stdin or as a prompt argument when using --print |
hook 的 log 沒有新增任何一行。
對照實驗 B 與 C,這個差異很乾淨。沒開這個變數時,不帶 prompt 的 resume 是合法的,因為有一個待決的呼叫可以接;開了之後,同一條指令變成需要 prompt,hook 也沒被叫。我的推論(只是推論)是:這個變數關掉的是「接回時重放待決呼叫」那一步,所以 resume 退回成一般的 -p --resume,和普通情況一樣必須給 prompt。文件另有一句說,接回帶 deferred 工具呼叫的 session 時可以省略 prompt,兩者互相對得上。
實驗 E:同一個 session,帶著這個變數,這次給了 prompt:「繼續。用一句話說你剛才有沒有執行那個指令。」,模式檔設成 allow。結果 stop_reason: end_turn,hook 的 log 一樣沒有新增行。Claude 的回答是:
不確定:我送出了那個 echo DEFER_TEST_B 的 Bash 呼叫,但 session 在結果記錄前就中斷了,所以我沒有看到輸出,無法證明它有沒有執行。
這句話是我覺得整個實驗裡最值得停下來的地方。被跳過的呼叫,hook 不會再被問。至於 transcript 裡實際長什麼樣,我沒有去看;從 Claude 的回答推測,它眼中的歷史是一個「發出去、沒有回音」的呼叫,它自己判斷不了。這次它選擇誠實說不確定,沒有重做;文件說它可以重做,我只跑了一次,不知道重做的機率有多高。我也沒有另外確認那個 echo 到底有沒有跑,只能說 hook 沒被觸發、Claude 自己說不準。
另外一條限定值得記:文件說這個變數寫在 settings 的 env 區塊會被忽略,只能放行程的環境變數。也就是說它是「呼叫端啟動 claude 的時候」設的,不是專案設定檔能代勞的。這句我沒有試。
文件寫了、我沒造出來的分支
下面這幾條,全部是文件原文,我沒有造出對應場景。
工具不可用的分支:如果接回的 session 裡,那個 deferred 呼叫的工具不存在,例如它是某個 MCP server 的工具而那個 server 沒連上,結果會帶 stop_reason: "tool_deferred_unavailable",hook 不會觸發,deferred_tool_use 會指出是哪個工具。這時你送的 prompt 到不了 Claude,行程以 exit 1 結束。要執行就讓工具回來再 resume;要放棄這個呼叫,就帶 prompt 並設 CLAUDE_CODE_DROP_UNAVAILABLE_DEFERRED_TOOL=1。文件註明 v2.1.319 之前的行為不同,那些版本會直接回答 prompt 並丟掉那個呼叫。changelog 的 2.1.319(11 月 6 日發布)只有一條對應的 Fixed,寫的是「keeps the call and refuses later input」,上面這兩個名字我在 CHANGELOG.md 裡 grep 不到,只在文件頁裡出現。
多個 hook 回不同決定時的優先序:deny 大於 defer 大於 ask 大於 allow。
defer 這個功能本身是 2.1.89(4 月 1 日)加進來的。後面還有幾次相關的修正:2.1.239 讓被 defer 的工具在接回時接進原本那一輪的 OpenTelemetry trace,2.1.321 修了「另一個 hook 的 defer 先跑完,導致 ask 被吞掉」。這些我只讀了 changelog。
這篇的實測只有五次 claude -p,環境是 2.1.330、工具是 Bash 的 echo,hook 是我自己掛在 --settings 上的一支。AskUserQuestion 搭配 --permission-prompt-tool 的完整來回、tool_deferred_unavailable 與 DROP 變數、多工具同輪、互動模式忽略 defer、plan 模式接回(文件說需要 v2.1.246 以上)、Ignored in a settings env block、不帶 DISABLE 但帶 prompt 的 resume 行為,我都沒有跑,上面寫的是「文件這樣說」。DISABLE 打開後 Claude 為什麼沒有重做那個呼叫,我也沒有答案。
拆完之後,這個東西是給誰用的
回頭用抽屜的圖來看,用途就很清楚了。
需要 defer 的,是把 claude -p 當子行程、並且自己有一套介面的人。Claude 想問使用者問題或要執行一個需要人點頭的工具,你的程式讀到 deferred_tool_use,把問題送到自己的畫面或審批系統,等人答完,再 resume 並讓 hook 回 allow(答案放進 updatedInput)。中間不管隔了五分鐘還是三天,都沒有行程在空等。文件舉的典型例子是 AskUserQuestion,它在 -p 裡只有在有 permission host 的時候才會被提供,所以要配 --permission-prompt-tool。
跟站上之前寫的兩個機制放在一起,會看得更清楚。沒人在場時把權限提示改成拒絕是一種答案:拿不到人,就拒絕。defer 是另一種:拿不到人,就把這一輪收好,等人到了再接。至於 claude -p 被 kill 之後 resume 會不會續跑,那是行程被外力打斷的情況,defer 是 hook 自己主動收手,兩者不要混在一起。
我的立場是:寫 defer 的 hook,要當成「每次接回都會被重新問一次」來寫,把有副作用的動作放在 allow 之後的那一邊,不要放在第一次回 defer 的時候做。會讓我放寬的條件是:如果文件或之後的實測顯示,同一個呼叫的第二次觸發帶著可以辨識「這是接回」的欄位,hook 就能安全地只在第一次做事。hook 的輸入有沒有這種欄位,我沒有查,這是個還沒查完的缺口。
DISABLE 那個變數該怎麼用,我的猜測(不是文件寫的)是:你只想接續對話,不想讓上次沒做完的工具在這次被執行。但實驗 E 看起來,跳過不等於乾淨,Claude 眼中的歷史裡似乎還留著一個沒有結果的呼叫(這是從它的回答推測的)。如果你要用,接回的 prompt 最好直接告訴它「那個呼叫已經取消,不要重做」,而不是讓它自己猜。
「暫停等於存檔加結束,接回等於重放加重問」這個形狀,我猜不只在 defer 出現(這是類比,我沒查過別的系統)。Web 表單的草稿、CI 的人工核准、佇列裡的待處理訊息,我想都得回答同一個問題:回來的時候,第一次的決定算不算數。你可以自己試一次,找一個無害的 Bash echo,掛一支回 defer 的 hook,然後連續 resume 三次看 hook 的 log。數一數它被叫了幾次,比讀一遍文件更能說服你。
原文來源:Hooks reference、Environment variables、Claude Code CHANGELOG(2.1.89、2.1.239、2.1.319、2.1.321、2.1.328)


















