Recipe idea: ROI harness + production gotchas for misc/prompt_caching.ipynb

# Recipe idea: ROI harness + production gotchas for `misc/prompt_caching.ipynb`

## Proposal

I'd like to add a **"Production ROI" section + a small reusable measurement harness** to the existing [`misc/prompt_caching.ipynb`](https://github.com/anthropics/claude-cookbooks/blob/main/misc/prompt_caching.ipynb), as a single notebook diff (not a new file).

The existing recipe teaches *how* to enable caching. This adds *what to instrument* once it's enabled — a gap I hit shipping a multi-step Q&A workload (3 Sonnet 4.6 calls per user request, 8-12KB shared system context). Numbers in the diff would come from a 24-hour instrumented run against that workload, which lives at `autoapply-ai-api.fly.dev`.

## What the diff adds (~150 lines, 3-4 cells)

1. **`CacheCostHarness` class** (~60 lines). Wraps `Anthropic().messages.create()`, reads `usage.cache_creation_input_tokens` and `usage.cache_read_input_tokens` per call, logs `$ saved` per call against current Sonnet pricing. Drop-in for any workload. Optional wall-clock latency annotation when the caller wraps the request with a timestamp.

2. **One worked before/after table** on a 3-call fan-out (cold, warm, warm). Cache hit rate per call position; $/request before vs after; Sonnet 4.6 pricing snapshot.

3. **Three production gotchas** (max 150 words each, frozen at three):
- **Templated system prompts invalidate the cache prefix.** Place the `cache_control: {"type": "ephemeral"}` breakpoint at the end of the static template (instructions + few-shot examples), and append per-user state as a separate, uncached block after the breakpoint. Shows the before/after block structure and the resulting `cache_read_input_tokens` delta.
- **Cold-cache penalty during rolling deploys.** TTL is ~5 min, so the penalty only hits users who arrive in the first few minutes after a deploy.
- **The 4-breakpoint-per-request budget** when a pipeline has system + tools + multi-turn user content. How to prioritize.

4. **Constants the cookbook should make explicit** (currently scattered across docs): 1024-token minimum for Sonnet caching, ~5-min TTL, max 4 `cache_control` breakpoints per request, GA on Sonnet 3.5+ / 4.x with no beta header required.

## Why this is complementary, not redundant

| Existing recipe | Proposed addition |
|---|---|
| Feature explainer: how to enable `cache_control` | Production diff: cache hit rate, $/req, 3 frozen gotchas |
| Single-call examples | 3-call fan-out sharing an 8-12KB system prefix |
| Synthetic prompts | Real workload measured over 24h |
| No measurement scaffolding | `CacheCostHarness` drop-in |

## Format

- Diff against `misc/prompt_caching.ipynb`, no new file.
- CONTRIBUTING.md compliant (uv, ruff, `/notebook-review`, `/model-check`, model alias, MIT) — outputs kept per repo convention.

## Two questions before I build

1. Diff against the existing notebook (closer to recent work on this file in #387), or a new sibling notebook? Happy to follow your preference.
2. Real production numbers (1-day instrumented window) vs fully reproducible synthetic example vs both? I can publish a public gist of harness output before the PR if that helps.

Happy to scope down to **harness-only** (skip the case study + gotchas) if you'd prefer a leaner diff. I'll close this if it's not the right scope.

---

For context, prior Claude-ecosystem work I maintain: [tailor-resume](https://pypi.org/project/tailor-resume/) (PyPI) and [repo-context-hooks](https://github.com/narendranathe/repo-context-hooks) (Sigstore-signed Claude Code skills toolkit).