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): repair client-side tool_search tool_reference blocks (#3443)
gglucassf12e3fbeed52
diff --git a/headroom/proxy/helpers.py b/headroom/proxy/helpers.pyindex 9ccadbb8d..498514149 100644--- a/headroom/proxy/helpers.py+++ b/headroom/proxy/helpers.py@@ -3946,6 +3946,11 @@ def inject_tool_search_deferral(# ---------------------------------------------------------------------------_TOOL_SEARCH_RESULT_TYPE = "tool_search_tool_result"+# A client-side tool-search result (a plain ``tool_result`` carrying+# ``tool_reference`` blocks) that is left with no resolvable references keeps+# this text as its content, so its paired ``tool_use`` stays valid -- dropping+# the block outright would orphan the tool_use (which 400s on its own).+_CLIENT_TOOL_REF_PLACEHOLDER = "[tool reference no longer available]"def _tool_search_reference_names(content: Any) -> list[str]:@@ -3980,10 +3985,12 @@ _TOOL_SEARCH_PLACEHOLDER_BLOCK: dict[str, Any] = {def strip_unsupported_tool_search_blocks(messages: Any, tools: Any) -> tuple[Any, int]:"""Neutralize tool-search blocks this request's ``tools`` array cannot support.- A block pair is unsupportable when the request carries no ``tool_search_tool_*``- tool, or when a ``tool_reference`` names a tool absent from ``tools`` — the two- shapes Anthropic rejects. Both the ``tool_search_tool_result`` and its paired- ``server_tool_use`` are handled (an orphan of either 400s on its own).+ Server-side search block pairs require a matching search mechanism and+ referenced tools in the outbound tools array. Unsupported pairs are+ replaced in place. Client-side ``tool_result`` references need only their+ target definitions: missing references are removed from the nested result,+ with ``_CLIENT_TOOL_REF_PLACEHOLDER`` retaining an otherwise empty result+ so its paired ``tool_use`` is not orphaned.Replace in place rather than remove (#3456). The block indexes of a messageare load-bearing: ``thinking_block_fingerprint`` keys a signed thinking block@@ -4033,8 +4040,41 @@ def strip_unsupported_tool_search_blocks(messages: Any, tools: Any) -> tuple[Anyneutralize_indexes: set[int] = set()orphaned_ids: set[str] = set()+ rewrites: dict[int, Any] = {}for index, block in enumerate(content):- if not isinstance(block, dict) or block.get("type") != _TOOL_SEARCH_RESULT_TYPE:+ if not isinstance(block, dict):+ continue+ block_type = block.get("type")+ # Client-side shape: a plain tool_result carrying tool_reference+ # blocks. Keep resolvable references (deferred-but-present included);+ # drop the unsupportable ones. If none survive, swap the content for+ # a placeholder so the paired tool_use is not orphaned.+ if block_type == "tool_result" and isinstance(block.get("content"), list):+ inner = block["content"]+ if any(isinstance(b, dict) and b.get("type") == "tool_reference" for b in inner):+ kept_inner: list[Any] = []+ dropped = 0+ for b in inner:+ if isinstance(b, dict) and b.get("type") == "tool_reference":+ # Validated against the available definitions ONLY.+ # A built-in tool_search_tool_* is deliberately not+ # required: Anthropic supports a custom client-side+ # search that returns tool_reference blocks from a+ # plain tool_use/tool_result pair, referencing the+ # top-level tools array. Gating on the server tool+ # deleted those valid references.+ name = b.get("tool_name") or b.get("name")+ if name is not None and str(name) not in available:+ dropped += 1+ continue+ kept_inner.append(b)+ if dropped:+ new_block = dict(block)+ new_block["content"] = kept_inner or _CLIENT_TOOL_REF_PLACEHOLDER+ rewrites[index] = new_block+ removed += dropped+ continue+ if block_type != _TOOL_SEARCH_RESULT_TYPE:continuenames = _tool_search_reference_names(block.get("content"))if has_search_tool and all(name in available for name in names):@@ -4053,7 +4093,7 @@ def strip_unsupported_tool_search_blocks(messages: Any, tools: Any) -> tuple[Anyif str(block.get("id", "")) in orphaned_ids or (is_search_call and not has_search_tool):neutralize_indexes.add(index)- if not neutralize_indexes:+ if not neutralize_indexes and not rewrites:out.append(message)continue@@ -4061,7 +4101,9 @@ def strip_unsupported_tool_search_blocks(messages: Any, tools: Any) -> tuple[Anyremoved += len(neutralize_indexes)repaired = dict(message)repaired["content"] = [- dict(_TOOL_SEARCH_PLACEHOLDER_BLOCK) if index in neutralize_indexes else block+ dict(_TOOL_SEARCH_PLACEHOLDER_BLOCK)+ if index in neutralize_indexes+ else rewrites.get(index, block)for index, block in enumerate(content)]out.append(repaired)diff --git a/tests/test_issue_746_tool_search.py b/tests/test_issue_746_tool_search.pyindex cb6f83314..dae480a60 100644--- a/tests/test_issue_746_tool_search.py+++ b/tests/test_issue_746_tool_search.py@@ -397,6 +397,7 @@ def test_core_tools_match_leading_underscore_namespace() -> None:# ---------------------------------------------------------------------------from headroom.proxy.helpers import ( # noqa: E402+ _CLIENT_TOOL_REF_PLACEHOLDER,strip_unsupported_tool_search_blocks,)@@ -516,6 +517,78 @@ def test_repair_strips_search_history_when_only_the_tool_is_missing() -> None:assert removed == 2+# ---------------------------------------------------------------------------+# Client-side tool search: Claude Code (and any custom implementation) stores+# discovered tools as tool_reference blocks inside a PLAIN tool_result, not a+# tool_search_tool_result. Anthropic validates those references too, so a stale+# one (e.g. an MCP server that disconnected mid-session) 400s the same way.+# ---------------------------------------------------------------------------+++def _client_side_transcript(*referenced: str) -> list[dict]:+ return [+ {+ "role": "assistant",+ "content": [+ {"type": "text", "text": "Searching."},+ {"type": "tool_use", "id": "toolu_cs", "name": "ToolSearch", "input": {"q": "x"}},+ ],+ },+ {+ "role": "user",+ "content": [+ {+ "type": "tool_result",+ "tool_use_id": "toolu_cs",+ "content": [+ {"type": "tool_reference", "tool_name": name} for name in referenced+ ],+ }+ ],+ },+ ]+++def test_repair_neutralizes_client_side_reference_to_absent_tool() -> None:+ # Absent tool: drop the reference, and because it was the whole result,+ # replace the content with a placeholder so the paired tool_use is kept+ # (an orphaned tool_use 400s on its own).+ messages, removed = strip_unsupported_tool_search_blocks(+ _client_side_transcript("mcp__x__ghost"),+ [_SEARCH_TOOL, {"name": "Read", "input_schema": {}}],+ )+ assert removed == 1+ assert messages[0]["content"][1]["type"] == "tool_use" # search call preserved+ result = messages[1]["content"][0]+ assert result["type"] == "tool_result"+ assert result["content"] == _CLIENT_TOOL_REF_PLACEHOLDER+++def test_repair_keeps_client_side_reference_to_present_deferred_tool() -> None:+ # A deferred-but-present tool is valid; keep it and return by identity.+ transcript = _client_side_transcript("CronCreate")+ messages, removed = strip_unsupported_tool_search_blocks(+ transcript,+ [_SEARCH_TOOL, {"name": "CronCreate", "input_schema": {}, "defer_loading": True}],+ )+ assert removed == 0+ assert messages is transcript+++def test_repair_keeps_present_client_side_reference_and_drops_absent() -> None:+ # Mixed result: keep the present reference, drop only the absent one.+ messages, removed = strip_unsupported_tool_search_blocks(+ _client_side_transcript("CronCreate", "mcp__x__ghost"),+ [_SEARCH_TOOL, {"name": "CronCreate", "input_schema": {}, "defer_loading": True}],+ )+ assert removed == 1+ refs = messages[1]["content"][0]["content"]+ names = [+ r["tool_name"] for r in refs if isinstance(r, dict) and r.get("type") == "tool_reference"+ ]+ assert names == ["CronCreate"]++# ---------------------------------------------------------------------------# Regression tests for the direct-Anthropic regression reported in PR #2539# comment #5280259642: "Tool reference 'tool_search_tool_regex' not found in@@ -654,6 +727,39 @@ def test_repair_drops_when_referenced_tool_absent_despite_search_tool_present()assert removed == 2+def test_repair_keeps_custom_client_side_references_without_a_builtin_search_tool() -> None:+ """Anthropic supports a custom client-side search: a normal tool_use /+ tool_result pair returning tool_reference blocks that point at the+ top-level tools array. No ``tool_search_tool_*`` server tool is involved,+ so gating the client-side branch on one deleted every valid reference."""+ transcript = _client_side_transcript("Calendar")+ messages, removed = strip_unsupported_tool_search_blocks(+ transcript,+ [+ {"name": "ToolSearch", "input_schema": {}},+ {"name": "Calendar", "input_schema": {}, "defer_loading": True},+ ],+ )+ assert removed == 0+ assert messages is transcript+++def test_repair_still_drops_an_absent_reference_without_a_builtin_search_tool() -> None:+ messages, removed = strip_unsupported_tool_search_blocks(+ _client_side_transcript("Calendar", "mcp__x__ghost"),+ [+ {"name": "ToolSearch", "input_schema": {}},+ {"name": "Calendar", "input_schema": {}, "defer_loading": True},+ ],+ )+ assert removed == 1+ refs = messages[1]["content"][0]["content"]+ names = [+ r["tool_name"] for r in refs if isinstance(r, dict) and r.get("type") == "tool_reference"+ ]+ assert names == ["Calendar"]++def test_repair_does_not_move_signed_thinking_blocks() -> None:# Production failure (#3456): the unsupportable block sat in the SAME# assistant message as signed thinking blocks. Removing it moved the