Module types 

Domain types shared across commands: enums for CLI options, version parsing, and structured JSONL events.

JSONL schema: what is verified and what is assumed

This parser was rewritten in #73 after the previous one was found to match an event shape the CLI never emits. It matched a fixture that invented the schema, so every test passed while real output produced empty results. The split below exists so the next person can check the assumptions instead of rediscovering the bug.

Verified against codex-cli 0.145.0, from the compiled serde tag list and live runs of both codex exec --json and codex exec review --json:

• The event vocabulary is thread.started, turn.started, turn.completed, turn.failed, item.started, item.updated, item.completed. There is no bare completed. Review emits the same vocabulary as exec.

• thread.started carries thread_id.

• A completed turn reports token counts, never a monetary cost. The usage object carries input_tokens, cached_input_tokens, cache_write_input_tokens, output_tokens, and reasoning_output_tokens. It does not carry total_tokens, so TokenUsage::total reaches a total through its input plus output fallback on every real run.

• Assistant text arrives as an item.completed event whose item has a type of agent_message and its text in a text field. A review’s diff-reading steps arrive as command_execution items on the same event.

• A review’s turn.completed reports a usage object of all zeros.

• Exhausting the native rollout budget emits an error event followed by turn.failed, both with shared rollout token budget exhausted. The terminal event carries no usage object on 0.145.0 even though Codex used its internal meter to make the decision.

• The stream carries no incremental text. Three captured runs, a one-word exec, a four-sentence exec, and a review, each delivered the whole assistant message in a single item.completed. No item.updated, no partial or delta fields, and codex exec --help has no flag that changes output granularity. There is nothing to assemble, which is why this module has no equivalent of claude-wrapper’s PartialMessageEvent (#84).

Assumed, still: nothing load-bearing. JsonLineEvent::agent_message_text also accepts an item_type discriminator and a content block array, neither of which has been seen in real output. That tolerance stays because the failure mode when this parser guesses wrong is an empty result rather than an error, which is how #73 went unnoticed.

To re-confirm after a CLI upgrade, capture a run and check result is non-empty:

codex exec --json --ephemeral --skip-git-repo-check "reply with: ok" > turn.jsonl

Structs

CliVersion

Parsed semantic version of the Codex CLI (major.minor.patch).

CommandExecution

A shell command the model ran, from a command_execution item.

JsonLineEvent

A single parsed JSONL event from --json output.

QueryResult

A typed summary of a completed codex exec run, assembled from the JSONL event stream.

TokenUsage

Token counts reported on a completed turn.

VersionParseError

Enums

ApprovalPolicy

When the model should ask for human approval before executing commands.

ApprovalPolicyConfig

Approval policy values accepted by the approval_policy config key.

CliVersionStatus

Classification of an installed CLI version against a tested range.

Color

Color output mode for exec commands.

SandboxMode

Sandbox policy for model-generated shell commands.

TurnFailureKind

A terminal turn.failed classification from the Codex JSONL stream.

WebSearchMode

Web search mode, set through the web_search config key.