fix(ccr): only proactively expand compressions present in the requesting conversation (#3924)

## Description

**What users see:** with Claude Code agent teams behind the proxy in
`token` mode, a teammate can receive a large block of another agent's
tool output glued onto the message it got from the lead. The teammate
never ran that tool, so it treats the block as junk ("got system context
garbage message, ignoring it" in #1174). The lead is not affected.

**Why it happens:** CCR proactive expansion keeps one tracker per proxy
process of every lossy compression it made. When a new user message
shares a few keywords with one of them, it appends that compression's
full original text to the message. Since the 2026-05-26 cross-project
leak, the tracker filters by workspace (the cwd). But a lead and its
teammates run in the same cwd, so they share every tracked entry. A
teammate's `<teammate-message>` that mentions the same files as the
lead's earlier `Bash`/`Read` output pulls that output in. In the repro
below a 127-character teammate message reached the model as 27,722
characters.

**Fix:** only expand compressions that the requesting conversation
actually holds, meaning their CCR marker is in this request. The handler
already scans the request for markers and drops hashes this proxy never
stored (`injector.verify_ownership()`, used for `headroom_retrieve`
injection). It now hands that list to
`ContextTracker.analyze_query(present_hashes=...)`, which skips
everything else before ranking. A conversation that still sees a
compressed marker gets its expansion exactly as before. A compression it
never received was never "context it lost", so it is no longer a
candidate.

This uses content (markers in the request) rather than a session id.
Parallel agents with the same model and system prompt can share a
fallback session id (#2193), so the session id cannot tell them apart.

Refs #1174. Related: #2706 (stale, changes requested) asks for
per-session ownership plus a claim/release and replay guard, for the
duplicate-expansion cost problem in #2186. This PR is smaller and
independent of it. It also keeps a new session from receiving expansions
of an earlier session's compressions in the same cwd, because those
markers are not in the new session's history.

## 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/ccr/context_tracker.py`: `analyze_query` takes an optional
keyword `present_hashes`. When given, contexts whose hash is not in it
are skipped before scoring, so a foreign match cannot take one of the
`max_proactive_expansions` slots. `None` (the default) keeps today's
workspace-only behaviour for other callers.
- `headroom/proxy/handlers/anthropic.py`: keeps the ownership-verified
marker list from the CCR scan (`ccr_present_hashes`, initialised next to
`ccr_workspace_key` so it is always bound) and passes it to
`analyze_query`.
- `tests/test_ccr_expansion_conversation_scope.py` (new): drives the
real `/v1/messages` handler in token mode. A lead compression is tracked
for a cwd, then (1) a teammate request from the same cwd without the
marker must be forwarded unchanged, and (2) a request that holds the
marker must still get the expansion, including a line that only exists
in the original.
- `tests/test_ccr_context_tracker.py`: `TestConversationScoping` covers
absent hash skipped, present hash expanded, a stronger foreign match not
taking the only slot, and `None` keeping the old behaviour.

## Testing

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

### Test Output

```text
# New tests on unmodified main
FAILED tests/test_ccr_expansion_conversation_scope.py::test_teammate_does_not_receive_lead_tool_output
PASSED tests/test_ccr_expansion_conversation_scope.py::test_conversation_holding_the_marker_still_expands
FAILED TestConversationScoping (3 tests: analyze_query has no present_hashes yet)
PASSED TestConversationScoping::test_none_keeps_workspace_only_behaviour
4 failed, 2 passed

# With the fix
6 passed in 4.45s

# Related suites, serial
$ pytest tests/test_ccr_context_tracker.py tests/test_ccr_expansion_conversation_scope.py \
    tests/test_anthropic_ccr_workspace_unbound.py tests/test_proxy_anthropic_cache_stability.py \
    tests/test_proxy_handler_helpers.py tests/test_proxy_system_prompt_immutable.py \
    tests/test_cache_breakpoint_diagnostics.py tests/test_testing_harness.py \
    tests/test_cli_proxy_env.py tests/test_proxy_ccr.py -q
278 passed, 8 skipped, 2 warnings in 42.08s

$ uvx ruff@0.16.8 check . && uvx ruff@0.16.8 format --check .
All checks passed!
1706 files already formatted

$ uvx mypy@1.20.2 headroom --ignore-missing-imports --no-site-packages
headroom\fileperms.py:71: error: Module has no attribute "fchmod"  [attr-defined]
Found 1 error in 1 file (checked 554 source files)
# Windows-only: os.fchmod does not exist on Windows. The file is not touched
# by this PR; CI runs mypy on Linux.
```

The same suites run in parallel (`-n 6`) once reported
`test_ccr_tool_stays_in_forwarded_tools_across_frozen_transition` as
failed. It passes on its own both with and without this change, and
passes in the serial run above, so it looks order-dependent and
unrelated.

## Real Behavior Proof

- Environment: Windows 11, Python 3.12, this branch vs `upstream/main`
at d5318ac2. Real proxy app (`create_app`) with `mode="token"`,
`savings_profile="coding"`, the real compression pipeline and a warm
Kompress ONNX model; only the upstream HTTP call is stubbed. Both
requests send the same `x-headroom-cwd`, as `headroom wrap claude` does
for a lead and its teammates.
- Exact command / steps: (1) "Lead" request: a `Bash` tool result of
about 27 KB of prose about the auth middleware, which the proxy
compresses with Kompress and tracks. (2) "Teammate" request: a different
system prompt and a single user message, `<teammate-message
teammate_id="team-lead">Review the auth middleware session token
handling and report back.</teammate-message>`. Inspect what the proxy
forwards for the teammate.
- Observed result: on `main` the teammate's message is forwarded as
27,722 characters instead of 127. After the teammate's text comes
`<headroom_proactive_expansion>[Proactive Context Expansion - relevant
to your query | workspace: …] --- Expanded from earlier (0 items
compressed in turn 1, high relevance to current query) ---` and then the
lead's full original tool output. On this branch the same teammate
message is forwarded unchanged (127 → 127). The lead's own compression
and tracking are unchanged (`tracked contexts: 1` in both runs).
- Not tested: a live Claude Code agent-team run against the real
Anthropic API. The OpenAI handler, which has no proactive expansion
path. Cache mode, where the append is already skipped, so this change
has no effect there.

## Runtime Rollout Safety

- Rollout-managed feature(s): None. CCR proactive expansion is not gated
in `headroom/rollout.py`.
- Minimum rollout channel: Not applicable.
- Stable/default behavior changed: Yes, in token mode only: proactive
expansion now fires only for compressions whose marker is in the
request. Cache mode (the default) already skips the append and is
unaffected.
- Kill switch / disable path: Unchanged. `--no-ccr-proactive-expansion`
or `HEADROOM_NO_CCR_PROACTIVE_EXPANSION=1` turns the feature off.
- Unsafe override required: No.
- Qualification impact: None.
- Rollback path: Revert this PR. All state is in-process; no persisted
format changes.

## 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
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Additional Notes

- No documentation change: proactive expansion's user-facing description
("expand what was compressed earlier when it becomes relevant") is
unchanged; this narrows it to the conversation's own content, which is
what the docs already imply.
- Trade-off: if the client itself drops the message that held a marker
(for example Claude Code's `/compact`), that compression is no longer
proactively expanded in that conversation. That is the behaviour #2186
asked for.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/3924"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
This commit is contained in:
Parideboy
2026-10-04 13:58:00 -07:00
committed by GitHub
co-authored by Claude Opus 5.5 JD Davis
parent 7f608ea932
commit 9b9a883e96
4 changed files with 273 additions and 1 deletions
+11
View File
@@ -23,6 +23,7 @@ from __future__ import annotations
import logging
import re
import time
from collections.abc import Collection
from dataclasses import dataclass
from typing import Any
@@ -232,6 +233,7 @@ class ContextTracker:
current_turn: int | None = None,
*,
workspace_key: str,
present_hashes: Collection[str] | None = None,
) -> list[ExpansionRecommendation]:
"""Analyze a query to find relevant compressed contexts.
@@ -246,6 +248,13 @@ class ContextTracker:
a workspace before invoking; the empty string short-
circuits to an empty result set rather than matching
empty-keyed test contexts to avoid accidental crossover.
present_hashes: CCR hashes whose markers appear in the request
being answered. When given, only those contexts may expand.
One workspace can serve several live conversations at once
(a Claude Code lead and its teammates share a cwd), and a
compression the requesting conversation never received is
another conversation's tool output, not context it lost
(#1174). ``None`` skips this filter.
Returns:
List of expansion recommendations, sorted by relevance.
@@ -278,6 +287,8 @@ class ContextTracker:
# the current request resolved to.
if context.workspace_key != workspace_key:
continue
if present_hashes is not None and hash_key not in present_hashes:
continue
# Check age
age = now - context.timestamp
+6 -1
View File
@@ -2534,6 +2534,7 @@ class AnthropicHandlerMixin:
# ``ccr_inject_system_instructions=False``, or when ``_bypass`` is
# set. The downstream uses already treat falsy as "unresolved".
ccr_workspace_key, ccr_workspace_label = None, None
ccr_present_hashes: list[str] = []
if (
self.config.ccr_inject_tool or self.config.ccr_inject_system_instructions
) and not _bypass:
@@ -2556,7 +2557,7 @@ class AnthropicHandlerMixin:
# Shape-only scanning also matches markers from other context
# tools; drop hashes this proxy never actually stored before
# they can drive tool injection (issue #2836).
injector.verify_ownership()
ccr_present_hashes = injector.verify_ownership()
if inject_system_instructions and injector.has_compressed_content:
optimized_messages = injector.inject_into_system_message(optimized_messages)
@@ -2690,6 +2691,10 @@ class AnthropicHandlerMixin:
user_query,
self._turn_counter,
workspace_key=ccr_workspace_key,
# Only this conversation's own compressions: a
# same-cwd teammate must not receive the lead's
# tool output (#1174).
present_hashes=ccr_present_hashes,
)
if recommendations:
expansions = self.ccr_context_tracker.execute_expansions(recommendations)
+88
View File
@@ -958,3 +958,91 @@ class TestWorkspaceScoping:
# read, not purging on write — workspace A could come back and use
# them again within the age window).
assert len(tracker.get_tracked_hashes()) == 5
# ============================================================================
# Conversation scoping (#1174).
#
# One workspace (cwd) can carry several live conversations at once: a Claude
# Code lead and its agent-team teammates all run in the same directory. The
# workspace gate alone let the lead's compressed tool output keyword-match a
# teammate's incoming message and get appended to it. `present_hashes` limits
# expansion to compressions whose markers the requesting conversation holds.
# ============================================================================
class TestConversationScoping:
"""Same-workspace conversations must not receive each other's content."""
_QUERY = "please review the auth middleware session code"
@pytest.fixture(autouse=True)
def reset_trackers(self):
reset_context_tracker()
reset_compression_store()
yield
reset_context_tracker()
reset_compression_store()
@staticmethod
def _track(tracker: ContextTracker, hash_key: str, sample: str) -> None:
tracker.track_compression(
hash_key=hash_key,
turn_number=1,
tool_name="Bash",
original_count=100,
compressed_count=10,
workspace_key="ws-team",
query_context="list the auth code",
sample_content=sample,
)
def test_hash_absent_from_request_is_not_expanded(self):
tracker = ContextTracker(ContextTrackerConfig(relevance_threshold=0.1))
self._track(tracker, "lead_hash", "auth middleware login session token")
recommendations = tracker.analyze_query(
query=self._QUERY, current_turn=2, workspace_key="ws-team", present_hashes=[]
)
assert recommendations == []
def test_hash_present_in_request_still_expands(self):
tracker = ContextTracker(ContextTrackerConfig(relevance_threshold=0.1))
self._track(tracker, "own_hash", "auth middleware login session token")
recommendations = tracker.analyze_query(
query=self._QUERY,
current_turn=2,
workspace_key="ws-team",
present_hashes=["own_hash"],
)
assert [r.hash_key for r in recommendations] == ["own_hash"]
def test_foreign_hash_does_not_take_an_expansion_slot(self):
config = ContextTrackerConfig(relevance_threshold=0.1, max_proactive_expansions=1)
tracker = ContextTracker(config)
# The foreign context is the stronger match; with a single slot it
# would win if it were scored at all.
self._track(tracker, "lead_hash", "auth middleware login session token review code")
self._track(tracker, "own_hash", "auth notes")
recommendations = tracker.analyze_query(
query=self._QUERY,
current_turn=2,
workspace_key="ws-team",
present_hashes=["own_hash"],
)
assert [r.hash_key for r in recommendations] == ["own_hash"]
def test_none_keeps_workspace_only_behaviour(self):
tracker = ContextTracker(ContextTrackerConfig(relevance_threshold=0.1))
self._track(tracker, "any_hash", "auth middleware login session token")
recommendations = tracker.analyze_query(
query=self._QUERY, current_turn=2, workspace_key="ws-team"
)
assert [r.hash_key for r in recommendations] == ["any_hash"]
@@ -0,0 +1,168 @@
"""Regression for #1174: proactive expansion must stay inside one conversation.
A Claude Code lead and its agent-team teammates run in the same directory, so
they resolve the same CCR workspace and share the proxy's process-global
``ContextTracker``. When a teammate's incoming message shared a few keywords
with tool output the lead had compressed, the proxy appended the lead's full
original output to the teammate's message. The teammate had never run that
tool and reported the block as garbage context.
These tests drive the real ``/v1/messages`` handler in token mode (where the
append is live) and inspect the body forwarded upstream.
"""
from __future__ import annotations
from types import SimpleNamespace
import httpx
import pytest
pytest.importorskip("fastapi")
from fastapi.testclient import TestClient
from headroom.cache.compression_store import get_compression_store, reset_compression_store
from headroom.proxy.server import ProxyConfig, create_app
_EXPANSION_TAG = "<headroom_proactive_expansion>"
_LEAD_OUTPUT = "\n".join(
f"src/auth/middleware_{i}.py session token login handler" for i in range(40)
)
_LEAD_COMPRESSED = "\n".join(_LEAD_OUTPUT.splitlines()[:4])
_LEAD_QUERY = "list the auth middleware files"
_TEAMMATE_QUERY = (
'<teammate-message teammate_id="team-lead">Review the auth middleware '
"session handling and report back.</teammate-message>"
)
@pytest.fixture(autouse=True)
def _fresh_store():
reset_compression_store()
yield
reset_compression_store()
def _client() -> TestClient:
config = ProxyConfig(
optimize=False,
mode="token",
cache_enabled=False,
rate_limit_enabled=False,
cost_tracking_enabled=False,
log_requests=False,
ccr_handle_responses=False,
ccr_context_tracking=True,
ccr_proactive_expansion=True,
image_optimize=False,
)
return TestClient(create_app(config))
def _track_lead_compression(proxy, cwd: str) -> str: # noqa: ANN001
"""Record a compression the way the handler does after the lead's turn."""
hash_key = get_compression_store().store(
_LEAD_OUTPUT,
_LEAD_COMPRESSED,
original_item_count=40,
compressed_item_count=4,
tool_name="Bash",
query_context=_LEAD_QUERY,
)
workspace_key, _ = proxy._resolve_ccr_workspace(
SimpleNamespace(headers={"x-headroom-cwd": cwd}), {}
)
assert workspace_key
proxy.ccr_context_tracker.track_compression(
hash_key=hash_key,
turn_number=1,
tool_name="Bash",
original_count=40,
compressed_count=4,
workspace_key=workspace_key,
query_context=_LEAD_QUERY,
sample_content=_LEAD_COMPRESSED,
)
return hash_key
def _forwarded_last_user_text(client: TestClient, cwd: str, messages: list[dict]) -> str:
proxy = client.app.state.proxy
captured: dict = {}
async def _fake_retry(method, url, headers, body, stream=False, **kwargs): # noqa: ANN001
captured["body"] = body
return httpx.Response(
200,
json={
"id": "msg_scope",
"type": "message",
"role": "assistant",
"content": [{"type": "text", "text": "ok"}],
"usage": {"input_tokens": 1, "output_tokens": 1},
},
)
proxy._retry_request = _fake_retry
response = client.post(
"/v1/messages",
headers={
"x-api-key": "test-key",
"anthropic-version": "2023-06-01",
"x-headroom-cwd": cwd,
},
json={"model": "claude-sonnet-4-6", "max_tokens": 16, "messages": messages},
)
assert response.status_code == 200, response.text
content = captured["body"]["messages"][-1]["content"]
return content if isinstance(content, str) else content[0]["text"]
def test_teammate_does_not_receive_lead_tool_output(tmp_path) -> None: # noqa: ANN001
cwd = str(tmp_path)
with _client() as client:
_track_lead_compression(client.app.state.proxy, cwd)
forwarded = _forwarded_last_user_text(
client, cwd, [{"role": "user", "content": _TEAMMATE_QUERY}]
)
assert _EXPANSION_TAG not in forwarded
assert forwarded == _TEAMMATE_QUERY
def test_conversation_holding_the_marker_still_expands(tmp_path) -> None: # noqa: ANN001
cwd = str(tmp_path)
with _client() as client:
hash_key = _track_lead_compression(client.app.state.proxy, cwd)
forwarded = _forwarded_last_user_text(
client,
cwd,
[
{"role": "user", "content": _LEAD_QUERY},
{
"role": "assistant",
"content": [
{"type": "tool_use", "id": "t1", "name": "Bash", "input": {"command": "ls"}}
],
},
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "t1",
"content": f"[40 items compressed to 4. Retrieve more: hash={hash_key}]",
}
],
},
{"role": "assistant", "content": "Listed them."},
{"role": "user", "content": _TEAMMATE_QUERY},
],
)
assert _EXPANSION_TAG in forwarded
# Line 39 is only in the original, never in the compressed preview.
assert "src/auth/middleware_39.py" in forwarded