JSON output mode docs are out of date

What is the type of issue?

Documentation is incorrect

What is the issue?

The documentation for codex exec --json in exec.md shows items using "item_type":"assistant_message", but actual output from codex v0.44.0 uses "type":"agent_message" instead. Clearly, the field name changed from item_type to type, and the message type value changed from assistant_message to agent_message.

Any parser following the documented schema will fail to extract agent responses. This is critical because machine-readable output formats are contracts. The entire point of --json mode is providing stable, parseable output that tools can depend on. Breaking this without documentation updates or versioning undermines the format's utility.

I'm filing this as a Documentation Issue, but I'd like to see it properly enforced in code, not just via manual doc updates:

1. Use JSON Schema specification instead of (or in addition to) free-form docs. All possible fields, item types, and valid values should be listed there explicitly and kept up to date with code changes.
2. Automated tests asserting output conformance to schema as part of CI/CD to prevent drift
3. Schema versioning for breaking changes with backward compatibility guarantees and deprecation periods

Format changes without version indicators make it impossible to know which codex versions work with which schemas, so current versionless schema is a ticking time bomb.

Where did you find it?

https://github.com/openai/codex/blob/main/docs/exec.md#json-output-mode