Codex hooks not firing: a tracing checklist

A hook can be configured without being allowed to run. A hook can also run successfully without its trace appearing in the workspace you are viewing. Check those boundaries separately before reinstalling anything.

This checklist covers Staso's local Codex hooks. For a new installation, start with the Codex tracing guide.

Identify the last working step

Each row narrows the investigation. Missing usage does not prove that the hook failed, and a successful setup does not prove that a task was traced.

Check the installation that owns the hooks

Run the status command from the Python environment used for Staso:

staso status --target codex

For a new installation, Python 3.11 or newer is required:

python3 -m pip install --upgrade staso
staso setup --target codex
staso status --target codex

Setup prompts for a Staso API key and workspace. It stores the credential separately and puts a reference in the hook configuration. Choose the workspace where you intend to inspect the run. The key needs traces:write; configured Guard checks also need guard:evaluate.

Review trust before running another task

OpenAI requires the exact definition of a non-managed hook to be reviewed and trusted. New or changed definitions are skipped until trusted. Use /hooks in the Codex CLI to inspect the source and review the commands. The app exposes hook review in Settings > Hooks. See the official hook trust reference.

Review again after an update changes a command. Staso setup configures its hooks; it cannot grant Codex trust on your behalf.

Check whether setup was global or project-specific

Global setup writes under ~/.codex/. Project setup writes .codex/hooks.json and .codex/config.toml in the project where you run it:

staso setup --target codex --scope project

If you chose project scope, reproduce the problem in that project. A different checkout or working directory can have different settings. Codex also requires trust in a project before loading its project-local hook layer; the official hooks documentation describes how sources combine.

Inspect the source shown by Codex instead of assuming which settings file it loaded.

Repair an outdated interpreter path

An existing hook can still reference the Python installation that originally configured it. After upgrading Staso or changing environments, synchronize the existing hooks:

staso sync --target codex
staso status --target codex

sync repairs configured hooks and adds missing supported events. It does not set up a new agent that has no Staso hooks. Use setup for that case. Review changed commands in Codex before retrying. The update guide covers the supported package-manager paths.

Generate one real event

Ask Codex to read a harmless file such as the project's README and explain it. Do not use a destructive command to test tracing.

Open Traces > Traces in the selected Staso workspace. Remove filters that exclude the new run, then inspect its prompt and exposed tool steps. They should belong to the same turn. Installing hooks alone leaves the first event pending.

If events still do not appear, check the key's workspace scope, the selected environment, account status, and outbound access to https://api.staso.ai. The troubleshooting guide separates rejected credentials, access errors, rate limits, and delivery failures. Ingestion acceptance and a queryable trace are separate milestones.

Separate trace completeness from missing fields

Staso uses Codex turn IDs to keep turns separate. It displays model, token, estimated cost, and timing fields only when the host supplies enough evidence. A missing value does not mean zero usage. Check captured prompt and tool activity before treating one absent usage field as a broken integration.

Guard is another boundary: an enabled policy with matching scope is required to check a supported proposal. A trace alone does not establish that a rule ran. See tool-call guardrails before dispatch for that distinction.