結論：失敗を通すか止めるかをhook単位で明示する
Claude Code公式changelogの2.1.295（2026年10月8日）は、commandとHTTP hooksにonFailure: "block"を追加しました。hookが起動できない、時間切れになる、想定外のコードで終了する場合にアクションをブロックする設定です。外部検査、承認、監査記録など「確認できなければ実行してはいけない」処理に向きます。
ただし、すべてのhookへ機械的に付けると、開発を止めるだけでなく、監査用通知の一時障害で無関係な作業まで止めることがあります。公式hooksガイドのイベント、matcher、handlerを読み、処理の危険度、再試行可能性、代替手段、停止条件を一つずつ決めます。以前の2.1.294のprompt・agent hooks検証は判定の回帰確認、本稿はhook自体の失敗時フェイルクローズへ絞ります。
onFailureの扱いを比較する
| 設定の考え方 | hook失敗時 | 向く処理 |
|---|---|---|
block | アクションを通さない | 承認確認、秘密情報検査、本番操作の前提条件 |
| 失敗を記録して継続 | 処理を止めず後で確認 | 補助的な通知、参考メトリクス |
| 再試行してから判断 | 回数・時間を決めて再実行 | 一時的な内部サービス障害。ただし副作用を要確認 |
| 手動へ戻す | 自動実行を止め承認待ち | 境界が曖昧な編集、外部送信、デプロイ |
「失敗」と「hookが正常に動いてdenyを返したこと」は同じではありません。終了コード、stdout・stderr、HTTPステータス、応答JSON、timeout、次に発生したtool callを分けてログへ残します。onFailure: blockは権限設定やsandboxを置き換える認証ではないため、危険操作の最終防衛線を一つにしません。
更新後に行う8手順
claude --versionを実行し、CI、開発端末、managed環境が2.1.295以上か記録します。- user、project、managed、pluginのsettingsとhooksを収集し、読み込み順を確認します。
- イベント、matcher、command・HTTP、入力、成功条件、失敗時の扱いを一覧にします。
- 秘密情報検査、本番ブランチ変更、外部送信など、失敗を通せない操作を選びます。
- 起動失敗、timeout、想定外終了コード、異常なHTTP応答をテスト用handlerで再現します。
- 各ケースでアクションがブロックされたか、tool callが続かなかったか、ログが残ったかを確認します。
- 一時障害の再試行回数、時間、二重実行防止、手動承認への戻し方を決めます。
- 合格した設定のhash、version、テスト結果、承認者、rollback方法を保存します。
テストでは実際の削除、push、顧客通知を実行しません。fake command、読み取り専用fixture、遮断したHTTP endpointを使います。handlerがエラーを返したときにClaude Code側の表示だけを見るのではなく、対象アクションが実行されなかった事実をGit差分、監査ログ、サーバー受信記録で照合してください。
command hookとHTTP hookの境界を分ける
command hookはローカルプロセスの終了コードや出力を、HTTP hookはネットワーク先の応答、TLS、認証、タイムアウトを確認する必要があります。同じblockでも故障点が異なるため、タイムアウトを短くしすぎると正しい検査を失敗扱いにし、長くしすぎると人が停止理由を理解できないまま待つことになります。秘密情報や権限トークンをログへ出さないことも、handler側の責任です。
本番操作の前にHTTP検査が必要なら、許可先、DNS、証明書、送信データ、レスポンスのschemaを固定します。検査先が停止した場合は、リトライのたびに同じ副作用を起こさない設計にし、最終的に手動承認へ戻します。便利な「通知が届かなければ止める」と、業務上必要な「証明書検査が失敗したら止める」を同じレベルで扱わないでください。
権限・prompt・hookの責任分界
公式Permissionsガイドのdeny・ask・allow、permission mode、sandboxは、Claude Codeが操作を実行できる範囲を決めます。hookはイベント前後の検査や判断を追加しますが、悪意あるhandler、誤ったmatcher、読み込まれていないsettingsを自動では修正しません。設定scopeを確認し、managed設定とproject設定が競合したときの最終結果をテストします。
たとえば本番ブランチへのpushを守るなら、Git側の保護、credentialの分離、Claude Codeのdeny、review hook、担当者の承認を重ねます。hookがblockを返すからといって、別のtoolやsubagent経由の操作まで同じ境界で守られるとは限りません。許可されたtool、引数、作業ディレクトリ、ネットワークをそれぞれ表にしてください。関連するrm安全対策も、危険操作を一設定へ集約しない例として参考になります。
企業運用チェックリスト
- 2.1.295以上を実際の端末・CIごとに確認した
- commandとHTTP hookの失敗条件を分けた
- blockにするアクションと通知だけのアクションを分けた
- 起動失敗、timeout、異常終了、異常HTTP応答を再現した
- block時に後続tool callが発生しないことを確認した
- 設定scope、matcher、handlerの変更者と承認者を記録した
- retry、二重実行、manual fallback、rollbackが決まっている
- hook、権限、sandbox、Git保護の責任分界がある
フェイルクローズは、失敗時に止めることを決めるだけでは完成しません。止まった後に誰が何を確認し、いつ再実行し、検査サービスが長時間使えないときにどの業務を安全に手動化するかまで運用へ含めます。監査のためには、成功ログだけでなくblockの理由と未確認範囲を残します。
更新直後は全自動化を広げるより、代表的な拒否ケースを回帰させることを優先してください。ログがない、設定が読めない、handlerのバージョンが不明という状態は、成功ではなく手動確認へ戻す条件です。無料診断では、hook一覧、危険操作、権限、通知、停止、再開を一枚の運用表へ整理します。
FAQ
- onFailure: blockは何を止めますか？
- command・HTTP hookが起動できない、タイムアウト、想定外の終了コードになるなど失敗した場合に、該当アクションを通さずブロックする設定です。実際のイベントと設定で検証します。
- Claude Code 2.1.295へ更新すれば十分ですか？
- いいえ。バージョン、hookの設定、matcher、権限、失敗時のログをテスト用リポジトリで確認します。
- hookの安全設計を相談できますか？
- できます。許可・拒否、タイムアウト、監査ログ、停止条件を無料診断（60秒）で整理します。