TL;DR
- Codex には「under development」ステータスの Hooks 機能があり、
codex features enable codex_hooksで有効化できる - 対応イベントは
SessionStart/UserPromptSubmit/Stopの3つ - ハンドラタイプは
command（シェルコマンド実行）のみ動作する
Hooks の有効化
Codex にはフィーチャーフラグの一覧を表示するコマンドがあります。
$ codex features list
codex_hooks under development false
有効化するには以下を実行します。
codex features enable codex_hooks
有効化すると起動時に警告が出ますが、機能は使えます。
設定ファイル
Hooks 設定は一般設定（~/.codex/config.toml）とは別の ~/.codex/hooks.json に書きます。
~/.codex/
├── config.toml ← 一般設定・feature flags
└── hooks.json ← hooks 設定（JSON）
JSON 構造
イベント配列に直接ハンドラを並べるのではなく、一段ラッパー（ソースコード上では MatcherGroup）を挟む必要があります。
hooks.<EventName>[].matcher → フィルタ条件（省略可）
hooks.<EventName>[].hooks[] → 実行するハンドラの配列
動く書き方:
{
"hooks": {
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": "echo 'session started'",
"timeout": 10
}
]
}
]
}
}
動かない書き方（MatcherGroup を省略）:
{
"hooks": {
"SessionStart": [
{
"type": "command",
"command": "echo 'session started'"
}
]
}
}
公式ドキュメントがないため、この構造は openai/codex の Rust ソースコード（codex-rs/hooks/src/engine/config.rs）を読んで特定しました。
対応イベント
| イベント | 発火タイミング |
|---|---|
SessionStart |
セッション開始・再開時 |
UserPromptSubmit |
ユーザーがプロンプトを送信した時 |
Stop |
エージェント応答完了時 |
ツール実行やサブエージェント関連のイベントは未実装です。
ハンドラタイプ
ソースコード上は command・prompt・agent の3タイプが定義されていますが、動作するのは command のみです。
| タイプ | 内容 | 状態 |
|---|---|---|
command |
シェルコマンドを実行する | 動作する |
prompt |
プロンプトを注入する | 未実装 |
agent |
別のエージェントを起動する | 未実装 |
stdin に渡される JSON ペイロード
hook コマンドは $SHELL -l -c "<command>" で実行され、stdin に JSON が渡されます。
{
"session_id": "019d07b0-...",
"cwd": "/Users/user/project",
"hook_event_name": "SessionStart",
"model": "o3-pro",
"permission_mode": "default",
"source": "startup",
"transcript_path": null
}
イベントごとの追加フィールド:
| フィールド | イベント | 説明 |
|---|---|---|
source |
SessionStart |
startup / resume / clear
|
prompt |
UserPromptSubmit | ユーザー入力テキスト |
turn_id |
UserPromptSubmit / Stop | 会話ターンの識別子 |
last_assistant_message |
Stop | 最後のアシスタント応答 |
活用例: セッション管理アプリへの連携
全イベントで stdin の JSON をそのままローカル API に転送する設定例です。
{
"hooks": {
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": "curl -s -X POST http://localhost:3000/api/hook -H 'Content-Type: application/json' -d \"$(cat)\"",
"timeout": 10
}
]
}
],
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "curl -s -X POST http://localhost:3000/api/hook -H 'Content-Type: application/json' -d \"$(cat)\"",
"timeout": 10
}
]
}
]
}
}
hooks.json が空または存在しなければ、フィーチャーフラグを有効にしても何も起きません。
制限事項
- 開発中ステータスのため API 変更の可能性あり
- イベント粒度が粗い（ツール実行単位のフックなし）
-
commandタイプのみ（prompt・agent・asyncは未サポート） - 公式ドキュメントがない
Codex は Apache License 2.0 の OSS なので、仕様が不明な場合は codex-rs/hooks/src/ のソースコードを直接確認できます。