Codex Session Format Check

This skill is for quickly verifying whether a newer Codex CLI version changes the local session JSONL schema, and whether Agent Sessions can safely bump its verified support.

It is evidence-first: - Gather a report + sample paths first. - Do not change parsers/fixtures/docs without explicit user approval.

Quick Start (Most common)

1. Run weekly monitoring and open the report: - ./scripts/agent_watch.py --mode weekly - Report path prints to stdout, and is also written under scripts/probe_scan_output/agent_watch/*/report.json.
2. In report.json, check results.codex: - verified_version, installed.parsed_version, upstream.parsed_version - weekly.local_schema.file (the newest rollout JSONL used for comparison) - weekly.schema_diff and evidence.schema_matches_baseline

Interpretation: - If installed == verified and upstream == verified: no action. - If installed/upstream > verified and schema_matches_baseline == true: safe to bump verified version (after approval). - If schema_matches_baseline == false: collect evidence and plan a parser/fixture update.

What to collect as evidence (Codex)

From the weekly report: - The path in results.codex.weekly.local_schema.file (the newest rollout-*.jsonl). - The schema diff summary in results.codex.weekly.schema_diff: - unknown_types, unknown_keys (additive drift) - missing_types, missing_keys (may just mean “not observed in this sample”)

Optional (recommended when a bump is needed): - Copy the newest session file into scripts/agent_captures/<timestamp>/codex/ so it can be diffed locally. - Keep it private (do not commit raw sessions; they can contain paths and prompts).

Verification update checklist (after approval)

1. Refresh Codex stage0 fixtures so they represent the current session shape: - Resources/Fixtures/stage0/agents/codex/small.jsonl - Resources/Fixtures/stage0/agents/codex/large.jsonl
2. Ensure fixtures include the “important” event families when present in real sessions: - session_meta payload keys (commonly grows over time) - response_item tool_call/tool_result and message events - usage/limits events (token_count / rate_limits) when emitted - optional event wrappers (e.g. compaction or context events) when present
3. Bump the verified version record: - docs/agent-support/agent-support-matrix.yml (agents.codex_cli.max_verified_version) - Append a new entry in docs/agent-support/agent-support-ledger.yml - Add a line to docs/agent-json-tracking.md under “Upstream Version Check Log”
4. Run tests locally: - xcodebuild -project AgentSessions.xcodeproj -scheme AgentSessions -destination 'platform=macOS' test

Redaction guardrails (fixtures)

Codex sessions can include user instructions, file paths, and other sensitive content. When turning a real session into a committed fixture: - Replace long instruction bodies with a short placeholder string (keep structure). - Remove or truncate large base64/data-url blobs if present. - Prefer keeping only minimal, deterministic message text (e.g., “List the files”). - Keep the schema shape intact: do not delete keys just because values were redacted.