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(proxy/anthropic): repair headroom_retrieve history references the tools array cannot support (#2876)
Abhay Singh7de35739c61b
diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.pyindex 7afc106c6..4abb25b41 100644--- a/headroom/proxy/handlers/anthropic.py+++ b/headroom/proxy/handlers/anthropic.py@@ -2737,6 +2737,28 @@ class AnthropicHandlerMixin:_ts_stripped,)+ # CCR retrieve history repair (#2814). Run beside the tool-search+ # repair and after both normal CCR injection and turn hooks, so it+ # validates against the final outbound tools array. A side-request+ # that does not declare headroom_retrieve cannot retain historical+ # tool_use/tool_result references that Anthropic would reject.+ from headroom.proxy.helpers import strip_unsupported_ccr_retrieve_blocks++ _ccr_repaired, _ccr_neutralized = strip_unsupported_ccr_retrieve_blocks(+ body.get("messages"), body.get("tools")+ )+ if _ccr_neutralized:+ body["messages"] = _ccr_repaired+ optimized_messages = _ccr_repaired+ body_mutation_tracker.mark_mutated("ccr_retrieve_history_repair")+ transforms_applied.append(f"router:ccr_retrieve_repair:{_ccr_neutralized}blocks")+ logger.info(+ "[%s] CCR: neutralized %d headroom_retrieve history block(s) "+ "(tools array does not declare the tool this turn)",+ request_id,+ _ccr_neutralized,+ )+# Consistency: report tok_before/tok_after with ONE tokenizer. The pipeline# and the handler use different token estimators, and cache-mode branches# can leave original_tokens (handler, line ~1049) and optimized_tokensdiff --git a/headroom/proxy/helpers.py b/headroom/proxy/helpers.pyindex 6ea06e19d..02a2f3c77 100644--- a/headroom/proxy/helpers.py+++ b/headroom/proxy/helpers.py@@ -3027,6 +3027,126 @@ def strip_unsupported_tool_search_blocks(messages: Any, tools: Any) -> tuple[Anyreturn (out, removed) if changed else (messages, 0)+def _ccr_result_as_text(block: dict[str, Any]) -> str:+ """Flatten a ``tool_result`` block's content to plain text, preserving what+ the model already saw. Falls back to a short placeholder when there is no+ textual content to keep."""+ content = block.get("content")+ if isinstance(content, str) and content.strip():+ return content+ if isinstance(content, list):+ parts = [+ b.get("text", "")+ for b in content+ if isinstance(b, dict) and b.get("type") == "text" and b.get("text")+ ]+ joined = "\n".join(part for part in parts if part)+ if joined.strip():+ return joined+ return "[headroom_retrieve result omitted]"+++def strip_unsupported_ccr_retrieve_blocks(messages: Any, tools: Any) -> tuple[Any, int]:+ """Neutralize ``headroom_retrieve`` history references the outbound ``tools``+ array cannot support.++ Claude Code replays one transcript across requests that carry different+ ``tools`` arrays, and Anthropic validates every history ``tool_use`` against+ the array of the request at hand. A passthrough side-request (the prompt-type+ Stop hook evaluator, ``/compact``) that the proxy forwards without declaring+ ``headroom_retrieve`` then 400s on a historical ``tool_use`` that names it --+ the CCR sibling of the tool-search history repair (#2814 / #2807). This is+ belt-and-braces with the injection-side fixes: they keep the tool available+ where it belongs; this makes the 400 structurally impossible where it cannot.++ When the request does NOT declare ``headroom_retrieve``, replace each+ ``headroom_retrieve`` ``tool_use`` block and its paired ``tool_result`` with a+ text block, so no dangling reference survives. Neutralize rather than drop:+ CCR's ``tool_use`` (an assistant turn) and its ``tool_result`` (the next user+ turn) live in DIFFERENT messages, so removing a message could leave two+ same-role messages adjacent and break Anthropic's user/assistant alternation.+ Replacing blocks in place keeps every message and role intact, and preserves+ the retrieved text the model already saw.++ Returns ``(messages, blocks_neutralized)``, and the ORIGINAL ``messages``+ object when nothing changed -- callers rely on identity to skip the write-back.+ """+ from headroom.ccr.tool_injection import CCR_TOOL_NAME++ if not isinstance(messages, list):+ return messages, 0++ tool_list = tools if isinstance(tools, list) else []+ available = {str(t["name"]) for t in tool_list if isinstance(t, dict) and t.get("name")}+ # The tool is declared this turn (e.g. the main loop, or sticky re-injection),+ # so its history references resolve. Nothing to repair.+ if CCR_TOOL_NAME in available:+ return messages, 0++ # First pass: collect the ids of headroom_retrieve tool_use blocks so their+ # paired tool_result blocks (in a later user turn) can be matched.+ retrieve_ids: set[str] = set()+ for message in messages:+ content = message.get("content") if isinstance(message, dict) else None+ if not isinstance(content, list):+ continue+ for block in content:+ if (+ isinstance(block, dict)+ and block.get("type") == "tool_use"+ and block.get("name") == CCR_TOOL_NAME+ ):+ use_id = block.get("id")+ if use_id:+ retrieve_ids.add(str(use_id))++ if not retrieve_ids:+ return messages, 0++ out: list[Any] = []+ neutralized = 0+ changed = False+ for message in messages:+ content = message.get("content") if isinstance(message, dict) else None+ if not isinstance(content, list):+ out.append(message)+ continue++ new_content: list[Any] = []+ touched = False+ for block in content:+ if isinstance(block, dict):+ if block.get("type") == "tool_use" and block.get("name") == CCR_TOOL_NAME:+ new_content.append(+ {+ "type": "text",+ "text": "[headroom_retrieve call omitted: tool not available this turn]",+ }+ )+ neutralized += 1+ touched = True+ continue+ if (+ block.get("type") == "tool_result"+ and str(block.get("tool_use_id", "")) in retrieve_ids+ ):+ new_content.append({"type": "text", "text": _ccr_result_as_text(block)})+ neutralized += 1+ touched = True+ continue+ new_content.append(block)++ if touched:+ changed = True+ repaired = dict(message)+ repaired["content"] = new_content+ out.append(repaired)+ else:+ out.append(message)++ return (out, neutralized) if changed else (messages, 0)++# ---------------------------------------------------------------------------# Server-side Tool Search injection — OpenAI Responses API (gpt-5.4+).#diff --git a/tests/test_ccr_retrieve_history_repair.py b/tests/test_ccr_retrieve_history_repair.pynew file mode 100644index 000000000..bbd840d95--- /dev/null+++ b/tests/test_ccr_retrieve_history_repair.py@@ -0,0 +1,119 @@+"""Regression tests for the CCR headroom_retrieve history repair (#2814).++A passthrough side-request (prompt-type Stop hook evaluator, /compact) replays a+transcript whose history contains a ``headroom_retrieve`` tool_use, but the+request's own ``tools`` array does not declare that tool. Anthropic 400s on the+dangling reference. The repair neutralizes those history blocks so the 400 is+structurally impossible, without breaking user/assistant alternation.+"""++from __future__ import annotations++from headroom.ccr.tool_injection import CCR_TOOL_NAME+from headroom.proxy.helpers import strip_unsupported_ccr_retrieve_blocks+++def _transcript_with_retrieve() -> list[dict]:+ return [+ {"role": "user", "content": [{"type": "text", "text": "read config"}]},+ {+ "role": "assistant",+ "content": [+ {"type": "text", "text": "Let me expand that."},+ {+ "type": "tool_use",+ "id": "toolu_ccr_1",+ "name": CCR_TOOL_NAME,+ "input": {"hash": "abc123def456abc123def456"},+ },+ ],+ },+ {+ "role": "user",+ "content": [+ {+ "type": "tool_result",+ "tool_use_id": "toolu_ccr_1",+ "content": "the full expanded config text",+ }+ ],+ },+ {"role": "assistant", "content": [{"type": "text", "text": "Done."}]},+ ]+++def test_noop_when_tool_is_declared() -> None:+ messages = _transcript_with_retrieve()+ tools = [{"name": CCR_TOOL_NAME}]+ out, n = strip_unsupported_ccr_retrieve_blocks(messages, tools)+ assert n == 0+ assert out is messages # identity: caller skips the write-back+++def test_noop_when_no_retrieve_history() -> None:+ messages = [+ {"role": "user", "content": [{"type": "text", "text": "hi"}]},+ {"role": "assistant", "content": [{"type": "text", "text": "hello"}]},+ ]+ out, n = strip_unsupported_ccr_retrieve_blocks(messages, tools=[])+ assert n == 0+ assert out is messages+++def test_neutralizes_retrieve_reference_when_tool_absent() -> None:+ messages = _transcript_with_retrieve()+ out, n = strip_unsupported_ccr_retrieve_blocks(messages, tools=[{"name": "Bash"}])++ assert n == 2 # tool_use + its paired tool_result+ # No dangling references survive anywhere.+ for message in out:+ for block in message["content"]:+ assert block.get("type") != "tool_use" or block.get("name") != CCR_TOOL_NAME+ assert not (+ block.get("type") == "tool_result" and block.get("tool_use_id") == "toolu_ccr_1"+ )++ # Message count and roles are unchanged (alternation intact).+ assert [m["role"] for m in out] == [m["role"] for m in messages]+ # The assistant's own text survives; the tool_use became a text block.+ assistant = out[1]["content"]+ assert assistant[0] == {"type": "text", "text": "Let me expand that."}+ assert assistant[1]["type"] == "text"+ # The retrieved result text is preserved, not dropped.+ assert out[2]["content"][0] == {+ "type": "text",+ "text": "the full expanded config text",+ }+++def test_leaves_foreign_tool_use_untouched() -> None:+ messages = [+ {+ "role": "assistant",+ "content": [+ {"type": "tool_use", "id": "toolu_bash_1", "name": "Bash", "input": {"cmd": "ls"}}+ ],+ },+ {+ "role": "user",+ "content": [+ {"type": "tool_result", "tool_use_id": "toolu_bash_1", "content": "file.txt"}+ ],+ },+ ]+ out, n = strip_unsupported_ccr_retrieve_blocks(messages, tools=[{"name": "Bash"}])+ assert n == 0+ assert out is messages+++def test_result_falls_back_to_placeholder_without_text() -> None:+ messages = [+ {+ "role": "assistant",+ "content": [{"type": "tool_use", "id": "t1", "name": CCR_TOOL_NAME, "input": {}}],+ },+ {"role": "user", "content": [{"type": "tool_result", "tool_use_id": "t1", "content": []}]},+ ]+ out, n = strip_unsupported_ccr_retrieve_blocks(messages, tools=[])+ assert n == 2+ assert out[1]["content"][0] == {"type": "text", "text": "[headroom_retrieve result omitted]"}diff --git a/tests/test_proxy/test_tool_search_repair_after_turn_hooks.py b/tests/test_proxy/test_tool_search_repair_after_turn_hooks.pyindex 30d495760..9d635fc1b 100644--- a/tests/test_proxy/test_tool_search_repair_after_turn_hooks.py+++ b/tests/test_proxy/test_tool_search_repair_after_turn_hooks.py@@ -21,12 +21,18 @@ pytest.importorskip("fastapi")from fastapi.testclient import TestClient+from headroom.ccr.tool_injection import CCR_TOOL_NAMEfrom headroom.proxy.server import ProxyConfig, create_appfrom headroom.proxy.turn_hooks import clear_turn_hooks, register_turn_hook_SEARCH_TOOL = {"type": "tool_search_tool_20250917", "name": "tool_search"}_GREP = {"name": "Grep", "description": "search files", "input_schema": {"type": "object"}}_READ = {"name": "Read", "description": "read a file", "input_schema": {"type": "object"}}+_CCR_TOOL = {+ "name": CCR_TOOL_NAME,+ "description": "retrieve compressed content",+ "input_schema": {"type": "object"},+}# A transcript that already carries a resolved tool-search round trip for `Grep`._POISONED_MESSAGES = [@@ -53,6 +59,31 @@ _POISONED_MESSAGES = [{"role": "user", "content": "now use it"},]+_CCR_POISONED_MESSAGES = [+ {"role": "user", "content": "expand the saved result"},+ {+ "role": "assistant",+ "content": [+ {+ "type": "tool_use",+ "id": "toolu_ccr_1",+ "name": CCR_TOOL_NAME,+ "input": {"hash": "abc123def456abc123def456"},+ }+ ],+ },+ {+ "role": "user",+ "content": [+ {+ "type": "tool_result",+ "tool_use_id": "toolu_ccr_1",+ "content": "the expanded result",+ }+ ],+ },+]+@pytest.fixture(autouse=True)def _clean_registry():@@ -77,7 +108,12 @@ class _InertHook:return None-def _run(hook) -> dict: # noqa: ANN001+def _run(+ hook, # noqa: ANN001+ *,+ messages: list[dict] = _POISONED_MESSAGES,+ tools: list[dict] | None = None,+) -> dict:"""POST a poisoned transcript through the handler, return the forwarded body."""captured: dict[str, object] = {}register_turn_hook(hook)@@ -123,8 +159,8 @@ def _run(hook) -> dict: # noqa: ANN001json={"model": "claude-sonnet-4-6","max_tokens": 64,- "messages": _POISONED_MESSAGES,- "tools": [_SEARCH_TOOL, _GREP, _READ],+ "messages": messages,+ "tools": tools or [_SEARCH_TOOL, _GREP, _READ],},)assert response.status_code == 200@@ -174,3 +210,30 @@ def test_repair_leaves_resolvable_history_alone_when_the_hook_keeps_the_tool() -assert _referenced_tool_names(forwarded) == ["Grep"]assert "tool_search_tool_result" in _block_types(forwarded)+++def test_ccr_repair_sees_the_tools_array_the_hook_left_behind() -> None:+ """CCR repair also runs after a hook removes headroom_retrieve."""+ forwarded = _run(+ _DropToolHook(CCR_TOOL_NAME),+ messages=_CCR_POISONED_MESSAGES,+ tools=[_CCR_TOOL, _READ],+ )++ assert CCR_TOOL_NAME not in [t.get("name") for t in forwarded["tools"]]+ assert "tool_use" not in _block_types(forwarded)+ assert "tool_result" not in _block_types(forwarded)+ assert forwarded["messages"][2]["content"] == [{"type": "text", "text": "the expanded result"}]+++def test_ccr_repair_leaves_resolvable_history_when_hook_keeps_tool() -> None:+ """CCR history remains structured when the final tools array declares it."""+ forwarded = _run(+ _InertHook(),+ messages=_CCR_POISONED_MESSAGES,+ tools=[_CCR_TOOL, _READ],+ )++ assert CCR_TOOL_NAME in [t.get("name") for t in forwarded["tools"]]+ assert "tool_use" in _block_types(forwarded)+ assert "tool_result" in _block_types(forwarded)