cache-guardlisted

# Cache Guard — stop paying 700× overhead on context rewrites ## The one mechanism to understand Prompt cache is a **prefix match with three tiers: tools → system → messages**. Reads from cache cost **0.1×** the base input price; writes cost **1.25×** — a **12.5× spread**. A long conversation is *cheap* as long as every call re-reads the cached prefix. **Any image anywhere in the request invalidates the entire messages tier.** The next call rewrites the whole conversation history at the 1.25× write price. The rewrite cost equals the *current context size* — in an 800k-token session, one glance at a screenshot costs ~800k cache-write tokens, even though the image itself is ~1–2k tokens. Measured in production: 91% of a session's cost was image-triggered rewrites; the images themselves were 0.13% of the tokens. Other full-rewrite triggers: cache TTL expiry (>5 min idle, next wake rewrites everything), model switch, tool-set / MCP change mid-session, editing earlier history. Details and pricing math: `references/mechanism.md`. ## Rules ### R1 — Batch image reads into one message Reading 1 image and reading 10 images cost the SAME rewrite. Never look at screenshots one-by-one across turns. Accumulate paths, then read them all with parallel Read calls in a single message, and draw every conclusion in that turn. ### R2 — Look once, write it down, never re-read Immediately after viewing images, append findings to a notes file (e.g. `qa-notes.md`): filename → verdict → require