hooks diff — Spybara

hooks.md +200 −59

Details

1# Hooks1# Hooks

2 2

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

~~4disabled.~~

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

9- Send the conversation to a custom logging/analytics engine6- Send the conversation to a custom logging/analytics engine

10- Scan your team's prompts to block accidentally pasting API keys7- Scan your team's prompts to block accidentally pasting API keys

11- Summarize conversations to create persistent memories automatically8- Summarize conversations to create persistent memories automatically

~~12- Run a custom validator when a conversation turn stops, enforcing standards~~9- Run a custom validation check when a conversation turn stops, enforcing standards

13- Customize prompting when in a certain directory10- Customize prompting when in a certain directory

14 11

15Hooks are behind a feature flag in `config.toml`:12Hooks are behind a feature flag in `config.toml`:

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 cannot prevent another matching hook from starting.23 so one hook cannot prevent another matching hook from starting.

~~27- `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, and `Stop` run at turn~~24- `PreToolUse`, `PermissionRequest`, `PostToolUse`, `UserPromptSubmit`, and

~~28 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:

31- `hooks.json`

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

34Installed plugins can also bundle lifecycle config through their plugin

35manifest or a default `hooks/hooks.json` file. See [Build

36plugins](https://developers.openai.com/codex/plugins/build#bundled-mcp-servers-and-lifecycle-config) for the

37plugin packaging rules.

34 38

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

36 40

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

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

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

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

39 45

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

41Higher-precedence config layers do not replace lower-precedence hooks.47Higher-precedence config layers do not replace lower-precedence hooks.

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

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

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

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

53active config layers.

42 54

43## Config shape55## Config shape

44 56

75 ]87 ]

76 }88 }

77 ],89 ],

90 "PermissionRequest": [

91 {

92 "matcher": "Bash",

93 "hooks": [

94 {

95 "type": "command",

96 "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/permission_request.py\"",

97 "statusMessage": "Checking approval request"

98 }

99 ]

100 }

101 ],

78 "PostToolUse": [102 "PostToolUse": [

79 {103 {

80 "matcher": "Bash",104 "matcher": "Bash",

115Notes:139Notes:

116 140

117- `timeout` is in seconds.141- `timeout` is in seconds.

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

119- If `timeout` is omitted, Codex uses `600` seconds.142- If `timeout` is omitted, Codex uses `600` seconds.

120- `statusMessage` is optional.143- `statusMessage` is optional.

121- Commands run with the session `cwd` as their working directory.144- Commands run with the session `cwd` as their working directory.

123 relative path such as `.codex/hooks/...`. Codex may be started from a146 relative path such as `.codex/hooks/...`. Codex may be started from a

124 subdirectory, and a git-root-based path keeps the hook location stable.147 subdirectory, and a git-root-based path keeps the hook location stable.

125 148

149Equivalent inline TOML in `config.toml`:

150

151```toml

152[features]

153codex_hooks = true

154

155[[hooks.PreToolUse]]

156matcher = "^Bash$"

157

158[[hooks.PreToolUse.hooks]]

159type = "command"

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

161timeout = 30

162statusMessage = "Checking Bash command"

163

164[[hooks.PostToolUse]]

165matcher = "^Bash$"

166

167[[hooks.PostToolUse.hooks]]

168type = "command"

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

170timeout = 30

171statusMessage = "Reviewing Bash output"

172```

173

174## Managed hooks from `requirements.toml`

175

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

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

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

179

180```toml

181[features]

182codex_hooks = true

183

184[hooks]

185managed_dir = "/enterprise/hooks"

186windows_managed_dir = 'C:\enterprise\hooks'

187

188[[hooks.PreToolUse]]

189matcher = "^Bash$"

190

191[[hooks.PreToolUse.hooks]]

192type = "command"

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

194timeout = 30

195statusMessage = "Checking managed Bash command"

