Claude Code の hook で危険なコマンドを止めたつもりなのに、そのまま実行されてしまうことがあります。
原因の 1 つは、hook の終了コードです。
PreToolUse の hook でツールを止めるのは exit 2 か JSON の決定で、exit 1 は止めません。
検査スクリプトが例外で落ちたときも同じです。
Python の未捕捉の例外は終了コード 1 になるので、検査を終えないままコマンドが動きます。
8 通りの組み合わせを手元で試した結果と、落ちたときに止める onFailure: "block" の効く版が分かると、hook が止まらないときの切り分けに使えます。
前提(最小限)
hook は、Claude Code の決まった時点で自分のスクリプトを走らせる仕組みです。
PreToolUse は、そのうちツールが動く直前に発火するイベントを指します。
仕組みの全体と向いている用途は別の記事に書いたので、ここでは終了コードと失敗時の挙動だけを扱います。
公式の仕様は 0・2・それ以外の 3 通り
公式の Hooks reference によると、PreToolUse での終了コードの意味は次のとおりです(2026 年 11 月 5 日に原文で確認)。
| 終了コード | 扱い | ツールの呼び出し |
|---|---|---|
| 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: 2 | 2.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 の項にも追加の記録があります。
実験で使った設定は次のとおりです。
{
"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 が無いときの動きは試していません。
止める条件そのものの作り方と誤検知の測り方は、個人情報の外部送信を止めた記録に書きました。
最後に
止める hook は、止めたいときの exit 2 だけでなく、自分が落ちたときの挙動まで決めておく必要があります。
Claude Code 2.1.295 以降なら onFailure: "block" を足し、古い版なら例外を受けて exit 2 にするところから始められます。
登録したら、スクリプトのパスをわざと間違えたり例外を起こしたりして、1 回止まることを確かめておくと安心です。
以上です。











コメントを残す