Repository navigation
[Feature] Document hooks payload schema or expose codex session info --json for current model/reasoning effort #21990
Description
What variant of Codex are you using?
CLI
What feature would you like to see?
Context
Codex CLI exposes per-turn structured spans in ~/.codex/log/codex-tui.log
including thread_id, model, and codex.turn.reasoning_effort. This
lets external tooling read current runtime config by filtering log
lines for the active thread.
This works as a workaround but would be cleaner with a documented API.
Request — any one would help
- Document the schema for
~/.codex/hooks.jsonevents (current
~/.codex/config.tomlshowsfeatures.codex_hooks = true, hooks
stable, but local install has no payload docs). - Expose
codex session info --jsonfor current model and
reasoning_effort, similar to other CLI introspection commands.
Use case
Multi-agent session coordination tooling tracks declared vs actual
runtime config provenance. Codex runtime log parsing works today;
a supported API would reduce maintenance burden and avoid relying
on log line patterns that may change.
Note
Not blocking — runtime-log parsing is a stable workaround. This is
about supported surface area, not unblocking critical functionality.
Additional information
No response
Activity
github-actions commentedon May 10, 2026
Potential duplicates detected. Please review them and close your issue if it is a duplicate.
Powered by Codex Action
09Catho commentedon May 10, 2026
@mattt0204 I implemented this and pushed it to my fork, but I’m blocked by the repo PR policy (
collaborators_only) so I can’t open the PR from my account.Ready compare link:
main...09Catho:21990-hooks-schema-docs
Commit:
61bbc5e
Could a maintainer either:
chrysent commentedon Sep 17, 2026
+1 from an external PreToolUse hook author, with one concrete sub-case for the schema docs on codex-cli 0.153.3 (official release tarball, Linux x86_64): the
tool_use_idshape and length contract.What we observed on the wire (captured from real PreToolUse envelopes):
{ "tool_name": "Bash", "tool_input": { "command": "…" }, "tool_use_id": "c1" }c1).function:exec_command,namespace:multi_agent_v1for the agent tools), others are bare.Why it matters. External hooks commonly want to validate or persist correlation ids before using them (we use them as audit correlation labels). Without a documented contract, a validator has two bad options: accept anything (and risk key collisions/injection-shaped ids in downstream storage), or over-restrict (our first implementation required 8..128 bytes — and on 0.153.3 every real request carried ids like
c1, so every request failed validation; worse, the harness ignored our hook's failure and executed anyway, per #41979 — the two gaps compound).Ask. When the payload schema is documented, please include: the
tool_use_idalphabet, min/max length, whether namespace prefixes are part of the id or separable metadata, and stability guarantees across versions. Alternatively, exposing the exact per-event payload viacodex session info --json(as proposed) would let hook authors derive the contract empirically.