Hook events are points in the lifecycle where Codex can run your handler. The current lifecycle documents 11 events, and their exact list is worth keeping at hand from the official reference, because on the event depend the moment of triggering and the available context. An important execution property: matching handlers from different active sources run together, and command handlers of one event may start concurrently - this is accounted for so the handlers do not conflict.

Events cover the key moments of the agent's work, and there are exactly 11. The session's life - SessionStart and SessionEnd; subagents - SubagentStart and SubagentStop; tool work - PreToolUse, PermissionRequest and PostToolUse; context compaction - PreCompact and PostCompact; user input - UserPromptSubmit; end of a turn - Stop. PreToolUse is especially important: it lets you check or block an action before it runs, and it is on it that policy checks are built. Below these events are gathered into a table by group.

A handler is described by a structure with several fields, and it matters to understand it precisely. The type field currently takes the value command - that is, a command is run; parsed prompt and agent handlers do not run yet. The command field sets the command for macOS and Linux, and commandWindows a separate command for Windows, because the platforms differ. A timeout is set alongside. It helps to see these fields gathered together once, to write a handler by the contract rather than at random.

It helps to gather the handler fields into a table once. Below is a map: type, command, platform command, timeout. It is worth using the reference with the whole book's caveat: the exact set of events and fields depends on the version, and rare and experimental details are checked against the linked reference page. And you remember the practical rules of a safe handler from the hooks chapter: do not print secrets, do not make a hook silently destructive, keep the timeout shorter than patience and the failure mode clear.