サイトのビルド日時: 2026年7月20日 12:16 JST

フック¶

フックは Codex の拡張フレームワークです。エージェントループに独自のスクリプトを挿入でき、次のような機能を実現できます。

チャットをカスタムのロギング／分析エンジンに送信する
チームのプロンプトをスキャンし、API キーの誤った貼り付けをブロックする
チャットを要約して永続的なメモリを自動的に作成する
チャットのターンが停止したときにカスタム検証を実行し、標準を適用する
特定のディレクトリにいるときのプロンプトをカスタマイズする

留意すべきランタイム動作は次のとおりです。

複数のファイルにある一致するフックはすべて実行されます。
同じイベントに一致する複数のコマンドフックは同時に起動されるため、1 つのフックで別の一致するフックの起動を防ぐことはできません。
管理対象外のコマンドフックは、実行前に確認して信頼する必要があります。
PreToolUse、PermissionRequest、PostToolUse、PreCompact、 PostCompact、UserPromptSubmit、SubagentStop、Stop はターンスコープで実行されます。SessionStart と SubagentStart はスレッドまたはサブエージェント開始スコープで実行されます。

Codex がフックを検索する場所¶

Codex は、アクティブな設定レイヤーの隣にある次のいずれかの形式のフックを検出します。

hooks.json
config.toml 内のインライン [hooks] テーブル

インストールされたプラグインは、プラグインマニフェストまたはデフォルトの hooks/hooks.json ファイルを通じてライフサイクル設定をバンドルすることもできます。プラグインのパッケージング規則については、プラグインのビルドを参照してください。

実際には、最も便利な 4 つの場所は次のとおりです。

~/.codex/hooks.json
~/.codex/config.toml
<repo>/.codex/hooks.json
<repo>/.codex/config.toml

複数のフックソースが存在する場合、Codex は一致するフックをすべて読み込みます。優先順位の高い設定レイヤーが、優先順位の低いフックを置き換えることはありません。 1 つのレイヤーに hooks.json とインライン [hooks] の両方が含まれる場合、 Codex はそれらをマージし、起動時に警告します。レイヤーごとに 1 つの表現を使用することを推奨します。

Codex は、有効なプラグインにバンドルされたフックも検出できます。プラグインにバンドルされたフックは他のフックソースと並行して読み込まれ、他の管理対象外フックと同じ信頼確認フローを使用します。

プロジェクトローカルのフックは、プロジェクトの .codex/ レイヤーが信頼されている場合にのみ読み込まれます。信頼されていないプロジェクトでは、Codex はユーザーおよびシステムのフックを、それぞれのアクティブな設定レイヤーから引き続き読み込みます。

フックの確認と信頼¶

Codex は、実行可能なフックを決定する前に、設定されたフックを一覧表示します。管理対象外のコマンドフックを実行する前に、Codex ではフック定義の正確な内容を確認して信頼する必要があります。Codex はフックの現在のハッシュに対して信頼を記録するため、新規または変更されたフックは確認対象としてマークされ、信頼されるまでスキップされます。

CLI で /hooks を使用すると、フックソースの調査、新規または変更されたフックの確認、フックの信頼、または個々の管理対象外フックの無効化を行えます。起動時にフックの確認が必要な場合、Codex は /hooks を開くよう指示する警告を表示します。

システム、MDM、クラウド、または requirements.toml ソースからの管理対象フックは管理対象としてマークされ、ポリシーによって信頼されます。ユーザーフックブラウザーから無効にすることはできません。

Codex 外部ですでにフックソースを検証している一度限りの自動化では、--dangerously-bypass-hook-trust を渡すことで、その呼び出しに対して保存されたフックの信頼を要求せずに有効なフックを実行できます。

設定の形式¶

フックは 3 つのレベルで構成されます。

PreToolUse、PostToolUse、PreCompact、SubagentStart、 Stop などのフックイベント
イベントが一致するタイミングを決定するマッチャーグループ
マッチャーグループが一致したときに実行される 1 つ以上のフックハンドラー

{
  "description": "Optional lifecycle hooks for this workspace.",
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.codex/hooks/session_start.py",
            "statusMessage": "Loading session notes"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py\"",
            "statusMessage": "Checking Bash command"
          }
        ]
      }
    ],
    "PermissionRequest": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/permission_request.py\"",
            "statusMessage": "Checking approval request"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/post_tool_use_review.py\"",
            "statusMessage": "Reviewing Bash output"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/user_prompt_submit_data_flywheel.py\""
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/stop_continue.py\"",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