196```

197

198Notes for managed hooks:

199

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

201- `windows_managed_dir` is used on Windows.

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

203 tooling must install and update them separately.

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

205 managed directory.

206

126## Matcher patterns207## Matcher patterns

127 208

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

132Only some current Codex events honor `matcher`:213Only some current Codex events honor `matcher`:

133 214

135| --- | --- | --- |216| ------------------- | ---------------------- | ------------------------------------------------------------ |

222| `Stop` | not supported | Any configured `matcher` is ignored for this event |

223

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

141 225

142Examples:226Examples:

143 227

144- `Bash`228- `Bash`

145- `startup|resume`229- `^apply_patch$`

146- `Edit|Write`230- `Edit|Write`

~~147~~ 231- `mcp__filesystem__read_file`

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

149`PostToolUse` events only emit `Bash`, so it will not match anything today.233- `startup|resume|clear`

150 234

151## Common input fields235## Common input fields

152 236

155These are the shared fields you will usually use:239These are the shared fields you will usually use:

156 240

158| --- | --- | --- |242| ----------------- | ---------------- | ------------------------------------------- |

161| `cwd` | `string` | Working directory for the session |245| `cwd` | `string` | Working directory for the session |

189 273

190Exit `0` with no output is treated as success and Codex continues.274Exit `0` with no output is treated as success and Codex continues.

191 275

192`PreToolUse` supports `systemMessage`, but `continue`, `stopReason`, and276`PreToolUse` and `PermissionRequest` support `systemMessage`, but `continue`,

193`suppressOutput` are not currently supported for that event.277`stopReason`, and `suppressOutput` aren't currently supported for those events.

194 278

195`PostToolUse` supports `systemMessage`, `continue: false`, and `stopReason`.279`PostToolUse` supports `systemMessage`, `continue: false`, and `stopReason`.

196`suppressOutput` is parsed but not currently supported for that event.280`suppressOutput` is parsed but not currently supported for that event.

204Fields in addition to [Common input fields](#common-input-fields):288Fields in addition to [Common input fields](#common-input-fields):

205 289

207| --- | --- | --- |291| -------- | -------- | ---------------------------------------------- |

209 293

210Plain text on `stdout` is added as extra developer context.294Plain text on `stdout` is added as extra developer context.

225 309

226### PreToolUse310### PreToolUse

227 311

228Work in progress312`PreToolUse` can intercept Bash, file edits performed through `apply_patch`,

~~229~~ 313and MCP tool calls. It is still a guardrail rather than a complete enforcement

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

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

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

233enforcement boundary

234 316

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

236 `unified_exec` mechanism allows richer streaming stdin/stdout handling of318 `unified_exec` mechanism allows richer streaming stdin/stdout handling of

237shell, but interception is incomplete. Similarly, this doesn’t intercept MCP,319 shell, but interception is incomplete. Similarly, this doesn't intercept

238Write, WebSearch, or other non-shell tool calls.320 `WebSearch` or other non-shell, non-MCP tool calls.

239 321

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

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

324still reports `tool_name: "apply_patch"`.

241 325

242Fields in addition to [Common input fields](#common-input-fields):326Fields in addition to [Common input fields](#common-input-fields):

243 327

245| --- | --- | --- |329| ------------- | ------------ | --------------------------------------------------------------------------------------------------------- |

250 334

251Plain text on `stdout` is ignored.335Plain text on `stdout` is ignored.

252 336

278`updatedInput`, `additionalContext`, `continue: false`, `stopReason`, and362`updatedInput`, `additionalContext`, `continue: false`, `stopReason`, and

279`suppressOutput` are parsed but not supported yet, so they fail open.363`suppressOutput` are parsed but not supported yet, so they fail open.

280 364

281### PostToolUse365### PermissionRequest

366

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

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

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

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

371

372`matcher` is applied to `tool_name` and matcher aliases. Current canonical

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

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

375

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

377

378| Field | Type | Meaning |

379| ------------------------ | ---------------- | --------------------------------------------------------------------------------------------------------- |

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

381| `tool_name` | `string` | Canonical hook tool name, such as `Bash`, `apply_patch`, or an MCP name like `mcp__fs__read` |

382| `tool_input` | `JSON value` | Tool-specific input. `Bash` and `apply_patch` use `tool_input.command` while MCP tools send all the args. |

384

385Plain text on `stdout` is ignored.

386

387To approve the request, return:

388

389```json

390{

391 "hookSpecificOutput": {

392 "hookEventName": "PermissionRequest",

393 "decision": {

394 "behavior": "allow"

395 }

396 }

397}

