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/anthropic): run tool-search history repair after turn hooks
gglucassc6f99482e1be
diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.pyindex c379df778..8e12401b7 100644--- a/headroom/proxy/handlers/anthropic.py+++ b/headroom/proxy/handlers/anthropic.py@@ -2504,35 +2504,6 @@ class AnthropicHandlerMixin:f"{_ts_saved_tokens}tok")- # Tool-search history repair (#2805). Once deferral is on, the client- # stores Anthropic's server_tool_use / tool_search_tool_result blocks in- # its transcript forever, and upstream validates every tool_reference in- # that history against THIS request's tools array. Claude Code replays- # the same transcript on side-requests carrying a different, smaller- # tools array (the prompt-type Stop hook evaluator, /compact), which the- # proxy cannot predict — so upstream 400s with "Tool reference 'X' not- # found in available tools". Drop the blocks such a request cannot- # support. Runs AFTER the injection above so the tool we just added- # counts as present: on the main loop nothing is stripped and the prefix- # is untouched. Unconditional (not gated on the flag) so transcripts- # poisoned before the flag was turned off still recover.- from headroom.proxy.helpers import strip_unsupported_tool_search_blocks-- _ts_repaired, _ts_stripped = strip_unsupported_tool_search_blocks(- body.get("messages"), body.get("tools")- )- if _ts_stripped:- body["messages"] = _ts_repaired- optimized_messages = _ts_repaired- body_mutation_tracker.mark_mutated("tool_search_history_repair")- transforms_applied.append(f"router:tool_search_repair:{_ts_stripped}blocks")- logger.info(- "[%s] Tool search: dropped %d unsupportable history block(s) "- "(tools array cannot resolve their tool_reference entries)",- request_id,- _ts_stripped,- )-# Turn hooks (opt-in extensions): a registered hook may inspect or# rewrite the outbound tools/messages before we send upstream — the# extensible counterpart to the built-in deferral above. A single@@ -2579,6 +2550,40 @@ class AnthropicHandlerMixin:int(tags.get("turn_hook_tools_saved_tokens", 0) or 0) + _th_saved)+ # Tool-search history repair (#2805). Once deferral is on, the client+ # stores Anthropic's server_tool_use / tool_search_tool_result blocks in+ # its transcript forever, and upstream validates every tool_reference in+ # that history against THIS request's tools array. Claude Code replays+ # the same transcript on side-requests carrying a different, smaller+ # tools array (the prompt-type Stop hook evaluator, /compact), which the+ # proxy cannot predict — so upstream 400s with "Tool reference 'X' not+ # found in available tools". Drop the blocks such a request cannot+ # support. Unconditional (not gated on the flag) so transcripts poisoned+ # before the flag was turned off still recover.+ #+ # ORDERING (#2888): this must be the LAST stage that can invalidate a+ # tool_reference, so it runs after BOTH the deferral injection above (the+ # tool we just added counts as present, so the main loop strips nothing+ # 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++ _ts_repaired, _ts_stripped = strip_unsupported_tool_search_blocks(+ body.get("messages"), body.get("tools")+ )+ if _ts_stripped:+ body["messages"] = _ts_repaired+ optimized_messages = _ts_repaired+ body_mutation_tracker.mark_mutated("tool_search_history_repair")+ transforms_applied.append(f"router:tool_search_repair:{_ts_stripped}blocks")+ logger.info(+ "[%s] Tool search: dropped %d unsupportable history block(s) "+ "(tools array cannot resolve their tool_reference entries)",+ request_id,+ _ts_stripped,+ )+# Consistency: report tok_before/tok_after with ONE tokenizer. The pipeline# and the handler use different token estimators, and cache-mode branches# can leave original_tokens (handler, line ~1049) and optimized_tokensdiff --git a/tests/test_proxy/test_tool_search_repair_after_turn_hooks.py b/tests/test_proxy/test_tool_search_repair_after_turn_hooks.pynew file mode 100644index 000000000..30d495760--- /dev/null+++ b/tests/test_proxy/test_tool_search_repair_after_turn_hooks.py@@ -0,0 +1,176 @@+"""Tool-search history repair must run AFTER the turn hooks (#2888).++``strip_unsupported_tool_search_blocks`` (#2807) validates every replayed+``tool_reference`` against the request's ``tools`` array. A registered turn hook+may rewrite that array, so repairing before the hook validates against a stale+view: the reference looks resolvable, the hook then drops the tool it named, and+upstream 400s with ``Tool reference 'X' not found in available tools``.++These drive the real handler and assert on the forwarded body, because ordering+is the whole property under test -- a unit test of the helper cannot see it.+"""++from __future__ import annotations++from types import SimpleNamespace++import httpx+import pytest++pytest.importorskip("fastapi")++from fastapi.testclient import TestClient++from headroom.proxy.server import ProxyConfig, create_app+from headroom.proxy.turn_hooks import clear_turn_hooks, register_turn_hook++_SEARCH_TOOL = {"type": "tool_search_tool_20250917", "name": "tool_search"}+_GREP = {"name": "Grep", "description": "search files", "input_schema": {"type": "object"}}+_READ = {"name": "Read", "description": "read a file", "input_schema": {"type": "object"}}++# A transcript that already carries a resolved tool-search round trip for `Grep`.+_POISONED_MESSAGES = [+ {"role": "user", "content": "find the thing"},+ {+ "role": "assistant",+ "content": [+ {+ "type": "server_tool_use",+ "id": "srvtoolu_1",+ "name": "tool_search_tool_20250917",+ "input": {"query": "grep"},+ },+ {+ "type": "tool_search_tool_result",+ "tool_use_id": "srvtoolu_1",+ "content": {+ "type": "tool_search_tool_result_content",+ "tool_references": [{"type": "tool_reference", "tool_name": "Grep"}],+ },+ },+ ],+ },+ {"role": "user", "content": "now use it"},+]++[email protected](autouse=True)+def _clean_registry():+ clear_turn_hooks()+ yield+ clear_turn_hooks()+++class _DropToolHook:+ """Turn hook that removes one tool from the outbound array."""++ def __init__(self, name: str):+ self._name = name++ def on_request(self, ctx) -> None: # noqa: ANN001+ if ctx.tools:+ ctx.tools = [t for t in ctx.tools if t.get("name") != self._name]+++class _InertHook:+ def on_request(self, ctx) -> None: # noqa: ANN001, ARG002+ return None+++def _run(hook) -> dict: # noqa: ANN001+ """POST a poisoned transcript through the handler, return the forwarded body."""+ captured: dict[str, object] = {}+ register_turn_hook(hook)++ config = ProxyConfig(+ optimize=False,+ cache_enabled=False,+ rate_limit_enabled=False,+ cost_tracking_enabled=False,+ log_requests=False,+ ccr_inject_tool=False,+ ccr_handle_responses=False,+ ccr_context_tracking=False,+ image_optimize=False,+ )+ with TestClient(create_app(config)) as client:+ proxy = client.app.state.proxy+ proxy.pipeline_extensions.emit = lambda *args, **kwargs: SimpleNamespace(+ messages=kwargs.get("messages"),+ tools=kwargs.get("tools"),+ headers=kwargs.get("headers"),+ metadata=kwargs.get("metadata"),+ )++ async def _fake_retry(method, url, headers, body, stream=False, **kwargs): # noqa: ANN001+ captured["body"] = body+ return httpx.Response(+ 200,+ json={+ "id": "msg_repair_order",+ "type": "message",+ "role": "assistant",+ "content": [{"type": "text", "text": "ok"}],+ "usage": {"input_tokens": 20, "output_tokens": 3},+ },+ )++ proxy._retry_request = _fake_retry++ response = client.post(+ "/v1/messages",+ headers={"x-api-key": "test-key", "anthropic-version": "2023-06-01"},+ json={+ "model": "claude-sonnet-4-6",+ "max_tokens": 64,+ "messages": _POISONED_MESSAGES,+ "tools": [_SEARCH_TOOL, _GREP, _READ],+ },+ )+ assert response.status_code == 200++ return captured["body"] # type: ignore[return-value]+++def _referenced_tool_names(body: dict) -> list[str]:+ names = []+ for message in body.get("messages", []):+ content = message.get("content")+ if not isinstance(content, list):+ continue+ for block in content:+ if not isinstance(block, dict) or block.get("type") != "tool_search_tool_result":+ continue+ inner = block.get("content")+ entries = inner.get("tool_references") if isinstance(inner, dict) else inner+ for entry in entries or []:+ names.append(str(entry.get("tool_name") or entry.get("name")))+ return names+++def _block_types(body: dict) -> list[str]:+ types = []+ for message in body.get("messages", []):+ content = message.get("content")+ if isinstance(content, list):+ types.extend(str(b.get("type")) for b in content if isinstance(b, dict))+ return types+++def test_repair_sees_the_tools_array_the_hook_left_behind() -> None:+ """A hook that drops `Grep` must leave no dangling reference to it."""+ forwarded = _run(_DropToolHook("Grep"))++ assert "Grep" not in [t.get("name") for t in forwarded["tools"]]+ # The whole pair goes: an orphaned server_tool_use 400s on its own.+ assert _referenced_tool_names(forwarded) == []+ assert "tool_search_tool_result" not in _block_types(forwarded)+ assert "server_tool_use" not in _block_types(forwarded)+++def test_repair_leaves_resolvable_history_alone_when_the_hook_keeps_the_tool() -> None:+ """The converse: no over-stripping when the hook does not touch `tools`."""+ forwarded = _run(_InertHook())++ assert _referenced_tool_names(forwarded) == ["Grep"]+ assert "tool_search_tool_result" in _block_types(forwarded)