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: preserve anthropic passthrough tool order (#1427)

Vinay Guptaa9322477e33e
diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.py
index a01c9a5a1..e10d1b171 100644
--- a/headroom/proxy/handlers/anthropic.py
+++ b/headroom/proxy/handlers/anthropic.py
@@ -149,6 +149,18 @@ class AnthropicHandlerMixin:
return tools
return sorted(tools, key=cls._tool_sort_key)
+ @classmethod
+ def _tools_for_forwarding(
+ cls,
+ tools: list[dict[str, Any]] | None,
+ *,
+ preserve_order: bool,
+ ) -> list[dict[str, Any]] | None:
+ """Return upstream tools, preserving client order for passthrough requests."""
+ if preserve_order:
+ return tools
+ return cls._sort_tools_deterministically(tools)
+
@staticmethod
def _compress_latest_user_turn_images_cache_safe(
messages: list[dict[str, Any]],
@@ -663,6 +675,7 @@ class AnthropicHandlerMixin:
request.headers.get("x-headroom-bypass", "").lower() == "true"
or request.headers.get("x-headroom-mode", "").lower() == "passthrough"
)
+ preserve_tool_order = _bypass or not self.config.optimize
if _bypass:
logger.info(f"[{request_id}] Bypass: skipping compression (header)")
@@ -1843,9 +1856,12 @@ class AnthropicHandlerMixin:
# Update body
body["messages"] = optimized_messages
if tools or _original_tools is not None:
- sorted_tools = self._sort_tools_deterministically(tools)
- if sorted_tools != tools:
- tools = sorted_tools
+ forwarded_tools = self._tools_for_forwarding(
+ tools,
+ preserve_order=preserve_tool_order,
+ )
+ if forwarded_tools != tools:
+ tools = forwarded_tools
if tools != _original_tools:
body["tools"] = tools
@@ -1865,11 +1881,10 @@ class AnthropicHandlerMixin:
optimized_messages = presend_event.messages
body["messages"] = optimized_messages
if presend_event.tools is not None:
- sorted_tools = self._sort_tools_deterministically(presend_event.tools)
- if sorted_tools != presend_event.tools:
- tools = sorted_tools
- else:
- tools = presend_event.tools
+ tools = self._tools_for_forwarding(
+ presend_event.tools,
+ preserve_order=preserve_tool_order,
+ )
if tools or body.get("tools") is not None:
if tools != body.get("tools"):
body["tools"] = tools
@@ -2897,10 +2912,6 @@ class AnthropicHandlerMixin:
params = batch_req.get("params", {})
canonical_params = dict(params)
original_tools = canonical_params.get("tools")
- if original_tools is not None:
- sorted_tools = self._sort_tools_deterministically(original_tools)
- if sorted_tools != original_tools:
- canonical_params["tools"] = sorted_tools
messages = params.get("messages", [])
original_messages = copy.deepcopy(messages)
model = params.get("model", "unknown")
@@ -2915,6 +2926,11 @@ class AnthropicHandlerMixin:
)
continue
+ if original_tools is not None:
+ sorted_tools = self._sort_tools_deterministically(original_tools)
+ if sorted_tools != original_tools:
+ canonical_params["tools"] = sorted_tools
+
# Apply optimization
original_tokens = 0 # Initialize before try to prevent UnboundLocalError
try:
diff --git a/tests/test_anthropic_stage_timings.py b/tests/test_anthropic_stage_timings.py
index 5a4ea86ef..cd4177310 100644
--- a/tests/test_anthropic_stage_timings.py
+++ b/tests/test_anthropic_stage_timings.py
@@ -245,6 +245,42 @@ def test_anthropic_http_happy_path_emits_stage_timings(stage_log_capture):
assert "total_pre_upstream" in emitted
+def test_anthropic_no_optimize_preserves_client_tool_order():
+ tools = [
+ {
+ "name": "Read",
+ "description": "Read a file",
+ "input_schema": {"type": "object", "properties": {}},
+ },
+ {
+ "name": "Bash",
+ "description": "Run a shell command",
+ "input_schema": {"type": "object", "properties": {}},
+ },
+ ]
+ request = _build_request(
+ {
+ "model": "claude-3-5-sonnet-latest",
+ "messages": [{"role": "user", "content": "use a tool"}],
+ "tools": tools,
+ },
+ {"authorization": "Bearer sk-ant-api-test"},
+ )
+ handler = _DummyAnthropicHandler()
+
+ import headroom.tokenizers as _tk
+
+ orig_get = _tk.get_tokenizer
+ _tk.get_tokenizer = lambda model: _DummyTokenizer()
+ try:
+ anyio.run(handler.handle_anthropic_messages, request)
+ finally:
+ _tk.get_tokenizer = orig_get
+
+ _, _, _, forwarded_body = handler.captured
+ assert [tool["name"] for tool in forwarded_body["tools"]] == ["Read", "Bash"]
+
+
def test_anthropic_http_invalid_body_still_emits_stage_timings(stage_log_capture):
async def receive():
# Invalid JSON — produces ``ValueError`` from ``_read_request_json``.
diff --git a/tests/test_proxy_anthropic_cache_stability.py b/tests/test_proxy_anthropic_cache_stability.py
index fb5d92187..086ba83ad 100644
--- a/tests/test_proxy_anthropic_cache_stability.py
+++ b/tests/test_proxy_anthropic_cache_stability.py
@@ -86,10 +86,32 @@ def _make_proxy_client() -> TestClient:
return TestClient(app)
-def test_anthropic_tools_sorted_deterministically_before_forward() -> None:
+ ("optimize", "expected_names"),
+ [
+ (False, ["zeta", "alpha", "mu"]),
+ (True, ["alpha", "mu", "zeta"]),
+ ],
+)
+def test_anthropic_tools_forwarding_order_matches_optimization_mode(
+ optimize: bool,
+ expected_names: list[str],
+) -> None:
captured = {}
with _make_proxy_client() as client:
proxy = client.app.state.proxy
+ proxy.config.optimize = optimize
+ proxy.config.mode = "token"
+
+ if optimize:
+ proxy.anthropic_pipeline.apply = lambda **kwargs: SimpleNamespace(
+ messages=kwargs["messages"],
+ transforms_applied=[],
+ timing={},
+ tokens_before=100,
+ tokens_after=100,
+ waste_signals=None,
+ )
async def _fake_retry(method, url, headers, body, stream=False, **kwargs): # noqa: ANN001
captured["body"] = body
@@ -128,7 +150,7 @@ def test_anthropic_tools_sorted_deterministically_before_forward() -> None:
assert response.status_code == 200
sent_tools = captured["body"]["tools"]
- assert [t["name"] for t in sent_tools] == ["alpha", "mu", "zeta"]
+ assert [t["name"] for t in sent_tools] == expected_names
def test_image_compression_only_applies_to_latest_non_frozen_user_turn() -> None:
@@ -186,10 +208,20 @@ def test_image_compression_does_not_touch_previous_turns_if_last_message_not_use
assert result[0]["content"][0]["source"]["data"] == "OLD_IMAGE_BYTES"
-def test_anthropic_batch_tools_sorted_deterministically_before_forward() -> None:
+ ("optimize", "expected_names"),
+ [
+ (False, ["zeta", "alpha", "mu"]),
+ (True, ["alpha", "mu", "zeta"]),
+ ],
+)
+def test_anthropic_batch_tools_forwarding_order_matches_optimization_mode(
+ optimize: bool,
+ expected_names: list[str],
+) -> None:
captured = {}
config = ProxyConfig(
- optimize=False,
+ optimize=optimize,
cache_enabled=False,
rate_limit_enabled=False,
cost_tracking_enabled=False,
@@ -203,6 +235,17 @@ def test_anthropic_batch_tools_sorted_deterministically_before_forward() -> None
with TestClient(app) as client:
proxy = client.app.state.proxy
+ proxy.config.mode = "token"
+
+ if optimize:
+ proxy.anthropic_pipeline.apply = lambda **kwargs: SimpleNamespace(
+ messages=kwargs["messages"],
+ transforms_applied=[],
+ timing={},
+ tokens_before=100,
+ tokens_after=100,
+ waste_signals=None,
+ )
async def _fake_retry(method, url, headers, body, stream=False, **kwargs): # noqa: ANN001
captured["body"] = body
@@ -259,7 +302,7 @@ def test_anthropic_batch_tools_sorted_deterministically_before_forward() -> None
assert response.status_code == 200
sent_tools = captured["body"]["requests"][0]["params"]["tools"]
- assert [t["name"] for t in sent_tools] == ["alpha", "mu", "zeta"]
+ assert [t["name"] for t in sent_tools] == expected_names
def test_append_context_targets_latest_non_frozen_user_turn() -> None:
diff --git a/tests/test_proxy_byte_faithful_forwarding.py b/tests/test_proxy_byte_faithful_forwarding.py
index d8c0eb87e..027956c5b 100644
--- a/tests/test_proxy_byte_faithful_forwarding.py
+++ b/tests/test_proxy_byte_faithful_forwarding.py
@@ -308,10 +308,10 @@ class _SortedEmptyToolsPreSendExtension:
return None
-def _make_no_optimize_app() -> tuple[TestClient, _CapturingTransport]:
- """Boot a proxy with all transforms disabled and a capturing transport."""
+def _make_anthropic_app(*, optimize: bool) -> tuple[TestClient, _CapturingTransport]:
+ """Boot an Anthropic proxy with a capturing transport."""
config = ProxyConfig(
- optimize=False,
+ optimize=optimize,
cache_enabled=False,
rate_limit_enabled=False,
cost_tracking_enabled=False,
@@ -335,6 +335,11 @@ def _make_no_optimize_app() -> tuple[TestClient, _CapturingTransport]:
return TestClient(app), transport
+def _make_no_optimize_app() -> tuple[TestClient, _CapturingTransport]:
+ """Boot a proxy with all transforms disabled and a capturing transport."""
+ return _make_anthropic_app(optimize=False)
+
+
def test_passthrough_no_mutation_byte_equal_sha256() -> None:
"""No transform → upstream SHA-256 equals client-sent SHA-256."""
client, transport = _make_no_optimize_app()
@@ -448,7 +453,7 @@ def test_anthropic_tools_canonical_order_preserves_byte_faithful_request() -> No
)
-def test_anthropic_tools_unsorted_reordered_and_canonicalized() -> None:
+def test_anthropic_tools_unsorted_order_preserves_byte_faithful_request() -> None:
client, transport = _make_no_optimize_app()
inbound_dict = {
"model": "claude-sonnet-4-6",
@@ -459,6 +464,49 @@ def test_anthropic_tools_unsorted_reordered_and_canonicalized() -> None:
{"name": "alpha"},
],
}
+ inbound_bytes = serialize_body_canonical(inbound_dict)
+
+ response = client.post(
+ "/v1/messages",
+ headers={
+ "x-api-key": "test-key",
+ "anthropic-version": "2023-06-01",
+ "content-type": "application/json",
+ },
+ content=inbound_bytes,
+ )
+ assert response.status_code == 200, response.text
+ upstream = transport.captured_body or b""
+ assert upstream == inbound_bytes
+ forwarded = json.loads(upstream.decode("utf-8"))
+ assert [tool["name"] for tool in forwarded["tools"]] == ["zeta", "alpha"]
+
+
+def test_anthropic_tools_unsorted_reordered_and_canonicalized_when_optimized() -> None:
+ client, transport = _make_anthropic_app(optimize=True)
+ proxy = client.app.state.proxy
+ proxy.config.mode = "token"
+
+ def _fake_apply(**kwargs):
+ return SimpleNamespace(
+ messages=kwargs["messages"],
+ transforms_applied=[],
+ timing={},
+ tokens_before=100,
+ tokens_after=100,
+ waste_signals=None,
+ )
+
+ proxy.anthropic_pipeline.apply = _fake_apply
+ inbound_dict = {
+ "model": "claude-sonnet-4-6",
+ "max_tokens": 64,
+ "messages": [{"role": "user", "content": "plan test"}],
+ "tools": [
+ {"name": "zeta", "description": "later"},
+ {"name": "alpha"},
+ ],
+ }
expected_dict = {
**inbound_dict,
"tools": [
diff --git a/tests/test_proxy_handler_helpers.py b/tests/test_proxy_handler_helpers.py
index daa0c42f7..fe2b48f6b 100644
--- a/tests/test_proxy_handler_helpers.py
+++ b/tests/test_proxy_handler_helpers.py
@@ -570,6 +570,15 @@ def test_anthropic_tool_sort_and_context_append_helpers() -> None:
"tool",
]
assert AnthropicHandlerMixin._sort_tools_deterministically(None) is None
+ assert AnthropicHandlerMixin._tools_for_forwarding(tools, preserve_order=True) == tools
+ assert [
+ AnthropicHandlerMixin._tool_sort_key(tool)[0]
+ for tool in AnthropicHandlerMixin._tools_for_forwarding(tools, preserve_order=False) or []
+ ] == [
+ "alpha",
+ "beta",
+ "tool",
+ ]
assert (
AnthropicHandlerMixin._append_context_to_latest_non_frozen_user_turn(
[], "ctx", frozen_message_count=0