OpenAI - Codex Docs Changes 2026-04-24 18:20 UTC → 2026-04-25 00:42 UTC

90 90 

91## Hooks (experimental)91## Hooks (experimental)

92 92 

93Codex can also load lifecycle hooks from `hooks.json` files that sit next to93Codex can also load lifecycle hooks from either `hooks.json` files or inline

94active config layers.94`[hooks]` tables in `config.toml` files that sit next to active config layers.

95 95 

96In practice, the two most useful locations are:96In practice, the two most useful locations are:

97 97 

98- `~/.codex/hooks.json`98- `~/.codex/hooks.json`

99- `~/.codex/config.toml`

99- `<repo>/.codex/hooks.json`100- `<repo>/.codex/hooks.json`

101- `<repo>/.codex/config.toml`

100 102 

101Project-local hooks load only when the project `.codex/` layer is trusted.103Project-local hooks load only when the project `.codex/` layer is trusted.

102User-level hooks remain independent of project trust.104User-level hooks remain independent of project trust.

108codex_hooks = true110codex_hooks = true

109```111```

110 112 

113Inline TOML hooks use the same event structure as `hooks.json`:

114 

115```toml

116[[hooks.PreToolUse]]

117matcher = "^Bash$"

118 

119[[hooks.PreToolUse.hooks]]

120type = "command"

121command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'

122timeout = 30

123statusMessage = "Checking Bash command"

124```

125 

126If a single layer contains both `hooks.json` and inline `[hooks]`, Codex loads

127both and warns. Prefer one representation per layer.

128 

111For the current event list, input fields, output behavior, and limitations, see129For the current event list, input fields, output behavior, and limitations, see

