Codex hooks 設計ガイド - lifecycle eventとMCP tool hookを安全に使う

Codex hooks を入れると、ファイル編集後の整形、作業完了時の検証、MCP tool 呼び出しの記録、危険な外部操作の検知を自動化できます。便利ですが、ここを「ちょっとした shell script 置き場」として扱うと、AI エージェントの実行経路に見えない副作用が混ざります。

この記事は、Codex hooks をチームで使い始める前に、どの lifecycle event に何を置き、どこから人間レビューへ戻すかを決めたい人向けです。sandbox / approval の基本は Codex sandbox / approvals 設計ガイド、approval request の自動 reviewer は Codex auto review ガイド、plugin に含まれる hook の許可は Codex plugin governance 設計ガイド、Claude Code 側の PreToolUse / PostToolUse / Stop Hook は Claude Code Hooks 実践ガイド に分けています。

今回は Codex 固有の hook 設計、特に lifecycle event、shell hook、MCP tool hook、managed hook、trust review に絞ります。

先に結論: hook は自動化ではなく実行経路としてレビューする

私なら Codex hooks を次の4層に分けます。

層	置くもの	初期判断
lifecycle hook	session start、tool実行前後、final response前後の処理	localで小さく試す
shell hook	format、lint、diff summary、通知	write範囲を限定する
MCP tool hook	tool call前後の検査、監査ログ、追加承認	read/writeを分ける
managed hook	workspace adminが配布する共通hook	例外とdisable条件を文書化する

hook は「プロンプトより確実に走る処理」です。だから、プロンプトより軽く見てはいけません。AGENTS.md に「外部送信しない」と書いても、hook が外部 webhook へ payload を送るなら実行経路は変わります。

最初に hook の目的を3つに絞る

Codex hooks で最初から何でも自動化しようとすると、原因追跡が難しくなります。私は最初の用途を3つだけに絞ります。

1. 編集後の決定的な後処理を走らせる
2. 危険な操作を止める前に記録する
3. 作業完了前に検証不足を見つける

たとえば、Markdown 記事の整形、変更ファイル一覧の保存、pnpm run build 未実行の検知は hook に向いています。一方で、deploy、課金操作、外部 SaaS への write、secret を読む処理は初期 hook に置きません。

hook が強いのは、LLM の気分に依存しない点です。弱いのは、LLM の判断を待たずに副作用を起こせる点です。この両方を同時に見る必要があります。

lifecycle event は「止める」「足す」「確認する」で分ける

Codex hooks では、Codex の作業 lifecycle に合わせて処理を差し込めます。設計時はイベント名を覚えるより先に、目的で分ける方が安定します。

目的	置く処理	注意点
止める	workspace外編集、危険command、secret file参照の検知	誤検知時の戻り先を用意する
足す	format、軽いlint、差分summary、通知	元操作の失敗と混ぜない
確認する	build未実行、test不足、PR本文不足の検査	重い検証を毎回走らせない

よくない例は、すべてを1つの post-task hook に詰めることです。整形、test、Slack 通知、PR comment、監査ログ送信を同じ hook に入れると、失敗時に何を直せばよいか分かりません。

まずは次のように粒度を分けます。

codex_hooks:
  after_file_edit:
    purpose: format changed markdown only
    side_effect: local file write
  before_external_tool:
    purpose: inspect target and risk tier
    side_effect: none
  before_final_response:
    purpose: ensure verification result is reported
    side_effect: none

hook の名前ではなく、目的、入力、許す副作用で管理します。

shell hook は idempotent にする

shell hook は一番手軽ですが、一番雑に増えます。私なら最初の条件を次にします。

• 同じ入力で何度走っても壊れない
• 対象ファイルを changed files に限定できる
• network を使わない
• secret を読まない
• 失敗時の message が人間に読める

たとえば、Markdown だけを整形する hook は比較的安全です。

pnpm exec prettier --write "$CODEX_CHANGED_FILE"

ただし、これも万能ではありません。keyword-plan.md のように表全体が大きく崩れやすいファイルでは、hook による全体整形が review noise になります。対象ファイルや拡張子だけでなく、この repo では整形してよいファイルかまで見るべきです。

私なら hook policy に次のように書きます。

format_hook_policy:
  allow:
    - "src/content/blog/*.md"
    - "src/**/*.astro"
  ask:
    - "data/seo/keyword-plan.md"
  deny:
    - ".env*"
    - "dist/**"

hook は自動実行なので、通常の「後でレビューすればよい」より一段厳しくします。

MCP tool hook は read / write で分ける

