Codex lifecycle hooks: trace the turn and check tool calls

Codex hooks run at specific points in an agent session. Picking the right event matters: a tool proposal, an approval request, and an executed tool are three different facts. The Codex hooks reference defines the event names and explains when Codex runs them.

Staso installs hooks for 11 Codex events. It uses the exposed events to group a turn, record tool activity, and check supported proposals against configured Guard policies. The host decides which events occur; a short task will not produce compaction or subagent events.

Follow one ordinary turn

1. SessionStart: A Codex session starts or resumes. Confirm Staso setup loaded from the scope you intended.
2. UserPromptSubmit: A user prompt opens a turn. Look for a new trace for that turn.
3. PreToolUse: Codex exposes a tool proposal before execution. Inspect the proposal and any Guard decision.
4. PermissionRequest: Codex asks for approval when needed. Its normal approval path still controls permission.
5. PostToolUse: A tool finishes and Codex exposes the result. Inspect the observed tool step and its outcome.
6. Stop: The turn ends. Check that the same trace is finalized.
7. SessionEnd: The main session ends. Any unfinished turn is closed.

PermissionRequest appears only when Codex asks for approval. SessionEnd is a session event, not a marker after every answer. A proposal in PreToolUse does not prove execution; check PostToolUse for the result Codex exposed.

Expect some events only when the task needs them

Staso also installs PreCompact and PostCompact for compaction, plus SubagentStart and SubagentStop for subagent activity. If your task did neither, their absence is normal. Codex may run hooks from multiple sources, so inspect the source and matcher in /hooks before assuming which definition ran.

The current Codex reference also documents PreModelRequest, PostModelRequest, and Interrupt. Staso's Codex setup does not install those three events. Model, token, cost, and timing details in a Staso trace depend on evidence the host makes available; do not read a missing field as zero usage.

Put a blocking check before the tool

PreToolUse is the boundary for Staso Guard on supported Codex proposals. An enabled policy must select a rule and match the agent, environment, and tool. In Audit, a match records a would-block finding while the call continues. In Enforce, a matching supported proposal can be stopped before execution where your plan permits it. Codex's own permission prompt remains separate.

A background or post-tool hook cannot undo a call that already ran. For a Python function called directly by your application, use an explicit st.guard() check before dispatch; a Codex hook does not govern that function. The tool-call guardrails guide shows the Python boundary.

Check a missing event in order

1. Run staso status --target codex in the Python environment where Staso was installed.
2. Open /hooks in Codex and review the exact generated commands. New or changed non-managed hooks are skipped until trusted. Project hooks also need the project to be trusted.
3. Confirm whether setup was global or project-scoped. A different checkout may load different hooks.
4. Ask Codex to read a harmless local file, then open the matching workspace in Staso. Setup alone does not create a trace.
5. Compare the prompt, proposed tool, and completed tool step. If the trace exists but one field is absent, check what the host exposed before reinstalling.

The Codex hooks troubleshooting checklist covers interpreter paths, workspace filters, delivery, and trust in more detail. For the supported setup path, start with the Codex tracing guide.