Hooks 実装 - ライフサイクルイベントで自動化する
約5分
対象読者: Codex の開始・ツール利用・停止時に検証や通知を自動実行したい開発者
前提知識: config.toml と、外部スクリプトを実行する際のセキュリティ境界を理解していること
Hooks は Codex のライフサイクル中に独自スクリプトを実行する拡張機能です。自然言語の指示では実行が揺れる処理を、決定的なチェックとして固定できます。
主なイベント
Section titled “主なイベント”Codex では SessionStart、UserPromptSubmit、PreToolUse、PermissionRequest、PostToolUse、SubagentStart、SubagentStop、Stop などのイベントを利用できます。
| イベント | 用途例 |
|---|---|
SessionStart | 環境情報やプロジェクト状態の確認 |
UserPromptSubmit | 秘密情報らしい入力の検出 |
PreToolUse | 特定ツール実行前のポリシーチェック |
PostToolUse | 変更後の軽量検証 |
Stop | ターン終了時の lint、リンク検証、報告生成 |
Hooks は有効な設定レイヤーの隣にある hooks.json、または config.toml の [hooks] で定義できます。プラグインから配布することもできます。
[features]
hooks = trueプロジェクト固有 Hook は、信頼済みプロジェクトだけで読み込ませます。取得したリポジトリのスクリプトを内容確認なしに実行してはいけません。
良い Hook の条件
Section titled “良い Hook の条件”- 高速: 毎回動いても作業を大きく遅らせない
- 決定的: 同じ状態なら同じ結果になる
- 狭い責務: 一つの Hook で多数の副作用を起こさない
- 秘密を残さない: プロンプトや環境変数をそのままログへ書かない
- 失敗が明確: 終了コードと短い修正案を返す
このリポジトリなら、ハーネス変更後の npm run harness:check や記事変更後のリンク検証が候補です。一方、npm run build やデプロイのような承認が必要な処理を自動 Hook に入れてはいけません。
最初は通知だけの Hook でイベントと入力を確認します。その後、読み取り専用の検証を追加し、最後に失敗時の停止条件を調整します。複数 Hook は並行実行される場合があるため、実行順に依存させない設計が必要です。
次は MCP・Plugins 統合 で、Codex の外部ツールを安全に増やします。
クイズ