Claude Codeのhookはexit 1では止まらない

Claude Codeのhookはexit 1では止まらない

Claude Code の hook で危険なコマンドを止めたつもりなのに、そのまま実行されてしまうことがあります。

原因の 1 つは、hook の終了コードです。

PreToolUse の hook でツールを止めるのは exit 2 か JSON の決定で、exit 1 は止めません。

検査スクリプトが例外で落ちたときも同じです。

Python の未捕捉の例外は終了コード 1 になるので、検査を終えないままコマンドが動きます。

8 通りの組み合わせを手元で試した結果と、落ちたときに止める onFailure: "block" の効く版が分かると、hook が止まらないときの切り分けに使えます。

前提(最小限)

hook は、Claude Code の決まった時点で自分のスクリプトを走らせる仕組みです。

PreToolUse は、そのうちツールが動く直前に発火するイベントを指します。

仕組みの全体と向いている用途は別の記事に書いたので、ここでは終了コードと失敗時の挙動だけを扱います。

フックとは?AIエージェントの操作をコードで止める仕組み

公式の仕様は 0・2・それ以外の 3 通り

公式の Hooks reference によると、PreToolUse での終了コードの意味は次のとおりです(2026 年 11 月 5 日に原文で確認)。

Hooks reference - Claude Code Docs
終了コード扱いツールの呼び出し
0成功動く(JSON で拒否すれば止まる)
2ブロックするエラー止まる(標準エラーの文が理由になる)
それ以外ブロックしないエラー動く(有効な JSON で拒否すれば止まる)

同じページは、有効な JSON を出さない exit 1 は、1 が Unix で普通の失敗の合図であっても止まらないと警告していて、ポリシーを強制する hook には exit 2 を使うよう書いています。

厄介なのは、ブロックしないエラーに入るのが自分で書いた sys.exit(1) だけではない点です。

公式は、起動できない hook、時間切れ、壊れた JSON の出力も、既定では止めずに通す失敗として扱うと書いています。

8 通りを実際に試した

環境は Windows 11、Claude Code 2.1.317(1 ケースだけ 2.1.234)、Python 3.12.10、Git Bash です。

一時フォルダの .claude/settings.json に hook を 1 つ登録し、claude -p で touch side_effect.txt を 1 回実行させました。

touch は --allowedTools で許可してあるので、表の「実行された」は許可の確認を挟まなかった結果です。

判定には、hook が残す印のファイルと、side_effect.txt ができたかどうかを使っています。

検証用の claude -p はログインが通らなかったので、本物のモデルは呼んでいません。

127.0.0.1 に置いたスタブを API の接続先にして、毎回同じ Bash の呼び出しを返すようにしました。

見ているのは CLI 本体のツール実行と hook の判定だけで、止められた後にモデルがどう振る舞うかは確かめていません。

hook の中身追加の設定版hook の実行touch
sys.exit(1)なし2.1.317した実行された
sys.exit(2)なし2.1.317した止まった
未捕捉の例外(KeyError)なし2.1.317した実行された
未捕捉の例外(KeyError)onFailure: "block"2.1.317した止まった
未捕捉の例外(KeyError)onFailure: "block"2.1.234した実行された
スクリプトのパスが誤りなし2.1.317できず止まった
20 秒待つtimeout: 22.1.317した実行された
JSON で deny を出して exit 1なし2.1.317した止まった

結果は、公式の記述と合っていました。

1 か所だけ公式の例と違って見えるのがパスの誤りで、理由は後の節で触れます。

例外で落ちても普通の完了に見える

例外のケースで気になったのは、hook は動いて落ちたのに、モデルへ返る結果が普通の完了と同じだったことです。

スタブが受け取ったツールの結果は、exit 1 でも例外でも (Bash completed with no output) だけでした。

標準出力の JSON の流れにも、hook の失敗を示す行はありませんでした。

公式はトランスクリプトに hook error の通知が出ると書いていますが、-p の stream-json の出力では見つけられませんでした。

止まったときは、モデルに次の文が返りました。

PreToolUse:Bash hook error: [python "$CLAUDE_PROJECT_DIR/.claude/hooks/hook.py" exit2]: blocked by hook

入力の JSON のキー名を間違えただけの検査スクリプトでも、モデルから見れば何も起きていないまま、呼び出しを通し続けることになります。

パスの誤りは言語で結果が変わる

パスを誤ったケースが止まったのは、Claude Code の配慮ではありません。

Python は、開けないスクリプトを渡されると自分で終了コード 2 を返すからです。

hook を登録せずに、プロセス単体で終了コードだけを見た結果は次のとおりでした。

実行したもの終了コード
python に無いファイルを渡す2
argparse が知らない引数を受ける2
python の未捕捉の例外・構文エラー1
node(v24.20.0)に無いファイルを渡す1
Git Bash で無いコマンドを実行する127

公式も、node で無いスクリプトを指す hook は onFailure がなければ通ると書いています。

