fix(proxy): repair client-side tool_search tool_reference blocks (#3443)

## Summary

`strip_unsupported_tool_search_blocks` (added in #2805/#2807 to stop
poisoned
Claude Code transcripts from 400ing) only scans the **server-side**
tool-search
shape: a `tool_search_tool_result` block with nested `tool_references`.
It never
scans the **client-side** shape documented under [Custom tool search

implementation](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool#custom-tool-search-implementation):
a plain `tool_result` whose `content` is a list of `tool_reference`
blocks. That
is the shape Claude Code persists when it discovers MCP tools
client-side
(e.g. `mcp__<server>__<tool>`).

Anthropic validates references in **both** shapes. When a referenced
tool goes
absent between turns (an MCP server that dropped mid-session, or a
side-request
carrying a smaller tools array), the request 400s with `Tool reference
'X' not
found in available tools`. The existing repair fixes the server-side
block but
leaves the client-side one, so the transcript stays poisoned and every
replay
400s even though the repair "fired".

## Root cause

The per-message loop keys entirely on `block.get("type") ==
"tool_search_tool_result"`.
A `tool_result` carrying `tool_reference` entries is never inspected.

## Fix

Extend the same absence test to client-side `tool_result` blocks: drop
the
unsupportable `tool_reference` entries (a deferred-but-present tool
stays valid),
and when that empties a search result, replace its content with a short
placeholder so the paired `tool_use` is not orphaned (an orphaned
`tool_use`
400s on its own). Server-side handling, the paired `server_tool_use`
cleanup,
and the identity-return fast path are unchanged.

## Testing

- Added: `uv run --extra dev pytest tests/test_issue_746_tool_search.py`
(61 passing)

## Proof

- Repro: a client-side `tool_result` referencing an absent tool 400s on
replay; the pre-fix repair leaves it untouched
- Fix: absence-keyed drop across both block shapes; present (incl.
`defer_loading`) references are kept
- Tests: 3 new cases (absent dropped + tool_use preserved,
present-deferred kept by identity, mixed keeps present / drops absent)
- Scope: only `tool_result` blocks that already carry `tool_reference`
entries are touched; ordinary tool results are untouched

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: Jerrett Davis <mxjerrett@gmail.com>
This commit is contained in:
gglucass
2026-09-24 16:53:40 -05:00
committed by GitHub
co-authored by Claude Opus 4.8 Jerrett Davis
parent b2b58474c4
commit f12e3fbeed
2 changed files with 155 additions and 7 deletions
+49 -7
View File
@@ -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)
+106
View File
@@ -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