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(cache): count a tool_result with no text as replayable in the frozen prefix (#4523)

gglucassfba09f674c8a
diff --git a/headroom/cache/compression_cache.py b/headroom/cache/compression_cache.py
index dcbe0c0ee..a135d7b16 100644
--- a/headroom/cache/compression_cache.py
+++ b/headroom/cache/compression_cache.py
@@ -76,6 +76,22 @@ def _extract_tool_result_content(msg: dict) -> str | None:
return None
+def _carries_tool_result_text(msg: dict) -> bool:
+ """Whether any tool result in ``msg`` holds text (both formats)."""
+ if msg.get("role") == "tool":
+ results = [msg.get("content")]
+ else:
+ results = [
+ b.get("content")
+ for b in msg.get("content") or []
+ if isinstance(b, dict) and b.get("type") == "tool_result"
+ ]
+ return any(
+ isinstance(c, str) or (isinstance(c, list) and _extract_text_from_blocks(c) is not None)
+ for c in results
+ )
+
+
def _swap_tool_result_content(msg: dict, new_content: str) -> dict:
"""Deep copy msg and replace tool result content with new_content."""
new_msg = copy.deepcopy(msg)
@@ -294,9 +310,10 @@ class CompressionCache:
"""Count consecutive stable messages from the start.
A message is stable if it is a plain user/assistant/system message,
- an assistant message with tool_use blocks, or a tool_result whose
- content hash is already in the cache. The first unstable tool_result
- (cache miss) stops the count.
+ an assistant message with tool_use blocks, a tool_result whose
+ content hash is already in the cache, or a tool_result with no text
+ (nothing to replay). The first unstable tool_result (cache miss)
+ stops the count.
The trailing message is *always* excluded from the frozen prefix
(cap of ``len(messages) - 1``). The trailing message represents
@@ -319,9 +336,15 @@ class CompressionCache:
h = self.content_hash(content)
if h not in self._cache and h not in self._stable_hashes:
break
- else:
- # tool_result with non-string content; treat as unstable
+ elif _carries_tool_result_text(msg):
+ # Text after a textless first tool_result: the cache
+ # keys a message by its first one, so this text was
+ # never stored and cannot be byte-replayed.
break
+ # A tool_result with no text at all (a ToolSearch
+ # tool_reference list, an image) gives the cache nothing
+ # to replay, so it is stable. As a miss it stopped the
+ # count for the rest of the session.
# Regular user/assistant/system messages and assistant+tool_use
# are always stable — fall through.
count += 1
diff --git a/tests/test_compression_cache.py b/tests/test_compression_cache.py
index 3a8f04efe..4859ff770 100644
--- a/tests/test_compression_cache.py
+++ b/tests/test_compression_cache.py
@@ -310,6 +310,60 @@ class TestCompressionCacheFrozenCount:
# count = 3, then capped at len-1 = 2 (live-zone reservation).
assert cache.compute_frozen_count(messages) == 2
+ @pytest.mark.parametrize(
+ "blocks",
+ [
+ [{"type": "tool_reference", "tool_name": "mcp__notes__search"}],
+ [
+ {
+ "type": "image",
+ "source": {"type": "base64", "media_type": "image/png", "data": "iVBO"},
+ }
+ ],
+ [],
+ ],
+ ids=["tool-reference", "image", "empty"],
+ )
+ def test_tool_result_without_text_does_not_stop_frozen(
+ self, cache: CompressionCache, blocks: list
+ ) -> None:
+ """Claude Code's ToolSearch answers with tool_reference blocks only. The
+ cache has nothing to replay for such a result; as a miss it stopped the
+ count at that message for the rest of the session."""
+ messages = [
+ {"role": "user", "content": "hello"},
+ {
+ "role": "user",
+ "content": [{"type": "tool_result", "tool_use_id": "t1", "content": blocks}],
+ },
+ {"role": "assistant", "content": "found it"},
+ {"role": "user", "content": "follow up"},
+ ]
+ assert cache.compute_frozen_count(messages) == 3
+
+ def test_text_beside_a_textless_tool_result_still_stops_frozen(
+ self, cache: CompressionCache
+ ) -> None:
+ """Parallel calls put several tool_results in one message, and the cache
+ keys it by the first. Text after a textless first result was never
+ stored, so it cannot be replayed."""
+ messages = [
+ {"role": "user", "content": "hello"},
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "tool_result",
+ "tool_use_id": "t1",
+ "content": [{"type": "tool_reference", "tool_name": "mcp__notes__search"}],
+ },
+ {"type": "tool_result", "tool_use_id": "t2", "content": "uncached output"},
+ ],
+ },
+ {"role": "user", "content": "follow up"},
+ ]
+ assert cache.compute_frozen_count(messages) == 1
+
def test_update_from_result_identical_content_marks_stable(
self, cache: CompressionCache
) -> None:
diff --git a/tests/test_session_engine.py b/tests/test_session_engine.py
index 148d789fe..9e5f6553e 100644
--- a/tests/test_session_engine.py
+++ b/tests/test_session_engine.py
@@ -89,6 +89,29 @@ def test_proxy_policy_clamps_by_cache_count() -> None:
assert prep.frozen_message_count == 3
+def test_proxy_policy_follows_the_tracker_past_a_tool_search_result() -> None:
+ """A ToolSearch result holds only tool_reference blocks. It used to stop
+ the cache count, so the freeze sat there for the whole session and the
+ pipeline re-ran everything after it on every turn."""
+ cache = CompressionCache()
+ search = {
+ "role": "user",
+ "content": [
+ {
+ "type": "tool_result",
+ "tool_use_id": "ts",
+ "content": [{"type": "tool_reference", "tool_name": "mcp__notes__search"}],
+ }
+ ],
+ }
+ messages = [{"role": "user", "content": "find the notes tool"}, search]
+ messages += [{"role": "assistant", "content": f"step {i}"} for i in range(6)]
+ messages.append({"role": "user", "content": "next"})
+
+ prep = prepare_turn(cache, messages, policy=FREEZE_POLICY_CONFIRMED_CLAMP, tracker_frozen=8)
+ assert prep.frozen_message_count == 8
+
+
def test_proxy_policy_clamps_by_tracker() -> None:
"""Local state could replay 3, but the provider only confirmed 1: content
past the confirmed prefix stays compressible (the #327 posture)."""