Replace line-based tool output truncation with token-based limits

[provencher]

Problem

Currently, Codex uses a naive line-based truncation mechanism for tool outputs:

• Hard limit: 256 lines OR 10 KiB (whichever is hit first)
• Strategy: Head+tail truncation showing first 128 lines + last 128 lines

This was introduced in commit 957d449 (August 2025, v0.24.0).

Why This Is Problematic

1. Arbitrary line limits don't correlate with token usage: A tool output with 256 short lines might only be 1-2k tokens, while another with 100 long lines could be 10k+ tokens. Line-based truncation doesn't account for actual context window pressure.

2. Forces excessive tool calls: When the model needs comprehensive information (e.g., reading a large file, analyzing test output), it must make many sequential tool calls to work around the 256-line limit, significantly slowing down task completion.

3. Head+tail strategy loses critical context: Showing first 128 + last 128 lines with a gap in the middle can hide the most important information, especially for:

   • Build outputs where errors appear in the middle
   • Test results with failures scattered throughout
   • File contents where key logic is in the middle sections

4. Recently made worse for MCP tools: In v0.56, this truncation was extended to MCP tools (previously they weren't truncated until the next turn), making the MCP experience significantly worse.

Proposed Solution

Replace line-based limits with token-based limits similar to how Claude Code handles this:

// Instead of:
const MODEL_FORMAT_MAX_LINES: usize = 256;

// Use:
const MODEL_FORMAT_MAX_TOKENS: usize = 25_000;

Benefits

1. Aligns with actual context window constraints: Tokens are what matters for the model, not lines
2. More efficient information transfer: 25k tokens could be 500+ lines of dense code or logs
3. Fewer tool calls needed: Model can digest more information per call
4. Faster overall execution: Less back-and-forth means faster task completion

Implementation Notes

• Use the existing tokenizer in codex-rs/core (already available for truncation in other parts of the codebase)
• Keep the 10 KiB byte limit as a secondary safeguard to prevent pathological cases
• Consider keeping head+tail strategy but with token-based boundaries instead of line-based
• Apply consistently to all tools (built-in and MCP) from the start

Impact

This change would significantly improve:

• Speed: Fewer tool calls means faster completion
• Accuracy: Model sees more context per call, makes better decisions
• MCP experience: Currently degraded in v0.56 due to aggressive line truncation
• User experience: Less waiting, better results

References

• Current truncation code: codex-rs/core/src/context_manager/truncate.rs
• Original line limit introduction: commit 957d449 (Aug 2025)
• Extension to MCP tools: commit 1c8507b (Oct 2025, v0.54.0)
• Claude Code tokenizer usage

[github-actions]

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

• Configurable tool output truncation limits via config.toml #5913
• Byte truncation doesn't preserve command output tails, confusing codex (e.g. with cargo output) #6415
• codex exec truncates command output #5095
• Codex CLI truncates outputs #5163

Powered by Codex Action

[SaschaHeyer]

Since upgrading to 0.57 it seems tool calls are truncated.
This makes the usage of MCP useless.

Can we mark this as a high priority issue!!!!

Blocked before implementation: I can’t access the ## PLAN section
because Linear truncates the issue description after ~10 KB, so the plan
content is cut off. I need the full ## PLAN text (or a smaller version)
pasted here or available through another endpoint before I can parse the
tasks and continue the /implement loop.

This breaks our complete development flow.

Downgrading to version ≤ 0.49does not have these issues.
So it seems it was introduced >= 0.50–0.55
Can we get this labeled as bug please.

⚠️⚠️ Lets take a simple yet fatal use case:

• Linear MCP
• Linear Issues can get quite long for example if a PRD is part of the issue
• Codex now fetches an issue via MCP and only retrieves a part of it
• This is worst case. Missing out on crucial information that is truncated

Relevant commit that introduced the issue: 1c8507b

problematic PR
#5979

@aibrahim-oai can you have a look into this please.
We had a big discussion today during a meetup this seem to affect a lot of people.

[aibrahim-oai]

Thanks for the report @provencher and @SaschaHeyer. This is on our list of priorities, I am hoping to get an update out next week.

Out of curiosity, what limit you think is reasonable for this?

[SaschaHeyer]

Thanks for jumping on it @aibrahim-oai

Personally I’d rather not have an artificial limit at all.
The model’s context window is the only cap that really matters, and forcing every tool to pre-chunk defeats the point of MCP.

If you need a guardrail for runaway outputs, I’d prefer a warning or optional setting, not hard truncation.

In other words, give users the choice: no limit by default, with an opt-in ceiling for people who care more about latency/cost than completeness.

For teams like ours, the priority is completeness.

Out of curiosity, what drove the original 10 KB/256-line cap? Was it mainly defensive (latency/cost), or something else?

[provencher]

Thanks for the report @provencher and @SaschaHeyer. This is on our list of priorities, I am hoping to get an update out next week.

Out of curiosity, what limit you think is reasonable for this?

Imo, a token based limit of 25k tokens to match Claude Code is much more reasonable, but in any case having something configurable makes sense. Consistency between these tools is important for MCP server builders

[aibrahim-oai]

Thanks for jumping on it @aibrahim-oai

Personally I’d rather not have an artificial limit at all.
The model’s context window is the only cap that really matters, and forcing every tool to pre-chunk defeats the point of MCP.

If you need a guardrail for runaway outputs, I’d prefer a warning or optional setting, not hard truncation.

In other words, give users the choice: no limit by default, with an opt-in ceiling for people who care more about latency/cost than completeness.

For teams like ours, the priority is completeness.

Out of curiosity, what drove the original 10 KB/256-line cap? Was it mainly defensive (latency/cost), or something else?

That limit is our observations to what produce the best results without overwhelming the model. Poorly designed MCPs can pollute the context and overwhelm the model, ultimately degrading the UX. Most users won't realize or understand what the MCP is doing.

imo, there should be a default limit and MCPs should provide pagination tools that models can call in parallel in case it needs more context. For now, we will add configuration to unlock use cases like you guys

[baron]

My apologies in advance for being that annoying person posting AI replies but here is the important part:

MCP pagination doesn’t apply to tool outputs. The MCP spec paginates list operations (resources/list, tools/list, etc.)—not tools/call. Large tool results should be returned as resource links or embedded resources, not paginated tool result pages. Client‑side truncation before feeding an LLM is compatible with the spec, but “use MCP pagination for tool outputs” would not be.

https://modelcontextprotocol.io/specification/2025-06-18/server/utilities/pagination#pagination

Bottom line

• The issue’s core critique is valid: line/byte heuristics are a poor proxy for model context and can hide crucial information. The underlying changes that extended truncation across tool outputs (including MCP) are real and landed via Truncate total tool calls text #5979 (in 0.54.0). ([GitHub]2)
• Moving to token‑based truncation with a byte failsafe, preserving order and tail, and steering MCP tools toward resource links/embedded resources would materially improve accuracy and user experience while staying fully within the MCP spec. ([Model Context Protocol]6)

Full Reply for reference:

Here’s my neutral take on Issue #6426 (“Replace line‑based tool output truncation with token‑based limits”) and what I’d recommend.

---

Unbiased feedback on the issue

What the issue gets right

• The current cap exists and works as described. The Codex CLI does define a line/byte cap for “model‑formatted” tool output (256 lines and ~10 KiB) with a head+tail strategy, while the UI still gets full streams. That policy was introduced in commit 957d449 (“send‑aggregated output”), which explicitly adds MODEL_FORMAT_MAX_LINES/MODEL_FORMAT_MAX_BYTES and notes only content sent to the model is truncated. ([GitHub]1)
• Truncation was later enforced across all tool outputs (incl. MCP). Commit 1c8507b (“Truncate total tool calls text”, PR Truncate total tool calls text #5979) added globally_truncate_function_output_items(...), which walks tool result content items and applies a single total‑bytes budget before building model input. Review comments also flagged image handling and ordering concerns. ([GitHub]2)
• This change shipped by v0.54.0. The 0.54.0 release notes list PR Truncate total tool calls text #5979 (“Truncate total tool calls text”). The issue text says users noticed the MCP impact in v0.56, but the code landed in 0.54.0; the discrepancy is likely observational rather than factual. ([GitHub]3)
• The criticism of line‑based caps is fair. Lines don’t correlate with tokens; long unbroken lines hit the byte fence and can drop important middle/tail content. That’s exactly the failure mode the report describes. ([GitHub]4)

Minor corrections/clarifications

• Versioning nuance. The issue body says “Recently made worse for MCP tools in v0.56,” but the PR that enforces a global cap across tool content items is credited in the 0.54.0 release. The observation may still be true (“I felt it in 0.56”), but the mechanism shipped earlier. ([GitHub]3)

Feasibility of the proposed solution

• Token‑based truncation is realistic here. Codex already does token‑aware work (e.g., autocompaction thresholds and reasoning‑token accounting), so the plumbing to tokenize exists. The changelog references auto‑compaction thresholds by tokens, which supports feasibility. ([OpenAI Developers]5)

MCP angle (important context)

• MCP pagination doesn’t apply to tool outputs. The MCP spec paginates list operations (resources/list, tools/list, etc.)—not tools/call. Large tool results should be returned as resource links or embedded resources, not paginated tool result pages. Client‑side truncation before feeding an LLM is compatible with the spec, but “use MCP pagination for tool outputs” would not be. ([Model Context Protocol]6)

---

Recommendation

Short version: Adopt token‑based truncation for text content items before model input, keep a byte‑limit failsafe, and adjust the aggregator to preserve ordering, salience, and tail visibility—plus document MCP best practices for large outputs.

1) Replace line caps with a token budget (retain a byte fuse)

• Count tokens across all text content items (including MCP tool outputs) until a configurable budget (e.g., 15k–30k tokens) is reached; then truncate at token boundaries.
• Keep the ~10 KiB byte fuse as a secondary guard for pathological inputs or tokenization failures. ([GitHub]1)

Why: Tokens map to real context pressure; the byte fence alone causes brittle mid/tail loss. The tooling to measure tokens is already present elsewhere in Codex. ([OpenAI Developers]5)

2) Use head+tail at the token level and protect the tail