同じパスの誤りでも、Python なら matcher に当たる呼び出しが全部止まり、Node なら全部通ることになります。

Node と Git Bash の行は Claude Code に登録して試していないので、終了コードと公式の記述からの読み取りです。

argparse を使う Python の hook は引数を間違えても exit 2 で終わるので、急に何も動かなくなったらここも見てください。

onFailure は版を確かめてから使う

落ちたときに止めたいなら、hook に "onFailure": "block" を足します。

公式の記載では Claude Code 2.1.295 以降の機能で、CHANGELOG の 2.1.295 の項にも追加の記録があります。

Claude Code changelog - Claude Code Docs

実験で使った設定は次のとおりです。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python \"$CLAUDE_PROJECT_DIR/.claude/hooks/hook.py\" crash",
            "onFailure": "block"
          }
        ]
      }
    ]
  }
}

2.1.317 では、モデルに次の文が返って touch は動きませんでした。

PreToolUse:Bash hook error: [python "$CLAUDE_PROJECT_DIR/.claude/hooks/hook.py" crash]: failed; blocking because onFailure is "block"
Traceback (most recent call last):
  # 略
KeyError: 'no_such_key'

同じ設定を 2.1.234 で動かすと、touch は実行され、claude -p は終了コード 0 で終わりました。

標準エラーと出力の JSON のどちらにも、onFailure に触れる行はありませんでした。

古い版だと、設定に書いてあっても効いていないことに気づきにくいわけです。

手元でも、PATH の claude は 2.1.234 のままで、デスクトップアプリが動かす版は 2.1.317 でした。

同じ PC でも起動の仕方で版が違うことがあるので、claude --version は実際に hook を動かす経路で確かめてください。

公式によると、効果がないものもあります。

  • Stop・SubagentStop・TaskCompleted・TeammateIdle の hook
  • async または asyncRewake を付けた裏で動く hook

また、警告のつもりで exit 1 を使っている hook は、onFailure: "block" を足すと止めるようになります。

公式は、その場合は exit 0 にして、警告を JSON の systemMessage で出すよう案内しています。

古い版でも例外だけは止められる

版を上げられないときは、スクリプトの側で例外を受けて exit 2 にする手があります。

# import と main の定義は省略
try:
    main()  # 検査の本体。止めるときは中で sys.exit(2)
except Exception as e:  # sys.exit はここに来ない
    print(f"guard failed: {e}", file=sys.stderr)
    sys.exit(2)

sys.exit が投げる SystemExit は Exception の子ではないので、検査の結果の 0 と 2 はそのまま外に出ます。

スクリプト単体に JSON を流すと、ls は 0、rm -rf は 2、キーが足りない入力と JSON でない入力はどちらも 2 で終わりました。

これは Claude Code に登録して試したものではありません。

検査の中の例外には効きますが、スクリプトの構文エラー、起動できないとき、時間切れには効かないので、そこは onFailure の担当です。

JSON で決定を返す書き方は、exit 0 と組み合わせるのが公式の想定です。

実験では exit 1 でも JSON の deny で止まりましたが、公式によると onFailure: "block" を付けた hook ではこの形が失敗として数えられます。

exit 2 でも止まらない場所

exit 2 にしたのに止まらないときは、ここを見てください。

  • PermissionRequest は exit 2 を受け付けない(決定は JSON の decision で返す)
  • PostToolUse はツールが動いた後なので、標準エラーを Claude に見せるだけになる
  • 2.1.316 より前は、型キャストや param などで始まる PowerShell の hook が exit 2 でも止まらない不具合があった

シェルで書いた hook は、最後の行の終了コードがそのまま hook の終了コードになります。

Git Bash で sys.exit(2) する Python を単体で試すと、| tee に通したときも、後ろに別のコマンドを続けたときも、全体の終了コードは 0 でした。

公式の例も、検査の後に別の処理を続けるときは || exit $? で検査の終了コードを引き継ぐ書き方でした。

Windows には、もう 1 つ別の挙動があります。

Git Bash が無い環境では、シェル形式の PreToolUse の hook が onFailure なしで失敗すると、逆に止まることがあると公式に書かれています。

Git for Windows を入れると止めなくなるとも書かれていて、PowerShell で止める hook には "onFailure": "block" と "shell": "powershell" の両方を付ける案内があります。

手元は Git Bash がある環境なので、Git Bash が無いときの動きは試していません。

止める条件そのものの作り方と誤検知の測り方は、個人情報の外部送信を止めた記録に書きました。

Claude Codeのhookで個人情報の外部送信を止める

最後に

止める hook は、止めたいときの exit 2 だけでなく、自分が落ちたときの挙動まで決めておく必要があります。

Claude Code 2.1.295 以降なら onFailure: "block" を足し、古い版なら例外を受けて exit 2 にするところから始められます。

登録したら、スクリプトのパスをわざと間違えたり例外を起こしたりして、1 回止まることを確かめておくと安心です。

以上です。

コメントを残す

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です

CAPTCHA