[Feature] Document hooks payload schema or expose codex session info --json for current model/reasoning effort

Open 💬 2 comments Opened May 10, 2026 by itssosunny
💡 Likely answer: A maintainer (github-actions[bot], contributor) responded on this thread — see the highlighted reply below.

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

  1. Document the schema for ~/.codex/hooks.json events (current

~/.codex/config.toml shows features.codex_hooks = true, hooks
stable, but local install has no payload docs).

  1. Expose codex session info --json for 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_

View original on GitHub ↗

2 Comments

github-actions[bot] contributor · 3 months ago

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

  • #21753

Powered by Codex Action

09Catho · 3 months ago

@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:
https://github.com/openai/codex/compare/main...09Catho:21990-hooks-schema-docs

Commit:
61bbc5e29f

Could a maintainer either:
1) grant collaborator permission so I can open the PR, or
2) open the PR from this branch on my behalf?