Files
18067b1d19 fix(content-router): protect cache_control markers nested in tool_result content (#4898)
## Description

`ContentRouter` never rewrites a block that carries `cache_control`
(contract 1 in `_process_content_blocks`), but the guard only checks
`"cache_control" in block`. The Messages API also accepts the marker on
a `text` sub-block of a `tool_result`'s list content. That shape is not
seen as marked, so the `tool_result` is compressed and re-wrapped as
`[{"type": "text", "text": compressed}]`: the marker is dropped and the
bytes under it change, even for a tool result earlier in the
conversation. The cross-turn dedup `protected` check has the same gap.
`compress()` and `POST /v1/compress` return the router output as-is, so
callers get the rewritten block back.

This PR treats a `tool_result` whose list content carries a marker as
marked, the same shapes `count_cache_breakpoints` in
`headroom/proxy/helpers.py` already counts.

Fixes #4890

## 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/transforms/content_router.py`: new helper
`_carries_cache_control(block)`, true when the block has `cache_control`
or is a `tool_result` whose list content has a sub-block with
`cache_control`.
- Used in the per-block contract 1 guard of `_process_content_blocks`
and in the `protected` check of the cross-turn dedup. The contract 1
docstring now names the nested shape. The fresh-turn release
(`fresh_turn` and a `tool_result` in the final message) is unchanged.
- `tests/test_transforms_content_router.py`: the existing
`test_tool_result_cache_control_protected` is parametrized over
`block_marker` / `nested_marker`, plus
`test_marked_tool_result_in_history_survives_apply`, which goes through
`apply()` with the marked tool result in history.
- `tests/test_cross_turn_dedup.py`:
`test_dedup_never_rewrites_nested_cache_control_tool_result`, with an
unmarked control that must still be folded.

## 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

Source: one commit `916e8395` on `main` `5023c84e`. Runs below were
built from `git archive` of that commit in a `python:3.13-slim-bookworm`
image with `uv sync --frozen --extra proxy --extra dev`
(`headroom._core` built by maturin). ruff ran on the three touched
files, mypy on `headroom`. The new and changed tests were run 5 times in
a row. The module run covers the two touched test files plus
`test_content_router_detection_dedup.py`,
`test_responses_cross_turn_dedup.py` and
`test_openai_chat_dedup_recoverability.py`. For the reverse check,
`content_router.py` was replaced with the copy from `5023c84e` and the
tests kept.

### Test Output

```text
== RUFF CHECK RC 0
== RUFF FORMAT RC 0
== MYPY RC 0
# new and changed tests, run 1 and run 5 (runs 2-4 identical):
====================== 9 passed, 124 deselected in 0.97s =======================
====================== 9 passed, 124 deselected in 0.37s =======================
# related modules:
======================= 149 passed, 1 skipped in 12.32s ========================
# with content_router.py restored to 5023c84e (fix removed):
PASSED tests/test_transforms_content_router.py::test_tool_result_cache_control_protected[block_marker]
PASSED tests/test_transforms_content_router.py::test_marked_tool_result_in_history_survives_apply[block_marker]
FAILED tests/test_transforms_content_router.py::test_tool_result_cache_control_protected[nested_marker]
FAILED tests/test_transforms_content_router.py::test_marked_tool_result_in_history_survives_apply[nested_marker]
FAILED tests/test_cross_turn_dedup.py::test_dedup_never_rewrites_nested_cache_control_tool_result
================= 3 failed, 6 passed, 124 deselected in 0.58s ==================
```

The `block_marker` cases are the existing behaviour and pass on both;
only the nested-marker tests fail without the fix.

## Real Behavior Proof

- Environment: Linux container, Python 3.13, headroom installed from
this branch with `uv sync --frozen --extra proxy`. No upstream provider
and no API key: `/v1/compress` does not forward.
- Exact command / steps: `python -m headroom.cli proxy --host 127.0.0.1
--port 8833 --no-telemetry --no-rate-limit`, wait for `/readyz`, then
POST `/v1/compress` with `model: claude-sonnet-4-5` and a `tool_result`
holding 17289 characters of log lines with one `cache_control: {"type":
"ephemeral"}`. Four requests: marker on the `tool_result` or on its
`text` sub-block, with the tool result either in the final message or in
history (followed by an assistant and a user turn). Same image, same
steps with `content_router.py` from `main`.
- Observed result: on `main` the nested-marker requests came back as
17289 -> 29 characters with 0 markers out of 1, both in the final
message and in history. With this patch all four requests came back
17289 -> 17289 characters with 1 marker out of 1, the same as the marker
on the `tool_result` itself (which was already 1 -> 1 on `main`).
- Not tested: a real Anthropic endpoint, the `/v1/messages` forwarding
path end to end with this patch, SSE streaming, Bedrock, Windows and
macOS.

## Runtime Rollout Safety

- Rollout-managed feature(s): N/A, this is a bug fix in the existing
compression path with no flag.
- Minimum rollout channel: N/A, no rollout-managed feature.
- Stable/default behavior changed: Yes, only for a `tool_result` whose
list content carries `cache_control` on a sub-block: outside the
fresh-turn release it is now passed through unchanged, as a marker on
the block itself already was.
- Kill switch / disable path: N/A, no flag. Removing the marker on the
client side gives the old compression.
- Unsafe override required: No.
- Qualification impact: None expected. Unmarked tool results and string
content take the same path as before.
- Rollback path: Revert this commit.

## 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

Documentation is N/A, the contract 1 docstring is the only place that
describes this. On `/v1/messages` the proxy already moved the marker
back onto the compressed `tool_result` before forwarding, so the
breakpoint count stayed the same there, but the bytes under it still
changed. That path uses the same router guard, so a marked tool result
in history should now stay uncompressed there too (not run end to end,
see Not tested). `read_maturation.py` intentionally rewrites marked
blocks while keeping their marker, so it is left alone. "New and
existing unit tests pass locally" refers to the modules listed above,
run in the container.

Written with help from Claude Code.

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

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4898"
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>
2026-11-16 23:52:21 -06:00
..