注:

description は hooks.json ファイルのオプションのトップレベルメタデータです。実行されるフックは変わりません。
timeout の単位は秒です。
timeout が省略された場合、Codex は 600 秒を使用します。
statusMessage はオプションです。
commandWindows は Windows 専用のオプションのコマンド上書きです。TOML では command_windows または commandWindows を使用します。
async オプションは解析されますが、非同期コマンドフックはまだサポートされていません。Codex はそれらのハンドラーをスキップします。
現在実行されるのは type: "command" ハンドラーのみです。prompt と agent ハンドラーは解析されますが、スキップされます。
コマンドはセッションの cwd を作業ディレクトリとして実行されます。
リポジトリローカルのフックでは、.codex/hooks/... のような相対パスを使用するのではなく、 git ルートから解決することを推奨します。Codex はサブディレクトリから起動されることがあるため、git ルートを基準にしたパスによってフックの場所を安定させられます。

config.toml 内の同等のインライン TOML:

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'
timeout = 30
statusMessage = "Checking Bash command"

[[hooks.PostToolUse]]
matcher = "^Bash$"

[[hooks.PostToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/post_tool_use_review.py"'
timeout = 30
statusMessage = "Reviewing Bash output"

ターンフックを無効にする¶

フックはデフォルトで有効です。config.toml で無効にするには、次を設定します。

[features]
hooks = false

正式な機能キーとして hooks を使用してください。codex_hooks も非推奨のエイリアスとして引き続き機能します。管理者は requirements.toml で [features].hooks = false を使用して、同じ方法でフックを強制的に無効にできます。

`requirements.toml` からの管理対象フック¶

エンタープライズ管理の要件では、[hooks] の下にフックをインラインで定義することもできます。これは、管理者がフック設定を適用しながら、実際のスクリプトを MDM やその他のデバイス管理システムを通じて配布したい場合に便利です。ローカルでフックを無効にしたユーザーに対しても管理対象フックを適用するには、requirements.toml で [hooks] と併せて [features].hooks = true を固定します。ユーザー、プロジェクト、セッション、プラグインのフックを無視しつつ、管理者が管理するフックを許可するには、 allow_managed_hooks_only = true を設定します。

allow_managed_hooks_only = true

[features]
hooks = true

[hooks]
managed_dir = "/enterprise/hooks"
windows_managed_dir = 'C:\enterprise\hooks'

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = "python3 /enterprise/hooks/pre_tool_use_policy.py"
command_windows = 'py -3 C:\enterprise\hooks\pre_tool_use_policy.py'
timeout = 30
statusMessage = "Checking managed Bash command"

管理対象フックに関する注:

managed_dir は macOS と Linux で使用されます。
windows_managed_dir は Windows で使用されます。
Codex は managed_dir のスクリプトを配布しません。エンタープライズのツールでそれらを個別にインストールおよび更新する必要があります。
管理対象フックのコマンドでは、設定された管理対象ディレクトリ下の絶対スクリプトパスを使用してください。
allow_managed_hooks_only = true はユーザー、プロジェクト、セッション、プラグインソースからのフックをスキップしますが、requirements.toml およびその他の管理対象設定レイヤーからの管理対象フックは引き続き読み込みます。

プラグインにバンドルされたフック¶

プラグインが有効になると、Codex はユーザー、プロジェクト、管理対象フックと並行して、そのプラグインのライフサイクルフックを読み込めます。

デフォルトでは、Codex はプラグインルート内の hooks/hooks.json を検索します。プラグインマニフェストは、.codex-plugin/plugin.json 内の hooks エントリによってこのデフォルトを上書きできます。マニフェストエントリには、./ プレフィックス付きパス、 ./ プレフィックス付きパスの配列、インラインフックオブジェクト、またはインラインフックオブジェクトの配列を指定できます。

{
  "name": "repo-policy",
  "hooks": "./hooks/hooks.json"
}

マニフェストのフックパスはプラグインルートを基準に解決され、そのルート内にとどまる必要があります。マニフェストで hooks が定義されている場合、Codex はデフォルトの hooks/hooks.json ではなく、それらのマニフェストエントリを使用します。

プラグインフックのコマンドは、次の環境変数を受け取ります。

PLUGIN_ROOT は、インストールされたプラグインルートを指す Codex 固有の拡張です。
PLUGIN_DATA は、プラグインの書き込み可能なデータディレクトリを指す Codex 固有の拡張です。
Codex は既存のプラグインフックとの互換性のために CLAUDE_PLUGIN_ROOT と CLAUDE_PLUGIN_DATA も設定します。

プラグインフックは他のフックと同じイベントスキーマを使用します。プラグインをインストールまたは有効化しても、そのフックが自動的に信頼されることはありません。Codex は、現在のフック定義を確認して信頼するまで、プラグインにバンドルされたフックをスキップします。

マッチャーパターン¶

matcher フィールドは、フックが発火するタイミングをフィルターする正規表現文字列です。"*"、"" を使用するか、matcher を完全に省略すると、サポートされているイベントのすべての発生に一致します。

現在の Codex イベントの一部だけが matcher を使用します。

イベント	`matcher` がフィルターする対象	注
`PermissionRequest`	ツール名	サポート対象には `Bash`、`apply_patch`*、MCP ツール名が含まれます
`PostToolUse`	ツール名	ツールの対象範囲を参照してください
`PostCompact`	コンパクションのトリガー	値は `manual` または `auto` です
`PreCompact`	コンパクションのトリガー	値は `manual` または `auto` です
`PreToolUse`	ツール名	ツールの対象範囲を参照してください
`SessionStart`	開始元	値は `startup`、`resume`、`clear`、`compact` です
`SubagentStart`	サブエージェントの種類	値は開始するサブエージェントによって異なります
`SubagentStop`	サブエージェントの種類	値は停止するサブエージェントによって異なります
`UserPromptSubmit`	サポート対象外	このイベントに設定された `matcher` は無視されます
`Stop`	サポート対象外	このイベントに設定された `matcher` は無視されます

*apply_patch では、matcher の値に Edit または Write も使用できます。

例:

Bash
^apply_patch$
Edit|Write
mcp__filesystem__read_file
mcp__filesystem__.*
startup|resume|clear|compact
manual|auto

ツールの対象範囲¶

PreToolUse と PostToolUse は、シェルおよび MCP 呼び出し以外も監視できます。ほとんどのローカル関数ツールは同じフックパスを使用するため、ツール名を照合し、JSON 引数を検査し、PreToolUse では呼び出しをブロックまたは書き換えることができます。

ツールパス	`PreToolUse`	`PostToolUse`	注
シェルコマンド	はい	はい	`Bash` として照合します。
Unified exec (`exec_command`)	はい	はい	`Bash` として照合します。後続の `write_stdin` ポーリングでは、コマンド完了時に元のコマンドの `PostToolUse` を返せます。
`apply_patch`	はい	はい	`apply_patch`、`Edit`、または `Write` として照合します。
MCP ツール	はい	はい	`mcp__filesystem__read_file` のように、MCP ツール名と照合します。
その他のローカル関数ツール	はい	はい	`update_plan` のように、関数ツール名と照合します。`spawn_agent` は `Agent` にも一致します。
`WebSearch` などのホスト型ツール	いいえ	いいえ	これらはローカル関数ツールのフックパスを使用しません。

write_stdin は既存の Unified exec セッションのトランスポートです。入力を送信したり、 PreToolUse をすでに通過したコマンドをポーリングしたりするときに、 PreToolUse を再度実行することはありません。

一部の特殊なツールパスでは、デフォルトのフックパスをオプトアウトできます。ツールフックは有用なガードレールですが、完全な強制境界ではないものとして扱ってください。

共通入力フィールド¶

すべてのコマンドフックは、stdin 上で 1 つの JSON オブジェクトを受け取ります。

通常使用する共有フィールドは次のとおりです。

フィールド	型	意味
`session_id`	`string`	現在の Codex セッション ID。サブエージェントフックでは親セッション ID です。
`transcript_path`	`string \\| null`	セッションのトランスクリプトファイルへのパス（存在する場合）
`cwd`	`string`	セッションの作業ディレクトリ
`hook_event_name`	`string`	現在のフックイベント名
`model`	`string`	Codex 固有の拡張。アクティブなモデルのスラッグ

ターンスコープのフックでは、イベント固有の表に turn_id が Codex 固有の拡張として記載されています。

SessionStart、PreToolUse、PermissionRequest、PostToolUse、 UserPromptSubmit、SubagentStart、SubagentStop、Stop には、現在の権限モードを default、acceptEdits、plan、 dontAsk、bypassPermissions のいずれかとして説明する permission_mode も含まれます。

transcript_path は便宜上チャットトランスクリプトを指しますが、トランスクリプト形式はフックの安定したインターフェイスではなく、時間の経過とともに変更される可能性があります。

完全なワイヤ形式が必要な場合は、スキーマを参照してください。

共通出力フィールド¶

SessionStart、PreCompact、PostCompact、UserPromptSubmit、 SubagentStop、Stop は、次の共有 JSON フィールドをサポートします。 SubagentStart は systemMessage とフック固有のコンテキストに対して同じ形式を受け付けますが、continue: false はサブエージェントを停止しません。

{
  "continue": true,
  "stopReason": "optional",
  "systemMessage": "optional",
  "suppressOutput": false
}

フィールド	効果
`continue`	`false` の場合、そのフック実行を停止済みとしてマークします
`stopReason`	停止理由として記録されます
`systemMessage`	UI またはイベントストリームに警告として表示されます
`suppressOutput`	現在は解析されますが、まだ実装されていません

出力なしで 0 を終了すると成功として扱われ、Codex は続行します。

PreToolUse と PermissionRequest は systemMessage をサポートしますが、 continue、stopReason、suppressOutput は現在これらのイベントではサポートされていません。PreToolUse フックがこれらのサポート対象外フィールドのいずれかを返すと、Codex はそのフック実行を失敗としてマークし、エラーを報告して、ツール呼び出しを続行します。

PostToolUse は systemMessage、continue: false、stopReason をサポートします。suppressOutput は解析されますが、そのイベントでは現在サポートされていません。

大きなフック出力¶

Codex は、モデルに表示される各フック出力メッセージを約 2,500 トークンに制限します。フックがそれを超える内容を返した場合、Codex は完全なテキストを <temp_dir>/hook_outputs/<session_id>/<uuid>.txt に保存し、保存ファイルのパスとともに先頭および末尾のプレビューをモデルに渡します。ファイルを書き込めない場合でも、モデルは切り詰められたプレビューを受け取ります。

これは、SessionStart、SubagentStart、PreToolUse、 PostToolUse、UserPromptSubmit からの追加コンテキスト、PostToolUse からのフィードバック、Stop と SubagentStop からの継続プロンプトに適用されます。制限は各追加コンテキストエントリまたは継続プロンプトに適用されます。PostToolUse フィードバックについては、Codex が一致するすべてのフックからのフィードバックを結合し、結合されたメッセージに制限を適用します。

サイズ超過した出力はディスクに書き込まれる可能性があるため、フック出力でシークレットやその他の機密データを返さないでください。

フック¶

SessionStart¶

このイベントでは、matcher が source に適用されます。

共通入力フィールドに加えて、次のフィールドがあります。

フィールド	型	意味
`source`	`string`	セッションの開始方法: `startup`、`resume`、`clear`、または `compact`

stdout 上のプレーンテキストは、追加の開発者コンテキストとして追加されます。

stdout 上の JSON は共通出力フィールドと、次のフック固有の形式をサポートします。

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Load the workspace conventions before editing."
  }
}

