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): drop a tool_reference naming the search tool itself (#3172)

Serge ARADJb73adaa0ce36
diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.py
index 6e5a185d5..9424c7935 100644
--- a/headroom/proxy/handlers/anthropic.py
+++ b/headroom/proxy/handlers/anthropic.py
@@ -3251,7 +3251,27 @@ class AnthropicHandlerMixin:
# and the prefix is untouched) AND the turn hooks (a hook may rewrite the
# tools array, and repairing before it validated against a stale view).
# Nothing past this point mutates `body["tools"]` on the outbound path.
- from headroom.proxy.helpers import strip_unsupported_tool_search_blocks
+ from headroom.proxy.helpers import (
+ strip_unsupported_tool_search_blocks,
+ strip_unsupported_tool_search_references,
+ )
+
+ # The tools array is repaired first: it shrinks what a history
+ # tool_reference can resolve against, so the block repair below has to
+ # validate against the final view (same reason as the ORDERING note).
+ _ts_tools, _ts_refs_dropped = strip_unsupported_tool_search_references(
+ body.get("tools")
+ )
+ if _ts_refs_dropped:
+ body["tools"] = tools = _ts_tools
+ body_mutation_tracker.mark_mutated("tool_search_reference_repair")
+ transforms_applied.append(f"router:tool_search_ref_repair:{_ts_refs_dropped}refs")
+ logger.info(
+ "[%s] Tool search: dropped %d unresolvable tool_reference "
+ "entr(y/ies) naming a typed search tool",
+ request_id,
+ _ts_refs_dropped,
+ )
_ts_repaired, _ts_stripped = strip_unsupported_tool_search_blocks(
body.get("messages"), body.get("tools")
diff --git a/headroom/proxy/helpers.py b/headroom/proxy/helpers.py
index f24acac5f..61a982de2 100644
--- a/headroom/proxy/helpers.py
+++ b/headroom/proxy/helpers.py
@@ -4016,6 +4016,17 @@ _TOOL_SEARCH_RESULT_TYPE = "tool_search_tool_result"
_CLIENT_TOOL_REF_PLACEHOLDER = "[tool reference no longer available]"
+def _tool_entry_name(entry: dict[str, Any]) -> str | None:
+ """Return the name a tool-search entry carries, or ``None``.
+
+ Server-side blocks use ``tool_name``; be liberal about ``name``. The one
+ precedence rule for this file, so every reader agrees on an entry that
+ carries both keys.
+ """
+ name = entry.get("tool_name") or entry.get("name")
+ return str(name) if name else None
+
+
def _tool_search_reference_names(content: Any) -> list[str]:
"""Return the ``tool_reference`` names carried by a tool-search result block.
@@ -4028,13 +4039,64 @@ def _tool_search_reference_names(content: Any) -> list[str]:
names = []
for entry in entries:
if isinstance(entry, dict) and entry.get("type") == "tool_reference":
- # Server-side blocks use ``tool_name``; be liberal about ``name``.
- name = entry.get("tool_name") or entry.get("name")
+ name = _tool_entry_name(entry)
if name:
- names.append(str(name))
+ names.append(name)
return names
+def strip_unsupported_tool_search_references(tools: Any) -> tuple[Any, int]:
+ """Drop ``tool_reference`` entries in ``tools`` that name a typed search tool.
+
+ Anthropic occasionally returns ``tool_search_tool_regex`` as a hit inside its
+ own match-all result (empty ``input``). Claude Code adds every hit to the
+ session's loaded-tool set and replays it as a ``tool_reference`` in ``tools``
+ on later turns, so upstream then 400s with "Tool reference
+ 'tool_search_tool_regex' not found in available tools" — a typed search tool
+ is the search mechanism, never a reference target. The block repair below
+ cannot reach this: the poison is in the tools array, not the history, which
+ is why ``/compact`` does not clear it and the session stays dead.
+
+ Scoped to the search mechanisms this request actually carries: the names are
+ derived from entries whose ``type`` starts with the typed-search prefix (the
+ same signal ``strip_unsupported_tool_search_blocks`` keys on), and a
+ ``tool_reference`` is dropped only when its name matches one of them exactly.
+ Matching on the name prefix alone would also remove a legitimate client tool
+ that merely happens to be called ``tool_search_tool_*`` — a typeless deferred
+ tool with such a name is a normal reference target, not a mechanism.
+
+ Returns ``(tools, entries_removed)``, and the ORIGINAL ``tools`` object when
+ nothing was removed — callers rely on identity to skip the write-back.
+ """
+ if not isinstance(tools, list):
+ return tools, 0
+
+ # The search mechanisms present on THIS request, identified by type. Names
+ # on both sides go through _tool_entry_name, so a mechanism shaped like a
+ # server-side block (``tool_name``) registers too.
+ mechanism_names = {
+ name
+ for t in tools
+ if isinstance(t, dict)
+ and str(t.get("type") or "").startswith(_TOOL_SEARCH_TOOL_TYPE_PREFIX)
+ and (name := _tool_entry_name(t))
+ }
+ if not mechanism_names:
+ return tools, 0
+
+ kept = [
+ t
+ for t in tools
+ if not (
+ isinstance(t, dict)
+ and t.get("type") == "tool_reference"
+ and _tool_entry_name(t) in mechanism_names
+ )
+ ]
+ removed = len(tools) - len(kept)
+ return (kept, removed) if removed else (tools, 0)
+
+
# Stand-in for a tool-search block the outbound tools array cannot support. Text
# so it is inert to every validator, short so it costs ~10 tokens, and constant so
# the repaired prefix stays byte-stable across turns (the provider cache needs the
diff --git a/tests/test_issue_746_tool_search.py b/tests/test_issue_746_tool_search.py
index dae480a60..3de7a9620 100644
--- a/tests/test_issue_746_tool_search.py
+++ b/tests/test_issue_746_tool_search.py
@@ -398,7 +398,9 @@ def test_core_tools_match_leading_underscore_namespace() -> None:
from headroom.proxy.helpers import ( # noqa: E402
_CLIENT_TOOL_REF_PLACEHOLDER,
+ _tool_search_reference_names,
strip_unsupported_tool_search_blocks,
+ strip_unsupported_tool_search_references,
)
_SEARCH_TOOL = {"type": _TOOL_SEARCH_DEFAULT_TYPE, "name": _TOOL_SEARCH_DEFAULT_NAME}
@@ -811,3 +813,115 @@ def test_repair_does_not_move_signed_thinking_blocks() -> None:
for block in message["content"]
if block["type"] in ("tool_search_tool_result", "server_tool_use")
]
+
+
+# ---------------------------------------------------------------------------
+# tools-array repair: a tool_reference naming the search tool itself
+# ---------------------------------------------------------------------------
+
+
+def test_reference_repair_drops_typed_search_tool_reference() -> None:
+ # Anthropic answered a match-all search (empty input) with a hit on its own
+ # server tool. Claude Code stored it in the session's loaded-tool set and
+ # replays it as a tool_reference, so every later turn 400s with "Tool
+ # reference 'tool_search_tool_regex' not found in available tools". The
+ # block repair cannot see this: the poison is in tools, not the history.
+ tools = [
+ _SEARCH_TOOL,
+ {"type": "tool_reference", "name": _TOOL_SEARCH_DEFAULT_NAME},
+ {"type": "tool_reference", "name": "Bash"},
+ {"name": "Read", "input_schema": {}},
+ ]
+ repaired, removed = strip_unsupported_tool_search_references(tools)
+ assert removed == 1
+ assert {"type": "tool_reference", "name": "Bash"} in repaired
+ assert _SEARCH_TOOL in repaired # the search mechanism itself must survive
+ assert all(
+ t.get("name") != _TOOL_SEARCH_DEFAULT_NAME
+ for t in repaired
+ if t.get("type") == "tool_reference"
+ )
+
+
+def test_reference_repair_is_a_noop_on_a_clean_tools_array() -> None:
+ # Identity return, so the caller skips the write-back and the prefix cache
+ # is not disturbed on the overwhelming majority of requests.
+ tools = [_SEARCH_TOOL, {"type": "tool_reference", "name": "Bash"}]
+ repaired, removed = strip_unsupported_tool_search_references(tools)
+ assert removed == 0
+ assert repaired is tools
+
+
+def test_reference_repair_keeps_a_deferred_tool_named_like_a_search_tool() -> None:
+ # A typeless client tool may legitimately be called "tool_search_tool_*".
+ # It is a normal reference target, not a search mechanism, so a reference to
+ # it must survive: the request carries no typed mechanism under that name.
+ # Matching on the name prefix alone would wrongly strip it.
+ deferred = {"name": "tool_search_tool_custom", "input_schema": {}}
+ tools = [
+ _SEARCH_TOOL,
+ deferred,
+ {"type": "tool_reference", "name": "tool_search_tool_custom"},
+ ]
+ repaired, removed = strip_unsupported_tool_search_references(tools)
+ assert removed == 0
+ assert repaired is tools
+
+
+def test_reference_repair_keeps_prefixed_reference_with_no_matching_mechanism() -> None:
+ # Prefix-shaped reference, but this request carries no typed search tool at
+ # all — there is nothing for it to be a self-reference to, so it is not ours
+ # to remove. Dropping it here would delete a reference the request needs.
+ tools = [
+ {"name": "Bash", "input_schema": {}},
+ {"type": "tool_reference", "name": _TOOL_SEARCH_DEFAULT_NAME},
+ ]
+ repaired, removed = strip_unsupported_tool_search_references(tools)
+ assert removed == 0
+ assert repaired is tools
+
+
+def test_reference_repair_matches_mechanism_name_exactly() -> None:
+ # Scoped to the mechanism names actually present: the exact name goes, a
+ # merely prefix-sharing sibling stays.
+ tools = [
+ _SEARCH_TOOL,
+ {"type": "tool_reference", "name": _TOOL_SEARCH_DEFAULT_NAME},
+ {"type": "tool_reference", "name": _TOOL_SEARCH_DEFAULT_NAME + "_other"},
+ ]
+ repaired, removed = strip_unsupported_tool_search_references(tools)
+ assert removed == 1
+ kept_names = [t.get("name") for t in repaired if t.get("type") == "tool_reference"]
+ assert kept_names == [_TOOL_SEARCH_DEFAULT_NAME + "_other"]
+
+
+def test_reference_repair_uses_the_file_wide_name_precedence() -> None:
+ # One precedence rule for the file: ``tool_name`` wins over ``name``, as in
+ # _tool_search_reference_names. An entry carrying both keys is judged by
+ # ``tool_name``, so these two readers can never disagree about it.
+ tools = [
+ _SEARCH_TOOL,
+ {"type": "tool_reference", "tool_name": _TOOL_SEARCH_DEFAULT_NAME, "name": "Bash"},
+ {"type": "tool_reference", "tool_name": "Bash", "name": _TOOL_SEARCH_DEFAULT_NAME},
+ ]
+ repaired, removed = strip_unsupported_tool_search_references(tools)
+ assert removed == 1
+ assert repaired == [
+ _SEARCH_TOOL,
+ {"type": "tool_reference", "tool_name": "Bash", "name": _TOOL_SEARCH_DEFAULT_NAME},
+ ]
+ # Same answer from the history-side reader for the same entries.
+ assert _tool_search_reference_names(tools[1:]) == [_TOOL_SEARCH_DEFAULT_NAME, "Bash"]
+
+
+def test_reference_repair_registers_a_mechanism_named_by_tool_name() -> None:
+ # A mechanism shaped like a server-side block (``tool_name``, no ``name``)
+ # must still register, symmetric with the liberal reference matching.
+ tools = [
+ {"type": _TOOL_SEARCH_DEFAULT_TYPE, "tool_name": _TOOL_SEARCH_DEFAULT_NAME},
+ {"type": "tool_reference", "name": _TOOL_SEARCH_DEFAULT_NAME},
+ {"type": "tool_reference", "name": "Bash"},
+ ]
+ repaired, removed = strip_unsupported_tool_search_references(tools)
+ assert removed == 1
+ assert {"type": "tool_reference", "name": "Bash"} in repaired