398```

282 399

283Work in progress400To deny the request, return:

401

402```json

403{

404 "hookSpecificOutput": {

405 "hookEventName": "PermissionRequest",

406 "decision": {

407 "behavior": "deny",

408 "message": "Blocked by repository policy."

409 }

410 }

411}

412```

413

414If multiple matching hooks return decisions, any `deny` wins. Otherwise, an

415`allow` lets the request proceed without surfacing the approval prompt. If no

416matching hook decides, Codex uses the normal approval flow.

417

418Don't return `updatedInput`, `updatedPermissions`, or `interrupt` for

419`PermissionRequest`; those fields are reserved for future behavior and fail

420closed today.

421

422### PostToolUse

284 423

285Currently `PostToolUse` only supports Bash tool results. It is not limited to424`PostToolUse` runs after supported tools produce output, including Bash,

286commands that exit successfully: non-interactive `exec_command` calls can still425`apply_patch`, and MCP tool calls. For Bash, it also runs after commands that

287trigger `PostToolUse` when Codex emits a Bash post-tool payload. It cannot undo426exit with a non-zero status. It can't undo side effects from the tool that

288side effects from the command that already ran.427already ran.

289 428

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

291 `unified_exec` mechanism allows richer streaming stdin/stdout handling of430 `unified_exec` mechanism allows richer streaming stdin/stdout handling of

292shell, but interception is incomplete. Similarly, this doesn’t intercept MCP,431 shell, but interception is incomplete. Similarly, this doesn't intercept

293Write, WebSearch, or other non-shell tool calls.432 `WebSearch` or other non-shell, non-MCP tool calls.

294 433

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

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

436still reports `tool_name: "apply_patch"`.

296 437

297Fields in addition to [Common input fields](#common-input-fields):438Fields in addition to [Common input fields](#common-input-fields):

298 439

300| --- | --- | --- |441| --------------- | ------------ | --------------------------------------------------------------------------------------------------------- |

306 447

307Plain text on `stdout` is ignored.448Plain text on `stdout` is ignored.

308 449

321 462

322That `additionalContext` text is added as extra developer context.463That `additionalContext` text is added as extra developer context.

323 464

324For this event, `decision: "block"` does not undo the completed Bash command.465For this event, `decision: "block"` doesn't undo the completed Bash command.

325Instead, Codex records the feedback, replaces the tool result with that466Instead, Codex records the feedback, replaces the tool result with that

326feedback, and continues the model from the hook-provided message.467feedback, and continues the model from the hook-provided message.

327 468

336 477

337### UserPromptSubmit478### UserPromptSubmit

338 479

339`matcher` is not currently used for this event.480`matcher` isn't currently used for this event.

340 481

341Fields in addition to [Common input fields](#common-input-fields):482Fields in addition to [Common input fields](#common-input-fields):

342 483

344| --- | --- | --- |485| --------- | -------- | ---------------------------------------------- |

347 488

348Plain text on `stdout` is added as extra developer context.489Plain text on `stdout` is added as extra developer context.

349 490

374 515

375### Stop516### Stop

376 517

377`matcher` is not currently used for this event.518`matcher` isn't currently used for this event.

378 519

379Fields in addition to [Common input fields](#common-input-fields):520Fields in addition to [Common input fields](#common-input-fields):

380 521

382| --- | --- | --- |523| ------------------------ | ---------------- | ------------------------------------------------- |

386 527

387`Stop` expects JSON on `stdout` when it exits `0`. Plain text output is invalid528`Stop` expects JSON on `stdout` when it exits `0`. Plain text output is invalid

388for this event.529for this event.

399 540

400You can also use exit code `2` and write the continuation reason to `stderr`.541You can also use exit code `2` and write the continuation reason to `stderr`.

401 542

402For this event, `decision: "block"` does not reject the turn. Instead, it tells543For this event, `decision: "block"` doesn't reject the turn. Instead, it tells

403Codex to continue and automatically creates a new continuation prompt that acts544Codex to continue and automatically creates a new continuation prompt that acts

404as a new user prompt, using your `reason` as that prompt text.545as a new user prompt, using your `reason` as that prompt text.

405 546

hooks.md Codex Docs, 2026-04-20 18:26 UTC → 2026-05-07 20:02 UTC