Expose agent lifecycle events for external consumers (turn start, streaming, tool timing, token usage)

What variant of Codex are you using?

CLI

What feature would you like to see?

External consumers care about one number: how long will this run take? I maintain a small open-source desk device (Rubato_Plugins) that mirrors agent state on physical hardware for several hosts (opencode, Cursor, OpenClaw) and decides whether to interrupt the user.

Today, doing this for Codex means:

• the notify hook fires once, on agent-turn-complete — there is no turn-started, streaming, or tool event;
• everything else has to be reconstructed by tailing rollout-*.jsonl after the fact — an audit log, not a live signal stream;
• per-request token usage, TTFT/streaming rate, and per-tool wall time never surface as structured, timely events.

I built a duration estimator for other hosts (kNN over pre-flight features, backfilled with real token usage) and it is the weakest part of the integration — consumer-side estimation cannot see what only the framework sees:

• Real token usage per request (prompt/completion/cached) — known within seconds of a turn starting.
• TTFT and streaming rate per turn — observable early, strongly correlated with remaining time.
• Per-tool wall time — Codex already observes every exec/apply_patch call and its duration.
• Turn/step structure — planned tool calls before execution, enabling "steps remaining" instead of a single-point ETA.

Proposed feature, in three levels of increasing ambition:

1. Enrich the event surface (the concrete ask): extend notify with additional opt-in event kinds — turn-started, tool-started / tool-finished — and add a usage payload (token counts, wall time). Additive and backward compatible.
2. Aggregate: persist per-tool / per-model duration summaries locally and expose them via the CLI or a status file plugins can read.
3. Native ETA (optional, long-term): first-class estimated-remaining with confidence. Levels 1–2 would already let the ecosystem build honest estimates.

Codex sits right next to the provider API, so it is uniquely positioned to normalize throughput calibration per model — something external consumers can never do reliably.

Additional information

• The device wire contract already reserves an estSec field; if level 1 lands, the device can finally display an honest estimated duration instead of hiding it.
• Everything proposed is additive — no changes to existing notify semantics or rollout format.
• My calibration dataset (feature vectors + real outcomes across hosts) and the reference consumer (four working host integrations, verified end-to-end on Codex CLI 0.153.0) are available — happy to share either, or to contribute if the shape of level 1 is agreed.

Start by tracing the existing notify hook and the rollout-*.jsonl audit log in the CLI. Compare the proposed turn-started, tool-started, and tool-finished events with current exec/apply_patch timing and usage data. Done means an agreed additive event contract that exposes timely lifecycle, tool, and token information without changing existing notify semantics.