fix(memory): avoid injecting tools into tool-free requests (#3677)

## Description

Memory tool injection should be suppressed only for a client that is
explicitly known not to support tools. An omitted or empty `tools` field
is not enough to make that determination because Codex and other clients
may advertise tool capability out of band.

Closes #3676

## Changes Made

- Carry the client capability decision through the Anthropic and OpenAI
Responses paths.
- Preserve existing and sticky memory tools for Codex and unknown
clients.
- Suppress fresh and sticky memory-tool injection only for an explicitly
tool-incapable client.
- Add endpoint-level and helper regressions for that distinction.

## Testing

- Targeted memory and routing tests passed locally.
- `ruff check .` passed.
- `ruff format --check .` passed.
- `mypy` passed for the changed modules.
- GitHub CI is running on the current head.

## Runtime Rollout Safety

- No new feature flag, schema, or migration is introduced.
- Existing memory injection configuration remains the available disable
path.
- Rollback is a normal revert of this change.

## Review Readiness

- Self-review completed.
- The PR is ready for human review.

---------

Co-authored-by: JD Davis <mxjerrett@gmail.com>
This commit is contained in:
AxelRay
2026-09-29 15:31:35 -05:00
committed by GitHub
co-authored by JD Davis
parent 3ffa57ec25
commit 46755b5f72
10 changed files with 212 additions and 7 deletions
+1
View File
@@ -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
+31 -1
View File
@@ -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
+16
View File
@@ -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)
+1
View File
@@ -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 = ""
+1
View File
@@ -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",
]
+45 -3
View File
@@ -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"]
@pytest.mark.asyncio
@pytest.mark.parametrize("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(
+45
View File
@@ -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()
+10 -2
View File
@@ -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()
+7 -1
View File
@@ -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
@@ -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
@pytest.mark.parametrize("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", []) == []