フック¶

フックは 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 つ以上のフックハンドラー

{
  "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
          }
        ]
      }
    ]
  }
}

注記:

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 または別のデバイス管理システムを通じて配布したい場合に便利です。ローカルでフックを無効にしたユーザーに対しても管理対象フックを適用するには、[hooks] とともに [features].hooks = true を requirements.toml に固定します。ユーザー、プロジェクト、セッション、プラグインのフックを無視しつつ、管理者が管理するフックを許可するには、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`	ツール名	サポート対象には `Bash`、`apply_patch`*、MCP ツール名が含まれます
`PostCompact`	コンパクションのトリガー	値は `manual` または `auto` です
`PreCompact`	コンパクションのトリガー	値は `manual` または `auto` です
`PreToolUse`	ツール名	サポート対象には `Bash`、`apply_patch`*、MCP ツール名が含まれます
`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

共通入力フィールド¶

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

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

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

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

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 は解析されますが、現在このイベントではサポートされていません。

フック¶

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 ツール呼び出しをインターセプトできます。ただし、Codex は別のサポートされているツール経路を通じて同等の処理を実行できることが多いため、完全な適用境界ではなく、ガードレールとして機能します。

これは現在、すべてのシェル呼び出しをインターセプトするわけではなく、単純なものだけを対象とします。新しい unified_exec メカニズムでは、シェルの stdin／stdout をより柔軟にストリーミング処理できますが、インターセプトは不完全です。同様に、WebSearch や、シェルでも MCP でもないその他のツール呼び出しもインターセプトしません。

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

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

フィールド	型	意味
`turn_id`	`string`	Codex 固有の拡張。アクティブな Codex ターン ID
`tool_name`	`string`	正規のフックツール名。`Bash`、`apply_patch`、MCP 名（`mcp__fs__read` など）
`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 名（`mcp__fs__read` など）
`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 では、ゼロ以外のステータスで終了したコマンドの後にも実行されます。すでに実行されたツールの副作用を元に戻すことはできません。

これは現在、すべてのシェル呼び出しをインターセプトするわけではなく、単純なものだけを対象とします。新しい unified_exec メカニズムでは、シェルの stdin／stdout をより柔軟にストリーミング処理できますが、インターセプトは不完全です。同様に、WebSearch や、シェルでも MCP でもないその他のツール呼び出しもインターセプトしません。

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

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

フィールド	型	意味
`turn_id`	`string`	Codex 固有の拡張。アクティブな Codex ターン ID
`tool_name`	`string`	正規のフックツール名。`Bash`、`apply_patch`、MCP 名（`mcp__fs__read` など）
`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 はフック実行を失敗としてマークし、エラーを報告して、ツール結果の通常処理を続行します。

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" はターンを拒否しません。その代わり、Codex に続行を指示し、reason をプロンプトテキストとして使用して、新しいユーザープロンプトとして機能する新しい継続プロンプトを自動的に作成します。

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

スキーマ¶

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

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

フック¶

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

フックの確認と信頼¶

設定の構造¶

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

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

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

マッチャーパターン¶

共通入力フィールド¶

共通出力フィールド¶

フック¶

SessionStart¶

SubagentStart¶

PreToolUse¶

PermissionRequest¶

PostToolUse¶

PreCompact¶

PostCompact¶

UserPromptSubmit¶

SubagentStop¶

Stop¶

スキーマ¶

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