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(router): gate block-form tool output against cached lossy results (#4504)
Gaurav Dubeye4a60ed72f6e
diff --git a/headroom/transforms/content_router.py b/headroom/transforms/content_router.pyindex d8838af2f..708a68cb3 100644--- a/headroom/transforms/content_router.py+++ b/headroom/transforms/content_router.py@@ -8109,11 +8109,14 @@ class ContentRouter(Transform):route_counts["already_compressed"] += 1continue- # Two-tier compression cache → shared helper+ # Two-tier compression cache → shared helper. Tool output is+ # gated (#1307), so it keys into the gated namespace like the+ # string path: an ungated entry for the same bytes must not+ # answer this lookup before the gate runs (#4477).compressed_content, was_compressed = self._compress_block_content(content=tool_text,content_key=self._content_cache_key(- tool_text, bias=bias, context=block_context+ tool_text, bias=bias, context=block_context, gated=True),context=block_context,bias=bias,@@ -8204,11 +8207,15 @@ class ContentRouter(Transform):route_counts["already_compressed"] += 1continue- # Two-tier compression cache → shared helper+ # Two-tier compression cache → shared helper. A role:"tool" /+ # "function" message in block-list form is tool output, the+ # same ground truth as its string form, so it gets the same+ # #1307 gate and the gated cache namespace (#4477).+ enforce_reversibility = role in ("tool", "function")compressed_content, _was_compressed = self._compress_block_content(content=text_content,content_key=self._content_cache_key(- text_content, bias=1.0, context=context+ text_content, bias=1.0, context=context, gated=enforce_reversibility),context=context,bias=1.0,@@ -8219,6 +8226,7 @@ class ContentRouter(Transform):compressed_details=compressed_details,strategy_label="text_block",details_prefix="text",+ enforce_reversibility=enforce_reversibility,)if compressed_content is not None:new_blocks.append({**block, "text": compressed_content})@@ -8398,8 +8406,9 @@ class ContentRouter(Transform):# (kompress/text/code/html) that emitted no CCR retrieve marker is# unrecoverable, so the agent would act on a fabricated summary# (#1307). The string/`role=="tool"` path guards this; mirror it- # here for tool_result blocks (never cached, so the Tier-2 path- # above can't serve a poisoned entry).+ # here for tool output in block form. Callers that enforce the gate+ # key with ``gated=True``, so the Tier-2 path above never serves+ # them an ungated entry for the same bytes.## EXCEPTION: no-CCR mode (config.ccr_inject_marker=False). Here the# operator has *deliberately* disabled retrieval markers — recoverydiff --git a/tests/test_content_router_tool_role_reversibility.py b/tests/test_content_router_tool_role_reversibility.pyindex b5f9c4f5b..4dbb85aac 100644--- a/tests/test_content_router_tool_role_reversibility.py+++ b/tests/test_content_router_tool_role_reversibility.py@@ -140,3 +140,102 @@ def test_tool_role_structured_strategies_accepted(monkeypatch, strategy) -> None"""Structured strategies are lossless/self-marking -> not gated, compressed kept."""result = _run(monkeypatch, _tool_msg(GREP_OUTPUT), strategy, LOSSY_SUMMARY)assert result.messages[0]["content"] == LOSSY_SUMMARY+++# --- Block-form tool output (#4477) -----------------------------------------+#+# Tool output also arrives as content blocks: an Anthropic ``tool_result`` block,+# or a role="tool"/"function" message whose content is a list of text blocks.+# Both shapes must get the same #1307 gate as the string path, and must read and+# write the gated cache namespace so an ungated entry for byte-identical text+# (an assistant message, a user text block) is never served as tool output.+++def _text_blocks_msg(role: str, content: str) -> dict:+ msg: dict = {"role": role, "content": [{"type": "text", "text": content}]}+ if role == "tool":+ msg["tool_call_id"] = "call_bash_1"+ else:+ msg["name"] = "qualification_tool"+ return msg+++def _tool_result_msg(content: str) -> dict:+ return {+ "role": "user",+ "content": [{"type": "tool_result", "tool_use_id": "toolu_bash_1", "content": content}],+ }+++def _apply(router: ContentRouter, message: dict, **kwargs):+ return router.apply(+ [message], _WordTokenizer(), protect_recent=0, protect_analysis_context=False, **kwargs+ )++[email protected]("role", ["tool", "function"])+def test_tool_role_text_blocks_lossy_unmarked_kept_verbatim(monkeypatch, role) -> None:+ """List-of-text tool output gets the gate the string form already has."""+ result = _run(+ monkeypatch,+ _text_blocks_msg(role, GREP_OUTPUT),+ CompressionStrategy.KOMPRESS,+ LOSSY_SUMMARY,+ )+ assert result.messages[0]["content"] == [{"type": "text", "text": GREP_OUTPUT}]++[email protected]("role", ["tool", "function"])+def test_tool_role_text_blocks_lossy_with_ccr_marker_accepted(monkeypatch, role) -> None:+ """A recoverable (marked) result still compresses list-of-text tool output."""+ result = _run(+ monkeypatch,+ _text_blocks_msg(role, GREP_OUTPUT),+ CompressionStrategy.KOMPRESS,+ CCR_MARKER_SUMMARY,+ )+ assert result.messages[0]["content"] == [{"type": "text", "text": CCR_MARKER_SUMMARY}]+++def test_tool_result_block_not_served_an_ungated_cache_entry(monkeypatch) -> None:+ """An unmarked lossy result cached for ungated text must not reach a tool_result.++ The assistant text-block path is not gated (assistant prose is not tool ground+ truth), so it caches the lossy summary. A later tool_result carrying the same+ bytes must miss that entry and be gated, not take the cache hit.+ """+ router = ContentRouter()+ monkeypatch.setattr(+ router,+ "compress",+ lambda *a, **k: _force_result(CompressionStrategy.KOMPRESS, LOSSY_SUMMARY),+ )+ first = _apply(+ router,+ {"role": "assistant", "content": [{"type": "text", "text": GREP_OUTPUT}]},+ compress_assistant_text_blocks=True,+ )+ assert first.messages[0]["content"][0]["text"] == LOSSY_SUMMARY # ungated: compressed++ second = _apply(router, _tool_result_msg(GREP_OUTPUT))+ assert second.messages[0]["content"][0]["content"] == GREP_OUTPUT+++def test_gated_tool_result_skip_does_not_suppress_ungated_text(monkeypatch) -> None:+ """The reverse direction: a gate skip recorded for tool output stays in the+ gated namespace, so ungated text with the same bytes still compresses."""+ router = ContentRouter()+ monkeypatch.setattr(+ router,+ "compress",+ lambda *a, **k: _force_result(CompressionStrategy.KOMPRESS, LOSSY_SUMMARY),+ )+ first = _apply(router, _tool_result_msg(GREP_OUTPUT))+ assert first.messages[0]["content"][0]["content"] == GREP_OUTPUT # gated: kept++ second = _apply(+ router,+ {"role": "assistant", "content": [{"type": "text", "text": GREP_OUTPUT}]},+ compress_assistant_text_blocks=True,+ )+ assert second.messages[0]["content"][0]["text"] == LOSSY_SUMMARYdiff --git a/tests/test_transforms_content_router.py b/tests/test_transforms_content_router.pyindex 3c1909dae..69a7f0d86 100644--- a/tests/test_transforms_content_router.py+++ b/tests/test_transforms_content_router.py@@ -1503,8 +1503,18 @@ def test_system_text_blocks_skipped_when_skip_system_true(def test_tool_role_text_blocks_compressed_by_default(monkeypatch: pytest.MonkeyPatch,) -> None:- router = _make_router_with_mock_compress(monkeypatch)+ router = ContentRouter(ContentRouterConfig())long_text = "T" * 1000+ recoverable = "T" * 100 + " [compressed] <<ccr:9f3a21>>"+ monkeypatch.setattr(+ router,+ "compress",+ lambda *a, **k: SimpleNamespace(+ compressed=recoverable,+ compression_ratio=0.5,+ strategy_used=CompressionStrategy.TEXT,+ ),+ )msg = {"role": "tool", "content": [{"type": "text", "text": long_text}]}result = router._process_content_blocks(msg,@@ -1514,8 +1524,9 @@ def test_tool_role_text_blocks_compressed_by_default(set(),set(),)- # tool role ≈ tool output — compress freely- assert "[compressed]" in result["content"][0]["text"]+ # tool role ≈ tool output — not protected like user/system text; a+ # recoverable result is accepted (an unmarked lossy one is gated, #1307).+ assert result["content"][0]["text"] == recoverabledef test_unknown_role_text_blocks_skipped_for_safety(