• When the budget trips, keep a head slice and a tail slice, with a clear elision marker. Ensure the tail is always preserved (logs and exceptions frequently end with crucial stack traces).
• If you must collapse many items, append a single summary “omitted N items …” line (the current aggregator already emits a similar marker). ([GitHub]2)

3) Preserve original item order and provenance across content items

• The current aggregator raised ordering concerns in PR review; ensure truncation runs in order, accumulating per‑item, so model input reflects the chronological flow of tool output. Also prefer dropping oversized non‑text items (e.g., base64 images) before dropping late text. ([GitHub]7)

4) Make it configurable (and easy to debug)

• Expose a model_input_token_budget (and model_input_byte_fuse) in config/TOML and surface a /status or debug line showing what got truncated and by how much. This helps advanced users tune throughput vs. context.

5) Document MCP server best practices for large results

• Encourage MCP tools to return big payloads as resource_link or embedded resource plus a concise textual summary, rather than giant text blobs. This is squarely in‑spec and reduces truncation pressure on the client. ([Model Context Protocol]8)

6) Rollout & tests

• Guarded rollout behind a feature flag for a release or two, with metrics on average tokens sent after truncation.
• Add tests that cover:
  a) few long lines (byte fuse), b) many short lines (token budget), c) middle‑of‑log error preservation, d) multiple content items with order retention, e) base64 image handling (skip/resize), f) MCP tool output with resource links.

