hooks.md Codex Docs, 2026-04-25 00:42 UTC → 2026-05-12 01:59 UTC

31- `hooks.json`31- `hooks.json`

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

33 33 

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.

38 

34In practice, the four most useful locations are:39In practice, the four most useful locations are:

35 40 

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

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

209 214 

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

211| --- | --- | --- |216| ------------------- | ---------------------- | ------------------------------------------------------------ |

212| `PermissionRequest` | tool name | Support includes `Bash`, `apply_patch`\*, and MCP tool names |217| `PermissionRequest` | tool name | Support includes `Bash`, `apply_patch`\*, and MCP tool names |

213| `PostToolUse` | tool name | Support includes `Bash`, `apply_patch`\*, and MCP tool names |218| `PostToolUse` | tool name | Support includes `Bash`, `apply_patch`\*, and MCP tool names |

214| `PreToolUse` | tool name | Support includes `Bash`, `apply_patch`\*, and MCP tool names |219| `PreToolUse` | tool name | Support includes `Bash`, `apply_patch`\*, and MCP tool names |

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

235 240 

236| Field | Type | Meaning |241| Field | Type | Meaning |

237| --- | --- | --- |242| ----------------- | ---------------- | ------------------------------------------- |

238| `session_id` | `string` | Current session or thread id. |243| `session_id` | `string` | Current session or thread id. |

239| `transcript_path` | `string | null` | Path to the session transcript file, if any |244| `transcript_path` | `string \| null` | Path to the session transcript file, if any |

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

241| `hook_event_name` | `string` | Current hook event name |246| `hook_event_name` | `string` | Current hook event name |

242| `model` | `string` | Active model slug |247| `model` | `string` | Active model slug |

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

284 289 

285| Field | Type | Meaning |290| Field | Type | Meaning |

286| --- | --- | --- |291| -------- | -------- | ---------------------------------------------- |

287| `source` | `string` | How the session started: `startup` or `resume` |292| `source` | `string` | How the session started: `startup` or `resume` |

288 293 

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

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

322 327 

323| Field | Type | Meaning |328| Field | Type | Meaning |

324| --- | --- | --- |329| ------------- | ------------ | --------------------------------------------------------------------------------------------------------- |

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

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

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

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

372 377 

373| Field | Type | Meaning |378| Field | Type | Meaning |

374| --- | --- | --- |379| ------------------------ | ---------------- | --------------------------------------------------------------------------------------------------------- |

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

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

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

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

379 384 

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

381 386 

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

434 439 

435| Field | Type | Meaning |440| Field | Type | Meaning |

436| --- | --- | --- |441| --------------- | ------------ | --------------------------------------------------------------------------------------------------------- |

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

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

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

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

478 483 

479| Field | Type | Meaning |484| Field | Type | Meaning |

480| --- | --- | --- |485| --------- | -------- | ---------------------------------------------- |

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

482| `prompt` | `string` | User prompt that's about to be sent |487| `prompt` | `string` | User prompt that's about to be sent |

483 488 

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

516 521 

517| Field | Type | Meaning |522| Field | Type | Meaning |

518| --- | --- | --- |523| ------------------------ | ---------------- | ------------------------------------------------- |

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

520| `stop_hook_active` | `boolean` | Whether this turn was already continued by `Stop` |525| `stop_hook_active` | `boolean` | Whether this turn was already continued by `Stop` |

521| `last_assistant_message` | `string | null` | Latest assistant message text, if available |526| `last_assistant_message` | `string \| null` | Latest assistant message text, if available |

522 527 

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

524for this event.529for this event.