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.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
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.pyindex 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 += 1diff --git a/tests/test_compression_cache.py b/tests/test_compression_cache.pyindex 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.pyindex 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: contentpast the confirmed prefix stays compressible (the #327 posture)."""