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(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.py
index 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"] += 1
continue
- # 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"] += 1
continue
- # 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 — recovery
diff --git a/tests/test_content_router_tool_role_reversibility.py b/tests/test_content_router_tool_role_reversibility.py
index 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_SUMMARY
diff --git a/tests/test_transforms_content_router.py b/tests/test_transforms_content_router.py
index 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"] == recoverable
def test_unknown_role_text_blocks_skipped_for_safety(