この additionalContext テキストは、追加の開発者コンテキストとして追加されます。

SubagentStart¶

このイベントでは、matcher が agent_type に適用されます。

共通入力フィールドに加えて、次のフィールドがあります。

フィールド	型	意味
`turn_id`	`string`	Codex 固有の拡張。アクティブな Codex ターン ID
`agent_id`	`string`	サブエージェントの識別子
`agent_type`	`string`	サブエージェントの種類またはプロファイル
`permission_mode`	`string`	現在の権限モード

stdout 上のプレーンテキストは、サブエージェントの追加の開発者コンテキストとして追加されます。

stdout 上の JSON は systemMessage と次のフック固有の形式をサポートします。

{
  "hookSpecificOutput": {
    "hookEventName": "SubagentStart",
    "additionalContext": "Review the repository test conventions first."
  }
}

この additionalContext テキストは、サブエージェントの追加の開発者コンテキストとして追加されます。continue: false は互換性のために解析されますが、サブエージェントの開始を停止することはありません。

PreToolUse¶

PreToolUse は、Bash、apply_patch を通じて実行されるファイル編集、MCP ツール呼び出し、その他のローカル関数ツールをインターセプトできます。サポートされるパスと例外については、ツールの対象範囲を参照してください。

matcher は tool_name とマッチャーエイリアスに適用されます。 apply_patch を通じたファイル編集では、apply_patch、Edit、 Write を matcher の値として使用できます。フック入力では引き続き tool_name: "apply_patch" が報告されます。

