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(proxy): snapshot the original messages when a turn hook can edit them (#4241)

Tejas Chopradf11f2749862
diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.py
index 3344e9fef..3de6f8295 100644
--- a/headroom/proxy/handlers/anthropic.py
+++ b/headroom/proxy/handlers/anthropic.py
@@ -1248,9 +1248,10 @@ class AnthropicHandlerMixin:
pipeline_path = request.url.path if upstream_base_url else "/v1/messages"
pipeline_stream = bool(body.get("stream", False) or force_stream)
# O1 (2026-09-27 perf audit): the snapshot of the original
- # conversation aliases the live list unless hooks or pipeline
- # extensions are configured - those can mutate `messages` in place
- # (pre_compress receives the live list), so then the snapshot is an
+ # conversation aliases the live list unless hooks, pipeline
+ # extensions or turn hooks are configured - those can mutate
+ # `messages` in place (pre_compress receives the live list, skill
+ # search folds text in place), so then the snapshot is an
# independently owned copy (snapshot_original_messages). The
# deep_copy stage is always measured so the timing summary keeps
# its key.
@@ -5779,7 +5780,7 @@ class AnthropicHandlerMixin:
pipeline_timing: dict[str, float] = {}
# O1 (2026-09-27 perf audit): the per-request snapshot aliases unless
- # hooks or extensions are configured (see the main handler).
+ # hooks, extensions or turn hooks are configured (see the main handler).
from headroom.proxy.helpers import snapshot_original_messages
from headroom.transforms.cold_prefix import anthropic_cache_ttl_seconds
diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.py
index 80f0657a4..f649553d5 100644
--- a/headroom/proxy/handlers/openai.py
+++ b/headroom/proxy/handlers/openai.py
@@ -3135,8 +3135,8 @@ class OpenAIHandlerMixin:
model = body.get("model", "unknown")
messages = body.get("messages", [])
# O1 (2026-09-27 perf audit): the snapshot of the original
- # conversation aliases the live list unless hooks or pipeline
- # extensions are configured; those can mutate `messages` in place
+ # conversation aliases the live list unless hooks, pipeline extensions
+ # or turn hooks are configured; those can mutate `messages` in place
# (pre_compress receives the live list), so then it is an
# independently owned copy (see snapshot_original_messages).
from headroom.proxy.helpers import snapshot_original_messages
diff --git a/headroom/proxy/helpers.py b/headroom/proxy/helpers.py
index e28c786ec..e3675ca3a 100644
--- a/headroom/proxy/helpers.py
+++ b/headroom/proxy/helpers.py
@@ -112,6 +112,7 @@ from headroom.proxy.tool_injection_logging import (
)
from headroom.proxy.tool_injection_tracker import SessionToolTracker as _SessionToolTracker
from headroom.proxy.tool_name_policy import extract_tool_name
+from headroom.proxy.turn_hooks import registered_turn_hooks
if TYPE_CHECKING:
import httpx
@@ -4793,11 +4794,12 @@ def snapshot_original_messages(
Aliasing the live list is safe only while nothing between ingress and the
pipeline's own deepcopy can mutate it in place. A configured
- ``config.hooks`` (``pre_compress`` and friends receive the live list) or an
- enabled pipeline extension can, so in that case the snapshot is an
- independently owned deep copy; with neither configured the alias is kept
- and costs nothing.
+ ``config.hooks`` (``pre_compress`` and friends receive the live list), an
+ enabled pipeline extension or a registered turn hook (skill search folds
+ message text in place) can, so in that case the snapshot is an
+ independently owned deep copy; with none of them the alias is kept and
+ costs nothing.
"""
- if hooks is not None or bool(getattr(extensions, "enabled", False)):
+ if hooks is not None or bool(getattr(extensions, "enabled", False)) or registered_turn_hooks():
return copy.deepcopy(messages)
return messages
diff --git a/tests/test_original_snapshot_in_place_hook.py b/tests/test_original_snapshot_in_place_hook.py
index 3b75a87e2..b08c0a321 100644
--- a/tests/test_original_snapshot_in_place_hook.py
+++ b/tests/test_original_snapshot_in_place_hook.py
@@ -4,8 +4,10 @@ O1 aliases ``original_client_messages`` to the live ``messages`` list to skip a
deepcopy per request. That is only safe while nothing mutates the list before
the pipeline's own copy; ``config.hooks.pre_compress`` receives the live list,
so a hook that edits it in place (and returns the same list) used to rewrite the
-recorded original too. With hooks or extensions configured the snapshot is an
-independently owned copy; with neither, the alias stays (no env switch).
+recorded original too. Registered turn hooks (skill search) fold message text
+in place the same way. With hooks, extensions or turn hooks configured the
+snapshot is an independently owned copy; with none, the alias stays (no env
+switch).
Observed at the handlers' own consumers: ``compute_session_id`` derives the
session from the ORIGINAL client messages after the hook has run, and the
@@ -27,8 +29,18 @@ from fastapi.testclient import TestClient # noqa: E402
from headroom.hooks import CompressionHooks # noqa: E402
from headroom.proxy.helpers import snapshot_original_messages # noqa: E402
from headroom.proxy.server import ProxyConfig, create_app # noqa: E402
+from headroom.proxy.turn_hooks import clear_turn_hooks, register_turn_hook # noqa: E402
ORIGINAL = "the original user text"
+
+
[email protected](autouse=True)
+def _clean_turn_hooks():
+ clear_turn_hooks()
+ yield
+ clear_turn_hooks()
+
+
HOOKED = "HOOKED IN PLACE"
@@ -175,3 +187,66 @@ def test_the_snapshot_aliases_only_when_nothing_can_mutate() -> None:
for kw in ({"hooks": _InPlaceHooks()}, {"extensions": _Ext()}):
snap = snapshot_original_messages(msgs, **kw)
assert snap == msgs and snap is not msgs and snap[0] is not msgs[0]
+
+
+def test_the_snapshot_is_a_copy_while_a_turn_hook_is_registered() -> None:
+ msgs = [{"role": "user", "content": ORIGINAL}]
+ register_turn_hook(_InPlaceTurnHook())
+ snap = snapshot_original_messages(msgs)
+ assert snap == msgs and snap is not msgs and snap[0] is not msgs[0]
+
+
+class _InPlaceTurnHook:
+ """Shaped like skill search: rewrites a message's text in place, adds a tool."""
+
+ name = "in_place_fold"
+ stream_safe = False
+
+ def on_request(self, ctx) -> None:
+ for m in ctx.messages:
+ if m.get("role") == "user":
+ m["content"] = "short"
+ ctx.tools = [
+ *(ctx.tools or []),
+ {"name": "search", "description": "find", "input_schema": {"type": "object"}},
+ ]
+
+
+def test_anthropic_headline_counts_a_turn_hook_fold_made_in_place() -> None:
+ register_turn_hook(_InPlaceTurnHook())
+ with TestClient(create_app(_config(hooks=None))) as client:
+ proxy = client.app.state.proxy
+
+ async def _fake_retry(method, url, headers, body, stream=False, **kwargs): # noqa: ANN001
+ return httpx.Response(
+ 200,
+ content=json.dumps(
+ {
+ "id": "msg_1",
+ "type": "message",
+ "role": "assistant",
+ "model": "claude-sonnet-4-5",
+ "content": [{"type": "text", "text": "ok"}],
+ "stop_reason": "end_turn",
+ "usage": {"input_tokens": 5, "output_tokens": 1},
+ }
+ ).encode(),
+ headers={"content-type": "application/json"},
+ )
+
+ proxy._retry_request = _fake_retry
+ r = client.post(
+ "/v1/messages",
+ headers={"x-api-key": "sk-ant-test", "anthropic-version": "2023-06-01"},
+ json={
+ "model": "claude-sonnet-4-5",
+ "max_tokens": 16,
+ "messages": [{"role": "user", "content": ORIGINAL + " word" * 400}],
+ },
+ )
+ assert r.status_code == 200, r.text
+
+ before = int(r.headers["x-headroom-tokens-before"])
+ after = int(r.headers["x-headroom-tokens-after"])
+ assert before > after
+ assert int(r.headers["x-headroom-tokens-saved"]) == before - after > 0