fix(proxy): make HEADROOM_DEFERRED_TOOL_AFFINITY a runtime-env knob

The rollback read the proxy's own environment, so `headroom wrap` reusing a
running proxy never propagated it: runtime_env.explicit_env dropped the key
and the default-on lineage behaviour stayed on. The knob is now registered
in RUNTIME_ENV_KNOBS and read through runtime_env.getenv in the Anthropic
handler, next to the first-party gate. cache_key_tools stays a pure filter,
so headroom.cache keeps no dependency on headroom.proxy. The security-model
allowlist lists the knob, and a test shows a propagated override counts
deferred tools again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Garm
2026-10-14 14:44:07 +02:00
co-authored by Claude Opus 5.5
parent 2cca8abe9a
commit 5b83c2ec1e
5 changed files with 33 additions and 11 deletions
+1
View File
@@ -284,6 +284,7 @@ accept arbitrary environment variables — writes are restricted to a hardcoded
| `HEADROOM_INTERCEPT_READ_MIN_CHARS` | ast-grep read-interception threshold |
| `HEADROOM_VERIFY_TRUNCATION_ON_DISK` | Verify ast-grep Read truncation against disk when no client banner is found. Always returns `UNKNOWN` on Windows, where `dir_fd` / `O_NOFOLLOW` support is unavailable. |
| `HEADROOM_VERIFY_TRUNCATION_MAX_BYTES` | Max on-disk file size (bytes) the disk-verify fallback will read |
| `HEADROOM_DEFERRED_TOOL_AFFINITY` | Keep `defer_loading` tools out of the Anthropic prefix-tracker lineage key (default on; `0` counts them again) |
Keys outside this list are ignored, and `/admin/upstream` is read-only — there is no
write route on the admin surface, specifically so a caller cannot redirect
+3 -8
View File
@@ -543,9 +543,6 @@ def classify_history_relation(
return _classify_history_canonical(current, previous)
_DEFERRED_TOOL_AFFINITY_ENV = "HEADROOM_DEFERRED_TOOL_AFFINITY"
def cache_key_tools(tools: Any) -> Any:
"""The Anthropic ``tools`` that count toward the prompt-cache key.
@@ -554,12 +551,10 @@ def cache_key_tools(tools: Any) -> Any:
Code appends every tool its ToolSearch loads to ``tools``, still marked
deferred; counting those would start a new lineage at frozen=0 after each
load and re-run the whole history. Every other tool, and a tool whose
``defer_loading`` is cleared, still counts.
``HEADROOM_DEFERRED_TOOL_AFFINITY=0`` counts every tool again.
``defer_loading`` is cleared, still counts. The Anthropic handler decides
when to apply this (first-party upstream, ``HEADROOM_DEFERRED_TOOL_AFFINITY``).
"""
if not isinstance(tools, list) or os.environ.get(
_DEFERRED_TOOL_AFFINITY_ENV, ""
).strip().lower() in ("0", "false", "no", "off"):
if not isinstance(tools, list):
return tools
return [t for t in tools if not (isinstance(t, dict) and t.get("defer_loading"))]
+4
View File
@@ -1671,9 +1671,13 @@ class AnthropicHandlerMixin:
affinity_tools = self._tools_for_forwarding(
body.get("tools"), preserve_order=preserve_tool_order
)
from headroom.proxy import runtime_env
if (
not _third_party_anthropic_upstream
and getattr(self, "anthropic_backend", None) is None
and runtime_env.getenv("HEADROOM_DEFERRED_TOOL_AFFINITY", "1").strip().lower()
not in ("0", "false", "no", "off")
):
affinity_tools = cache_key_tools(affinity_tools)
cache_affinity = segment_fingerprint(
+6
View File
@@ -84,6 +84,12 @@ RUNTIME_ENV_KNOBS: tuple[Knob, ...] = (
"int",
"Max on-disk file size (bytes) the disk-verify fallback will read.",
),
Knob(
"HEADROOM_DEFERRED_TOOL_AFFINITY",
"bool",
"Keep defer_loading tools out of the Anthropic prefix-tracker lineage key "
"(default on; 0 counts them again).",
),
)
_KNOBS_BY_ENV: dict[str, Knob] = {k.env: k for k in RUNTIME_ENV_KNOBS}
+19 -3
View File
@@ -308,6 +308,24 @@ def test_kill_switch_keys_deferred_tools_again(monkeypatch) -> None: # noqa: AN
assert after["read"] == 0
def test_runtime_env_override_keys_deferred_tools_again() -> None:
# `headroom wrap` pushes this knob to a reused proxy, so the rollback
# works without the proxy's own environment or a restart.
from headroom.proxy import runtime_env
assert runtime_env.explicit_env({"HEADROOM_DEFERRED_TOOL_AFFINITY": "0"}) == {
"HEADROOM_DEFERRED_TOOL_AFFINITY": "0"
}
runtime_env.set_overrides({"HEADROOM_DEFERRED_TOOL_AFFINITY": "0"})
try:
before, after = _session(LOADED)
finally:
runtime_env.clear_overrides()
assert after["tracker"] is not before["tracker"]
assert after["frozen"] == 0
def test_eager_tool_still_starts_a_new_lineage() -> None:
before, after = _session(EAGER)
@@ -315,12 +333,10 @@ def test_eager_tool_still_starts_a_new_lineage() -> None:
assert after["frozen"] == 0
def test_cache_key_tools_drops_only_deferred_tools(monkeypatch) -> None: # noqa: ANN001
def test_cache_key_tools_drops_only_deferred_tools() -> None:
undeferred = {**LOADED, "defer_loading": False}
tools = [READ, LOADED, undeferred]
assert cache_key_tools(tools) == [READ, undeferred]
assert tools == [READ, LOADED, undeferred]
assert cache_key_tools(None) is None
monkeypatch.setenv("HEADROOM_DEFERRED_TOOL_AFFINITY", "off")
assert cache_key_tools(tools) is tools