Hooks (フック)

たとえば、チームのプロンプトを走査して API キーの誤った貼り付けを止める使い方があります。フックは既定で有効です。

Hooks は Codex の拡張の仕組みで、エージェントループの途中でスクリプトや MCP ツールを実行します。

• Codex は、有効な設定レイヤーの隣にある hooks.json ファイル、または config.toml 内のインラインの [hooks] テーブルからフックを見つけます。読み込み元が複数あるときは、条件に合うフックをすべて読み込みます。
• プラグインが有効なときは、ユーザー・プロジェクト・管理のフックと並べて、そのプラグインのライフサイクルフックも読み込めます。
• ハンドラーの種類は command と mcp_tool に対応しています。prompt と agent のハンドラーは解析されますが、実行はされません。
• matcher フィールドは正規表現の文字列で、フックが発火する条件を絞り込みます。
• 同じイベントに一致する複数のコマンドフックは同時に起動するため、あるフックが別の一致するフックの起動を妨げることはありません。

• UserPromptSubmit: decision: "block" と理由を返すと、プロンプトを止めます。
• PreToolUse: Bash、apply_patch によるファイル編集、MCP ツールの呼び出し、その他のローカル関数ツールに割り込めます。permissionDecision: "allow" と updatedInput を返すと、止めずに対応ツールの呼び出しを書き換えます。
• PermissionRequest: Codex が承認を求める直前に実行され、許可・拒否のほか、判断せずに通常の承認プロンプトへ進めることもできます。
• PostToolUse: 対応ツールが出力を返した後に実行されます。すでに実行されたツールの副作用は取り消せません。
• PreModelRequest / PostModelRequest: 同じターン内の再試行も含めて、モデルへのリクエストを記録できます。出力は診断用で、モデルのコンテキストを変えたりリクエストを止めたりはできません。
• Stop: decision: "block" を返すと、Codex は処理を続け、フックの理由を本文とする継続プロンプトを新しいユーザープロンプトとして自動で作ります。
• SessionEnd: セッション終了時にコマンドを実行します。最終メモの保存やファイルの片付けに使えます。サブエージェントでは実行されません。
• Interrupt: メインスレッドで実行中のターンを中断したときに実行されます。中断の記録や、フックが始めた作業の片付けに使えます。出力で中断を防いだり、ターンを再開したりはできません。

なお、WebSearch などのホスト型ツールはローカルの関数ツールのフック経路を通らないため、PreToolUse と PostToolUse は適用されません。

既定では、Codex はコマンドフックの完了を待ってから、きっかけとなった操作を続けます。async を true にすると、Codex は処理を続けながらコマンドフックをバックグラウンドで実行します。hooks.json ではコマンドハンドラーに "async": true を、config.toml のインラインのフックでは async = true を設定します。バックグラウンドのフックは、きっかけとなった操作を止める・承認する・書き換えるなどの制御はできません。

モデルに見えるフック出力は、既定で 1 メッセージあたりおよそ 2,500 トークンまでです。これを超えると、全文を <temp_dir>/hook_outputs/<session_id>/<uuid>.txt に保存し、モデルには先頭と末尾のプレビューと保存先のパスを渡します。

MCP ツールのフックは既存の MCP 接続を使い、サーバーの起動や再接続は行いません。

• フックは既定で有効です。無効にするには、config.toml で次のように設定します。

[features]
hooks = false

• allow_managed_hooks_only = true を設定すると、ユーザー・プロジェクト・セッション・プラグインのフックを無視し、管理者が管理するフックだけを許可します。
• 読み込めない必須の管理フックがあるセッションは拒否されます。
• プロジェクト内のフックは、プロジェクトの .codex/ レイヤーが信頼されている場合だけ読み込まれます。
• Codex はフックの現在のハッシュに対して信頼を記録します。新規または変更されたフックはレビュー対象になり、信頼されるまで実行されません。
• Codex の外でフックの出どころを確認済みの単発の自動化では、--dangerously-bypass-hook-trust を渡すと、その実行に限り保存済みの信頼なしで有効なフックを実行します。
• ツールのフックは有用なガードレールであり、完全な強制の境界としては扱わない位置付けです。

以下は、フックを定義して信頼するまでの基本の流れです。

1. フックを hooks.json ファイル、または config.toml に定義します。置き場所としては ~/.codex/ や <repo>/.codex/ が使いやすい場所です。
2. CLI で /hooks を使い、フックの読み込み元の確認、新規・変更されたフックのレビュー、フックの信頼、管理対象でない個別フックの無効化を行います。
3. プラグインに同梱されたフックは、CLI では /hooks、デスクトップアプリでは composer の Review hooks (フックをレビュー) を選ぶか、Settings (設定) > Hooks (フック) を開いてレビューし、信頼します。