共通入力フィールドに加えて、次のフィールドがあります。

フィールド	型	意味
`turn_id`	`string`	Codex 固有の拡張。アクティブな Codex ターン ID
`tool_name`	`string`	正規のフックツール名。`Bash`、`apply_patch`、または `mcp__fs__read` のような MCP 名など
`tool_use_id`	`string`	この呼び出しのツール呼び出し ID
`tool_input`	`JSON value`	ツール固有の入力。`Bash` と `apply_patch` は `tool_input.command` を使用します。MCP およびその他のローカル関数ツールは引数を送信します。

stdout 上のプレーンテキストは無視されます。

stdout 上の JSON では systemMessage を使用できます。サポートされているツール呼び出しを拒否するには、次のフック固有の形式を返します。

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Destructive command blocked by hook."
  }
}

Codex は次の古いブロック形式も受け付けます。

{
  "decision": "block",
  "reason": "Destructive command blocked by hook."
}

終了コード 2 を使用し、ブロック理由を stderr に書き込むこともできます。

ブロックせずにモデルに表示されるコンテキストを追加するには、hookSpecificOutput.additionalContext を返します。

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "additionalContext": "The pending command touches generated files."
  }
}

ブロックせずにサポートされているツール呼び出しを書き換えるには、 updatedInput とともに permissionDecision: "allow" を返します。

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "updatedInput": {
      "command": "echo rewritten"
    }
  }
}

