Claude Code hooks は「守ってほしいお願い」を実行境界へ移す
このノートは原文の代替ではありません。読むべきポイントと実装上の意味を整理し、原典への入口を示します。
要点まとめ
- prompt に『この command は使わないで』『編集後に formatter を回して』と書くだけでは、必ず守られる保証にはならない。
- Claude Code hooks は、その弱さを埋めるために、禁止や必須処理を会話文ではなく決まった実行イベントへぶら下げる仕組みだ。
- `PreToolUse` は実行前に止める、`PostToolUse` は実行後に整える、という役割分担が明確で、permission mode を緩めても deny 側の制約を残せる。
- 日本語圏で起きやすい『丁寧なプロンプトを書けば安全』という誤解を崩し、instruction と deterministic enforcement を分けて考えさせる。
読み終えたら次へ
この1本で終わらせず、同じ目的・同じテーマ・近い原典へ進めます。
何が変わったのか
この docs が示している変化は、customization の重心が instructions を増やすことから lifecycle event ごとに何を強制するかへ移ったことです。`UserPromptSubmit`、`PreToolUse`、`PostToolUse`、`Stop` などの event ごとに何を見て何を返せるかが整理され、特に `PreToolUse` は permission check より前に走ります。つまり hooks は単なる補助通知ではなく、LLM の善意や記憶に依らない deterministic automation を repo policy の位置まで引き上げる道具です。
なぜ重要か
日本の coding agent 運用では、危険 command 禁止や必須 formatter を chat 内 instruction に載せたままにしがちです。しかしその設計では、再現性も監査性も弱い。hooks を理解すると、禁止系は実行前フック、整形や通知は実行後フック、と責務を分けて team workflow に埋め込めます。個人の好みメモと物理的な強制を混ぜないための一次情報としても重要です。
技術的ポイント
- `PreToolUse` は tool 実行前、permission-mode check 前に走る。`permissionDecision: "deny"` を返せば権限設定が緩くても止められる。
- `PostToolUse` は実行後フックであり、起きた操作を取り消せない。整形、通知、ログ収集には向くが危険操作の遮断には向かない。
- prompt hook は hook input data だけで判定する軽量 LLM call、agent hook は subagent を起動して file read や command 実行まで使う検証型フックである。ただし agent hooks は experimental と明記されている。
- HTTP hook は shell command の代わりに event JSON を endpoint へ POST できるが、HTTP status code だけでは block できず返却 JSON の `hookSpecificOutput` が必要になる。
- 複数の `PreToolUse` hook が同じ tool input を `updatedInput` で書き換えると、parallel 実行のため最後に終わったものが勝つ。rewrite hook の多重定義は non-deterministic になりうる。
英日キーワード
| 英語 | 日本語 | 補足 |
|---|---|---|
| hooks | フック | 決まったイベントで自動実行される処理。会話内のお願いを実行境界へ移すための仕組み。 |
| PreToolUse | ツール実行前フック | 実行前に block や書き換えを行うイベント。禁止系ガードレールはここに置く。 |
| PostToolUse | ツール実行後フック | 実行後の整形、通知、監査向けイベント。危険操作の遮断には使えない。 |
| permissionDecision | 許可判断 | hook が返す allow / deny の判定。permission mode を緩めても deny 側の制約は残せる。 |
| deterministic automation | 決定的自動化 | LLM の気分に依らず必ず走る処理。禁止操作や必須後処理を instruction から分離する時に使う。 |
| agent hook | エージェントフック | subagent で実状態を確認する実験的フック。強力だが production では安定性前提を置けない。 |
試すなら
- まず『守ってほしいお願い』を棚卸しし、instruction で十分なものと hook に移すべきものを分ける。
- 危険 command、push、削除、外部送信のような禁止系は `PreToolUse` に寄せる。
- formatter、lint、secret scan、変更サマリ通知のような後処理は `PostToolUse` で試す。
- 実ファイルの状態確認が要る終了判定だけ agent hook を検討し、本番では experimental 前提の fallback を持つ。
注意点
- agent hooks は experimental で、docs 自体が production workflow では command hooks を優先すると書いている。強力だからといって主力に据えるのは早い。
- `PostToolUse` は止血ではなく事後処理である。危険操作を後段 hook に置く設計は間違いだ。
- hook を増やし過ぎると遅延や非決定性が増える。特に input rewrite を複数箇所で行う設計は避けるべきだ。
この記事は役に立ちましたか
公益的に続けるため、役に立った点や読みづらかった点だけを短く送れます。メールアドレスは不要です。