112[Hooks](https://developers.openai.com/codex/hooks).130[Hooks](https://developers.openai.com/codex/hooks).

113 131 

148| Key | Default | Maturity | Description |148| Key | Default | Maturity | Description |

149| -------------------- | :-------------------: | ------------ | ---------------------------------------------------------------------------------------- |149| -------------------- | :-------------------: | ------------ | ---------------------------------------------------------------------------------------- |

150| `apps` | false | Experimental | Enable ChatGPT Apps/connectors support |150| `apps` | false | Experimental | Enable ChatGPT Apps/connectors support |

151| `codex_hooks` | false | Under development | Enable lifecycle hooks from `hooks.json`. See [Hooks](https://developers.openai.com/codex/hooks). |151| `codex_hooks` | true | Stable | Enable lifecycle hooks from `hooks.json` or inline `[hooks]`. See [Hooks](https://developers.openai.com/codex/hooks). |

152| `fast_mode` | true | Stable | Enable Fast mode selection and the `service_tier = "fast"` path |152| `fast_mode` | true | Stable | Enable Fast mode selection and the `service_tier = "fast"` path |

153| `memories` | false | Stable | Enable [Memories](https://developers.openai.com/codex/memories) |153| `memories` | false | Stable | Enable [Memories](https://developers.openai.com/codex/memories) |

154| `multi_agent` | true | Stable | Enable subagent collaboration tools |154| `multi_agent` | true | Stable | Enable subagent collaboration tools |

48| `experimental_compact_prompt_file` | `string (path)` | Load the compaction prompt override from a file (experimental). |48| `experimental_compact_prompt_file` | `string (path)` | Load the compaction prompt override from a file (experimental). |

49| `experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`. |49| `experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`. |

50| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |50| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |

51| `features.codex_hooks` | `boolean` | Enable lifecycle hooks loaded from `hooks.json` (under development; off by default). |51| `features.codex_hooks` | `boolean` | Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config. |

52| `features.enable_request_compression` | `boolean` | Compress streaming request bodies with zstd when supported (stable; on by default). |52| `features.enable_request_compression` | `boolean` | Compress streaming request bodies with zstd when supported (stable; on by default). |

53| `features.fast_mode` | `boolean` | Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default). |53| `features.fast_mode` | `boolean` | Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default). |

54| `features.memories` | `boolean` | Enable [Memories](https://developers.openai.com/codex/memories) (off by default). |54| `features.memories` | `boolean` | Enable [Memories](https://developers.openai.com/codex/memories) (off by default). |

70| `hide_agent_reasoning` | `boolean` | Suppress reasoning events in both the TUI and `codex exec` output. |70| `hide_agent_reasoning` | `boolean` | Suppress reasoning events in both the TUI and `codex exec` output. |

71| `history.max_bytes` | `number` | If set, caps the history file size in bytes by dropping oldest entries. |71| `history.max_bytes` | `number` | If set, caps the history file size in bytes by dropping oldest entries. |

72| `history.persistence` | `save-all | none` | Control whether Codex saves session transcripts to history.jsonl. |72| `history.persistence` | `save-all | none` | Control whether Codex saves session transcripts to history.jsonl. |

73| `hooks` | `table` | Lifecycle hooks configured inline in `config.toml`. Uses the same event schema as `hooks.json`; see the Hooks guide for examples and supported events. |

73| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |74| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |

74| `log_dir` | `string (path)` | Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`. |75| `log_dir` | `string (path)` | Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`. |

75| `mcp_oauth_callback_port` | `integer` | Optional fixed port for the local HTTP callback server used during MCP OAuth login. When unset, Codex binds to an ephemeral port chosen by the OS. |76| `mcp_oauth_callback_port` | `integer` | Optional fixed port for the local HTTP callback server used during MCP OAuth login. When unset, Codex binds to an ephemeral port chosen by the OS. |

701 702 

702Details703Details

703 704 

704Enable lifecycle hooks loaded from `hooks.json` (under development; off by default).705Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config.

705 706 

706Key707Key

707 708 

957 958 

958Key959Key

959 960 

961`hooks`

962 

963Type / Values

964 

965`table`

966 

967Details

968 

969Lifecycle hooks configured inline in `config.toml`. Uses the same event schema as `hooks.json`; see the Hooks guide for examples and supported events.

970 

971Key

972 

960`instructions`973`instructions`

961 974 

962Type / Values975Type / Values

2951| `allowed_approvals_reviewers` | `array<string>` | Allowed values for `approvals_reviewer`, such as `user` and `auto_review`. |2964| `allowed_approvals_reviewers` | `array<string>` | Allowed values for `approvals_reviewer`, such as `user` and `auto_review`. |

2952| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |2965| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |

2953| `allowed_web_search_modes` | `array<string>` | Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`. |2966| `allowed_web_search_modes` | `array<string>` | Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`. |

2967| `feature_requirements` | `table` | Alias for `features` in `requirements.toml`. Use it to pin feature values by canonical feature key. |

2968| `feature_requirements.browser_use` | `boolean` | Set to `false` in `requirements.toml` to disable Browser Use and Browser Agent availability. You can also set `features.browser_use`. |

2969| `feature_requirements.computer_use` | `boolean` | Set to `false` in `requirements.toml` to disable Computer Use availability and related install or enablement flows. You can also set `features.computer_use`. |

2970| `feature_requirements.in_app_browser` | `boolean` | Set to `false` in `requirements.toml` to disable the in-app browser pane. You can also set `features.in_app_browser`. |

2954| `features` | `table` | Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table. |2971| `features` | `table` | Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table. |

2955| `features.<name>` | `boolean` | Require a specific canonical feature key to stay enabled or disabled. |2972| `features.<name>` | `boolean` | Require a specific canonical feature key to stay enabled or disabled. |

2956| `guardian_policy_config` | `string` | Managed Markdown policy instructions for automatic review. This takes precedence over local `[auto_review].policy`. Blank values are ignored. |2973| `guardian_policy_config` | `string` | Managed Markdown policy instructions for automatic review. This takes precedence over local `[auto_review].policy`. Blank values are ignored. |

2974| `hooks` | `table` | Admin-enforced managed lifecycle hooks. Requires a managed hook directory and uses the same event schema as inline `[hooks]` in `config.toml`. |

2975| `hooks.<Event>` | `array<table>` | Matcher groups for a hook event such as `PreToolUse`, `PostToolUse`, `PermissionRequest`, `SessionStart`, `UserPromptSubmit`, or `Stop`. |

2976| `hooks.<Event>[].hooks` | `array<table>` | Hook handlers for a matcher group. Command hooks are currently supported; prompt and agent hook handlers are parsed but skipped. |

2977| `hooks.managed_dir` | `string (absolute path)` | Directory containing managed hook scripts on macOS and Linux. Codex validates that it is absolute and exists before loading managed hooks. |

2978| `hooks.windows_managed_dir` | `string (absolute path)` | Directory containing managed hook scripts on Windows. Codex validates that it is absolute and exists before loading managed hooks. |

2957| `mcp_servers` | `table` | Allowlist of MCP servers that may be enabled. Both the server name (`<id>`) and its identity must match for the MCP server to be enabled. Any configured MCP server not in the allowlist (or with a mismatched identity) is disabled. |2979| `mcp_servers` | `table` | Allowlist of MCP servers that may be enabled. Both the server name (`<id>`) and its identity must match for the MCP server to be enabled. Any configured MCP server not in the allowlist (or with a mismatched identity) is disabled. |

2958| `mcp_servers.<id>.identity` | `table` | Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP). |2980| `mcp_servers.<id>.identity` | `table` | Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP). |

