hooks diff — Spybara

hooks.md +114 −48

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

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:

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.

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

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

48active config layers.

42 49

43## Config shape50## Config shape

44 51

127Notes:134Notes:

128 135

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

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

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

132- `statusMessage` is optional.138- `statusMessage` is optional.

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

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

136 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.

137 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

138## Matcher patterns202## Matcher patterns

139 203

140The `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 `"*"`,

145 209

147| --- | --- | --- |211| --- | --- | --- |

218

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

154 220

155Examples:221Examples:

156 222

157- `Bash`223- `Bash`

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

159- `Edit|Write`225- `Edit|Write`

~~160~~ 226- `mcp__filesystem__read_file`

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

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

163 229

164## Common input fields230## Common input fields

165 231

238 304

239### PreToolUse305### PreToolUse

240 306

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

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

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

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

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

246enforcement boundary

247 311

248This 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

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

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

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

252 316

253`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"`.

254 320

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

256 322

258| --- | --- | --- |324| --- | --- | --- |

263 329

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

265 331

293 359

294### PermissionRequest360### PermissionRequest

295 361

296Work in progress

~~297~~

298`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

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

300the 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.

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

302 366

303`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`.

304 370

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

306 372

308| --- | --- | --- |374| --- | --- | --- |

313 379

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

350 416

351### PostToolUse417### PostToolUse

352 418

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

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

355Currently `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

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

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

358side effects from the command that already ran.

359 423

360This 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

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

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

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

364 428

365`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"`.

366 432

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

368 434

370| --- | --- | --- |436| --- | --- | --- |

376 442

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

378 444

hooks.md Codex Docs, 2026-04-23 18:31 UTC → 2026-04-29 00:50 UTC