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(proxy): repair client-side tool_search tool_reference blocks (#3443)

gglucassf12e3fbeed52
diff --git a/headroom/proxy/helpers.py b/headroom/proxy/helpers.py
index 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 message
are 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[Any
neutralize_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:
continue
names = _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[Any
if 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[Any
removed += 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.py
index 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