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(memory): avoid injecting tools into tool-free requests (#3677)

AxelRay46755b5f7280
diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.py
index 584bcfafd..9ca8199f2 100644
--- a/headroom/proxy/handlers/anthropic.py
+++ b/headroom/proxy/handlers/anthropic.py
@@ -2797,6 +2797,7 @@ class AnthropicHandlerMixin:
existing_tools=tools,
memory_tools_to_inject=memory_tool_defs,
inject_this_turn=bool(self.memory_handler.config.inject_tools),
+ client_declared_tools=bool(_original_tools),
)
if mem_tools_injected:
memory_tools_injected = True
diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.py
index 4bccb8779..77c659b68 100644
--- a/headroom/proxy/handlers/openai.py
+++ b/headroom/proxy/handlers/openai.py
@@ -192,6 +192,17 @@ def _codex_ws_compression_timeout_seconds() -> float:
_WS_ALLOWED_ORIGINS_ENV = "HEADROOM_WS_ORIGINS"
_CORS_ALLOWED_ORIGINS_ENV = "HEADROOM_CORS_ORIGINS"
_CODEX_RESPONSES_LITE_HEADER = "x-openai-internal-codex-responses-lite"
+# Memory-tool injection needs affirmative protocol evidence. A caller that
+# explicitly supplies tools is handled separately at each endpoint; when the
+# caller omits them, only a real client known to support Headroom's memory
+# tools may opt in.
+_KNOWN_TOOL_CAPABLE_CLIENTS = frozenset({"codex"})
+
+
+def _client_can_receive_memory_tools(client: str | None) -> bool:
+ return client in _KNOWN_TOOL_CAPABLE_CLIENTS
+
+
# Codex mirrors the responses-lite request header into the response.create
# frame body under client_metadata; upstream rejects gpt-5.x when it is
# truthy. Stripping the WS handshake header alone is insufficient
@@ -4352,6 +4363,7 @@ class OpenAIHandlerMixin:
existing_tools=tools,
memory_tools_to_inject=memory_tool_defs,
inject_this_turn=bool(self.memory_handler.config.inject_tools),
+ client_declared_tools=bool(_original_tools),
)
if mem_tools_injected:
memory_tools_injected = True
@@ -5842,6 +5854,14 @@ class OpenAIHandlerMixin:
headers, is_chatgpt_auth = _resolve_codex_routing_headers(headers)
if is_chatgpt_auth:
client = "codex"
+ memory_client = (
+ "codex"
+ if is_chatgpt_auth
+ else (None if request.scope.get("headroom_codex_client_stamped") else client)
+ )
+ client_declared_response_tools = bool(
+ body.get("tools")
+ ) or _client_can_receive_memory_tools(memory_client)
if _ensure_chatgpt_responses_store_false(body, is_chatgpt_auth=is_chatgpt_auth):
logger.info(f"[{request_id}] Responses: forced store=false for ChatGPT auth")
responses_memory_tools_allowed = _allow_responses_memory_tools(is_chatgpt_auth)
@@ -6112,6 +6132,7 @@ class OpenAIHandlerMixin:
existing_tools=resp_tools,
memory_tools_to_inject=memory_tool_defs_responses,
inject_this_turn=bool(self.memory_handler.config.inject_tools),
+ client_declared_tools=client_declared_response_tools,
)
if mem_tools_injected:
body["tools"] = resp_tools
@@ -7101,7 +7122,9 @@ class OpenAIHandlerMixin:
# WS sessions bypass the HTTP middleware that stamps X-Client: codex on
# the Responses endpoint, so apply the same path-based stamp here before
# classify_client runs (parallels server.py / should_stamp_codex_client).
- if should_stamp_codex_client(_ws_path, ws_headers):
+ codex_client_was_stamped = should_stamp_codex_client(_ws_path, ws_headers)
+ raw_client = classify_client(ws_headers)
+ if codex_client_was_stamped:
ws_headers["x-client"] = "codex"
# Identify the WS harness before downstream auth/header rewrites.
# Captured in closure so per-turn RequestOutcome can stamp it.
@@ -7186,6 +7209,9 @@ class OpenAIHandlerMixin:
)
upstream_headers, is_chatgpt_auth = _resolve_codex_routing_headers(upstream_headers)
+ memory_client = (
+ "codex" if is_chatgpt_auth else (None if codex_client_was_stamped else raw_client)
+ )
# OpenAI rejects newer Codex models when this client-only lite header leaks upstream.
upstream_headers = {
key: value
@@ -7807,6 +7833,9 @@ class OpenAIHandlerMixin:
t.get("name") or t.get("function", {}).get("name", "?")
for t in (ws_response_body.get("tools") or [])
]
+ client_declared_ws_tools = bool(
+ ws_response_body.get("tools")
+ ) or _client_can_receive_memory_tools(memory_client)
instr_preview = (ws_response_body.get("instructions") or "")[:200]
logger.info(
f"[{request_id}] WS Memory: Codex tools={existing_tool_names}, "
@@ -7927,6 +7956,7 @@ class OpenAIHandlerMixin:
inject_this_turn=bool(
self.memory_handler.config.inject_tools and ws_memory_tools_allowed
),
+ client_declared_tools=client_declared_ws_tools,
)
if mem_injected:
ws_response_body["tools"] = ws_tools
diff --git a/headroom/proxy/helpers.py b/headroom/proxy/helpers.py
index b7f502759..c1d0cb58d 100644
--- a/headroom/proxy/helpers.py
+++ b/headroom/proxy/helpers.py
@@ -2403,6 +2403,7 @@ def apply_session_sticky_memory_tools(
existing_tools: list[dict[str, Any]] | None,
memory_tools_to_inject: list[dict[str, Any]],
inject_this_turn: bool,
+ client_declared_tools: bool = True,
) -> tuple[list[dict[str, Any]], bool]:
"""Apply sticky-on memory tool injection per `SessionToolTracker`.
@@ -2431,6 +2432,11 @@ def apply_session_sticky_memory_tools(
``inject_this_turn`` flag drives the decision verbatim. We log the
bypass once so operators can see it.
+ ``client_declared_tools`` is False when the inbound request omitted
+ tools or explicitly sent an empty list. In that case memory tools are
+ never added, including sticky replay, because the client cannot service
+ them.
+
Returns ``(updated_tools, was_injected)``. The returned list is a
fresh list (caller-safe). ``was_injected`` is True iff at least one
memory tool was added to the list.
@@ -2439,6 +2445,16 @@ def apply_session_sticky_memory_tools(
raise ValueError(f"unsupported provider: {provider!r}")
tools_out: list[dict[str, Any]] = list(existing_tools) if existing_tools else []
+ if not client_declared_tools:
+ log_tool_injection_decision(
+ provider=provider,
+ session_id=session_id,
+ decision="skip_no_client_tools",
+ tool_definition_bytes_count=0,
+ request_id=request_id,
+ )
+ return tools_out, False
+
existing_names: set[str] = set()
for t in tools_out:
n = _extract_tool_name(t)
diff --git a/headroom/proxy/server.py b/headroom/proxy/server.py
index 9a0ddf14c..11ca2f9fc 100644
--- a/headroom/proxy/server.py
+++ b/headroom/proxy/server.py
@@ -3728,6 +3728,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
# hard connection failure. Mutating scope["headers"] before call_next
# makes every downstream classify_client(headers) read "codex".
if should_stamp_codex_client(path, headers):
+ request.scope["headroom_codex_client_stamped"] = True
request.scope["headers"].append((b"x-client", b"codex"))
client = getattr(request, "client", None)
client_addr = ""
diff --git a/headroom/proxy/tool_injection_logging.py b/headroom/proxy/tool_injection_logging.py
index ad05554eb..a05b0b0b6 100644
--- a/headroom/proxy/tool_injection_logging.py
+++ b/headroom/proxy/tool_injection_logging.py
@@ -18,6 +18,7 @@ ToolInjectionDecision = Literal[
# tool definition is re-injected even without fresh compression (#2440).
"inject_history_reference",
"skip",
+ "skip_no_client_tools",
"skip_disabled_via_env",
]
diff --git a/tests/test_codex_ws_per_frame_memory.py b/tests/test_codex_ws_per_frame_memory.py
index 278b00ec3..8949c4672 100644
--- a/tests/test_codex_ws_per_frame_memory.py
+++ b/tests/test_codex_ws_per_frame_memory.py
@@ -72,6 +72,24 @@ def _turn(text: str) -> str:
return json.dumps({"type": "response.create", "response": {"input": text}})
+def _turn_with_tools(text: str, tools: list[dict[str, object]] | None) -> str:
+ response: dict[str, object] = {"input": text}
+ if tools is not None:
+ response["tools"] = tools
+ return json.dumps({"type": "response.create", "response": response})
+
+
+def _client_response_tools() -> list[dict[str, object]]:
+ return [
+ {
+ "type": "function",
+ "name": "client_tool",
+ "description": "client tool",
+ "parameters": {"type": "object", "properties": {}},
+ }
+ ]
+
+
def _direct_turn(text: str) -> str:
return json.dumps({"input": text})
@@ -152,9 +170,9 @@ async def test_memory_lookup_runs_for_each_issue_artifact_frame_and_preserves_no
first_turn, later_turn = _issue_2059_turns()
first_input, later_input = _issue_2059_inputs()
client_frames = [
- first_turn,
+ _turn_with_tools(json.loads(first_turn)["response"]["input"], _client_response_tools()),
json.dumps({"type": "response.cancel"}),
- later_turn,
+ _turn_with_tools(json.loads(later_turn)["response"]["input"], _client_response_tools()),
]
client_ws = _FakeWebSocket(frames=client_frames)
handler = _DummyOpenAIHandler()
@@ -171,12 +189,36 @@ async def test_memory_lookup_runs_for_each_issue_artifact_frame_and_preserves_no
]
assert f"current memory: {first_input}" in forwarded_turns[0]["response"]["input"]
assert f"current memory: {later_input}" in forwarded_turns[1]["response"]["input"]
- expected_tools = _expected_memory_response_tools()
+ expected_tools = [*_client_response_tools(), *_expected_memory_response_tools()]
for frame in forwarded_turns:
assert frame["response"]["tools"] == expected_tools
assert forwarded_turns[0]["response"]["tools"] == forwarded_turns[1]["response"]["tools"]
[email protected]("tools", [None, []], ids=["omitted", "empty"])
+async def test_ws_responses_do_not_inject_memory_tools_without_client_tools(tools):
+ upstream = _FakeUpstream(
+ [
+ json.dumps({"type": "response.created", "response": {"id": "r_no_tools"}}),
+ json.dumps({"type": "response.completed", "response": {"id": "r_no_tools"}}),
+ ]
+ )
+ client_ws = _FakeWebSocket(
+ frames=[_turn_with_tools("no tools requested", tools)],
+ headers={"authorization": "Bearer test", "x-client": "unknown-client"},
+ )
+ handler = _DummyOpenAIHandler()
+ handler.memory_handler = _MemoryHandler()
+
+ with patch.dict(sys.modules, {"websockets": _make_fake_websockets_module(upstream)}):
+ await handler.handle_openai_responses_ws(client_ws)
+
+ forwarded = [json.loads(frame) for frame in upstream.sent if "response" in json.loads(frame)]
+ assert forwarded
+ assert forwarded[0]["response"].get("tools", []) == []
+
+
@pytest.mark.asyncio
async def test_memory_lookup_skips_input_bearing_non_create_first_frame():
upstream = _FakeUpstream(
diff --git a/tests/test_memory_tool_session_sticky.py b/tests/test_memory_tool_session_sticky.py
index dd3b761f5..c20931019 100644
--- a/tests/test_memory_tool_session_sticky.py
+++ b/tests/test_memory_tool_session_sticky.py
@@ -500,6 +500,51 @@ def test_memory_disabled_after_inject_still_injects() -> None:
assert bytes1 == bytes2
+def test_no_client_tools_suppresses_fresh_and_sticky_injection() -> None:
+ """Requests without client-declared tools must not receive memory tools."""
+ defs = _anthropic_memory_defs()
+ client_tools = [{"name": "client_tool", "description": "client-owned", "input_schema": {}}]
+
+ fresh_tools, fresh_was = apply_session_sticky_memory_tools(
+ provider="anthropic",
+ session_id="s-fresh-no-client-tools",
+ request_id="r-fresh",
+ existing_tools=None,
+ memory_tools_to_inject=defs,
+ inject_this_turn=True,
+ client_declared_tools=False,
+ )
+ assert fresh_was is False
+ assert fresh_tools == []
+
+ # Establish sticky memory tools while the client has declared tools.
+ tools1, was1 = apply_session_sticky_memory_tools(
+ provider="anthropic",
+ session_id="s-no-client-tools",
+ request_id="r-1",
+ existing_tools=client_tools,
+ memory_tools_to_inject=defs,
+ inject_this_turn=True,
+ client_declared_tools=True,
+ )
+ assert was1 is True
+ assert "memory_search" in _names_in(tools1)
+
+ # A later request omits tools entirely. Sticky replay must not turn it into
+ # a tool-capable request that the client cannot service.
+ tools2, was2 = apply_session_sticky_memory_tools(
+ provider="anthropic",
+ session_id="s-no-client-tools",
+ request_id="r-2",
+ existing_tools=[],
+ memory_tools_to_inject=defs,
+ inject_this_turn=True,
+ client_declared_tools=False,
+ )
+ assert was2 is False
+ assert tools2 == []
+
+
def test_different_sessions_independent() -> None:
"""Session A injects; session B doesn't; verify isolation."""
defs = _anthropic_memory_defs()
diff --git a/tests/test_openai_codex_routing.py b/tests/test_openai_codex_routing.py
index 5b7d4b0d2..447a10196 100644
--- a/tests/test_openai_codex_routing.py
+++ b/tests/test_openai_codex_routing.py
@@ -553,7 +553,11 @@ def test_handle_openai_responses_chatgpt_codex_timeout_fails_open(monkeypatch):
def test_handle_openai_responses_api_auth_store_false_injects_stateless_memory_tools(monkeypatch):
request = _build_request(
{"model": "gpt-4o-mini", "input": "hello", "store": False},
- {"Authorization": "Bearer sk-test", "x-headroom-user-id": "user-1"},
+ {
+ "Authorization": "Bearer sk-test",
+ "User-Agent": "codex-cli/0.5",
+ "x-headroom-user-id": "user-1",
+ },
)
handler = _DummyOpenAIHandler()
memory_handler = _MemoryToolsOnlyHandler()
@@ -618,7 +622,11 @@ def test_openai_responses_memory_continuation_is_zdr_safe(store, include, monkey
body["store"] = store
request = _build_request(
body,
- {"Authorization": "Bearer sk-test", "x-headroom-user-id": "user-1"},
+ {
+ "Authorization": "Bearer sk-test",
+ "User-Agent": "codex-cli/0.5",
+ "x-headroom-user-id": "user-1",
+ },
)
handler = _ZdrResponsesHandler()
diff --git a/tests/test_openai_codex_ws_lifecycle.py b/tests/test_openai_codex_ws_lifecycle.py
index 37331607d..054cd921a 100644
--- a/tests/test_openai_codex_ws_lifecycle.py
+++ b/tests/test_openai_codex_ws_lifecycle.py
@@ -195,7 +195,13 @@ class _FakeWebSocket:
hold_after_initial: bool = False,
call_log: list[str] | None = None,
) -> None:
- self.headers = dict(headers or {"authorization": "Bearer test"})
+ self.headers = dict(
+ headers
+ or {
+ "authorization": "Bearer test",
+ "user-agent": "codex-cli/0.5",
+ }
+ )
self._frames = list(frames or [])
self._hold_after_initial = hold_after_initial
self._disconnect_after_n_sends = disconnect_after_n_sends
diff --git a/tests/test_proxy_openai_responses_bypass.py b/tests/test_proxy_openai_responses_bypass.py
index f119d435b..864f188eb 100644
--- a/tests/test_proxy_openai_responses_bypass.py
+++ b/tests/test_proxy_openai_responses_bypass.py
@@ -112,3 +112,58 @@ def test_responses_bypass_skips_memory_and_compression_mutation() -> None:
assert "tools" not in captured["body"]
assert memory_handler.search_calls == 0
assert memory_handler.tool_calls == 0
+
+
[email protected]("tools", [None, []], ids=["omitted", "empty"])
+def test_responses_do_not_inject_memory_tools_without_client_tools(tools) -> None:
+ app = create_app(
+ ProxyConfig(
+ optimize=False,
+ cache_enabled=False,
+ rate_limit_enabled=False,
+ cost_tracking_enabled=False,
+ log_requests=False,
+ )
+ )
+ app.dependency_overrides[require_loopback] = lambda: None
+ captured: dict[str, Any] = {}
+
+ with TestClient(app) as client:
+ proxy = client.app.state.proxy
+ memory_handler = _MemoryHandler()
+ memory_handler.config.inject_context = False
+ proxy.memory_handler = memory_handler
+
+ async def _fake_retry(
+ method: str,
+ url: str,
+ headers: dict[str, str],
+ body: dict[str, Any],
+ stream: bool = False,
+ **kwargs: Any,
+ ) -> httpx.Response:
+ captured["body"] = dict(body)
+ return httpx.Response(
+ 200,
+ json={
+ "id": "resp_no_memory_tools",
+ "output": [],
+ "usage": {"input_tokens": 1, "output_tokens": 1},
+ },
+ )
+
+ proxy._retry_request = _fake_retry
+ payload: dict[str, Any] = {"model": "gpt-4o-mini", "input": "hello"}
+ if tools is not None:
+ payload["tools"] = tools
+ response = client.post(
+ "/v1/responses",
+ headers={
+ "authorization": "Bearer test-key",
+ "x-headroom-user-id": "user-no-memory-tools",
+ },
+ json=payload,
+ )
+
+ assert response.status_code == 200
+ assert captured["body"].get("tools", []) == []