Claude Codeのフックに失敗時ブロック「onFailure: block」が追加、v2.1.295の変更点
✔ 事実確認済み（2026-10-08）：記事中の事実 18 件を出典の本文と照合しています。
Claude Code v2.1.295 で、フックの失敗時に操作を止める設定 onFailure: "block" が追加されました。Claude Code を業務で使い、フック（特定のタイミングで自動実行されるスクリプト）で社内ルールを守らせたい方に向けた記事です。従来の失敗時の動き、新設定の内容、v2.1.294 の修正点を整理します。
今回の変更の概要
結論から言うと、onFailure: "block" は「フックが正しく動かなかったときに、操作を通さず止める」ための設定です。v2.1.295 のリリースノートには、次のように書かれています。
Added
onFailure: "block"for command and HTTP hooks: a hook that can’t start, times out, or exits with an unexpected code blocks the action instead of letting it through
日本語にすると、次のとおりです。
- 対象は、コマンド（command）フックと HTTP フックです。
- フックが起動できないとき、時間切れになったとき、想定外の終了コードで終わったときが対象です。
- この設定を使うと、操作をそのまま通さず、ブロックします。
リリースノートの原文は英語です。設定をどこに書くかなど、細かい書き方は、公式ドキュメントで確認してください。
従来のフックは、失敗しても操作を通すことが多い
新設定の意味を理解するには、これまでの動きを知っておく必要があります。2026年10月9日時点の公式ドキュメント（Hooks reference）には、次の説明があります。
| 状況 | 公式ドキュメントの説明（要点） |
|---|---|
| 終了コード 2 | ブロックするエラーになる（ブロックできるイベントの場合） |
| 終了コード 2 以外 | 多くのイベントで、それだけではブロックしない |
| 終了コード 1 | 有効な JSON が標準出力になければ、ブロックしないエラーとして扱い、操作は進む |
| 時間切れ（command・http・mcp_tool） | フックの出力は捨てられ、多くのイベントで判断は出ない |
| PreToolUse の時間切れ | ツール呼び出しはブロックされず、通常の許可の流れで進む |
| HTTP フックの 2xx 以外の応答、接続失敗 | ブロックしないエラーで、実行は続く |
公式ドキュメントには、こうも書かれています。ルールを強制したいフックでは exit 2 を使うこと、止まったフックを「関所」として当てにしないことです。
つまり、フックが失敗しても、操作が通ってしまう場面がありました。ルールを守らせるためのフックが、失敗したときに何もしないのは、運用上は不安な点です。onFailure: "block" は、この不安に対応する設定だと読めます。ただし、リリースノートは「どの失敗でも止める」と書いているわけではありません。対象は、上に挙げた3つの場合です。
注意: すべてのフックに
onFailureが使えるとは限りません。リリースノートが挙げているのは、コマンドフックと HTTP フックです。
タイムアウトの既定値も確認しておく
時間切れの扱いを考えるときは、既定の待ち時間も知っておくと便利です。公式ドキュメントでは、既定値は次のとおりです。
| フックの種類 | 既定のタイムアウト（秒） |
|---|---|
| command・http・mcp_tool | 600 |
| prompt | 30 |
| agent | 60 |
onFailure: "block" を使うと、時間切れも「止める」側に倒れます。重い処理を行うフックでは、既定の待ち時間で足りるかを先に確かめておくと、意図せず操作が止まることを減らせます。
v2.1.294 の修正：指示文で書いた prompt／agent フック
v2.1.295 の1つ前の版である v2.1.294 では、別のフック関連の修正がありました。リリースノートの内容は次の2点です。
- 「Block commands that…（〜のコマンドを止める）」のように、指示文として書いた prompt フックと agent フックが、止めるべきものを通してしまう問題を修正しました。
- Stop と SubagentStop の prompt フックの判定方法を改善しました。対象は、「Carry on if the build is broken（ビルドが壊れていれば続ける）」のような指示文です。Claude が早く止まりにくくなります。
prompt フックは、公式ドキュメントでは「Claude のモデルに1回だけ評価させ、判断を JSON で返させるフック」と説明されています。agent フックは、Read や Grep などのツールを使える副エージェントを起動して条件を確かめるフックで、「実験的で、変わる可能性がある」と書かれています。指示文でフックを書いている方は、v2.1.294 以降に更新すると、動きが変わる可能性があります。
v2.1.295 のそのほかの変更
フックの設定以外にも、v2.1.295 には多くの変更が入っています。リリースノートから、目立つものを挙げます。
- Program Status Protocol（OSC 7501）に対応しました。対応するターミナルは、Claude Code が作業中か、あなたの入力待ちか、完了したかを表示できます。
/copyの選択肢に引用文が加わり、下書きしたメッセージを>の記号なしでコピーできます。claude plugin installなどの実行時に、書き込み先の設定ファイルが読み込まれない場合は警告が出ます。- Claude apps gateway まわりの設定や修正が複数あります。
全文は長く、修正項目が多数あります。自分の環境に関わる項目は、リリースノートで探してください。
よくある質問
Q. 今までのフックは、アップデートすると勝手に止める動きに変わりますか。
A. リリースノートには「onFailure: "block" を追加した」と書かれています。既存のフックの動きが自動で変わるとは書かれていません。設定を加えるかどうかは、利用者が選ぶ形と読めます。
Q. 終了コード 2 を返すのと、何が違いますか。
A. 終了コード 2 は、フックが「ブロックしたい」と自分で伝える方法です。onFailure: "block" は、フックが起動できない、時間切れ、想定外の終了コードといった「正常に判断できなかった」場合の扱いを指すと、リリースノートの文面から読めます。
まとめ
- v2.1.295 で、コマンドフックと HTTP フックに
onFailure: "block"が追加されました。起動できない・時間切れ・想定外の終了コードのとき、操作を通さず止めます。 - 従来は、終了コード 2 以外や時間切れ、HTTP フックの失敗では、操作が進む場面がありました（2026年10月9日時点の公式ドキュメント）。
- v2.1.294 では、指示文で書いた prompt／agent フックが、止めるべきものを通す問題が修正されました。
フックでルールを守らせている方は、まず公式ドキュメントで onFailure の書き方を確認し、重要なフックから試すとよいでしょう。Claude Code の拡張の仕組み全体は、Claude Mods の解説記事も参考になります。記事の内容は2026年10月9日時点のものなので、最新の仕様は公式サイトで確認してください。