Bash コマンドおよび apply_patch では、updatedInput に文字列の command フィールドを含める必要があります。MCP およびその他のローカル関数ツールでは、updatedInput が置換後の引数オブジェクトです。updatedInput は permissionDecision: "allow" とともにのみ返してください。その他の updatedInput 形式はエラーとして報告されます。

permissionDecision: "ask"、従来の decision: "approve"、continue: false、 stopReason、suppressOutput は解析されますが、まだサポートされていません。 Codex はフック実行を失敗としてマークし、エラーを報告して、ツール呼び出しを続行します。

PermissionRequest¶

PermissionRequest は、シェルの権限昇格や管理対象ネットワークの承認など、Codex が承認を求めようとする際に実行されます。リクエストを許可、拒否、または判断を保留して通常の承認プロンプトに委ねることができます。承認を必要としないコマンドでは実行されません。

matcher は tool_name とマッチャーエイリアスに適用されます。現在の正規値には Bash、apply_patch、mcp__server__tool のような MCP ツール名が含まれます。apply_patch は Edit と Write にも一致します。

共通入力フィールドに加えて、次のフィールドがあります。

フィールド	型	意味
`turn_id`	`string`	Codex 固有の拡張。アクティブな Codex ターン ID
`tool_name`	`string`	正規のフックツール名。`Bash`、`apply_patch`、または `mcp__fs__read` のような MCP 名など
`tool_input`	`JSON value`	ツール固有の入力。`Bash` と `apply_patch` は `tool_input.command` を使用し、MCP ツールはすべての引数を送信します。
`tool_input.description`	`string \\| null`	Codex が持っている場合の、人間が読める承認理由

stdout 上のプレーンテキストは無視されます。

一部のツール入力には人間が読める説明が含まれる場合がありますが、すべてのツールで tool_input.description フィールドが使えるとは限りません。

リクエストを承認するには、次を返します。

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow"
    }
  }
}

リクエストを拒否するには、次を返します。

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "deny",
      "message": "Blocked by repository policy."
    }
  }
}

一致する複数のフックが判断を返す場合、いずれかの deny が優先されます。それ以外の場合、allow により承認プロンプトを表示せずにリクエストが続行されます。一致するフックが判断しない場合、Codex は通常の承認フローを使用します。

PermissionRequest に対して updatedInput、updatedPermissions、interrupt を返さないでください。これらのフィールドは将来の動作用に予約されており、現在は安全側に倒れて失敗します。

PostToolUse¶

