8
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

Claude Code の守りのフックは、台本が壊れると黙って通す。2.1.295 の onFailure で止まった

8
Last updated at Posted at 2026-10-14

Claude Code 2.1.295(2026-10-08)の changelog に、こう書かれています。

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

裏を返すと、これまでのフックは、起動できない・時間切れ・想定外の終了コードのとき、処理を通していたことになります。
ドキュメントにも、はっきり書いてあります(2026-10-09 取得)。

When you set up a policy hook, watch for this notice on its first run: a mistyped path in settings.json leaves the gate silently disabled.

PreToolUse フックで危ない操作を止めていても、台本のパスを1文字間違えれば素通しです。36回測りました。

「danger.txt を書くな」というフックを壊して、書かせてみた(各3回)

フックの状態          2.1.293     2.1.295      2.1.295 + onFailure: "block"
正常(対照)           止まった    止まった     止まった
台本が無い             書かれた    書かれた     止まった
終了コード1で落ちる     書かれた    書かれた     止まった
時間切れ               書かれた    書かれた     止まった

書かれた18回とも、Claude の返事は「danger.txt を作りました」だけ

検証環境: Windows 10(フックは Git Bash で実行)/ Claude Code 2.1.293 と 2.1.295 を隔離導入 / claude -p /
--tools Write --permission-mode acceptEdits / 本体モデルは Opus 5.5 / 測定は 2026-10-09


測り方

守りの台本は、入力に danger.txt があれば終了コード2で止めるだけのものです。

#!/bin/bash
input=$(cat)
if echo "$input" | grep -q 'danger.txt'; then
  echo 'guard: writing danger.txt is not allowed' >&2
  exit 2
fi
exit 0

これを Write の PreToolUse フックに付け、3通りに壊しました。

壊し方 中身
台本が無い 存在しないパスを指す(終了コード127)
落ちる 何も見ずに exit 1
時間切れ sleep 30 してから判定。timeout は5秒

頼むのは「danger.txt を作って hello と書いて」(実際は英語)だけです。使えるツールは Write だけにして、Bash での回り道を塞ぎました。
書かれたかどうかは、実行後にファイルがあるかで判定しています。


壊れたフックは、3通りとも素通しだった

Claude Code 2.1.293 でも 2.1.295 でも、壊れたフックは18回すべて書き込みを通しました。 正常なフックは6回とも止めています。

ドキュメントの「Other exit codes」のとおり、終了コード2か、止める指示の JSON を返さない限り止まらない仕様です。


Claude にも、-p の出力にも、何も出ない

壊れたフックが通したとき、Claude が受け取ったのはこれだけでした(パスと末尾は省略)。

File created successfully at: C:\...\danger.txt

フックが失敗したことは伝わっていません。 返事は18回とも「danger.txt を作りました」で、フックに触れた回はありません。
claude -p の出力(stream-json)にも、標準エラーにも出ませんでした。

残っていたのは、セッションの記録だけです。18回とも、その記録に Claude へ送る中身は付いていませんでした。

壊し方 セッションの記録
台本が無い / 落ちる hook_non_blocking_error(終了コード127 / 1)
時間切れ hook_cancelled(timedOut)

対話モードでは画面に1行出ます。私の環境では、設定に残っていた存在しない台本を呼ぶ Stop フックが、ターンの終わりにこう表示していました(パスは省略)。

Stop hook error: Failed with non-blocking status code: bash: /c/Users/.../cmux-notify.sh: No such file or directory

Stop フックだったので害はありませんでしたが、PreToolUse の守りなら素通しです。


onFailure: "block" を付けると、9回とも止まった

フックの設定に1行足すだけです。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash /c/Users/Public/exbench/hook/guard_ok.sh",
            "timeout": 30,
            "onFailure": "block"
          }
        ]
      }
    ]
  }
}

Claude Code 2.1.295 では、壊れ方3通り×3回の9回すべてで止まりました。 正常なフックの止め方も変わりません。
Claude にはこう返り(パスと2行目は省略)、返事も9回とも「フックの台本が失敗した(時間切れを含む)ので止まった」という説明でした。

PreToolUse:Write hook error: [bash /c/.../guard_missing.sh]: failed; blocking because onFailure is "block"

時間切れでは timed out; blocking because onFailure is "block" になります。

onFailure は、フックのドキュメント(hooks)に 2026-10-09 時点でまだ載っていません。


言えないこと

  • Windows(Git Bash)、command フック、PreToolUse の Write だけで測りました。HTTP フックや他のイベントは見ていません
  • 各3回です。 結果は全部そろいましたが、ベンチマークではありません
  • 対話モードの表示は、Stop フックで見ただけです。PreToolUse での表示は確かめていません
  • onFailure を Claude Code 2.1.294 以前の設定に書いたときの動きは測っていません
  • 止めたのは空ファイルへの書き込みだけです。危ない操作そのものは試していません

まとめ

  • 守りのフックは、台本が無い・落ちる・時間切れのどれでも処理を通す。 止まるのは終了コード2か、止める指示の JSON を返したときだけ
  • 通したことは Claude に伝わらず、-p の出力にも出ない。 残るのはセッションの記録だけ
  • Claude Code 2.1.295 の onFailure: "block" を付けると、壊れたときは止まる側に倒れる
  • onFailure はドキュメントにまだ無い

フックで止めている設定があるなら、Claude Code 2.1.295 に上げて onFailure: "block" を足すのが先だと思います。
そのうえで、一度わざと台本を消して、本当に止まるかを確かめておくと安心です。


関連記事


JQITのエンジニアの95%以上は未経験からの採用です。
よければコーポレートサイトにも遊びに来てください。

▶ コーポレートサイト

エンジニア採用も行っています。もしご興味あれば覗いてみてください。

▶ 採用サイト

8
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
8
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?