Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

fix: keep file-read tool output byte-exact through the lossless fold

Tejas Chopra59499f73ac49
diff --git a/headroom/config.py b/headroom/config.py
index b1dc607eb..5bc864f70 100644
--- a/headroom/config.py
+++ b/headroom/config.py
@@ -244,11 +244,15 @@ DEFAULT_EXCLUDE_TOOLS: frozenset[str] = frozenset(
# These excluded web-tool results must remain byte-faithful. Even the
# excluded-tool lossless fold rewrites formatted JSON.
-# Three independent consumers key off this frozenset, all in
-# transforms/content_router.py: ContentRouter's two per-block CCR-retrieve
-# guards, and _cross_turn_dedup_messages's verbatim_tool_ids -- the latter has
-# no dedicated guard of its own, so removing headroom_retrieve from here would
-# silently reopen the retrieval loop for that path with cross-turn dedup on.
+# Five consumers key off this frozenset, across two modules -- a name added here
+# is protected on every wire shape, not just the one you happened to test:
+# transforms/content_router.py has ContentRouter's two per-block excluded-tool
+# guards (OpenAI chat + Anthropic blocks) and _cross_turn_dedup_messages's
+# verbatim_tool_ids; proxy/handlers/openai.py builds verbatim_excluded_call_ids
+# for the Responses excluded-tool guard and for the Responses dedup's
+# protected_call_ids. The dedup consumers have no dedicated guard of their own,
+# so removing headroom_retrieve from here would silently reopen the retrieval
+# loop for those paths with cross-turn dedup on.
DEFAULT_VERBATIM_EXCLUDE_TOOLS: frozenset[str] = frozenset(
{
"WebSearch",
@@ -263,6 +267,45 @@ DEFAULT_VERBATIM_EXCLUDE_TOOLS: frozenset[str] = frozenset(
}
)
+# File-READ tools whose output the excluded-tool lossless fold must never
+# REWRITE. A strictly weaker protection than DEFAULT_VERBATIM_EXCLUDE_TOOLS
+# above, and that gap is the whole reason there are two sets: this one gates only
+# the fold, so these tools keep cross-turn dedup and the age-based fall-through.
+#
+# The failure being fixed: a read tool that returns raw file bytes (Codex-style
+# `read`, custom agents, /v1/compress callers naming their own tools) hands
+# `_lossless_compact_excluded` a pretty-printed JSON file, which json-min's it.
+# That fold is data-lossless and the proxy can invert it -- but the inverse runs
+# on OUR side, while the copy that has to match on disk is typed by the MODEL out
+# of the bytes it was SHOWN. It builds `Edit(old_string=...)` from minified JSON,
+# the file on disk is still pretty-printed, the edit misses, and the retry turn
+# costs far more than the fold saved. The log fold (repeats rewritten to
+# `... (repeated N times)`) and the search fold (path hoisted into a heading)
+# destroy an Edit anchor the same way, so this gates the fold as a whole rather
+# than the JSON branch alone. DEFAULT_EXCLUDE_TOOLS has claimed since forever
+# that Read "Returns exact file content needed for Edit tool's old_string
+# matching"; this is what makes that true instead of aspirational.
+#
+# Why NOT just add these to DEFAULT_VERBATIM_EXCLUDE_TOOLS, which would have been
+# the one-line fix: that set also gates cross-turn dedup and the age-based lossy
+# fall-through, and neither shares the failure mode. Dedup replaces a repeat with
+# an in-context pointer to an EARLIER copy that is never rewritten (the
+# keep-earliest invariant in transforms/cross_turn_dedup.py), so the true bytes
+# stay physically in the window for the model to copy from; the fold leaves them
+# nowhere at all. Measured on one file read three times, dedup is worth ~66% of
+# those tokens -- the largest Read-side saving there is, and the one that still
+# fires on Claude Code's `cat -n`-shaped Read output, where the fold never fires
+# in the first place. Buying byte-exactness with dedup would be paying the large
+# bill to plug the small leak. `view` stays in the stricter set above: that was a
+# deliberate, documented call for Copilot and loosening it is not this change's
+# business.
+DEFAULT_BYTE_EXACT_EXCLUDE_TOOLS: frozenset[str] = frozenset(
+ {
+ "Read",
+ "read",
+ }
+)
+
def _tool_name_aliases(name: str) -> tuple[str, ...]:
"""Return equivalent spellings for tool exclusion matching."""
diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.py
index 8905f91e7..af42e36ee 100644
--- a/headroom/proxy/handlers/openai.py
+++ b/headroom/proxy/handlers/openai.py
@@ -2110,6 +2110,7 @@ class OpenAIHandlerMixin:
# original and lowercased name variants (see _parse_exclude_tools), but
# we also test the lowercased name defensively for case-insensitivity.
from headroom.config import (
+ DEFAULT_BYTE_EXACT_EXCLUDE_TOOLS,
DEFAULT_EXCLUDE_TOOLS,
DEFAULT_VERBATIM_EXCLUDE_TOOLS,
is_tool_excluded,
@@ -2129,6 +2130,16 @@ class OpenAIHandlerMixin:
for call_id, fn_name in function_name_by_call_id.items()
if is_tool_excluded(fn_name, DEFAULT_VERBATIM_EXCLUDE_TOOLS)
}
+ # A file read is protected from the lossless FOLD only — its bytes come
+ # back as the model's `Edit(old_string=…)` anchor, so a rewrite costs a
+ # missed edit. Deliberately NOT folded into verbatim_excluded_call_ids:
+ # that set also gates the Responses cross-turn dedup below, and dedup
+ # leaves the true bytes in context (see DEFAULT_BYTE_EXACT_EXCLUDE_TOOLS).
+ byte_exact_call_ids: set[str] = {
+ call_id
+ for call_id, fn_name in function_name_by_call_id.items()
+ if is_tool_excluded(fn_name, DEFAULT_BYTE_EXACT_EXCLUDE_TOOLS)
+ }
# Read protection (HEADROOM_PROTECT_READS) — parity with the
# chat/Anthropic path (ContentRouter.apply). Output of a file-READ
@@ -2251,9 +2262,14 @@ class OpenAIHandlerMixin:
# Note: when output is a content-part array, fold each text part
# individually using ("output_part", index) slots to preserve the
# array structure (non-text parts like images are left untouched).
+ # A file read skips the fold entirely: this is the Codex wire,
+ # where `read` really does return raw file bytes, so a fold here
+ # is exactly what breaks the next `Edit(old_string=…)`.
excluded_folded = False
raw_output = item.get("output")
- if isinstance(raw_output, list):
+ if call_id in byte_exact_call_ids:
+ pass # byte-exact: no fold, fall through to the debug record
+ elif isinstance(raw_output, list):
for pidx, part in enumerate(raw_output):
if (
isinstance(part, dict)
diff --git a/headroom/transforms/content_router.py b/headroom/transforms/content_router.py
index 71f7f6072..a1c07e10d 100644
--- a/headroom/transforms/content_router.py
+++ b/headroom/transforms/content_router.py
@@ -51,6 +51,7 @@ from enum import Enum
from typing import Any
from ..config import (
+ DEFAULT_BYTE_EXACT_EXCLUDE_TOOLS,
DEFAULT_EXCLUDE_TOOLS,
DEFAULT_VERBATIM_EXCLUDE_TOOLS,
ReadLifecycleConfig,
@@ -5201,8 +5202,15 @@ class ContentRouter(Transform):
continue
if messages_from_end <= read_protection_window:
# Protected from lossy compression — but grep/log/json
- # output can still be losslessly compacted.
- compacted = self._lossless_compact_excluded(content)
+ # output can still be losslessly compacted, UNLESS this is
+ # a file read: every fold rewrites the bytes the model
+ # copies into `Edit(old_string=…)`, and a missed edit costs
+ # a whole turn (see DEFAULT_BYTE_EXACT_EXCLUDE_TOOLS).
+ compacted = (
+ None
+ if is_tool_excluded(tool_name, DEFAULT_BYTE_EXACT_EXCLUDE_TOOLS)
+ else self._lossless_compact_excluded(content)
+ )
if compacted is not None:
folded, kind = compacted
result_slots[i] = {**message, "content": folded}
@@ -6174,8 +6182,15 @@ class ContentRouter(Transform):
continue
if messages_from_end <= read_protection_window:
# Protected from lossy compression — but grep/log/json
- # output can still be losslessly compacted.
- compacted = self._lossless_compact_excluded(block.get("content"))
+ # output can still be losslessly compacted, UNLESS this is
+ # a file read (see DEFAULT_BYTE_EXACT_EXCLUDE_TOOLS). This
+ # is the shape Claude Code's own `Read` arrives in, so it
+ # has to carry the same guard as the OpenAI branch above.
+ compacted = (
+ None
+ if is_tool_excluded(tool_name, DEFAULT_BYTE_EXACT_EXCLUDE_TOOLS)
+ else self._lossless_compact_excluded(block.get("content"))
+ )
if compacted is not None:
folded, kind = compacted
new_blocks.append({**block, "content": folded})
diff --git a/tests/test_lossless_excluded_compaction.py b/tests/test_lossless_excluded_compaction.py
index 5872299fe..20a4fc86d 100644
--- a/tests/test_lossless_excluded_compaction.py
+++ b/tests/test_lossless_excluded_compaction.py
@@ -1,8 +1,8 @@
"""Information-preserving compaction for EXCLUDED tool output.
-Excluded tools (Read/Grep/Glob/Write/Edit) are protected from *lossy*
-compression for accuracy. This feature still compacts them by detected shape,
-using only reversible / data-preserving transforms:
+Excluded tools (Grep/Glob/Write/Edit) are protected from *lossy* compression for
+accuracy. This feature still compacts them by detected shape, using only
+reversible / data-preserving transforms:
* SEARCH (grep) -> ripgrep --heading fold [byte-lossless]
* LOG -> ANSI strip + run-collapse [byte-lossless modulo ANSI color]
@@ -10,6 +10,11 @@ using only reversible / data-preserving transforms:
Source code and glob path-lists match nothing -> untouched. Always on
(information-preserving, so it needs no feature gate) in every path.
+
+File-READ tools (`Read`/`read`, Copilot's `view`) are the exception: they are in
+DEFAULT_VERBATIM_EXCLUDE_TOOLS and skip the fold entirely, because their bytes
+come back to us as the model's `Edit(old_string=...)` anchor and must therefore
+be byte-faithful, not merely recoverable.
"""
from __future__ import annotations
@@ -106,14 +111,21 @@ def test_pipeline_folds_grep_and_recovers(tokenizer):
assert search_unheading(out) == GREP
-def test_pipeline_compacts_log_read(tokenizer):
- out, transforms = _run(LOG, "read", tokenizer)
+# The two shape tests below drive `grep`, not `read`. A file-read tool is now
+# short-circuited before the fold ever runs (see the byte-faithfulness tests
+# further down), so `read` would prove nothing about the fold. `grep` is
+# excluded-but-foldable: its output is search results the agent greps again,
+# never a string it re-emits as an Edit anchor.
+
+
+def test_pipeline_compacts_log_from_excluded_tool(tokenizer):
+ out, transforms = _run(LOG, "grep", tokenizer)
assert "router:excluded:lossless_log" in transforms
assert expand_runs(out) == strip_ansi(LOG)
-def test_pipeline_minifies_json_read(tokenizer):
- out, transforms = _run(JSON, "read", tokenizer)
+def test_pipeline_minifies_json_from_excluded_tool(tokenizer):
+ out, transforms = _run(JSON, "grep", tokenizer)
assert "router:excluded:lossless_json" in transforms
assert json.loads(out) == json.loads(JSON) # data-lossless (same object)
@@ -123,6 +135,92 @@ def test_pipeline_leaves_source_read_untouched(tokenizer):
assert out == CODE
+# --- file reads must be BYTE-faithful, not merely recoverable ----------------
+#
+# Regression for the read-then-Edit miss: `Read`/`read` were excluded from LOSSY
+# compression but not from the excluded-tool lossless fold, so a read of a
+# pretty-printed JSON file came back json-min'd. That fold is data-lossless and
+# the proxy can invert it -- but the inverse runs on OUR side, while the copy
+# that has to match on disk is typed by the MODEL from the bytes it was shown.
+# It built `Edit(old_string=...)` out of minified JSON, the file on disk was
+# still pretty-printed, the edit missed, and the retry turn cost more than the
+# ~480 tokens the fold saved. Copilot's equivalent `view` was already protected;
+# `Read` was the asymmetry.
+
+
+def _run_anthropic(content: str, tool: str, tokenizer):
+ """Claude Code's own wire shape: tool_use / tool_result content blocks.
+
+ Gated by a *separate* guard from the OpenAI chat path (`_run`), so the
+ byte-exact rule has to be asserted on both or one wire keeps folding.
+ """
+ router = ContentRouter(ContentRouterConfig())
+ messages = [
+ {
+ "role": "assistant",
+ "content": [{"type": "tool_use", "id": "t1", "name": tool, "input": {}}],
+ },
+ {
+ "role": "user",
+ "content": [{"type": "tool_result", "tool_use_id": "t1", "content": content}],
+ },
+ ]
+ result = router.apply(messages, tokenizer, compress_user_messages=True)
+ return result.messages[1]["content"][0]["content"], result.transforms_applied
+
+
[email protected]("shape", [_run, _run_anthropic], ids=["openai_chat", "anthropic_blocks"])
[email protected]("tool", ["Read", "read", "view"])
[email protected]("body", [JSON, LOG, GREP], ids=["json", "log", "grep"])
+def test_file_read_result_is_byte_exact(shape, tool, body, tokenizer):
+ out, transforms = shape(body, tool, tokenizer)
+ assert out == body, f"{tool} result was rewritten; the model's Edit anchor would miss"
+ assert "router:excluded:tool" in transforms
+ assert not any(t.startswith("router:excluded:lossless") for t in transforms)
+
+
+def test_read_json_edit_anchor_survives(tokenizer):
+ """The exact failure this protects: an Edit anchor copied out of a Read.
+
+ `old_string` is a verbatim slice of the pretty-printed file. Before the fix
+ the model saw minified JSON, so the anchor it could construct was not a
+ substring of the file on disk and `Edit` missed.
+ """
+ anchor = ' "users": [\n {\n "id": 0,'
+ assert anchor in JSON # the anchor is real on disk
+ shown, _ = _run(JSON, "Read", tokenizer)
+ assert anchor in shown
+
+
+def test_read_is_still_cross_turn_deduped(tokenizer):
+ """The deliberate line between the two protection sets — hold it.
+
+ Read is byte-exact against the FOLD, not blanket-verbatim. The one-line
+ alternative (adding Read to DEFAULT_VERBATIM_EXCLUDE_TOOLS, next to `view`)
+ would also switch off cross-turn dedup, which is worth ~66% of the tokens on
+ a file read three times — the largest Read-side saving there is, and unlike
+ the fold it does not destroy the bytes: keep-earliest guarantees the first,
+ unrewritten copy is still in the window for the model to copy its anchor
+ from. If someone later "simplifies" the two sets into one, this fails.
+ """
+ config = ContentRouterConfig()
+ config.enable_cross_turn_dedup = True
+ router = ContentRouter(config)
+ messages = []
+ for k in range(3):
+ messages.append(
+ {
+ "role": "assistant",
+ "tool_calls": [{"id": f"c{k}", "function": {"name": "Read", "arguments": "{}"}}],
+ }
+ )
+ messages.append({"role": "tool", "tool_call_id": f"c{k}", "content": CODE})
+ result = router.apply(messages, tokenizer, compress_user_messages=True)
+ outs = [m["content"] for m in result.messages if m.get("role") == "tool"]
+ assert outs[0] == CODE # keep-earliest: the anchor copy is never rewritten
+ assert len(outs[2]) < len(CODE) # …and the later repeats still fold to pointers
+
+
# --- pluggable lossless provider seam ---------------------------------------
@@ -150,6 +248,31 @@ def test_registered_provider_is_authoritative():
assert _compact(GREP) is None
+def test_byte_exact_read_gate_runs_before_the_provider_seam(tokenizer):
+ """The read gate is OSS's own guarantee, not something a provider can opt out of.
+
+ An external provider is contractually only "information-preserving" (see
+ transforms/lossless_provider.py) — that admits json-min, which is exactly the
+ rewrite that misses the Edit. And the seam hands over `content` with no tool
+ name, so a provider *cannot* recognise a read and protect it itself. So the
+ gate sits in front of the seam: a read is never offered to a provider at all.
+ Every other excluded tool still reaches it, unchanged — the seam's reach
+ narrows for file reads only.
+ """
+ seen: list[str] = []
+ set_lossless_provider(lambda content: (seen.append(content), None)[1])
+
+ for tool in ("Read", "read"):
+ seen.clear()
+ _run(GREP, tool, tokenizer)
+ assert seen == [], f"{tool} content was handed to the provider"
+
+ for tool in ("Grep", "grep", "Glob", "Write", "Edit"):
+ seen.clear()
+ _run(GREP, tool, tokenizer)
+ assert seen, f"provider lost reach for {tool}"
+
+
def test_provider_exception_falls_back_to_builtin():
def boom(content):
raise RuntimeError("provider blew up")
diff --git a/tests/test_openai_responses_compression_units.py b/tests/test_openai_responses_compression_units.py
index 863e91272..264fdfe68 100644
--- a/tests/test_openai_responses_compression_units.py
+++ b/tests/test_openai_responses_compression_units.py
@@ -1,8 +1,11 @@
from __future__ import annotations
+import json
import threading
from types import MethodType, SimpleNamespace
+import pytest
+
from headroom.proxy.handlers import openai as openai_handler
from headroom.proxy.handlers.openai import OpenAIHandlerMixin
from headroom.transforms.compression_units import UnitCompressionResult
@@ -824,6 +827,44 @@ def test_openai_responses_adapter_losslessly_folds_excluded_grep_output_content_
assert folded_list[2]["refusal"] == "I cannot process this request"
[email protected]("tool", ["read", "Read"])
[email protected]("as_content_part", [False, True], ids=["plain", "content_part"])
+def test_openai_responses_adapter_never_folds_a_file_read(tool, as_content_part):
+ """A file read stays byte-exact on the Responses wire too.
+
+ This is the Codex wire, where `read` genuinely returns raw file bytes rather
+ than Claude Code's `cat -n` rendering — so it is the shape where folding a
+ read really does destroy the `Edit(old_string=…)` anchor the model is about
+ to type. See DEFAULT_BYTE_EXACT_EXCLUDE_TOOLS. The grep folds above must keep
+ working; only reads opt out.
+ """
+ router = ContentRouter()
+ handler = _handler_with_router(router)
+ # Pretty-printed JSON: json-min is the fold that used to eat this.
+ file_bytes = json.dumps(
+ {"deps": [{"name": f"pkg{i}", "version": "1.0.0"} for i in range(40)]}, indent=2
+ )
+ output = [{"type": "output_text", "text": file_bytes}] if as_content_part else file_bytes
+ payload = {
+ "model": "gpt-5",
+ "input": [
+ {"type": "function_call", "call_id": "call_1", "name": tool, "arguments": "{}"},
+ {"type": "function_call_output", "call_id": "call_1", "output": output},
+ ],
+ }
+
+ new_payload, _modified, _saved, transforms, _units, _chain, _attempted = (
+ handler._compress_openai_responses_live_text_units_with_router(
+ payload,
+ model="gpt-5",
+ request_id=f"req_read_verbatim_{tool}_{as_content_part}",
+ )
+ )
+
+ assert "router:excluded:lossless" not in transforms
+ assert new_payload["input"][1]["output"] == output
+
+
def test_openai_responses_adapter_excludes_tool_case_insensitively_with_debug(monkeypatch):
"""Excluded match is case-insensitive, and the debug path stays exercised.