2959| `mcp_servers.<id>.identity.command` | `string` | Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command. |2981| `mcp_servers.<id>.identity.command` | `string` | Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command. |

2960| `mcp_servers.<id>.identity.url` | `string` | Allow an MCP streamable HTTP server when its `mcp_servers.<id>.url` matches this URL. |2982| `mcp_servers.<id>.identity.url` | `string` | Allow an MCP streamable HTTP server when its `mcp_servers.<id>.url` matches this URL. |

2961| `permissions.filesystem.deny_read` | `array<string>` | Admin-enforced filesystem read denials. Entries can be paths or glob patterns, and users cannot weaken them with local config. |2983| `permissions.filesystem.deny_read` | `array<string>` | Admin-enforced filesystem read denials. Entries can be paths or glob patterns, and users cannot weaken them with local config. |

2984| `remote_sandbox_config` | `array<table>` | Host-specific sandbox requirements. The first entry whose `hostname_patterns` match the resolved host name overrides top-level `allowed_sandbox_modes` for that requirements source. Host-specific entries currently override sandbox modes only. |

2985| `remote_sandbox_config[].allowed_sandbox_modes` | `array<string>` | Allowed sandbox modes to apply when this host-specific entry matches. |

2986| `remote_sandbox_config[].hostname_patterns` | `array<string>` | Case-insensitive host name patterns. Supports `*` for any sequence of characters and `?` for one character. |

2962| `rules` | `table` | Admin-enforced command rules merged with `.rules` files. Requirements rules must be restrictive. |2987| `rules` | `table` | Admin-enforced command rules merged with `.rules` files. Requirements rules must be restrictive. |

2963| `rules.prefix_rules` | `array<table>` | List of enforced prefix rules. Each rule must include `pattern` and `decision`. |2988| `rules.prefix_rules` | `array<table>` | List of enforced prefix rules. Each rule must include `pattern` and `decision`. |

2964| `rules.prefix_rules[].decision` | `prompt | forbidden` | Required. Requirements rules can only prompt or forbid (not allow). |2989| `rules.prefix_rules[].decision` | `prompt | forbidden` | Required. Requirements rules can only prompt or forbid (not allow). |

3017 3042 

3018Key3043Key

3019 3044 

3045`feature_requirements`

3046 

3047Type / Values

3048 

3049`table`

3050 

3051Details

3052 

3053Alias for `features` in `requirements.toml`. Use it to pin feature values by canonical feature key.

3054 

3055Key

3056 

3057`feature_requirements.browser_use`

3058 

3059Type / Values

3060 

3061`boolean`

3062 

3063Details

3064 

3065Set to `false` in `requirements.toml` to disable Browser Use and Browser Agent availability. You can also set `features.browser_use`.

3066 

3067Key

3068 

3069`feature_requirements.computer_use`

3070 

3071Type / Values

3072 

3073`boolean`

3074 

3075Details

3076 

3077Set to `false` in `requirements.toml` to disable Computer Use availability and related install or enablement flows. You can also set `features.computer_use`.

3078 

3079Key

3080 

3081`feature_requirements.in_app_browser`

3082 

3083Type / Values

3084 

3085`boolean`

3086 

3087Details

3088 

3089Set to `false` in `requirements.toml` to disable the in-app browser pane. You can also set `features.in_app_browser`.

3090 

3091Key

3092 

3020`features`3093`features`

3021 3094 

3022Type / Values3095Type / Values

3053 3126 

3054Key3127Key

3055 3128 

3129`hooks`

3130 

3131Type / Values

3132 

3133`table`

3134 

3135Details

3136 

3137Admin-enforced managed lifecycle hooks. Requires a managed hook directory and uses the same event schema as inline `[hooks]` in `config.toml`.

3138 

3139Key

3140 

3141`hooks.<Event>`

3142 

3143Type / Values

3144 

3145`array<table>`

3146 

3147Details

3148 

3149Matcher groups for a hook event such as `PreToolUse`, `PostToolUse`, `PermissionRequest`, `SessionStart`, `UserPromptSubmit`, or `Stop`.

3150 

3151Key

3152 

3153`hooks.<Event>[].hooks`

3154 

3155Type / Values

3156 

3157`array<table>`

3158 

3159Details

3160 

3161Hook handlers for a matcher group. Command hooks are currently supported; prompt and agent hook handlers are parsed but skipped.

3162 

3163Key

3164 

3165`hooks.managed_dir`

3166 

3167Type / Values

3168 

3169`string (absolute path)`

3170 

3171Details

3172 

3173Directory containing managed hook scripts on macOS and Linux. Codex validates that it is absolute and exists before loading managed hooks.

3174 

3175Key

3176 

3177`hooks.windows_managed_dir`