PostToolUse は、Bash、apply_patch、MCP ツール呼び出し、その他のローカル関数ツールなど、サポートされているツールが出力を生成した後に実行されます。Bash では、ゼロ以外のステータスで終了したコマンドの後にも実行されます。すでに実行されたツールの副作用を元に戻すことはできません。サポートされるパスと例外については、ツールの対象範囲を参照してください。

matcher は tool_name とマッチャーエイリアスに適用されます。 apply_patch を通じたファイル編集では、apply_patch、Edit、 Write を matcher の値として使用できます。フック入力では引き続き tool_name: "apply_patch" が報告されます。

共通入力フィールドに加えて、次のフィールドがあります。

フィールド	型	意味
`turn_id`	`string`	Codex 固有の拡張。アクティブな Codex ターン ID
`tool_name`	`string`	正規のフックツール名。`Bash`、`apply_patch`、または `mcp__fs__read` のような MCP 名など
`tool_use_id`	`string`	この呼び出しのツール呼び出し ID
`tool_input`	`JSON value`	ツール固有の入力。`Bash` と `apply_patch` は `tool_input.command` を使用します。MCP およびその他のローカル関数ツールは引数を送信します。
`tool_response`	`JSON value`	ツール固有の出力。MCP ツールは MCP 呼び出し結果を送信します。その他のローカル関数ツールは通常、モデル向け出力を送信します。

stdout 上のプレーンテキストは無視されます。

stdout 上の JSON では systemMessage と次のフック固有の形式を使用できます。

{
  "decision": "block",
  "reason": "The Bash output needs review before continuing.",
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "The command updated generated files."
  }
}

この additionalContext テキストは、追加の開発者コンテキストとして追加されます。

このイベントでは、decision: "block" によって完了済みの Bash コマンドが元に戻ることはありません。代わりに Codex はフィードバックを記録し、ツール結果をそのフィードバックに置き換え、フックが提供したメッセージからモデルを続行します。

終了コード 2 を使用し、フィードバック理由を stderr に書き込むこともできます。

コマンドの実行後に元のツール結果の通常処理を停止するには、continue: false を返します。 Codex はツール結果をフィードバックまたは停止テキストに置き換え、そこから続行します。

updatedMCPToolOutput と suppressOutput は解析されますが、まだサポートされていません。 Codex はフック実行を失敗としてマークし、エラーを報告して、ツール結果の通常処理を続行します。

コードモードからのツール呼び出し¶

モデルがコードモードを使用して JavaScript からツールを呼び出す場合、フックの判断はそのネストされた呼び出しに適用されます。PreToolUse はツールの実行前に停止したり、入力を書き換えたりできます。ブロックする PostToolUse はツールの副作用を元に戻せませんが、元の結果が実行中のスクリプトに到達するのを防ぐことはできます。

フック結果	コードモードから見える内容
`PreToolUse` がブロック	ツールの実行前にツールの Promise が reject されます。
`PreToolUse` が `updatedInput` を返す	ツールは書き換えられた入力で実行され、Promise はその結果で resolve します。
`PostToolUse` が `decision: "block"` を返す、またはコード `2` で終了する	ツールは実行され、その後 Promise がフック理由とともに reject されます。
`PostToolUse` が `continue: false` を返す	Codex はモデルに表示される結果にフックのフィードバックを使用しますが、ネストされたツールの Promise は reject しません。

PreCompact¶

PreCompact は Codex がチャットをコンパクションする前に実行されます。 matcher は trigger に適用され、その値は manual と auto です。

共通入力フィールドに加えて、次のフィールドがあります。

フィールド	型	意味
`turn_id`	`string`	Codex 固有の拡張。アクティブな Codex ターン ID
`trigger`	`string`	コンパクションをトリガーしたもの: `manual` または `auto`

stdout 上のプレーンテキストは無視されます。

stdout 上の JSON は共通出力フィールドをサポートします。一致する PreCompact フックが continue: false を返した場合、Codex はコンパクション前に停止します。

PostCompact¶

PostCompact は Codex がチャットをコンパクションした後に実行されます。 matcher は trigger に適用され、その値は manual と auto です。

共通入力フィールドに加えて、次のフィールドがあります。

フィールド	型	意味
`turn_id`	`string`	Codex 固有の拡張。アクティブな Codex ターン ID
`trigger`	`string`	コンパクションをトリガーしたもの: `manual` または `auto`

stdout 上のプレーンテキストは無視されます。

stdout 上の JSON は共通出力フィールドをサポートします。一致する PostCompact フックが continue: false を返した場合、Codex はコンパクション後に停止します。

