hooks.md Codex Docs, 2026-05-02 06:45 UTC → 2026-05-05 23:00 UTC

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

214 214 

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

216| --- | --- | --- |216| ------------------- | ---------------------- | ------------------------------------------------------------ |

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

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

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

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

240 240 

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

242| --- | --- | --- |242| ----------------- | ---------------- | ------------------------------------------- |

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

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

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

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

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

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

289 289 

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

291| --- | --- | --- |291| -------- | -------- | ---------------------------------------------- |

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

293 293 

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

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

327 327 

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

329| --- | --- | --- |329| ------------- | ------------ | --------------------------------------------------------------------------------------------------------- |

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

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

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

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

377 377 

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

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

380| `turn_id` | `string` | Codex-specific extension. Active Codex turn id |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` |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. |382| `tool_input` | `JSON value` | Tool-specific input. `Bash` and `apply_patch` use `tool_input.command` while MCP tools send all the args. |

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

384 384 

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

386 386 

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

439 439 

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

441| --- | --- | --- |441| --------------- | ------------ | --------------------------------------------------------------------------------------------------------- |

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

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

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

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

483 483 

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

485| --- | --- | --- |485| --------- | -------- | ---------------------------------------------- |

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

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

488 488 

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

521 521 

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

523| --- | --- | --- |523| ------------------------ | ---------------- | ------------------------------------------------- |

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

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

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

527 527 

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

529for this event.529for this event.