hookを設定した。settings.jsonに書いた。Claude Codeを起動した。
何も起きない。
hookが発火しない原因の95%は、5つのパターンに集約される。全て30秒で直せる。
原因1: 実行権限がない
最も多い。シェルスクリプトをhookに指定したが、chmod +xを忘れている。
確認方法
ls -la .claude/hooks/
出力に-rw-r--r--と表示されたらアウト。xがない。
修正方法
chmod +x .claude/hooks/*.sh
一括修正なら:
npx cc-safe-setup --quickfix
原因2: shebang行がない
ファイル先頭に#!/bin/bashがない。macOSとLinuxで挙動が変わる原因にもなる。
確認方法
head -1 .claude/hooks/my-hook.sh
修正方法
ファイルの1行目に追加:
#!/usr/bin/env bash
/usr/bin/env bashを使う理由はポータビリティ。環境に依存しない。
原因3: matcherの大文字小文字が間違っている
hookのmatcherフィールドは大文字小文字を区別する。
"matcher": "bash" // NG
"matcher": "Bash" // OK
| 正しい | よくある間違い |
|---|---|
Bash |
bash, BASH, shell
|
Edit |
edit, Write, file_edit
|
Read |
read, cat, file_read
|
Glob |
glob, find
|
Grep |
grep, search
|
Claude Codeのツール名はPascalCase。
原因4: exit codeが間違っている
| exit code | 意味 |
|---|---|
exit 0 |
許可（続行） |
exit 1 |
エラー（hookが壊れている） |
exit 2 |
ブロック（ツール実行を阻止） |
exit 1でブロックしようとしている人が非常に多い。exit 1はhookスクリプト自体のエラーを意味する。
# NG
exit 1
# OK
exit 2
exit 2 = ブロック。これだけ覚えればいい。
原因5: jqがインストールされていない
hookはstdinからJSONを受け取る。多くのhookスクリプトはjqで解析する。
CMD=$(cat | jq -r '.tool_input.command')
jqが入っていないとエラーで終了し、ブロックもされない。
# macOS
brew install jq
# Ubuntu / Debian
sudo apt install jq
一括診断
npx cc-safe-setup --doctor
実行権限、shebang、matcher、exit code、jq依存、JSON構文エラー、イベント名typoを全自動チェック。--quickfixで自動修正。
npx cc-safe-setup --doctor --quickfix
| 原因 | 確認 | 修正 |
|---|---|---|
| 実行権限なし | ls -la |
chmod +x |
| shebangなし | head -1 |
#!/usr/bin/env bash追加 |
| matcher不一致 | grep matcher |
PascalCaseに統一 |
| exit code誤り | grep 'exit 1' |
exit 2に変更 |
| jq未インストール | which jq |
パッケージマネージャで導入 |
📘 Claude Codeを本番品質にする——700+時間の自律稼働から生まれた実践ガイド（¥800）
第2章「Safety Guards」を無料で読む
同じ事故防止本は Kindle 版（Amazon・¥800）でも読めます。Kindle Unlimited なら追加料金なしで全文読めるので、まず無料で中身を確かめたい方はそちらが早いです。
npx cc-safe-setup # 748 hooks / 9,250+ tests
npx cc-safe-setup --doctor # hookの一括診断
関連の素材
5月22日に新刊の事例集 Claude Code Claim-Verify Handbook ($19、 約89頁、 約113,000字) を公開しました。 道具が「成功した」 「比較した」 「設定された」 と主張する一方で実態が乖離していた事例を GitHubの起票の集まりから130件 (本文15件+付録D 115件) 整理した本で、 14件の防衛の手順と5件の自動の点検の道具と一緒に提供しています。 本書は Gumroad（$19） で販売しています。
予防 hook の集まりは cc-safe-setup (MIT、 約800件の hook)。 月額の継続の媒体 Claude Code 事故まとめ(無料・月次) (¥500/月) は毎月の事故の整理を配信。
📅 本日 2026 年 5 月 22 日発売。 Claim-Verify Handbook (Gumroad、 19 米ドル) は、 operator の意図と system の主張と runtime の動作の三層で 100 件以上の Claude Code の失敗事例を整理した本です。 本書は Gumroad（$19） で販売しています。
📚 関連の参考資料 (2026年5月28日追加)
本記事の内容と関連する整理を、 公開済の素材で articulate しています。
-
6月15日に予定された課金分離(当日に一時停止・再実施に備える)の判定の枠組み: Migration Playbook v2 (Gumroad、 $19) ——14日後の決定の整理、 9集積の文脈、 130件の claim-verify divergence の事例。
-
月次の追補の継続: Claude Code 事故まとめ(無料・月次) ——5月から12月の8ヶ月の章本文 (cache_control / 副の作業者 / AGENTS.md / Pro Max / 権限 / Skills / v2.1.150 / AUP false-positive)
-
9集積の枠組みの英語の長編 Gist: The 9-Cluster Framework: Mapping the Structural Failure Surface of Claude Code Operator Defense（英語） ——約3,300単語、 全件の集積の mechanism / symptom family / defense path の整理。
-
約800件の MIT ライセンスの hook: cc-safe-setup (GitHub) ——9集積に対応する hook を整備した累計
毎月、その月に報告された Claude Code の事故（データ消失・暴走・無断課金など）と設定での防ぎ方を一か所にまとめています → 2026年6月 Claude Code 事故まとめ（無料・毎月更新）。新しい号の通知は note のゆるくさ のフォローで届きます(無料)。
ほかにも、800時間の運用データから、トークン消費の削減・複数ベンダー(Claude / Codex / Gemini / Copilot)の並行運用・サブエージェントの沈黙の失敗対策など、テーマ別の手引きを公開しています。気になる人は著者の本の一覧から、価格と評価を見て選べます。