UserPromptSubmit¶

matcher は現在、このイベントでは使用されていません。

共通入力フィールドに加えて、次のフィールドがあります。

フィールド	型	意味
`turn_id`	`string`	Codex 固有の拡張。アクティブな Codex ターン ID
`prompt`	`string`	送信されようとしているユーザープロンプト

stdout 上のプレーンテキストは、追加の開発者コンテキストとして追加されます。

stdout 上の JSON は共通出力フィールドと次のフック固有の形式をサポートします。

{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Ask for a clearer reproduction before editing files."
  }
}

この additionalContext テキストは、追加の開発者コンテキストとして追加されます。

プロンプトをブロックするには、次を返します。

{
  "decision": "block",
  "reason": "Ask for confirmation before doing that."
}

終了コード 2 を使用し、ブロック理由を stderr に書き込むこともできます。

SubagentStop¶

このイベントでは、matcher が agent_type に適用されます。

共通入力フィールドに加えて、次のフィールドがあります。

フィールド	型	意味
`turn_id`	`string`	Codex 固有の拡張。アクティブな Codex ターン ID
`agent_id`	`string`	サブエージェントの識別子
`agent_type`	`string`	サブエージェントの種類またはプロファイル
`agent_transcript_path`	`string \\| null`	サブエージェントのトランスクリプトファイルへのパス（存在する場合）
`stop_hook_active`	`boolean`	このサブエージェントがすでに継続されたかどうか
`last_assistant_message`	`string \\| null`	最新のサブエージェントアシスタントメッセージ（利用可能な場合）

SubagentStop は、0 で終了するとき、stdout 上の JSON を要求します。このイベントではプレーンテキスト出力は無効です。

stdout 上の JSON は共通出力フィールドをサポートします。 Codex にサブエージェントフローの継続を要求するには、次を返します。

{
  "decision": "block",
  "reason": "Run one more focused pass inside the subagent."
}

終了コード 2 を使用し、継続理由を stderr に書き込むこともできます。

一致する SubagentStop フックのいずれかが continue: false を返した場合、それは他の一致する SubagentStop フックからの継続判断より優先されます。

Stop¶

matcher は現在、このイベントでは使用されていません。

共通入力フィールドに加えて、次のフィールドがあります。

フィールド	型	意味
`turn_id`	`string`	Codex 固有の拡張。アクティブな Codex ターン ID
`stop_hook_active`	`boolean`	このターンが `Stop` によってすでに継続されたかどうか
`last_assistant_message`	`string \\| null`	最新のアシスタントメッセージテキスト（利用可能な場合）

Stop は、0 で終了するとき、stdout 上の JSON を要求します。このイベントではプレーンテキスト出力は無効です。

stdout 上の JSON は共通出力フィールドをサポートします。 Codex を続行させるには、次を返します。

{
  "decision": "block",
  "reason": "Run one more pass over the failing tests."
}

終了コード 2 を使用し、継続理由を stderr に書き込むこともできます。

このイベントでは、decision: "block" によってターンが reject されることはありません。代わりに Codex に続行を指示し、reason をプロンプトテキストとして使用して、新しいユーザープロンプトとして機能する新しい継続プロンプトを自動的に作成します。

一致する Stop フックのいずれかが continue: false を返した場合、それは他の一致する Stop フックからの継続判断より優先されます。

スキーマ¶

リンク先の main ブランチスキーマには、現在のリリースに含まれていないフックフィールドが含まれる場合があります。このページをリリース動作のリファレンスとして使用してください。

正確な現在のワイヤ形式が必要な場合は、Codex GitHub リポジトリにある生成済みスキーマを参照してください。

フック¶

Codex がフックを検索する場所¶

フックの確認と信頼¶

設定の形式¶

ターンフックを無効にする¶

requirements.toml からの管理対象フック¶

プラグインにバンドルされたフック¶

マッチャーパターン¶

ツールの対象範囲¶

共通入力フィールド¶

共通出力フィールド¶

大きなフック出力¶

フック¶

SessionStart¶

SubagentStart¶

PreToolUse¶

PermissionRequest¶

PostToolUse¶

コードモードからのツール呼び出し¶

PreCompact¶

PostCompact¶

UserPromptSubmit¶

SubagentStop¶

Stop¶

スキーマ¶

`requirements.toml` からの管理対象フック¶