Bound Codex-session context intake: read-discipline instructions, fresh-context sub-agents, and per-repo output ceilings

[Trecek]

Problem

Codex-backend sessions (gpt-5.6-sol, xhigh, code_mode_only) repeatedly exhaust or nearly exhaust their context window through aggressive file intake. Two verified incidents:

1. Session 019f6b5a (2026-07-16, retry-worktree in generic_automation_mcp): 226K/258.4K tokens in one 24-minute turn; 88 exec calls, whole-file multi-file sed reads at max_output_tokens=50000; user-interrupted. Full report: .autoskillit/temp/investigate/investigation_codex_context_blowout_019f6b5a_2026-07-16_083606.md
2. Sessions 019f7273/019f7283 + 6 sub-agents (2026-07-17, gemini-deep-research-mcp): wave-1 main hit 88.6% of window in ~9 minutes; verified single-call event call_EAVeXqU404pBGUiyBvWcytsl reading 7 of 9 package files in one nl -ba chain, 5 seconds after a wc -l listing of the same package ("list -> read everything listed" pattern, repeated 20+ times across both waves; worst sub-agent: 24 batch reads, 570KB total).

Root mechanism (verified in Codex source at origin/main): gpt-5.6-sol runs tool_mode: code_mode_only (no Read tool; one JS script per turn), its base instructions say "prefer parallelization over sequential tool calls" with NO read-size guidance (the "read files in chunks with a max chunk size of 250 lines" rule was deleted upstream Dec 12 2025, commit 570eb5fe78 / openai/codex PR #7941), code-mode honors model-declared max_output_tokens unclamped (context.rs:373-386), and overflow is middle-truncated in context rather than spilled to a file. Claude Code is structurally immune: Read paginates, Bash spills >30K chars to a file with path+preview, so identical CLAUDE.md content does not produce this failure there.

Amplifiers on our side: (a) generic_automation_mcp/AGENTS.md Section 5's package table ("each has its own AGENTS.md") rationally induces 13-16-file AGENTS.md sweep reads on Codex; (b) Codex sub-agents were spawned with fork_turns:"all", inheriting the parent's entire conversation instead of starting specialized and fresh; (c) prose-level restraint instructions ("be conservative with your context") were demonstrably ignored by 2 of 3 sub-agents in wave 2 — numeric rules are required.

Proposed work

1. Codex-specific numeric read-discipline instructions injected into Codex sessions (AGENTS.md section, dispatch prompt template, or output-discipline digest — implementer chooses the layer): at most 2 files per exec command; never read a file end-to-end (use rg -n with context or sed -n ranges <=250 lines); never pass max_output_tokens above 10000; after listing a directory, open at most 2 of the listed files; the AGENTS.md package table is an index, not required reading — consult per-package AGENTS.md only for packages being modified.
2. Sub-agent spawn discipline for Codex: instruct Codex sessions to spawn specialized sub-agents with fresh context (not fork_turns:"all") and an explicit narrow brief, returning summaries only. Sub-agents are supposed to be specialized and instructed, not full-context clones.
3. Per-repo output ceiling guidance: the global ~/.codex/config.toml tool_output_token_limit (54,500 after PR Output Budget Protocol Audit Remediation #4277, derived from the open_kitchen exemption ceiling) is sized for autoskillit kitchen sessions; for non-autoskillit repos (e.g. gemini-deep-research-mcp) document/provide a lower-ceiling launch path (per-project CODEX_HOME or -c tool_output_token_limit=10000 override) so casual reads cap at ~40KB instead of ~218KB.
4. Track codex-cli upgrade: upstream models.json now gives gpt-5.6-sol a 372,000-token window (vs 258,400 in cli 0.144.1's registry) — upgrading buys ~44% headroom; verify autoskillit's derived constants (CODEX_TOOL_OUTPUT_TOKEN_LIMIT, auto-compact sentinel) remain consistent after upgrade.

Related, no action needed here

The recipe-exemption inconsistency investigated alongside this (develop's hardcoded anthropic/maxResultSizeChars=100_000 vs the measured 186,000-char open_kitchen ceiling — a real violation band on Claude Code today) is fixed by PR #4277, which derives the annotation from RESPONSE_BACKSTOP_EXEMPTION_REGISTRY (_serve_helpers.py:60) with test pinning (test_response_backstop_tool_metadata_comes_from_registry). Confirm post-merge; no work in this issue.

Requirements

REQ-RD-001: Codex sessions must receive a numeric instruction limiting file reads to at most 2 files per exec command.
REQ-RD-002: Codex sessions must be instructed to never read a file end-to-end, using ranged reads (rg -n with context, or sed -n ranges of at most 250 lines) instead.
REQ-RD-003: Codex sessions must be instructed to never pass max_output_tokens above 10000.
REQ-RD-004: Codex sessions must be instructed to open at most 2 of the files returned by a preceding directory listing.
REQ-RD-005: The AGENTS.md package table must be documented as an index rather than required reading, with per-package AGENTS.md consulted only for packages being modified.

REQ-SUB-001: Codex sessions must be instructed to spawn sub-agents with fresh context rather than fork_turns:"all".
REQ-SUB-002: Sub-agent spawn instructions must require an explicit narrow brief per sub-agent and specify that only a summary is returned to the parent.

REQ-CFG-001: A lower-ceiling launch path (per-project CODEX_HOME, or a -c tool_output_token_limit=N override) must be documented for non-autoskillit repos.
REQ-CFG-002: The documented per-repo ceiling must cap casual reads at approximately 40KB of output, down from the ~218KB produced by the autoskillit-sized default.

REQ-DEP-001: The codex-cli upgrade path must be tracked to capture the larger upstream gpt-5.6-sol context window (372,000 tokens vs. 258,400 tokens in the cli 0.144.1 registry).
REQ-DEP-002: Autoskillit's derived constants (CODEX_TOOL_OUTPUT_TOKEN_LIMIT, the auto-compact sentinel) must be verified consistent with the upstream registry after any codex-cli upgrade.

Completion Status — 2026-07-22

Implemented by PR #4281, merged into develop on 2026-07-18 as commit 38e08ad35eb33b33d717828c2f301dd03154aa4c.

Verified against current develop:

• all REQ-RD-* numeric read-discipline rules are present in the Codex output-discipline digest and contract tests;
• REQ-SUB-* fresh-context subagent guidance is present and tested;
• REQ-CFG-* lower-ceiling launch paths are documented in docs/configuration.md and ADR-0005;
• REQ-DEP-* version pinning and Doctor Check 39 (codex_limits_verified) are implemented with regression tests; and
• the merged commit is an ancestor of current develop.

The issue remained open because PR #4281 targeted develop, while GitHub closing keywords automatically close issues only after merge into the repository's default branch. The implementation is complete; this issue is closed as completed and marked staged pending promotion to main.