fix(ccr): re-inject headroom_retrieve when history references it on the sessionless path (#2440) (#2533)

## Description

Fixes #2440. `apply_session_sticky_ccr_tool` bypasses the
`SessionCcrTracker` when `session_id` is `None` (WS / pre-session paths)
and drives injection purely off the per-turn
`has_compressed_content_this_turn` flag:

```python
if not session_id:
    if not has_compressed_content_this_turn:
        ...  # skip: tool NOT re-declared
        return tools_out, False
    ...
```

If an earlier turn emitted a `headroom_retrieve` tool_use into history
but the current turn produced no fresh compression marker, the tool
definition is not re-declared in `tools`, while the forwarded history
still references it. The provider then rejects the whole request:

```
API Error: 400 Tool reference 'headroom_retrieve' not found in available tools.
```

Without a session the tracker can't remember the earlier turn's CCR, so
this is unique to the sessionless path.

## Fix

Add `history_references_ccr_tool(messages)` which detects an existing
`headroom_retrieve` call in the forwarded messages — both the Anthropic
assistant `tool_use` content block and the OpenAI assistant
`tool_calls[].function.name` shapes, fully null-guarded. On the
sessionless path, injection now fires when
`has_compressed_content_this_turn` **or** history already references the
tool, so the definition is re-declared and the request validates. The
decision is logged as a new `inject_history_reference` outcome. Both
handlers pass the signal computed from `optimized_messages` (the bytes
actually forwarded). Behavior with a real `session_id` (the sticky
tracker path) is unchanged.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `headroom/proxy/helpers.py`: add `history_references_ccr_tool`; add a
`history_has_ccr_reference` parameter to `apply_session_sticky_ccr_tool`
and OR it into the sessionless injection decision.
- `headroom/proxy/tool_injection_logging.py`: add the
`inject_history_reference` decision literal.
- `headroom/proxy/handlers/anthropic.py`,
`headroom/proxy/handlers/openai.py`: pass
`history_references_ccr_tool(optimized_messages)` into the sticky-tool
call.
- `tests/test_ccr_tool_always_on.py`: regressions for the detector (both
provider shapes + malformed inputs) and for sessionless re-injection
when history references the tool.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [ ] Manual testing performed

### Test Output

```text
$ python -m pytest tests/test_ccr_tool_always_on.py -q
14 passed

# with just the `or history_has_ccr_reference` condition reverted, the new
# sessionless re-injection test fails (tool not injected -> would 400)

$ uvx ruff@0.15.17 check headroom/proxy/helpers.py headroom/proxy/tool_injection_logging.py headroom/proxy/handlers/anthropic.py headroom/proxy/handlers/openai.py tests/test_ccr_tool_always_on.py
All checks passed!
$ uvx mypy@1.20.2 --ignore-missing-imports headroom/proxy/helpers.py headroom/proxy/tool_injection_logging.py
Success: no issues found in 2 source files
```

## Real Behavior Proof

- Environment: Windows 11, Python 3.12, project venv (`uv sync --extra
proxy`), `uvx ruff@0.15.17` / `uvx mypy@1.20.2`, pytest in the venv.
- Exact command / steps: called `history_references_ccr_tool` on
Anthropic `tool_use` and OpenAI `tool_calls` histories (plus
null/non-list shapes), and
`apply_session_sticky_ccr_tool(session_id=None,
has_compressed_content_this_turn=False,
history_has_ccr_reference=True)`; then temporarily reverted only the `or
history_has_ccr_reference` condition and re-ran the regression.
- Observed result: the detector returns `True` for both provider shapes
and `False`/no-crash for malformed input; with the fix the sessionless
call injects the tool (`was_injected=True`, tool present) even with no
fresh compression; with the condition reverted the same call returns
`was_injected=False` (the tool is dropped — exactly the 400 path). Ran
against the actual module via `tests/test_ccr_tool_always_on.py`.
- Not tested: a live sessionless multi-turn WS request reproducing the
upstream 400 end to end.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [ ] I have updated the CHANGELOG.md if applicable

Co-authored-by: JD Davis <jd@jds-macbook-air.tail2a279.ts.net>

headroom/proxy/handlers/anthropic.py

@@ -2026,7 +2026,10 @@ class AnthropicHandlerMixin:
                 # dropping the gate cannot start injecting into non-CCR
                 # conversations.
                 if configured_inject_tool:
-                    from headroom.proxy.helpers import apply_session_sticky_ccr_tool
+                    from headroom.proxy.helpers import (
+                        apply_session_sticky_ccr_tool,
+                        history_references_ccr_tool,
+                    )
 
                     # Inject whenever the request carries ANY CCR marker, new or
                     # replayed from the frozen prefix. #1850 narrowed the
@@ -2051,6 +2054,7 @@ class AnthropicHandlerMixin:
                         request_id=request_id,
                         existing_tools=tools,
                         has_compressed_content_this_turn=injector.has_compressed_content,
+                        history_has_ccr_reference=history_references_ccr_tool(optimized_messages),
                     )
                     if ccr_tool_injected:
                         logger.debug(

headroom/proxy/handlers/openai.py

@@ -3573,6 +3573,7 @@ class OpenAIHandlerMixin:
                 from headroom.proxy.helpers import (
                     apply_session_sticky_ccr_tool,
                     has_new_ccr_markers,
+                    history_references_ccr_tool,
                 )
 
                 # #1850: markers replayed from overlay_cached_prefix are
@@ -3591,6 +3592,7 @@ class OpenAIHandlerMixin:
                     request_id=request_id,
                     existing_tools=tools,
                     has_compressed_content_this_turn=has_new_compressed_content,
+                    history_has_ccr_reference=history_references_ccr_tool(optimized_messages),
                 )
                 if ccr_tool_injected:
                     logger.debug(

headroom/proxy/helpers.py

@@ -2102,6 +2102,43 @@ def has_new_ccr_markers(
     )
 
 
+def history_references_ccr_tool(messages: Any) -> bool:
+    """True when the request history already contains a ``headroom_retrieve`` call.
+
+    Anthropic emits it as an assistant ``tool_use`` content block; OpenAI as an
+    assistant ``tool_calls[].function.name``. When such a reference is present in
+    history but the tool is not re-declared in ``tools``, the provider rejects
+    the whole request (``400 Tool reference 'headroom_retrieve' not found``,
+    #2440). Used to force sticky re-injection on the sessionless path.
+    """
+    from headroom.ccr.tool_injection import CCR_TOOL_NAME
+
+    if not isinstance(messages, list):
+        return False
+    for msg in messages:
+        if not isinstance(msg, dict):
+            continue
+        content = msg.get("content")
+        if isinstance(content, list):
+            for block in content:
+                if (
+                    isinstance(block, dict)
+                    and block.get("type") == "tool_use"
+                    and block.get("name") == CCR_TOOL_NAME
+                ):
+                    return True
+        tool_calls = msg.get("tool_calls")
+        if isinstance(tool_calls, list):
+            for tc in tool_calls:
+                if not isinstance(tc, dict):
+                    continue
+                fn = tc.get("function")
+                name = fn.get("name") if isinstance(fn, dict) else tc.get("name")
+                if name == CCR_TOOL_NAME:
+                    return True
+    return False
+
+
 def apply_session_sticky_ccr_tool(
     *,
     provider: Literal["anthropic", "openai", "google"],
@@ -2109,6 +2146,7 @@ def apply_session_sticky_ccr_tool(
     request_id: str | None,
     existing_tools: list[dict[str, Any]] | None,
     has_compressed_content_this_turn: bool,
+    history_has_ccr_reference: bool = False,
 ) -> tuple[list[dict[str, Any]], bool]:
     """Apply sticky-on CCR retrieval-tool injection per :class:`SessionCcrTracker`.
 
@@ -2157,9 +2195,14 @@ def apply_session_sticky_ccr_tool(
         )
         return tools_out, False
 
-    # No session_id (e.g. WS path): per-turn decision drives directly.
+    # No session_id (e.g. WS path): the per-turn flag drives the decision, but
+    # a headroom_retrieve tool_use already sitting in history must ALSO force
+    # re-injection. Without a session the tracker can't remember a prior turn's
+    # CCR, so a later turn with no fresh compression would drop the tool
+    # definition and the provider rejects the request because history still
+    # references it (#2440).
     if not session_id:
-        if not has_compressed_content_this_turn:
+        if not (has_compressed_content_this_turn or history_has_ccr_reference):
             log_tool_injection_decision(
                 provider=provider,
                 session_id=None,
@@ -2173,7 +2216,9 @@ def apply_session_sticky_ccr_tool(
         log_tool_injection_decision(
             provider=provider,
             session_id=None,
-            decision="inject_first_time",
+            decision="inject_first_time"
+            if has_compressed_content_this_turn
+            else "inject_history_reference",
             tool_definition_bytes_count=len(replay.canonical_bytes),
             request_id=request_id,
         )

headroom/proxy/tool_injection_logging.py

@@ -8,6 +8,9 @@ from typing import Literal
 ToolInjectionDecision = Literal[
     "inject_first_time",
     "inject_sticky_replay",
+    # Sessionless path: history already references headroom_retrieve, so the
+    # tool definition is re-injected even without fresh compression (#2440).
+    "inject_history_reference",
     "skip",
     "skip_disabled_via_env",
 ]

tests/test_ccr_tool_always_on.py

@@ -30,6 +30,7 @@ from headroom.proxy.helpers import (
     _reset_session_ccr_tracker_for_test,
     apply_session_sticky_ccr_tool,
     get_session_ccr_tracker,
+    history_references_ccr_tool,
     serialize_tool_definition_canonical,
 )
 
@@ -228,6 +229,68 @@ def test_no_session_id_falls_back_to_per_turn_decision():
     assert _has_ccr_tool(tools)
 
 
+def test_history_references_ccr_tool_detects_both_provider_shapes():
+    # Anthropic: assistant tool_use content block.
+    anthropic_hist = [
+        {"role": "user", "content": "hi"},
+        {
+            "role": "assistant",
+            "content": [{"type": "tool_use", "name": CCR_TOOL_NAME, "id": "t1", "input": {}}],
+        },
+    ]
+    assert history_references_ccr_tool(anthropic_hist) is True
+
+    # OpenAI: assistant tool_calls[].function.name.
+    openai_hist = [
+        {
+            "role": "assistant",
+            "tool_calls": [{"id": "c1", "function": {"name": CCR_TOOL_NAME, "arguments": "{}"}}],
+        }
+    ]
+    assert history_references_ccr_tool(openai_hist) is True
+
+    # No reference, and malformed shapes must not crash.
+    assert history_references_ccr_tool([{"role": "user", "content": "hi"}]) is False
+    assert (
+        history_references_ccr_tool([{"content": None}, {"tool_calls": None}, "x", None]) is False
+    )
+    assert history_references_ccr_tool("not-a-list") is False
+
+
+def test_sessionless_history_reference_forces_reinjection():
+    """#2440: no session_id + no fresh compression, but history already
+    references headroom_retrieve → the tool definition MUST be re-injected,
+    otherwise the provider rejects the request (400 tool not found)."""
+    history = [
+        {
+            "role": "assistant",
+            "content": [{"type": "tool_use", "name": CCR_TOOL_NAME, "id": "t1", "input": {}}],
+        }
+    ]
+
+    tools, injected = apply_session_sticky_ccr_tool(
+        provider="anthropic",
+        session_id=None,
+        request_id="r3",
+        existing_tools=None,
+        has_compressed_content_this_turn=False,
+        history_has_ccr_reference=history_references_ccr_tool(history),
+    )
+    assert injected is True
+    assert _has_ccr_tool(tools)
+
+    # No history reference and no fresh compression → still skip.
+    tools, injected = apply_session_sticky_ccr_tool(
+        provider="anthropic",
+        session_id=None,
+        request_id="r4",
+        existing_tools=None,
+        has_compressed_content_this_turn=False,
+        history_has_ccr_reference=False,
+    )
+    assert injected is False
+
+
 # ─── Byte-stable tool definition ───────────────────────────────────────