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.

feat(hooks): add protect_messages, a hard per-message compression veto (#3772)

Tejas Choprad17ac6a174d9
diff --git a/headroom/compress.py b/headroom/compress.py
index 2d1a786b6..c40e0993c 100644
--- a/headroom/compress.py
+++ b/headroom/compress.py
@@ -230,12 +230,17 @@ def compress(
try:
# Compute biases from hooks if provided
biases = None
+ # Hard per-message veto. Separate from ``biases`` because a bias is a
+ # soft multiplier that several strategies clamp or ignore, so it cannot
+ # express "leave this one alone".
+ protect = None
if hooks:
- from headroom.hooks import CompressContext
+ from headroom.hooks import CompressContext, collect_protected
ctx = CompressContext(model=model)
messages = hooks.pre_compress(messages, ctx)
biases = hooks.compute_biases(messages, ctx)
+ protect = collect_protected(hooks, messages, ctx)
received_event = pipeline_extensions.emit(
PipelineStage.INPUT_RECEIVED,
@@ -257,6 +262,7 @@ def compress(
model_limit=model_limit,
context=context,
biases=biases,
+ protect=protect,
# Pass CompressConfig options through to transforms
compress_user_messages=cfg.compress_user_messages,
compress_system_messages=cfg.compress_system_messages,
diff --git a/headroom/hooks.py b/headroom/hooks.py
index 4f3cf82ce..3ae985e85 100644
--- a/headroom/hooks.py
+++ b/headroom/hooks.py
@@ -1,10 +1,11 @@
"""Compression hooks and pipeline lifecycle events.
-Three hooks at well-defined pipeline stages:
+Four hooks at well-defined pipeline stages:
1. pre_compress: modify messages before compression (dedup, filter, inject)
2. compute_biases: set per-message compression aggressiveness (position-aware, phase-aware)
-3. post_compress: observe results after compression (learning, analytics, logging)
+3. protect_messages: veto compression of specific messages outright
+4. post_compress: observe results after compression (learning, analytics, logging)
The canonical pipeline also emits lifecycle events through ``on_pipeline_event``.
That gives extensions one stable contract across SDK, ``compress()``, and proxy
@@ -39,7 +40,7 @@ from .pipeline import PipelineEvent
@dataclass
class CompressContext:
- """Context passed to pre_compress and compute_biases hooks.
+ """Context passed to the pre_compress, compute_biases and protect_messages hooks.
Provides enough information for hooks to make decisions without
needing to understand the proxy's internals.
@@ -128,6 +129,32 @@ class CompressionHooks:
"""
return {}
+ def protect_messages(
+ self,
+ messages: list[dict[str, Any]],
+ ctx: CompressContext,
+ ) -> set[int]:
+ """Return message indices that must not be compressed at all.
+
+ ``compute_biases`` is a *soft* lever: a multiplier on how aggressively
+ a compressor prunes. Several strategies clamp it against their own
+ floors or ignore it entirely, so no bias — however large — reliably
+ means "leave this one alone". A hook that has concluded a specific
+ message must survive verbatim needs to say so directly, and this is how.
+
+ The router honours these before any routing decision, so the message is
+ passed through untouched whatever its content type or role. Use
+ sparingly: a protected message is context the compressor cannot reclaim.
+
+ Args:
+ messages: The full message list.
+ ctx: Compression context.
+
+ Returns:
+ Set of message indices to pass through verbatim. Empty = no vetoes.
+ """
+ return set()
+
def post_compress(self, event: CompressEvent) -> None:
"""Called after compression completes. Observational only.
@@ -149,3 +176,33 @@ class CompressionHooks:
the three legacy compression-specific hooks.
"""
return None
+
+
+def collect_protected(
+ hooks: Any,
+ messages: list[dict[str, Any]],
+ ctx: CompressContext,
+) -> set[int] | None:
+ """Ask a hooks object for its per-message vetoes, tolerating older ones.
+
+ ``hooks`` is duck-typed at every call site: nothing requires the object to
+ be a :class:`CompressionHooks` subclass, and objects written before
+ ``protect_messages`` existed will not have the attribute at all. Calling it
+ blind would raise ``AttributeError`` inside the compression block, which the
+ proxy catches as a compression failure — so adding this hook would silently
+ stop compressing for those callers, turning an additive seam into a
+ regression. A missing method means "no vetoes".
+
+ Returns None when the hook cannot be asked, which the router treats the same
+ as an empty set.
+ """
+ fn = getattr(hooks, "protect_messages", None)
+ if fn is None:
+ return None
+ protected = fn(messages, ctx)
+ if protected is None:
+ return None
+ # Normalise here rather than trusting the hook: ``hooks`` is duck-typed, so
+ # a set is a convention, not a guarantee, and a list of indices is the
+ # obvious thing for an implementer to return.
+ return {int(i) for i in protected}
diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.py
index 0a3a4a6a5..33ce52171 100644
--- a/headroom/proxy/handlers/anthropic.py
+++ b/headroom/proxy/handlers/anthropic.py
@@ -1739,6 +1739,16 @@ class AnthropicHandlerMixin:
if self.config.hooks and _hook_ctx is not None
else None
)
+ # Hard per-message veto. Separate from ``biases`` because a
+ # bias is a soft multiplier that several strategies clamp or
+ # ignore, so it cannot express "leave this one alone".
+ from headroom.hooks import collect_protected
+
+ protect = (
+ collect_protected(self.config.hooks, messages, _hook_ctx)
+ if self.config.hooks and _hook_ctx is not None
+ else None
+ )
# F2.1 c5/5: derive the per-request CompressionPolicy
# from the auth_mode classified at request entry. The
@@ -1807,6 +1817,7 @@ class AnthropicHandlerMixin:
prefix_replay_guaranteed=True,
idle_seconds=idle_seconds,
biases=biases,
+ protect=protect,
request_id=request_id,
compression_policy=compression_policy,
cache_ttl_seconds=_cc_ttl,
@@ -1853,6 +1864,7 @@ class AnthropicHandlerMixin:
prefix_replay_guaranteed=True,
idle_seconds=idle_seconds,
biases=biases,
+ protect=protect,
request_id=request_id,
compression_policy=compression_policy,
cache_ttl_seconds=_cc_ttl,
@@ -1905,6 +1917,7 @@ class AnthropicHandlerMixin:
prefix_replay_guaranteed=True,
idle_seconds=idle_seconds,
biases=biases,
+ protect=protect,
request_id=request_id,
compression_policy=compression_policy,
cache_ttl_seconds=_cc_ttl,
@@ -1948,6 +1961,7 @@ class AnthropicHandlerMixin:
frozen_message_count=frozen_message_count,
prefix_replay_guaranteed=True,
biases=biases,
+ protect=protect,
request_id=request_id,
compression_policy=compression_policy,
cache_ttl_seconds=_cc_ttl,
@@ -2010,6 +2024,7 @@ class AnthropicHandlerMixin:
frozen_message_count=frozen_message_count,
prefix_replay_guaranteed=True,
biases=biases,
+ protect=protect,
request_id=request_id,
compression_policy=compression_policy,
**proxy_pipeline_kwargs(self.config),
@@ -2082,6 +2097,7 @@ class AnthropicHandlerMixin:
frozen_message_count=prefix_n,
idle_seconds=idle_seconds,
biases=biases,
+ protect=protect,
request_id=request_id,
compression_policy=compression_policy,
cache_ttl_seconds=_cc_ttl,
diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.py
index 85231d543..bdd29b82f 100644
--- a/headroom/proxy/handlers/openai.py
+++ b/headroom/proxy/handlers/openai.py
@@ -3687,13 +3687,18 @@ class OpenAIHandlerMixin:
# Hook: pre_compress
_hook_biases = None
+ # Hard per-message veto. Separate from ``_hook_biases`` because a bias is
+ # a soft multiplier that several strategies clamp or ignore, so it cannot
+ # express "leave this one alone".
+ _hook_protect = None
if self.config.hooks:
- from headroom.hooks import CompressContext
+ from headroom.hooks import CompressContext, collect_protected
_hook_ctx = CompressContext(model=model, provider="openai")
try:
messages = self.config.hooks.pre_compress(messages, _hook_ctx)
_hook_biases = self.config.hooks.compute_biases(messages, _hook_ctx)
+ _hook_protect = collect_protected(self.config.hooks, messages, _hook_ctx)
except Exception as e:
logger.debug(f"[{request_id}] Hook error: {e}")
@@ -3898,6 +3903,7 @@ class OpenAIHandlerMixin:
),
prefix_replay_guaranteed=True,
biases=_hook_biases,
+ protect=_hook_protect,
compression_policy=compression_policy,
cross_turn_dedup_recoverable=_dedup_pointers_recoverable,
# Thread the savings-profile knobs (e.g.
@@ -3940,6 +3946,7 @@ class OpenAIHandlerMixin:
frozen_message_count=apply_frozen_count,
prefix_replay_guaranteed=True,
biases=_hook_biases,
+ protect=_hook_protect,
compression_policy=compression_policy,
cross_turn_dedup_recoverable=_dedup_pointers_recoverable,
# Same savings-profile threading as the token-mode
diff --git a/headroom/transforms/content_router.py b/headroom/transforms/content_router.py
index 41fcd749d..395035623 100644
--- a/headroom/transforms/content_router.py
+++ b/headroom/transforms/content_router.py
@@ -5258,6 +5258,15 @@ class ContentRouter(Transform):
tokens_before = sum(tokenizer.count_text(str(m.get("content", ""))) for m in messages)
context = kwargs.get("context", "")
hook_biases: dict[int, float] = kwargs.get("biases") or {}
+ # Per-message veto from a compression hook (``CompressionHooks.
+ # protect_messages``). Distinct from ``biases``, which is a soft
+ # multiplier on how aggressively a compressor prunes: several
+ # strategies clamp or ignore it, so a bias — however large — cannot
+ # express "leave this one alone". This can. Empty unless a hook is
+ # installed, so the default path is unchanged.
+ hook_protect: set[int] = {
+ int(i) for i in (kwargs.get("protect") or ()) if isinstance(i, (int, bool))
+ }
# Build tool name map for exclusion checking
tool_name_map = self._build_tool_name_map(messages)
@@ -5557,6 +5566,14 @@ class ContentRouter(Transform):
content = message.get("content", "")
bias = 1.0 # Default bias, may be overridden for tool messages
+ # Hook veto, checked before any routing decision so it covers both
+ # the content-block path and the string path below.
+ if i in hook_protect:
+ result_slots[i] = message
+ transforms_applied.append("router:protected:hook")
+ route_counts["hook_protected"] = route_counts.get("hook_protected", 0) + 1
+ continue
+
messages_from_end = num_messages - i
# The caller's own words stay verbatim on a replaying path even
# when user messages are compressible for their tool observations:
diff --git a/tests/test_hook_protect_messages.py b/tests/test_hook_protect_messages.py
new file mode 100644
index 000000000..ff5b5255a
--- /dev/null
+++ b/tests/test_hook_protect_messages.py
@@ -0,0 +1,180 @@
+"""``CompressionHooks.protect_messages`` — the hard per-message veto.
+
+``compute_biases`` is a soft multiplier, and several strategies clamp it
+against their own floors or ignore it outright: measured against the log and
+JSON routes, bias 0.1 and bias 1000 produce byte-identical output. A hook that
+has concluded a specific message must survive verbatim therefore cannot say so
+with a bias, and this seam is how it says so instead.
+"""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from headroom import compress
+from headroom.hooks import CompressionHooks
+from headroom.tokenizers import get_tokenizer
+from headroom.transforms.content_router import ContentRouter
+
+MODEL = "gpt-4o"
+LOG = "\n".join(
+ f"2026-09-2{i % 9} 10:{i % 60:02d}:00 INFO worker={i} processed batch {i} in {i * 3}ms"
+ for i in range(300)
+)
+BLOB = json.dumps([{"id": i, "name": f"item-{i}", "size": i * 7} for i in range(200)])
+
+
+def openai_messages(body: str) -> list[dict]:
+ return [
+ {"role": "user", "content": "look"},
+ {
+ "role": "assistant",
+ "content": None,
+ "tool_calls": [
+ {
+ "id": "t1",
+ "type": "function",
+ "function": {"name": "run_terminal_cmd", "arguments": '{"command": "cat x"}'},
+ }
+ ],
+ },
+ {"role": "tool", "tool_call_id": "t1", "content": body},
+ {"role": "user", "content": "now summarise"},
+ ]
+
+
+def anthropic_messages(body: str) -> list[dict]:
+ return [
+ {"role": "user", "content": "look"},
+ {
+ "role": "assistant",
+ "content": [
+ {"type": "tool_use", "id": "t1", "name": "Bash", "input": {"command": "cat x"}}
+ ],
+ },
+ {
+ "role": "user",
+ "content": [{"type": "tool_result", "tool_use_id": "t1", "content": body}],
+ },
+ {"role": "user", "content": "now summarise"},
+ ]
+
+
+def _text_at(messages: list[dict], index: int) -> str:
+ content = messages[index]["content"]
+ if isinstance(content, str):
+ return content
+ return "".join(
+ block.get("content", "") if isinstance(block.get("content"), str) else ""
+ for block in content
+ )
+
+
+ "build", [openai_messages, anthropic_messages], ids=["openai", "anthropic"]
+)
[email protected]("body", [LOG, BLOB], ids=["log", "json"])
+def test_a_protected_message_survives_verbatim(build, body) -> None:
+ """Both content shapes, and routes that ignore bias entirely."""
+ tokenizer = get_tokenizer(MODEL)
+
+ compressed = ContentRouter().apply(build(body), tokenizer)
+ assert _text_at(compressed.messages, 2) != body, "fixture must actually be compressible"
+
+ protected = ContentRouter().apply(build(body), tokenizer, protect={2})
+ assert _text_at(protected.messages, 2) == body
+ assert "router:protected:hook" in protected.transforms_applied
+
+
+ "protect", [None, set(), {99}, frozenset()], ids=["none", "empty", "miss", "frozen"]
+)
+def test_the_seam_is_inert_unless_used(protect) -> None:
+ """The default path must be byte-identical to not passing the kwarg."""
+ tokenizer = get_tokenizer(MODEL)
+ baseline = ContentRouter().apply(openai_messages(LOG), tokenizer)
+ result = ContentRouter().apply(openai_messages(LOG), tokenizer, protect=protect)
+ assert _text_at(result.messages, 2) == _text_at(baseline.messages, 2)
+ assert "router:protected:hook" not in result.transforms_applied
+
+
+def test_protection_beats_every_bias() -> None:
+ """The point of the seam: no bias can do this."""
+ tokenizer = get_tokenizer(MODEL)
+ for bias in (0.1, 1.0, 8.0, 1000.0):
+ biased = ContentRouter().apply(openai_messages(LOG), tokenizer, biases={2: bias})
+ assert _text_at(biased.messages, 2) != LOG
+ protected = ContentRouter().apply(openai_messages(LOG), tokenizer, protect={2})
+ assert _text_at(protected.messages, 2) == LOG
+
+
+def test_the_default_hook_protects_nothing() -> None:
+ assert CompressionHooks().protect_messages(openai_messages(LOG), None) == set()
+
+
+def test_the_seam_is_reachable_from_the_sdk() -> None:
+ """Wiring check: a hook installed through ``compress(hooks=...)`` reaches
+ the router. Without this the seam exists and nobody can use it."""
+
+ class Protecting(CompressionHooks):
+ def protect_messages(self, messages, ctx):
+ return {2}
+
+ plain = compress(openai_messages(LOG), model=MODEL, hooks=CompressionHooks())
+ protecting = compress(openai_messages(LOG), model=MODEL, hooks=Protecting())
+
+ assert _text_at(plain.messages, 2) != LOG
+ assert _text_at(protecting.messages, 2) == LOG
+ assert protecting.tokens_after > plain.tokens_after
+
+
+def test_hooks_that_do_not_implement_it_still_work() -> None:
+ """A subclass predating this method inherits the empty default."""
+
+ class Legacy(CompressionHooks):
+ def compute_biases(self, messages, ctx):
+ return {2: 1.5}
+
+ result = compress(openai_messages(LOG), model=MODEL, hooks=Legacy())
+ assert result.tokens_after < result.tokens_before
+
+
+def test_a_hooks_object_that_is_not_a_subclass_still_compresses() -> None:
+ """The real compatibility case: ``hooks`` is duck-typed, not type-checked.
+
+ Nothing requires the object passed as ``hooks`` to subclass
+ CompressionHooks, so one written before ``protect_messages`` existed has no
+ such attribute. Calling it blind raises AttributeError inside the
+ compression block, which the proxy catches as a *compression failure* — so
+ the request would silently stop being compressed. That would make this
+ additive seam a regression for those callers.
+ """
+
+ class DuckTyped: # deliberately not a CompressionHooks subclass
+ def pre_compress(self, messages, ctx):
+ return messages
+
+ def compute_biases(self, messages, ctx):
+ return {}
+
+ def post_compress(self, event):
+ pass
+
+ def on_pipeline_event(self, event):
+ return None
+
+ result = compress(openai_messages(LOG), model=MODEL, hooks=DuckTyped())
+ assert result.tokens_after < result.tokens_before
+
+
+def test_collect_protected_reports_a_missing_method_as_no_vetoes() -> None:
+ from headroom.hooks import CompressContext, collect_protected
+
+ class Without:
+ pass
+
+ ctx = CompressContext(model=MODEL)
+ assert collect_protected(Without(), [], ctx) is None
+ assert collect_protected(CompressionHooks(), [], ctx) == set()