Codex hooks は MCP tool の前後にも関わります。ここは特に慎重に扱います。MCP は外部システム接続なので、tool call の前後で何を記録し、何を止めるかがそのまま監査境界になります。

私なら MCP tool hook は最初に4分類します。

tool 種別	hook の役割	例
read-only	sourceとqueryを記録する	GitHub PR diff取得
inspect	結果件数と対象IDを残す	issue検索、Drive検索
write	approval IDとpayload digestを残す	PR comment、ticket更新
external action	原則止めるか別承認に戻す	email送信、deploy起動

大事なのは、tool result 全文を hook で雑に保存しないことです。PR comment、顧客データ、社内文書、secret に近い値が混ざる可能性があります。保存するなら、raw log ではなく operation ID、tool name、risk tier、redacted summary、artifact pointer に分けます。

mcp_tool_audit_event:
  tool: github.create_pr_comment
  risk_tier: write_internal
  approval_id: apr_123
  payload_digest: sha256:...
  redacted_summary: "posts review summary to PR 42"

MCP tool hook は「何でもログに残す」ためではなく、後から説明できる最小証跡を残すために使います。

managed hooks は配布前に disable 条件を決める

OpenAI docs では、managed hooks を workspace policy として配布できる導線が示されています。これは便利ですが、個人の local hook より責任が重いです。全員の作業 lifecycle に同じ処理が差し込まれるからです。

managed hook を配る前に、私は次を必須にします。

1. 何のための hook か1文で説明できる
2. どの event で走るか分かる
3. どの file / command / tool を対象にするか分かる
4. どの情報を外へ出すか分かる
5. 利用者が一時停止できる条件がある
6. incident 時の owner が決まっている

特に外部送信 hook は重く見ます。たとえば「全 tool call を監査基盤へ送る」は分かりやすいですが、payload に顧客データや private issue 本文が含まれるなら危険です。最初は metadata だけにします。

trust review を省略しない

Codex hooks では、hook configuration を信頼するかどうかの確認が重要です。repo に入っている hook は、便利な project rule であると同時に、作業者の端末で実行される command でもあります。

新しい repo を開いたら、私は次を確認します。

• hook が shell command を実行するか
• network へ出るか
• workspace 外を読むか
• token / cookie / .env を読むか
• MCP tool call の payload を保存するか
• hook 自体が誰に管理されているか

この確認をしないまま hook を信頼すると、外部から持ち込んだ repo rule が自分の Codex 実行経路になります。特に採用課題、外部委託、サンプル repo、未レビューの plugin では慎重にします。

Claude Code Hooks と同じ設計にしない

Claude Code Hooks と Codex hooks は、目的は似ていますが同じものではありません。Claude Code 側は PreToolUse / PostToolUse / Stop Hook のようなイベント語彙と settings.json の運用が中心です。一方 Codex 側では、Codex の sandbox、approval reviewer、MCP、plugins、managed workspace policy と一緒に見る必要があります。

移行時にやりがちな失敗は、Claude Code の hook をそのまま Codex へ持ち込むことです。

Claude Code で動いていたから、Codex でも同じタイミングで同じ payload が来るはず。

これは危険です。event semantics、payload、blocking behavior、MCP tool の扱い、設定の配布範囲が違う可能性があります。移行するときは、まず dry-run にし、write や外部送信は無効にして、payload と発火タイミングを確認します。

導入チェックリスト

Codex hooks をチームで使う前に、最低限これだけ決めます。

1. local hook と managed hook を分けたか
2. lifecycle event ごとの目的を1つに絞ったか
3. shell hook は idempotent か
4. MCP tool hook は read / write / external action を分けたか
5. raw payload を保存しない設計になっているか
6. repo 由来の hook を trust review する手順があるか
7. Claude Code から移した hook を dry-run で検証したか

まとめ

Codex hooks は、AI エージェント運用の品質を上げる強い部品です。ただし、便利な自動化としてではなく、Codex の lifecycle に差し込まれる実行経路としてレビューする必要があります。

私なら、最初は local の shell hook で整形や軽い検証だけを入れます。次に MCP tool hook で read / write の証跡を最小化し、最後に managed hooks を配布します。外部送信、secret 参照、deploy、広い write は hook で隠さず、approval と review gate へ戻します。

hook は「AI に守ってほしいルール」ではありません。実際に走るルールです。だからこそ、プロンプトや AGENTS.md より強いものとして扱ってください。

参考資料

• Hooks - Codex
• Advanced configuration - Codex
• Config reference - Codex
• Auto-review - Codex