Claude Code hooksのチェックが動かないとき、AIの操作は止まるのか

要点

対象：hooksでAIの操作を止めている

1. デフォルトでは、スクリプトが動かないと操作は進む
2. block なら3通りの壊し方で全部止まった
3. onFailure は 2.1.295 で加わった

Claude Codeのフック（hooks）で、AIにさせたくない操作を止めているなら、設定に "onFailure": "block" を書き足してください。書き足さないと、チェック用のスクリプトが動かなかったとき、操作は止まらずに進みます。¹

この記事の目次（5節）

1. スクリプトが動かないときの動き
2. onFailureの書き方
3. スクリプトをわざと壊して試した結果
4. onFailureが効かないフック
5. 設定したら確かめる4つのこと

onFailure は、2026年10月9日（日本時間）に公開された Claude Code 2.1.295 で加わりました。²⁴

スクリプトが動かないときの動き

フックは、Claude Code の決まった場面で自動で動く処理です。シェルのコマンドのほか、HTTP で送る形や、AIに判断させる形もあります。¹

AIがツールを使う直前に動くイベントを、PreToolUse といいます。ここに置いたフックは、その操作を止められます。¹

止めるかどうかは、ふつうはスクリプトの終了コードで決まります。2で終われば、操作は止まります。

0で終わり、JSON で止める指示も出さなければ、フックは操作を止めません。そのあとは、いつもどおり権限の設定（allow・deny のルール）で、実行するか、使う人に確認するかが決まります。¹

Claude Code は、command のフックの次の4つを「失敗」と数えます。¹

• スクリプトが見つからないなどで起動できない
• 終了コードが0でも2でもない
• timeout の秒数（書かなければ600秒）のうちに終わらない
• 出力した JSON が読み取れない

失敗したときに操作を通すか止めるかは、onFailure で決めます。デフォルトの "continue" では、フックは操作を止めません。¹

onFailureの書き方

フックの設定は、3段の入れ子になっています。onFailure は、いちばん内側の { } に、type や command と並べて書きます。

チームで同じチェックを使うなら、プロジェクトの .claude/settings.json に書いてコミットします。³

3段目の { } は、{"type": "command", "command": "…", "onFailure": "block"} の形です。

onFailure は、type が command か http のフックで使えます。¹ 使っているバージョンは、claude --version で確かめられます。

timeout を書かないと、スクリプトが固まったとき、Claude Code は600秒（10分）待ちます。¹ 止めるためのフックには、そのスクリプトに要る時間に合わせた短い timeout も書いておくのがよいと考えています。

スクリプトをわざと壊して試した結果

2026年10月16日に、当サイトで Linux 上の Claude Code 2.1.301 を使って試しました。AIには、空のファイルを作るコマンド touch done.txt を実行させました。

AIが Bash を使う直前にスクリプトが動くよう設定し、そのスクリプトを次の3通りに壊しました。ファイルができれば、操作が進んだことになります。

デフォルトでは、AIの返事は3通りとも「成功した」で、スクリプトが動かなかったことには触れていませんでした。

公式の文書によると、このとき会話の画面（トランスクリプト）には hook error の通知が出ます。¹ AIの返事だけを見ていると、気づきにくいということです。

block を書いたときは、エラーメッセージに failed; blocking because onFailure is "block" と出ました。時間切れのときは、このメッセージの failed の所が timed out でした。

onFailureが効かないフック

次のフックでは、block と書いても効きません。¹

• AIが作業を終えようとするときのフック（Stop・SubagentStop など）
• バックグラウンドで動かすフック（async か asyncRewake を true にしたもの）

AIに判断させるフック（type が prompt や agent）の設定項目には、onFailure がありません。¹ 必ず止めたい操作は、command か http のフックで確かめてください。

設定したら確かめる4つのこと

自分で設定した場合も、開発会社に作ってもらった場合も、次の4つを確かめてください。

1. Claude Code が 2.1.295 以降か
2. 操作を止めるためのフックに、"onFailure": "block" があるか
3. timeout を書いてあり、スクリプトがその時間内に終わるか
4. スクリプトを消すか壊すかして、操作が止まることを一度試したか

組織の全員に入れるなら、管理者が配る設定（管理設定）に置く方法もあります。管理設定に置いたフックは、使う人やプロジェクトの設定からは消せず、止めることもできません。¹

関わる記事は次のとおりです。

• AIにファイルを読ませないようにする設定: .envを読ませない設定の記事
• AIに画面の操作を任せる前に決めること: AIがフォームを送信してしまった例
• クラウドや拡張を使うときの確認: クラウドセッションの記事・modsの記事

まずは自分の作業用のフォルダーで、スクリプトのファイル名を1文字だけ変え、止めたい操作が止まるかを試してください。

出典

1. Claude Code「フックリファレンス」（公式文書・日本語）（参照 2026-10-16）
2. Anthropic「Claude Code CHANGELOG」（GitHub。2.1.295 の項）（参照 2026-10-16）
3. Claude Code「設定」（公式文書・日本語）（参照 2026-10-16）
4. npm「@anthropic-ai/claude-code」バージョンの一覧（参照 2026-10-16）