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): 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.pyindex 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.pyindex 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 thediff --git a/tests/test_issue_746_tool_search.py b/tests/test_issue_746_tool_search.pyindex 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