---

Bottom line

• The issue’s core critique is valid: line/byte heuristics are a poor proxy for model context and can hide crucial information. The underlying changes that extended truncation across tool outputs (including MCP) are real and landed via Truncate total tool calls text #5979 (in 0.54.0). ([GitHub]2)
• Moving to token‑based truncation with a byte failsafe, preserving order and tail, and steering MCP tools toward resource links/embedded resources would materially improve accuracy and user experience while staying fully within the MCP spec. ([Model Context Protocol]6)

For reference: the issue text and commit links summarize today’s behavior and the proposed change, and the PR and release notes confirm the MCP‑wide truncation behavior now in Codex. ([GitHub]4)

[provencher]

Thank you for the detailed feedback! You're correct that commit 1c8507b landed in v0.54.0, but there was an additional change that I should clarify.

The v0.56 Change

While the truncation mechanism () was added in v0.54.0, there was a significant architectural change in v0.56 (commit 1a89f70, PR #6229) that changed when truncation happens in the pipeline.

Before v0.56 (including v0.54 and v0.55):

• Truncation happened in ConversationHistory::record_items during history recording
• MCP tool outputs could flow to the model first, then get truncated when saved to history
• The model saw full output in the current turn; only subsequent turns saw the truncated version

After v0.56:

• New context_manager module created with dedicated truncate.rs
• Truncation moved to response conversion pipeline (response_processing.rs)
• MCP outputs are now truncated before reaching the model on first use
• This is mentioned in the PR refactor Conversation history file into its own directory #6229 description: "centralize truncation in conversation history"

This explains why MCP users noticed a significant experience change specifically in v0.56, even though the truncation limits themselves were established in v0.54.0.

[provencher]

Thanks for jumping on it @aibrahim-oai
Personally I’d rather not have an artificial limit at all.
The model’s context window is the only cap that really matters, and forcing every tool to pre-chunk defeats the point of MCP.
If you need a guardrail for runaway outputs, I’d prefer a warning or optional setting, not hard truncation.
In other words, give users the choice: no limit by default, with an opt-in ceiling for people who care more about latency/cost than completeness.
For teams like ours, the priority is completeness.
Out of curiosity, what drove the original 10 KB/256-line cap? Was it mainly defensive (latency/cost), or something else?

That limit is our observations to what produce the best results without overwhelming the model. Poorly designed MCPs can pollute the context and overwhelm the model, ultimately degrading the UX. Most users won't realize or understand what the MCP is doing.

imo, there should be a default limit and MCPs should provide pagination tools that models can call in parallel in case it needs more context. For now, we will add configuration to unlock use cases like you guys

Just a note @aibrahim-oai. Hopefully your config option is a per-mcp one, like the tool timeout (which is 60s and I think too low imo, but the config is there so not a huge issue). I think it makes sense for each server to have it's own truncation limits.