Claude Codeのフックエラー対策｜失敗時に操作を止める設定

Claude Codeのフックエラーで操作が進む理由

フックは、Claudeがツールを使う前後などに、自分で用意したスクリプトを自動で動かす仕組みです。危ないコマンドを止める「門番」として使っている人も多いはずです。ただし公式のフック資料は、門番として使うときの落とし穴を説明しています。多くのイベントでは、JSONで拒否を返す方法を除けば、終了コードだけで操作を止められるのは2のときだけです。終了コード1や、スクリプトが見つからずに起動できない場合は「止めないエラー」として扱われ、操作はそのまま進みます。PreToolUseでコマンド型のフックが時間切れになった場合も、ツールの呼び出しは止まりません。

v2.1.295では、この「失敗したら通してしまう」動きを、フックごとに「失敗したら止める」へ変えられるようになりました。対象はコマンド型とHTTP型のフックです。

設定は、フックの定義に1行足すだけです。次は、Bashを使う前にcheck.shで確かめ、そのスクリプト自体が動かなかったときも止める例です。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/check.sh",
            "onFailure": "block"
          }
        ]
      }
    ]
  }
}

現在の公式フック資料にも、v2.1.295以降で使える設定として掲載されています。

Claude Codeのフックエラーで停止する設定を比較

公式資料は、PreToolUseから呼ぶスクリプトを一時的に存在しないパスへ向け、Bashの操作を依頼する確認例を示しています。たとえばNode.jsが使える検証環境で、check-command.jsが存在しない状態にしてlsを頼む例です。公開環境の設定を直接壊さず、元の設定を保存した使い捨ての作業場所で確認します。

ブロックされた例のエラーには、failed; blocking because onFailure is "block"が含まれます。時間切れの場合は失敗理由の表示が変わります。表は公式資料の設定例の比較であり、すべての端末・イベントに同じ既定動作を約束するものではありません。

Claude Codeのフックエラーを止める設定の注意点

• 壊れたフックが全部を止める：スクリプトのパスを間違えたり、必要なコマンドが入っていなかったりすると、その操作はすべて止まります。付けたら、わざと失敗させて止まることと、正常なときに通ることの両方を確かめてください。
• 止めたい門番だけに付ける：整形や通知のように、失敗しても作業を続けてよいフックには付ける理由がありません。
• 時間切れの設定も見直す：時間切れも止める対象になるため、時間のかかるスクリプトはtimeoutの値に余裕を持たせます。

WindowsでGit Bashがない環境では、シェル形式のPreToolUse・PermissionRequestフックが失敗すると、onFailure未指定でも操作を止める場合があります。既定動作の推測に頼らず、利用環境と明示した設定を確認します。

onFailureはすべてのイベントで同じように働く設定ではありません。現行の公式資料では、Stop・SubagentStop・TaskCompleted・TeammateIdleや、async・asyncRewakeを使うバックグラウンドのコマンド型フックでは効果がありません。対象イベントと実行方式も確認してください。

Claude Codeのフックエラーを確認する手順

claude --version

onFailureはv2.1.295以降が対象です。古い版なら、公式のセットアップ資料で導入方法に合う更新手順を確認します。更新後は元のフック設定を残し、検証用の作業場所で正常時と失敗時を分けて確かめます。

フックを変える前に用意する確認表です。使い捨ての作業場所で元設定を保存し、1条件ずつ切り替えます。次は読者が自分の設定で確かめる項目です。実行結果を記録し、意図した操作だけが止まるか判断してください。

操作が止まったときは、CLIの終了状態だけでなく、実ファイルや対象操作が実行されなかったことも確認します。

Claude Codeのフックエラーでよくある質問

onFailureを付けないと、何が起きますか？

利用環境とイベントによって異なります。公式のフック資料では、多くのイベントで、終了コード2以外の失敗や起動できないフックは止めないエラーとして扱われ、操作は進むと説明されています。門番にしたいフックは、スクリプト側でexit 2を返す作りにしたうえで、onFailure: "block"を足すと、失敗したときも止まるようになります。

prompt型やagent型のフックにも付けられますか？

現行の公式資料で対象とされているのは、コマンド型とHTTP型です。prompt型やagent型へ同じ設定を流用せず、それぞれの判定方法を確認してください。

まとめ：フックエラー時に止めるかを先に決める

危険な操作を止めるためのフックでは、正常に判定できたときだけでなく、スクリプト自体が動かない場合も確認します。対象のコマンド型・HTTP型フックにonFailure: "block"を設定し、正常時は通ること、失敗時は対象操作が実行されないことを確かめてください。