---

name: codex-session-format-check description: Verify Codex CLI session JSONL format compatibility for Agent Sessions. Use when codex-cli updates, when daily monitoring flags Codex drift, or when bumping Codex max verified version (fixtures + docs + tests).

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.