3178 

3179Type / Values

3180 

3181`string (absolute path)`

3182 

3183Details

3184 

3185Directory containing managed hook scripts on Windows. Codex validates that it is absolute and exists before loading managed hooks.

3186 

3187Key

3188 

3056`mcp_servers`3189`mcp_servers`

3057 3190 

3058Type / Values3191Type / Values

3113 3246 

3114Key3247Key

3115 3248 

3249`remote_sandbox_config`

3250 

3251Type / Values

3252 

3253`array<table>`

3254 

3255Details

3256 

3257Host-specific sandbox requirements. The first entry whose `hostname_patterns` match the resolved host name overrides top-level `allowed_sandbox_modes` for that requirements source. Host-specific entries currently override sandbox modes only.

3258 

3259Key

3260 

3261`remote_sandbox_config[].allowed_sandbox_modes`

3262 

3263Type / Values

3264 

3265`array<string>`

3266 

3267Details

3268 

3269Allowed sandbox modes to apply when this host-specific entry matches.

3270 

3271Key

3272 

3273`remote_sandbox_config[].hostname_patterns`

3274 

3275Type / Values

3276 

3277`array<string>`

3278 

3279Details

3280 

3281Case-insensitive host name patterns. Supports `*` for any sequence of characters and `?` for one character.

3282 

3283Key

3284 

3116`rules`3285`rules`

3117 3286 

3118Type / Values3287Type / Values

407# use_memories = true407# use_memories = true

408# disable_on_external_context = false # legacy alias: no_memories_if_mcp_or_web_search408# disable_on_external_context = false # legacy alias: no_memories_if_mcp_or_web_search

409 409 

410################################################################################

411# Lifecycle hooks can be configured here inline or in a sibling hooks.json.

412################################################################################

413 

414# [hooks]

415# [[hooks.PreToolUse]]

416# matcher = "^Bash$"

417#

418# [[hooks.PreToolUse.hooks]]

419# type = "command"

420# command = 'python3 "/absolute/path/to/pre_tool_use_policy.py"'

421# timeout = 30

422# statusMessage = "Checking Bash command"

423 

410################################################################################424################################################################################

411# Define MCP servers under this table. Leave empty to disable.425# Define MCP servers under this table. Leave empty to disable.

412################################################################################426################################################################################

139 139 

