フックが黙って動かないのは、たいてい matcher の書き方

`"matcher": "bash"` と書いたフックは、何にも当たりません。エラーも出ません。

これまで書いてきたフックの記事は、exit 2 で止める、deny を返す、文脈を注ぎ直す、と、どれも「発火した後」の話でした。今回はその手前、書いたのに発火しないときの話です。

まず分けるのは「読まれていない」か「当たっていない」か

Claude Code には `/hooks` というコマンドがあり、いまのセッションに登録されているフックをイベントごとに一覧で出します。原因探しはここから始めます。

一覧に出てこないなら、フックはそもそも読まれていません。一覧に出ているのに動かないなら、読まれてはいて、当たっていません。docs は後者について、原因はたいてい `matcher` だと書いています。

一覧に出てこないとき、まず疑うのは置き場所です。フック専用のファイルはありません。フックは設定ファイル（`settings.json`）の `"hooks"` キーの下に書きます。`hooks/hooks.json` という別ファイルを読むのはプラグインだけで、自分のプロジェクトやユーザー設定でそれを作っても読まれません。

matcher が外れる形

`matcher` は、どのツールの呼び出しでフックを動かすかを決める1本の文字列です。docs が挙げている外れ方を並べると、こうなります。

```

"matcher": "Edit|Write" ← 当たる

"matcher": "Edit,Write" ← v2.1.191 以降は当たる。それより前は何にも当たらない

"matcher": "bash" ← 何にも当たらない（Bash と書く）

"matcher": ["Edit", "Write"] ← 設定ファイルごと拒否される

```

冒頭の `"bash"` が当たらないのは、大文字と小文字が区別されるからです。ツール名は `Bash`・`Edit`・`Write`・`Read` のように先頭が大文字です。綴りを間違えた場合も同じで、何にも当たらない `matcher` ができるだけなので、エラーは出ません。

複数のツールは `|` で繋ぎます。`,` が同じ意味になるのは v2.1.191 からなので、版が分からないなら `|` を使うのが確実です。

配列で書くと、フック以外まで巻き添えになる

いちばん影響が大きいのは配列です。`matcher` に配列を書くとスキーマエラーになり、ユーザー・プロジェクト・ローカルの設定ファイルは、そのファイルが丸ごと拒否されます。そのファイルにあるフックは1本も `/hooks` に出てきません。`matcher` の書き方の問題なのに、症状は「読まれていない」側に出ます。

設定エラーの通知は出ますし、ターミナルで `claude doctor` を実行すると検証の失敗が表示されます。フックだけの問題に見えて、実際はそのファイル全体が効いていない、という状態です。

組織が配る管理設定（managed settings）だけは扱いが違い、配列を含むファイルから `hooks` キーだけが落ち、ほかの設定は効き続けます。`claude doctor` は落としたキーを列挙します。

それでも動かないときは、評価の記録を見る

`settings.json` を直したら、再起動は要りません。少し待てば実行中のセッションに反映されます。`/hooks` の表示が古いままなら、もう一度 `/hooks` を実行すると更新されます。

一覧に出ていて、`matcher` も正しいのに動かない。そこまで来たら、`claude --debug` でセッションを始めて、フックを起こしたいツール呼び出しを実際に起こします。デバッグログには、どのイベントが起きたか、どの `matcher` を照合したか、フックの終了コードと出力が残ります。

`/hooks` に出ているか、`matcher` が当たっているか、評価の記録に何が残っているか。この順に見ていけば、黙っているフックの原因は、たいてい途中で見つかります。

※ 仕様の記述は Claude Code 公式ドキュメント「Debug your configuration」（2026-09-27 確認）によります。版ごとの挙動（`,` 区切りの扱いなど）は変わることがあるため、最新は公式ドキュメントでご確認ください。
#ClaudeCode #AI #開発環境 #個人開発 #エンジニア