hooksとは何か【2026年】AIエージェント時代の必要性とClaude Code・Codexでの使い方
「hooks って、イベントにスクリプトを差し込む仕組みだよね」で理解を止めると、AI エージェントではだいたい足りません。実際には、どこで止めるのか、どこで自動化するのか、承認を誰が持つのかまで含めて設計に効いてきます。
特に Claude Code や Codex のように、ファイル編集、コマンド実行、承認要求まで自律的に進めるツールでは、hooks は便利機能というより運用ルールの差し込み口です。危険な Bash を止める、編集後に formatter を走らせる、終了前に未実行テストを確認する、といった制御を LLM 任せにしないために使います。
この記事では、まず hooks とは何かを整理し、そのうえで AIエージェント時代になぜ必要なのか、最後に Claude Code と Codex での具体的な使い方をまとめます。事実関係は 2026年6月21日時点の公式ドキュメントで確認しています。
hooksとは何か
先に結論を言うと、hooks は「処理の途中に自分のルールを差し込む仕組み」です。決まったイベントが起きたときに、ログを取る、入力を検査する、危険操作を止める、後続処理を追加する、といった処理を自動で走らせます。
一般的なソフトウェアの文脈でも意味は近く、Microsoft Learn では hook を、イベントやメッセージを途中で受け取り、必要なら変更や破棄までできる仕組みとして説明しています。AI エージェントに置き換えると、監視対象がキーボードやマウスではなく、プロンプト送信、ツール実行、承認要求、応答終了になるイメージです。
混同されやすいので、callback との違いだけ先に分けておきます。
| 用語 | 役割 |
|---|---|
| callback | 実際に呼ばれる関数や処理 |
| hook | callback やスクリプトを差し込むための場所や仕組み |
つまり、AI エージェントの PreToolUse や PostToolUse は hook point で、そこに登録する shell script や Python script が hook handler です。
AIエージェント時代になぜhooksが必要なのか
AI エージェント時代に hooks が必要なのは、モデルが「考える」だけでなく「動く」からです。コードを書く、ファイルを編集する、Bash を打つ、承認を取りに来る、といった一連の動作が入る以上、どこかで deterministic なガードレールを差し込まないと運用が不安定になります。
自分が hooks を重要だと感じる理由は、主に次の 4 つです。
| 必要になる場面 | hooks でやること |
|---|---|
| 危険操作を止めたい | rm -rf や本番 DB への接続を PreToolUse で deny する |
| 承認フローを固定したい | 安全な操作だけ自動許可し、危険な操作だけ人間確認に寄せる |
| 品質チェックを自動化したい | 編集後に formatter、lint、test を走らせる |
| 監査や通知を残したい | 実行ログ送信、入力待ち通知、終了前チェックを入れる |
ここが普通の補助 AI と違うところです。チャットで質問に答えるだけのツールなら、人間が最後に全部判断すれば済みます。ただ、Claude Code や Codex はリポジトリを読んで、そのまま編集や実行まで進みます。だから「賢いかどうか」より前に、「どこまで勝手に進んでよいか」を外から制御する仕組みが要ります。
実務で効くのは、LLM の判断を否定するためではなく、LLM の判断だけにしないために hooks を置くことです。運用ルールをコード化しておけば、セッションごとのムラを減らせます。
Claude Codeでの具体的な使い方
Claude Code の hooks は、エージェントのライフサイクル全体に広くルールを差し込みたいときに向いています。単に Bash を止めるだけでなく、通知、外部連携、停止判定、後処理まで 1 つの枠組みで持てるのが強みです。
2026年6月21日時点の公式 reference では、SessionStart、UserPromptSubmit、PreToolUse、PermissionRequest、PostToolUse、SubagentStart / SubagentStop、Stop に加えて、Notification、InstructionsLoaded、CwdChanged、FileChanged、WorktreeCreate / WorktreeRemove、Elicitation / ElicitationResult などもあります。運用ルールを外出しする場所がかなり多いです。
まず入れやすい使い方は次の 3 つです。
| 使い方 | どこで効くか | 例 |
|---|---|---|
| 危険コマンドのブロック | PreToolUse | 破壊的な Bash、保護ファイルへの編集を deny |
| 編集後の自動処理 | PostToolUse | formatter、lint、通知を実行 |
| 入力待ちや終了前の確認 | Notification / Stop | 入力待ち通知、停止前の自己チェック |
Claude Code が強いのは handler の種類です。command だけでなく、http、mcp_tool、prompt、agent まで使えます。なので「監査ログを外部 API に流す」「Stop 時だけ LLM に続行判定させる」「subagent に後検証させる」といった、少し太い運用も組めます。
ただし、広く使えるぶん、何でも hooks に寄せると責務が散ります。特に prompt hook や agent hook は便利ですが、再現性より判断力を優先する仕組みです。中核のルールは、まず command hook で固める方が崩れにくいです。
Codexでの具体的な使い方
Codex の hooks は、現時点では「広い拡張基盤」というより、「CLI の重要な実行点に deterministic な検査を入れる仕組み」として使うのが自然です。2026年6月21日時点の公式 docs では、実行される handler は type: "command" のみで、prompt と agent は parse されるが skip、async: true も parse されるが未サポートと明記されています。
つまり Codex では、まず次のような使い方から考えるのがよいです。
| 使い方 | どこで効くか | 例 |
|---|---|---|
| Bash や編集内容の検査 | PreToolUse | 危険コマンド、禁止パス、秘密情報の扱いを止める |
| 承認フローの固定 | PermissionRequest | 安全な読み取りだけ allow、危険操作は deny か人間確認 |
| 実行結果の追加チェック | PostToolUse / Stop | Bash 出力のレビュー、未実行テストの検出 |
実務で特に効くのは PermissionRequest です。承認ルールを hook 側に寄せると、「読み取りだけなら自動許可」「特定ディレクトリ配下での破壊操作は deny」といった設計を固定できます。LLM がその場で良さそうに見える判断をしても、最後はルールで止められます。
Codex は non-managed の command hook をそのまま走らせず、定義を review / trust したものだけ実行します。ここはかなり Codex らしい設計で、拡張性よりもガードレールを優先しています。雑に増やすより、少数の明確な hooks を置く方が相性がよいです。
Claude CodeとCodexの違いは「広く拡張するか、堅く止めるか」です
どちらにも hooks はありますが、同じ感覚で設計するとズレます。大づかみに言うと、Claude Code は「広く拡張する hooks」、Codex は「堅く制御する hooks」です。
| 観点 | Claude Code | Codex |
|---|---|---|
| 基本の立ち位置 | エージェントのライフサイクル全体を広く拡張する | CLI の重要な実行点にガードレールを入れる |
| 実行できる handler | command / http / mcp_tool / prompt / agent | 現時点で実行されるのは command のみ |
| event の広さ | セッション、通知、worktree、Elicitation まで広い | SessionStart、PreToolUse、PermissionRequest、PostToolUse、Stop など主要点中心 |
| async | command hook で利用可 | 未サポート |
| 向いている設計 | 通知、外部連携、停止判定、後処理までまとめたい | 承認、禁止操作、定型チェックを固くしたい |
どちらを選ぶか迷ったら、「どこまで広く運用を外出ししたいか」で考えると整理しやすいです。通知や外部 API 連携まで含めて組みたいなら Claude Code、まず事故を減らして承認と検査を固定したいなら Codex が向きます。
導入前に見ておきたい落とし穴
hooks は便利ですが、入れた瞬間に運用コストも増えます。最初に見ておきたいのは次の 3 点です。
async の有無で設計が変わる
Claude Code は command hook の async 実行に対応していますが、非同期 hook は即時ブロックには使えません。Codex はそもそも async が未対応です。「あとで通知する処理」と「今ここで止める処理」は分けて設計する必要があります。
hooks を増やすほど、どこで止まったか分かりにくくなる
PreToolUse、PostToolUse、Stop に似たような検査を積み増すと、止まった理由の追跡が難しくなります。最初は「危険操作を止める」「整形を走らせる」「終了前に未実行テストだけ見る」くらいに絞る方が安定します。
仕様差分は必ず公式 docs で見直す
hook 系は変化が早いので、記事や社内ルールに書く前にその日の docs で差分確認した方が安全です。今回の比較でも、Codex は hooks 自体は有効でも handler 実行範囲がかなり限定的ですし、Claude Code 側は event も hook type も広がっています。
まとめ
hooks は、AI エージェントが「考えるだけでなく動く」時代に、運用ルールを deterministic に差し込むための仕組みです。Claude Code は広く拡張しやすく、Codex は堅く制御しやすい、という違いがあります。
まず試すなら、1 本だけ PreToolUse か PermissionRequest を入れて、何を止めるかを明確にするところから始めるのが安全です。そこが固まってから、通知、整形、テスト、監査ログに広げる方が運用も崩れません。
参考リンク
- OpenAI Developers: Codex Hooks
- OpenAI Developers: Config basics
- Claude Code Docs: Hooks reference
- Claude Code Docs: Automate actions with hooks
- Microsoft Learn: Hooks Overview
