claude-api eval/hillclimb guides: the `model × usage` cost recipe ignores the cache TTL and model-specific cache-read rates; prefer an agent-reported cost when a row has one

Version: measured on Claude Code 2.1.288; the guide text is unchanged in 2.1.289. Bundled claude-api skill: build-eval.md (the "dollars per full run" step and its estimate template), which the hillclimb guide's $/run / spend columns rely on; eval-hillclimb.md (Step 2's budget note, the Step 4 status table); cost-hillclimb.md (the billing-basis bullet).

What the guides do. When the full viewer isn't available, the loop computes each row's cost_usd from model × usage. build-eval.md prices every cache write at 1.25× input and every cache read at 0.1× input, and the hillclimb guide's budget note uses the same flat read rate. The $/run and spend columns come from that figure, and with the lite report it's the only cost number the user sees.

Why it's off. Per the public pricing page (https://platform.claude.com/docs/en/about-claude/pricing#prompt-caching):

• 1-hour cache writes bill at 2× input; only 5-minute writes are 1.25×.
• Cache reads are 0.1× on most models, but 0.05× on Opus 5.5 and 0.025× on Fable 5.1 / Mythos 5.1.

What I measured. The system under test was a Claude Code agent on a claude.ai subscription login. Its usage.cache_creation reports writes as ephemeral_1h_input_tokens.

• 11 hillclimb rows (one skill, Sonnet 5, no sub-agents): the recipe came out a median 17.9% below the agent's own total_cost_usd (range −16% to −29%). Pricing the writes at 2× matched all 11.
• Over a wider set of my agent runs (about 1,100, mostly subscription logins), about 95% wrote 1-hour cache. Across their per-model usage entries the recipe ran a median 17% low. A 2× write rate fixes the median but matches exactly on only about a third of entries (p10 −33%, p90 +19%), and some entries differ even with no cache writes. So no fixed multiplier reproduces the agent's figure.
• Runs on an API key with no subscription login wrote 5-minute cache (41 of 43). There, 1.25× is right. The undercount seems to follow the login type, not the Claude Code version.

Net effect on subscription-login runs: $/run, spend and any budget check read roughly 18% below the agent's own estimate.

Inferred from the pricing page, not measured: on Opus 5.5 and Fable 5.1 / Mythos 5.1 the flat 0.1× read rate overstates the cache-read part of the cost (2× and 4× respectively). Whether a whole row then comes out high or low depends on its read/write mix. I haven't analysed those models separately.

Quick check: on a claude.ai subscription login, run claude -p --output-format json "<any prompt>" and compare total_cost_usd with the guide's recipe applied to the result's usage. With non-zero ephemeral_1h_input_tokens, writes at 1.25× come out below total_cost_usd; at 2× they should match.

Suggested change.

1. When a row already carries an agent-reported cost (e.g. cost_usd taken from the agent's total_cost_usd), use it as-is. It already reflects the cache TTL actually used: all 11 rows above matched once writes were priced at 2×. It's also the natural place for price dimensions the recipe doesn't price, such as web-search fees or the inference_geo: "us" multiplier. I haven't verified that the agent's figure includes those.
2. Keep model × usage as the fallback, but price usage.cache_creation.ephemeral_1h_input_tokens at 2× input and use the per-model cache-read rate.
3. In cost-hillclimb.md, where it asks to state each cell's billing basis, note that on a subscription login the agent's reported cost is a list-price estimate, not a charge.