# Cache-Control Passthrough — Design

> How a caller-placed `cache_control` mark on a content block reaches the
> Anthropic Messages API request body unchanged, so the prompt cache breakpoint
> lands where the caller wants it rather than where the provider guesses.

## 1. The problem

A caller such as the screenspot locator in GUI-Agent-Harness knows which part of
its prompt is stable: a long fixed rule block, followed by dynamic text and a
screenshot. It wants the cache breakpoint right after that stable prefix.

Without passthrough, a `cache_control` key written into a content dict is
dropped inside OpenProgram, and the only breakpoint that survives is the one the
provider adds automatically on the last block. The last block is the image or
the dynamic text, which differs on every request, so the cache never hits.

Scope: **anthropic**-class providers only — the native Anthropic API, the Claude
Code subscription through a proxy, and any anthropic-messages interface. The
OpenAI and codex classes use automatic prefix caching and never read
`cache_control`; the field is inert for them.

## 2. The passthrough path

`cache_control` is an optional field carried unchanged across three layers.

**Content types** (`openprogram/providers/types.py`). `TextContent` and
`ImageContent` each carry `cache_control: dict | None = None`. Video and audio
do not — nothing marks them today. The value is an opaque dict such as
`{"type": "ephemeral"}`, possibly with a `ttl`. OpenProgram never parses or
validates its contents; whatever the caller writes is what Anthropic receives.

**Context building** (`openprogram/agentic_programming/runtime.py`,
`_build_pi_context`). When the caller's `content: list[dict]` is converted into
`TextContent` / `ImageContent` objects, each block's `cache_control` is copied
onto the object. The `role == "system"` text block is an exception: it is
extracted into `system_text` and does not carry a per-block breakpoint, because
system breakpoints are placed separately by the Anthropic provider's
`_build_system`.

**Wire building** (`openprogram/providers/anthropic/anthropic.py`,
`_build_messages`). When API blocks are reconstructed from the content objects,
a block whose object carries `cache_control` gets the field written into the
generated dict. This applies to the list-content branch of `UserMessage`; the
string-content branch, `AssistantMessage`, and `ToolResultMessage` have no
per-block caller marks and are unaffected.

A call that passes no `cache_control` produces a request body identical to one
built before the field existed. Every existing caller is unaffected.

## 3. Automatic breakpoint versus caller breakpoint

The provider still places a breakpoint on the last block of a message on its
own. The rule that reconciles the two:

> If any block in a message carries a caller-placed `cache_control`, the
> provider does not auto-place a breakpoint on that message's last block at all.

The check is `caller_marked = any("cache_control" in b for b in
content_blocks)`. This is stronger than merely declining to overwrite the last
block. When the caller marks a stable prefix early in the message, an automatic
breakpoint on the dynamic tail block would waste one of the four available slots
and pin the cache boundary past the very content that changes every request.
Suppressing it entirely keeps the caller's intent as the only breakpoint in that
message.

## 4. Boundaries the caller must respect

**Minimum cacheable prefix.** A breakpoint only caches when the content before
it is at least 1024 tokens (2048 for Haiku). Below that, Anthropic **silently
ignores it** — no error, no hit. A caller that marks a short prefix sees
`cache_read` stay at 0 and will look for a bug in the passthrough that is not
there.

**Four breakpoints per request.** OpenProgram already adds roughly two on its
own (the system block and the last block). Exceeding four makes Anthropic return
400. A caller has roughly two slots to work with.

**Proxy fidelity.** When the Claude Code subscription goes through the Meridian
proxy, a proxy that strips `cache_control` from the body keeps `cache_read` at 0
regardless of what OpenProgram sends. This is a proxy-layer property and has to
be verified separately; sending the same fixed prefix twice and checking that
the second response reports `cache_read > 0` tests OpenProgram and the proxy
together.

**Other providers.** OpenAI and codex block construction reads fields
individually (`.text` / `.data` in `openai_completions` and
`_shared/transform_messages`), and the two `model_dump()` calls in the responses
and codex paths dump the options object rather than a content block, so the new
optional field never leaks into their request bodies. `TextContent.model_dump()`
round-trips cleanly, so persistence is unaffected.

## 5. Caller-side work, not OpenProgram's

Splitting a prompt so its fixed rules form the first text block and marking that
block is a caller change — for screenspot, in
`GUI-Agent-Harness/screenspot_locator.py`. Prefix-caching optimization for the
OpenAI and codex classes needs only that the caller put its stable prefix first,
with no OpenProgram change at all.

## Appendix: Implementation Status

Implemented across `providers/types.py`, `runtime._build_pi_context`, and
`anthropic._build_messages`, with the auto-breakpoint suppression rule of §3.
Covered by `tests/unit/test_cache_control_passthrough.py` (six cases):
full-chain passthrough from runtime to the Anthropic body, image passthrough,
byte-identical body when the field is absent, the automatic breakpoint still
working when there is no caller mark, no overwrite when the caller marks the
last block, and auto-breakpoint suppression when the caller marks an earlier
block. The non-Anthropic no-leak property in §4 was verified by reading the
OpenAI and codex block construction paths. Proxy passthrough is the one boundary
still unverified in practice.