Files
headroom/tests/test_prefix_tracker_client_rewrote_reply.py
aeb09f8d18 fix(cache): keep cache mode when Claude Code re-serializes its last reply (#4003)
## Description

This PR fixes two problems that cost Headroom users money on Claude
Code. A live benchmark (`benchmarks/tool_search_vs_native/`) found both.

**1. Cache mode broke when Claude Code re-serialized its last reply.**

Headroom records the model's raw reply as the last message of the
previous turn. Claude Code sends that reply back edited:

- it strips a leading `cd <cwd> &&` from Bash commands;
- it drops `caller`.

The history then read as `relation=diverged`
(`cache_mode_prefix_mismatch`). Cache mode forwarded the raw originals
over every earlier compressed message, and the whole conversation was
written to cache again: 66.8K tokens on every long-task run.

The fix: when only the recorded reply differs, and it is the same turn,
Headroom replays the forwarded prefix and takes the client's version of
the reply. That reply was never part of a cached prefix. "Same turn"
means the same block kinds and the same `tool_use` ids.

**2. Small MCP results were compressed.**

The Jira ticket (a few hundred tokens) lost its description. The model
called `headroom_retrieve` and then re-fetched the ticket, which cost
two extra turns and about +15% on the long task. MCP results under
`HEADROOM_MCP_RESULT_MIN_CHARS` (default 4000) are now forwarded
verbatim. This covers both Anthropic `tool_result` blocks and OpenAI
`role: "tool"` messages.

No linked issue.

## 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
- [x] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- **`headroom/cache/prefix_tracker.py`:** adds
`_client_rewrote_reply_delta`, tried on `RELATION_DIVERGED` after
`_replaced_system_tail_delta`. A change earlier in the history still
diverges.
- **`headroom/transforms/content_router.py`:** adds
`_is_small_mcp_result`, applied in `_process_content_blocks` (Anthropic)
and on the `role: "tool"` branch (OpenAI). It recognises the `mcp__`,
`mcp_` and `mcp--` name prefixes. `HEADROOM_MCP_RESULT_MIN_CHARS=0`
restores the old behaviour.
- **`headroom/proxy/handlers/anthropic.py`:** adds an opt-in
`HEADROOM_DEBUG_PREFIX_MISMATCH=<dir>`. It logs the first diverging
message and dumps both histories, with the directory created `0700` and
the file `0600`, because the dump holds the full conversation.
- **`tests/test_cache_mode_delta_marker.py`:**
`test_tool_use_different_input_still_falls_back` becomes
`..._forwards_the_clients_version`, because the client's copy of the
last reply is what gets forwarded and never the recorded one. A new test
keeps the divergence for an edit earlier in the history.
- **New tests:**
  - `tests/test_prefix_tracker_client_rewrote_reply.py`;
- `tests/test_content_router_mcp_small_result.py`, which covers both
wire formats and three MCP prefixes.
- **`benchmarks/tool_search_vs_native/`:** a live A/B harness. It runs
isolated `claude -p` sessions against six fake MCP servers and a fixture
repo, and reads billed usage from Claude Code's transcripts. A run
passes only if Claude Code exits 0, the tests pass, and the four MCP
actions happened (`get_issue` counts as reading the ticket; a search
does not).

## 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
$ pytest -q tests/test_prefix_tracker_client_rewrote_reply.py tests/test_content_router_mcp_small_result.py tests/test_cache_mode_delta_marker.py
============================== 20 passed in 3.42s ==============================

$ pytest -q tests -k "content_router or router or prefix or cache_mode or delta"
========= 1 failed, 983 passed, 15147 deselected in 222.61s (0:03:42) ==========
# the 1 failure is test_content_router_single_item_deadline.py::test_single_cache_miss_fails_open_at_deadline,
# a wall-clock assertion (0.126s vs < 0.12s). It fails identically on origin/main on this machine.

$ ruff check .            (ruff 0.16.8, CI's pinned version)
All checks passed!
$ ruff format --check .
1757 files already formatted
$ mypy headroom/proxy/handlers/anthropic.py headroom/transforms/content_router.py headroom/cache/prefix_tracker.py --ignore-missing-imports
Success: no issues found
```

## Real Behavior Proof

- Environment: macOS 26.6 (arm64), Python 3.12.13 (the repo's `.venv`),
Claude Code 2.1.290, `claude-sonnet-5-5`, real Anthropic API calls, with
the proxy started from this branch.
- Exact command / steps: `python3
benchmarks/tool_search_vs_native/run.py --arms native,hr_hot,hr_client
--reps 3 --warmup`, then the same with `--context-kb 200` for the long
task.
- Observed result: median of 3 runs after a warmup; every run passed
(table below). Before the fix, `HEADROOM_DEBUG_PREFIX_MISMATCH` showed
`relation=diverged first_diff_index=8`: the Bash `tool_use` with `cd …
&&` stripped and `caller` dropped.
- Not tested: harnesses other than Claude Code (the OpenAI-format MCP
path is unit-tested only), Bedrock and Vertex upstreams, real (larger)
MCP server catalogs, models other than Sonnet 5.5.

| | native Claude Code | Headroom + CC ToolSearch | Headroom, routine
tools resident |
|---|---|---|---|
| long task, before | $0.283 | $0.323 | $0.426 (66.8K-token cache
re-write every run) |
| long task, after | $0.284 | **$0.284** | **$0.255** (6 API calls vs
native's 7) |
| short task, after | $0.061 | $0.062 | **$0.046** |

## Runtime Rollout Safety

- Rollout-managed feature(s): none; both changes are in the always-on
cache-mode and compression paths.
- Minimum rollout channel: stable.
- Stable/default behavior changed: yes. A re-serialized last reply no
longer drops cache mode to raw forwarding, and MCP results under 4000
characters are no longer compressed, giving up a few tokens of savings
on those results.
- Kill switch / disable path: `HEADROOM_MCP_RESULT_MIN_CHARS=0` for the
MCP floor. The prefix fix has no flag, because it only applies where the
old code forwarded raw.
- Unsafe override required: no.
- Qualification impact: less compression on small MCP results; fewer
cache writes and extra turns.
- Rollback path: revert this PR.

## 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
- [x] 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)

## Screenshots (if applicable)

N/A

## Additional Notes

- **Devin review follow-ups are in `d043bd5e`:**
  - the OpenAI-format MCP floor;
  - owner-only debug dumps;
  - exit-code and `get_issue` scoring;
  - the environment and commands in the README.
- **The two `npm audit` failures** (docs, e2e/wrap/tools) also fail on
`main`.
- **`tests/test_cli_proxy_improvements.py` hangs** when the whole file
runs locally, also on `main`. That is pre-existing and not touched here.

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-10-07 10:58:23 -05:00

149 lines
5.0 KiB
Python

"""Cache mode must survive a client re-serializing the model's last reply.
Claude Code sends the model's Bash call back with the leading ``cd <cwd> &&``
stripped and without ``caller``. Before the fix the whole history counted as
diverged, cache mode fell back to raw forwarding, and every earlier compressed
message was replaced by its original: a full cache re-write (observed 66.8K
tokens per occurrence in benchmarks/tool_search_vs_native).
"""
import os
import stat
import pytest
from headroom.cache.prefix_tracker import extract_cache_stable_delta
USER = {"role": "user", "content": "fix the bug"}
RESULT_ORIGINAL = {
"role": "user",
"content": [{"type": "tool_result", "tool_use_id": "t1", "content": "x" * 5000}],
}
RESULT_COMPRESSED = {
"role": "user",
"content": [{"type": "tool_result", "tool_use_id": "t1", "content": "x…"}],
}
CALL = {
"role": "assistant",
"content": [{"type": "tool_use", "id": "t1", "name": "Read", "input": {"file_path": "a"}}],
}
RAW_REPLY = {
"role": "assistant",
"content": [
{"type": "text", "text": "Listing files."},
{
"type": "tool_use",
"id": "t2",
"name": "Bash",
"input": {"command": "cd /work && git ls-files"},
"caller": {"type": "direct"},
},
],
}
CLIENT_REPLY = {
"role": "assistant",
"content": [
{"type": "text", "text": "Listing files."},
{"type": "tool_use", "id": "t2", "name": "Bash", "input": {"command": "git ls-files"}},
],
}
NEXT = {
"role": "user",
"content": [{"type": "tool_result", "tool_use_id": "t2", "content": "a.py"}],
}
def test_rewritten_reply_keeps_compressed_prefix():
previous_original = [USER, CALL, RESULT_ORIGINAL, RAW_REPLY]
previous_forwarded = [USER, CALL, RESULT_COMPRESSED, RAW_REPLY]
current = [USER, CALL, RESULT_ORIGINAL, CLIENT_REPLY, NEXT]
delta = extract_cache_stable_delta(current, previous_original, previous_forwarded)
assert delta is not None
prefix, appended = delta
assert prefix[2] == RESULT_COMPRESSED # earlier compression replayed, cache intact
assert prefix[3] == CLIENT_REPLY # the client's own version of the reply
assert appended == [NEXT]
def test_different_turn_is_still_a_divergence():
other = {
"role": "assistant",
"content": [
{"type": "text", "text": "Listing files."},
{"type": "tool_use", "id": "t9", "name": "Bash", "input": {"command": "ls"}},
],
}
previous_original = [USER, CALL, RESULT_ORIGINAL, RAW_REPLY]
previous_forwarded = [USER, CALL, RESULT_COMPRESSED, RAW_REPLY]
assert (
extract_cache_stable_delta(
[USER, CALL, RESULT_ORIGINAL, other, NEXT], previous_original, previous_forwarded
)
is None
)
def test_earlier_history_edit_is_still_a_divergence():
edited_user = {"role": "user", "content": "something else"}
previous_original = [USER, CALL, RESULT_ORIGINAL, RAW_REPLY]
previous_forwarded = [USER, CALL, RESULT_COMPRESSED, RAW_REPLY]
assert (
extract_cache_stable_delta(
[edited_user, CALL, RESULT_ORIGINAL, CLIENT_REPLY, NEXT],
previous_original,
previous_forwarded,
)
is None
)
@pytest.mark.skipif(not hasattr(os, "fchmod"), reason="POSIX file modes only")
def test_debug_dump_is_owner_only_even_if_it_exists(tmp_path, monkeypatch):
from headroom.proxy.handlers.anthropic import _dump_prefix_mismatch
monkeypatch.setenv("HEADROOM_DEBUG_PREFIX_MISMATCH", str(tmp_path))
# A dump left world-readable by an earlier run: created under the common
# 022 umask, so it gets the default 0644 without any explicit chmod.
existing = tmp_path / "req1.json"
previous_umask = os.umask(0o022)
try:
existing.write_text("{}")
finally:
os.umask(previous_umask)
assert stat.S_IMODE(existing.stat().st_mode) == 0o644
_dump_prefix_mismatch("req1", [USER, CLIENT_REPLY], [USER, RAW_REPLY])
_dump_prefix_mismatch("req2", [USER, CLIENT_REPLY], [USER, RAW_REPLY])
for name in ("req1.json", "req2.json"):
assert stat.S_IMODE((tmp_path / name).stat().st_mode) == 0o600, name
def test_debug_dump_closes_its_descriptor_when_chmod_fails(tmp_path, monkeypatch):
# A long-running proxy must not leak a descriptor per failed debug dump.
from headroom.proxy.handlers import anthropic as handler
monkeypatch.setenv("HEADROOM_DEBUG_PREFIX_MISMATCH", str(tmp_path))
opened = []
real_fdopen = os.fdopen
def tracking_fdopen(fd, *args, **kwargs):
fh = real_fdopen(fd, *args, **kwargs)
opened.append(fh)
return fh
def failing_fchmod(fd, mode):
raise PermissionError("not permitted")
monkeypatch.setattr(handler.os, "fdopen", tracking_fdopen)
monkeypatch.setattr(handler.os, "fchmod", failing_fchmod, raising=False)
handler._dump_prefix_mismatch("req1", [USER, CLIENT_REPLY], [USER, RAW_REPLY])
assert len(opened) == 1
assert opened[0].closed