140Codex Admins can deploy admin-enforced `requirements.toml` policies from the Codex [Policies page](https://chatgpt.com/codex/settings/policies).140Codex Admins can deploy admin-enforced `requirements.toml` policies from the Codex [Policies page](https://chatgpt.com/codex/settings/policies).

141 141 

142Use this page when you want to apply different local Codex constraints to different groups without distributing device-level files first. The managed policy uses the same `requirements.toml` format described in [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration), so you can define allowed approval policies, sandbox modes, web search behavior, MCP server allowlists, feature pins, and restrictive command rules.142Use this page when you want to apply different local Codex constraints to different groups without distributing device-level files first. The managed policy uses the same `requirements.toml` format described in [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration), so you can define allowed approval policies, sandbox modes, web search behavior, MCP server allowlists, feature pins, and restrictive command rules. To disable Browser Use, the in-app browser, or Computer Use, see [Disable Codex feature surfaces](https://developers.openai.com/codex/enterprise/managed-configuration#disable-codex-feature-surfaces).

143 143 

144![Codex policies and configurations page](/images/codex/enterprise/policies_and_configurations_page.png)144![Codex policies and configurations page](/images/codex/enterprise/policies_and_configurations_page.png)

145 145 

7 7 

8## Admin-enforced requirements (requirements.toml)8## Admin-enforced requirements (requirements.toml)

9 9 

10Requirements constrain security-sensitive settings (approval policy, approvals reviewer, automatic review policy, sandbox mode, web search mode, and optionally which MCP servers users can enable). When resolving configuration (for example from `config.toml`, profiles, or CLI config overrides), if a value conflicts with an enforced rule, Codex falls back to a compatible value and notifies the user. If you configure an `mcp_servers` allowlist, Codex enables an MCP server only when both its name and identity match an approved entry; otherwise, Codex disables it.10Requirements constrain security-sensitive settings (approval policy, approvals reviewer, automatic review policy, sandbox mode, web search mode, managed hooks, and optionally which MCP servers users can enable). When resolving configuration (for example from `config.toml`, profiles, or CLI config overrides), if a value conflicts with an enforced rule, Codex falls back to a compatible value and notifies the user. If you configure an `mcp_servers` allowlist, Codex enables an MCP server only when both its name and identity match an approved entry; otherwise, Codex disables it.

11 11 

12Requirements can also constrain [feature flags](https://developers.openai.com/codex/config-basic/#feature-flags) via the `[features]` table in `requirements.toml`. Note that features aren't always security-sensitive, but enterprises can pin values if desired. Omitted keys remain unconstrained.12Requirements can also constrain [feature flags](https://developers.openai.com/codex/config-basic/#feature-flags) via the `[features]` table in `requirements.toml`. Note that features aren't always security-sensitive, but enterprises can pin values if desired. Omitted keys remain unconstrained.

13 13 

72allowed_sandbox_modes = ["read-only", "workspace-write"]72allowed_sandbox_modes = ["read-only", "workspace-write"]

73```73```

74 74 

75### Override sandbox requirements by host

76 

77Use `[[remote_sandbox_config]]` when one managed policy should apply different

78sandbox requirements on different hosts. For example, you can keep a stricter

79default for laptops while allowing workspace writes on matching devboxes or CI

80runners. Host-specific entries currently override `allowed_sandbox_modes` only:

81 

82```toml

83allowed_sandbox_modes = ["read-only"]

84 

85[[remote_sandbox_config]]

86hostname_patterns = ["*.devbox.example.com", "runner-??.ci.example.com"]

87allowed_sandbox_modes = ["read-only", "workspace-write"]

88```

89 

90Codex compares each `hostname_patterns` entry against the best-effort resolved

91host name. It prefers the fully qualified domain name when available and falls

92back to the local host name. Matching is case-insensitive; `*` matches any

93sequence of characters, and `?` matches one character.

94 

95The first matching `[[remote_sandbox_config]]` entry wins within the same

96requirements source. If no entry matches, Codex keeps the top-level

97`allowed_sandbox_modes`. Hostname matching is for policy selection only; don't

98treat it as authenticated device proof.

99 

75You can also constrain web search mode:100You can also constrain web search mode:

76 101 

77```toml102```toml

91 116 

92Use the canonical feature keys from `config.toml`'s `[features]` table. Codex normalizes the resulting feature set to meet these pins and rejects conflicting writes to `config.toml` or profile-scoped feature settings.117Use the canonical feature keys from `config.toml`'s `[features]` table. Codex normalizes the resulting feature set to meet these pins and rejects conflicting writes to `config.toml` or profile-scoped feature settings.

93 118 

119### Disable Codex feature surfaces

120 

121Admins can use `[feature_requirements]` to disable specific Codex feature

122surfaces for users receiving a managed `requirements.toml`. You can also set

123the same keys in the existing `[features]` table.

124 

125```

126[feature_requirements]

127browser_use = false

128in_app_browser = false

129computer_use = false

130```

131 

132- `in_app_browser = false` disables the in-app browser pane.

133- `browser_use = false` disables Browser Use and Browser Agent availability.

134- `computer_use = false` disables Computer Use availability and related

135 install or enablement flows.

136 

137If omitted, these features are allowed by policy, subject to normal client,

138platform, and rollout availability.

139 

94### Configure automatic review policy140### Configure automatic review policy

95 141 

96Use `allowed_approvals_reviewers` to require or allow automatic review. Set it142Use `allowed_approvals_reviewers` to require or allow automatic review. Set it

137Windows, managed `deny_read` applies to direct file tools; shell subprocess183Windows, managed `deny_read` applies to direct file tools; shell subprocess

138reads don't use this sandbox rule.184reads don't use this sandbox rule.

139 185 

186### Enforce managed hooks from requirements

187 

188Admins can also define managed lifecycle hooks directly in `requirements.toml`.

189Use `[hooks]` for the hook configuration itself, and point `managed_dir` at the

190directory where your MDM or endpoint-management tooling installs the referenced

191scripts.

192 

193```toml

194[features]

195codex_hooks = true

196 

197[hooks]

198managed_dir = "/enterprise/hooks"

199windows_managed_dir = 'C:\enterprise\hooks'

200 

201[[hooks.PreToolUse]]

202matcher = "^Bash$"

203 

204[[hooks.PreToolUse.hooks]]

205type = "command"

206command = "python3 /enterprise/hooks/pre_tool_use_policy.py"

207timeout = 30

208statusMessage = "Checking managed Bash command"

209```

210 

211Notes:

212 

213- Codex enforces the hook configuration from `requirements.toml`, but it does

214 not distribute the scripts in `managed_dir`.

215- Deliver those scripts separately with your MDM or device-management solution.

216- Managed hook commands should reference absolute script paths under the

217 configured managed directory.

218 

140### Enforce command rules from requirements219### Enforce command rules from requirements

141 220 

142Admins can also enforce restrictive command rules from `requirements.toml`221Admins can also enforce restrictive command rules from `requirements.toml`

1# Hooks1# Hooks

2 2 

3Experimental. Hooks are under active development. Windows support temporarily

4disabled.

5 

6Hooks are an extensibility framework for Codex. They allow3Hooks are an extensibility framework for Codex. They allow

7you to inject your own scripts into the agentic loop, enabling features such as:4you to inject your own scripts into the agentic loop, enabling features such as:

8 5 

23 20 

24- Matching hooks from multiple files all run.21- Matching hooks from multiple files all run.

25- Multiple matching command hooks for the same event are launched concurrently,22- Multiple matching command hooks for the same event are launched concurrently,

26 so one hook can’t prevent another matching hook from starting.23 so one hook cannot prevent another matching hook from starting.

27- `PreToolUse`, `PermissionRequest`, `PostToolUse`, `UserPromptSubmit`, and24- `PreToolUse`, `PermissionRequest`, `PostToolUse`, `UserPromptSubmit`, and

28 `Stop` run at turn scope.25 `Stop` run at turn scope.

29- Hooks are currently disabled on Windows.

30 26 

31## Where Codex looks for hooks27## Where Codex looks for hooks

32 28 

33Codex discovers `hooks.json` next to active config layers.29Codex discovers hooks next to active config layers in either of these forms:

30 

31- `hooks.json`

32- inline `[hooks]` tables inside `config.toml`

34 33 

35In practice, the two most useful locations are:34In practice, the four most useful locations are:

36 35 

37- `~/.codex/hooks.json`36- `~/.codex/hooks.json`

37- `~/.codex/config.toml`

38- `<repo>/.codex/hooks.json`38- `<repo>/.codex/hooks.json`

39- `<repo>/.codex/config.toml`

39 40 

40If more than one `hooks.json` file exists, Codex loads all matching hooks.41If more than one hook source exists, Codex loads all matching hooks.

41Higher-precedence config layers don’t replace lower-precedence hooks.42Higher-precedence config layers do not replace lower-precedence hooks.

43If a single layer contains both `hooks.json` and inline `[hooks]`, Codex

44merges them and warns at startup. Prefer one representation per layer.

42 45 

43Project-local hooks load only when the project `.codex/` layer is trusted. In46Project-local hooks load only when the project `.codex/` layer is trusted. In

44untrusted projects, Codex still loads user and system hooks from their own47untrusted projects, Codex still loads user and system hooks from their own

131Notes:134Notes:

132 135 

133- `timeout` is in seconds.136- `timeout` is in seconds.

134- `timeoutSec` is also accepted as an alias.

135- If `timeout` is omitted, Codex uses `600` seconds.137- If `timeout` is omitted, Codex uses `600` seconds.

136- `statusMessage` is optional.138- `statusMessage` is optional.

137- Commands run with the session `cwd` as their working directory.139- Commands run with the session `cwd` as their working directory.

139 relative path such as `.codex/hooks/...`. Codex may be started from a141 relative path such as `.codex/hooks/...`. Codex may be started from a

140 subdirectory, and a git-root-based path keeps the hook location stable.142 subdirectory, and a git-root-based path keeps the hook location stable.

141 143 

144Equivalent inline TOML in `config.toml`:

145 

146```toml

147[features]

148codex_hooks = true

149 

150[[hooks.PreToolUse]]

151matcher = "^Bash$"

152 

153[[hooks.PreToolUse.hooks]]

154type = "command"

155command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'

156timeout = 30

157statusMessage = "Checking Bash command"

158 

159[[hooks.PostToolUse]]

160matcher = "^Bash$"

161 

162[[hooks.PostToolUse.hooks]]

163type = "command"

164command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/post_tool_use_review.py"'

165timeout = 30

166statusMessage = "Reviewing Bash output"

167```

168 

169## Managed hooks from `requirements.toml`

170 

171Enterprise-managed requirements can also define hooks inline under `[hooks]`.

172This is useful when admins want to enforce the hook configuration while

173delivering the actual scripts through MDM or another device-management system.

174 

175```toml

176[features]

177codex_hooks = true

178 

179[hooks]

180managed_dir = "/enterprise/hooks"

181windows_managed_dir = 'C:\enterprise\hooks'

182 

183[[hooks.PreToolUse]]

184matcher = "^Bash$"

185 

186[[hooks.PreToolUse.hooks]]

187type = "command"

188command = "python3 /enterprise/hooks/pre_tool_use_policy.py"

189timeout = 30

190statusMessage = "Checking managed Bash command"

191```

192 

193Notes for managed hooks:

194 

195- `managed_dir` is used on macOS and Linux.

196- `windows_managed_dir` is used on Windows.

197- Codex does not distribute the scripts in `managed_dir`; your enterprise

198 tooling must install and update them separately.

199- Managed hook commands should use absolute script paths under the configured

200 managed directory.

201 

142## Matcher patterns202## Matcher patterns

143 203 

144The `matcher` field is a regex string that filters when hooks fire. Use `"*"`,204The `matcher` field is a regex string that filters when hooks fire. Use `"*"`,

149 209 

150| Event | What `matcher` filters | Notes |210| Event | What `matcher` filters | Notes |

151| --- | --- | --- |211| --- | --- | --- |

152| `PermissionRequest` | tool name | Current Codex runtime only emits `Bash`. |212| `PermissionRequest` | tool name | Support includes `Bash`, `apply_patch`\*, and MCP tool names |

153| `PostToolUse` | tool name | Current Codex runtime only emits `Bash`. |213| `PostToolUse` | tool name | Support includes `Bash`, `apply_patch`\*, and MCP tool names |

154| `PreToolUse` | tool name | Current Codex runtime only emits `Bash`. |214| `PreToolUse` | tool name | Support includes `Bash`, `apply_patch`\*, and MCP tool names |

155| `SessionStart` | start source | Current runtime values are `startup` and `resume`. |215| `SessionStart` | start source | Current runtime values are `startup`, `resume`, and `clear` |

156| `UserPromptSubmit` | not supported | Any configured `matcher` is ignored for this event. |216| `UserPromptSubmit` | not supported | Any configured `matcher` is ignored for this event |

157| `Stop` | not supported | Any configured `matcher` is ignored for this event. |217| `Stop` | not supported | Any configured `matcher` is ignored for this event |

218 

219\*For `apply_patch`, matchers can also use `Edit` or `Write`.

158 220 

159Examples:221Examples:

160 222 

161- `Bash`223- `Bash`

162- `startup|resume`224- `^apply_patch$`

163- `Edit|Write`225- `Edit|Write`

164 226- `mcp__filesystem__read_file`

165That last example is still a valid regex, but current Codex `PreToolUse` and227- `mcp__filesystem__.*`

166`PostToolUse` events only emit `Bash`, so it won’t match anything today.228- `startup|resume|clear`

167 229 

168## Common input fields230## Common input fields

169 231 

242 304 

243### PreToolUse305### PreToolUse

244 306 

245Work in progress307`PreToolUse` can intercept Bash, file edits performed through `apply_patch`,

246 308and MCP tool calls. It is still a guardrail rather than a complete enforcement

247Currently `PreToolUse` only supports Bash tool interception. The model can309boundary because Codex can often perform equivalent work through another

248still work around this by writing its own script to disk and then running that310supported tool path.

249script with Bash, so treat this as a useful guardrail rather than a complete

250enforcement boundary

251 311 

252This doesn't intercept all shell calls yet, only the simple ones. The newer312This doesn't intercept all shell calls yet, only the simple ones. The newer

253 `unified_exec` mechanism allows richer streaming stdin/stdout handling of313 `unified_exec` mechanism allows richer streaming stdin/stdout handling of

254shell, but interception is incomplete. Similarly, this doesn’t intercept MCP,314 shell, but interception is incomplete. Similarly, this doesn't intercept

255Write, WebSearch, or other non-shell tool calls.315 `WebSearch` or other non-shell, non-MCP tool calls.

256 316 

257`matcher` is applied to `tool_name`, which currently always equals `Bash`.317`matcher` is applied to `tool_name` and matcher aliases. For file edits through

318`apply_patch`, matchers can use `apply_patch`, `Edit`, or `Write`; hook input

319still reports `tool_name: "apply_patch"`.

258 320 

259Fields in addition to [Common input fields](#common-input-fields):321Fields in addition to [Common input fields](#common-input-fields):

260 322 

261| Field | Type | Meaning |323| Field | Type | Meaning |

262| --- | --- | --- |324| --- | --- | --- |

263| `turn_id` | `string` | Codex-specific extension. Active Codex turn id |325| `turn_id` | `string` | Codex-specific extension. Active Codex turn id |

264| `tool_name` | `string` | Currently always `Bash` |326| `tool_name` | `string` | Canonical hook tool name, such as `Bash`, `apply_patch`, or an MCP name like `mcp__fs__read` |

265| `tool_use_id` | `string` | Tool-call id for this invocation |327| `tool_use_id` | `string` | Tool-call id for this invocation |

266| `tool_input.command` | `string` | Shell command Codex is about to run |328| `tool_input` | `JSON value` | Tool-specific input. `Bash` and `apply_patch` use `tool_input.command` while MCP tools send all the args. |

267 329 

268Plain text on `stdout` is ignored.330Plain text on `stdout` is ignored.

269 331 

297 359 

298### PermissionRequest360### PermissionRequest

299 361 

300Work in progress

301 

302`PermissionRequest` runs when Codex is about to ask for approval, such as a362`PermissionRequest` runs when Codex is about to ask for approval, such as a

303shell escalation or managed-network approval. It can allow the request, deny363shell escalation or managed-network approval. It can allow the request, deny

304the request, or decline to decide and let the normal approval prompt continue.364the request, or decline to decide and let the normal approval prompt continue.

305It doesn't run for commands that don't need approval.365It doesn't run for commands that don't need approval.

306 366 

307`matcher` is applied to `tool_name`, which currently always equals `Bash`.367`matcher` is applied to `tool_name` and matcher aliases. Current canonical

368values include `Bash`, `apply_patch`, and MCP tool names such as

369`mcp__server__tool`; `apply_patch` also matches `Edit` and `Write`.

308 370 

309Fields in addition to [Common input fields](#common-input-fields):371Fields in addition to [Common input fields](#common-input-fields):

310 372 

311| Field | Type | Meaning |373| Field | Type | Meaning |

312| --- | --- | --- |374| --- | --- | --- |

313| `turn_id` | `string` | Codex-specific extension. Active Codex turn id |375| `turn_id` | `string` | Codex-specific extension. Active Codex turn id |

314| `tool_name` | `string` | Currently always `Bash` |376| `tool_name` | `string` | Canonical hook tool name, such as `Bash`, `apply_patch`, or an MCP name like `mcp__fs__read` |

315| `tool_input.command` | `string` | Shell command associated with the approval request |377| `tool_input` | `JSON value` | Tool-specific input. `Bash` and `apply_patch` use `tool_input.command` while MCP tools send all the args. |

316| `tool_input.description` | `string | null` | Human-readable approval reason, when Codex has one |378| `tool_input.description` | `string | null` | Human-readable approval reason, when Codex has one |

317 379 

318Plain text on `stdout` is ignored.380Plain text on `stdout` is ignored.

354 416 

355### PostToolUse417### PostToolUse

356 418 

357Work in progress419`PostToolUse` runs after supported tools produce output, including Bash,

358 420`apply_patch`, and MCP tool calls. For Bash, it also runs after commands that

359Currently `PostToolUse` only supports Bash tool results. It’s not limited to421exit with a non-zero status. It can't undo side effects from the tool that

360commands that exit successfully: non-interactive `exec_command` calls can still422already ran.

361trigger `PostToolUse` when Codex emits a Bash post-tool payload. It can’t undo

362side effects from the command that already ran.

363 423 

364This doesn't intercept all shell calls yet, only the simple ones. The newer424This doesn't intercept all shell calls yet, only the simple ones. The newer

365 `unified_exec` mechanism allows richer streaming stdin/stdout handling of425 `unified_exec` mechanism allows richer streaming stdin/stdout handling of

366shell, but interception is incomplete. Similarly, this doesn’t intercept MCP,426 shell, but interception is incomplete. Similarly, this doesn't intercept

367Write, WebSearch, or other non-shell tool calls.427 `WebSearch` or other non-shell, non-MCP tool calls.

368 428 

369`matcher` is applied to `tool_name`, which currently always equals `Bash`.429`matcher` is applied to `tool_name` and matcher aliases. For file edits through

430`apply_patch`, matchers can use `apply_patch`, `Edit`, or `Write`; hook input

431still reports `tool_name: "apply_patch"`.

370 432 

371Fields in addition to [Common input fields](#common-input-fields):433Fields in addition to [Common input fields](#common-input-fields):

372 434 

373| Field | Type | Meaning |435| Field | Type | Meaning |

374| --- | --- | --- |436| --- | --- | --- |

375| `turn_id` | `string` | Codex-specific extension. Active Codex turn id |437| `turn_id` | `string` | Codex-specific extension. Active Codex turn id |

376| `tool_name` | `string` | Currently always `Bash` |438| `tool_name` | `string` | Canonical hook tool name, such as `Bash`, `apply_patch`, or an MCP name like `mcp__fs__read` |

377| `tool_use_id` | `string` | Tool-call id for this invocation |439| `tool_use_id` | `string` | Tool-call id for this invocation |

378| `tool_input.command` | `string` | Shell command Codex just ran |440| `tool_input` | `JSON value` | Tool-specific input. `Bash` and `apply_patch` use `tool_input.command` while MCP tools send all the args. |

379| `tool_response` | `JSON value` | Bash tool output payload. Today this is usually a JSON string |441| `tool_response` | `JSON value` | Tool-specific output. For MCP tools, this is the MCP call result. |

380 442 

381Plain text on `stdout` is ignored.443Plain text on `stdout` is ignored.

382 444