mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
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:
co-authored by
Claude Opus 4.8
Jerrett Davis
parent
b2b58474c4
commit
f12e3fbeed
@@ -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)
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user