A5 · Cost and Model Strategy

A5 · 20 min

Cost and Model Strategy

Your first serious month of agent work ends and the invoice is four times what you guessed. You cannot say which agent spent it, which model tier did the work, or whether your caching ever hit. So you do what most people do: downgrade everything to the cheapest model, watch quality crater, and conclude agents are expensive. They are not. Unengineered spend is expensive, and spend is an engineering surface like latency or memory: measurable, attributable, and mostly fixable in an afternoon.

Spend engineering: four quadrants, one rule about numbers

Everything you pay for is tokens: input tokens the model reads, output tokens it writes, and two special input classes, cache writes and cache reads. Four levers control what those tokens cost you:

  1. Routing. Which model tier does which task.
  2. Caching. Whether repeated context is billed at full price or a fraction of it.
  3. Context economy. How many tokens are in the window at all, because every one of them is billed input on every subsequent turn.
  4. Monitoring. Whether you can attribute spend to a feature or agent precisely enough to cut it.

Before the levers, the rule this whole appendix hangs on: never build strategy on memorized prices. Model prices, aliases, and cache minimums have all changed during the lifetime of this course's drafts. Sonnet 5 currently has introductory API pricing with a scheduled increase on September 1, 2026, printed right in the pricing table: a number you memorize today is scheduled to be wrong. So every figure in this lesson is an illustration stamped "as of July 2026" with the page it came from. The number is the example. The URL is the lesson. Recheck the URL before any decision with money attached.

What the July 2026 pricing page shows, as illustration: roughly an order of magnitude separates the cheapest tier (Haiku 4.5 at $1 input / $5 output per million tokens) from the most expensive (Fable 5 at $10 / $50). Output costs about five times input at every tier, and that ratio has been the durable shape across generations even as the absolute numbers moved. Two structural consequences follow. Tier choice is a 10x lever, the largest single lever you have. And verbose output is disproportionately expensive, which is one more reason the tight, scoped dispatches this course teaches also happen to be the cheap ones.

Rendering diagram...

Routing: by verification cost, not just difficulty

The common framing is "easy tasks to cheap models, hard tasks to expensive ones." Half right. The position this course takes: route by the cost of verifying the output, not just the cost of producing it. A task whose output is machine-checkable in seconds (does the script run, does the JSON validate, does the test pass) is safe to send to a cheap tier, because a failure costs you one retry. A task whose output you must verify by reading carefully (an architectural plan, a migration strategy, a security-sensitive diff) belongs on a frontier tier, because a plausible-but-wrong answer there burns the most expensive resource in the system: your attention, plus every downstream token built on the bad plan.

Lesson 2.1 already gave you the interactive routing surface: aliases, /model, and opusplan, which runs the expensive model exactly where a wrong decision multiplies (the plan) and the cheaper one where work is mechanical (the edits). That is verification-cost routing built into a single setting. Extend the same logic everywhere agents run: the Claude Code costs doc recommends model: haiku in subagent configuration for simple delegated tasks, and every SDK agent you built in lesson 2.11 takes a per-agent model choice. A fleet where the triage agent, the search agent, and the architect all run the same frontier model is a fleet nobody routed.

Caching: learn the ratios, not the prices

Prompt caching bills repeated prefix content at a fraction of base input price. The July 2026 ratios from the pricing page: a 5-minute-TTL cache write costs 1.25x base input, a 1-hour write costs 2x, and a cache hit costs 0.1x. Ratios are worth internalizing because they have held while absolute prices moved, but confirm them on the pricing page before modeling anything. The arithmetic they imply: a 5-minute write pays for itself on the first hit, and every hit after that reads context at a tenth of what an uncached agent pays to re-read the same tokens.

That matters enormously for agents specifically, because an agent loop re-sends its entire transcript every turn. A 40-turn session over a large stable prefix is 40 reads of mostly identical content; whether those reads bill at 1.0x or 0.1x is often the difference between a viable automation and an absurd one. Claude Code and the Agent SDK cache automatically. Your job is not to configure caching but to stop breaking it: the cache key is an exact prefix over tools, then system prompt, then messages, in that order, so anything that churns early content (rotating tool definitions, timestamps in the system prompt, toggling images) invalidates everything after it. There are also per-model minimum cacheable lengths (512 tokens for Fable 5, 1,024 for Sonnet 5, 4,096 for Haiku 4.5, as of July 2026), below which nothing caches at all.

One more mechanism for one more shape of work: anything that does not need an interactive answer (nightly triage, bulk classification, report generation) can go through the Batch API at a 50% discount on both input and output, with most batches finishing under an hour inside a 24-hour window, per the batch processing doc. If an agent runs on a schedule and nobody is watching it run, it is a batch candidate.

Context economy is cost control wearing a different hat

Lesson 1.3 argued the context window as a quality budget: past roughly half full, clear before starting anything new. Reread that lesson with a billing lens and every recommendation doubles as spend control, because the whole window is billed input on every turn. A bloated CLAUDE.md is a tax on every future call. A 3,000-token tool result you did not need re-bills on every turn until compaction. Context bloat is a cost bug you can fix today, with tools you already have: /clear between tasks, /context to see what is actually consuming the window, subagents to quarantine verbose research in a disposable window (their transcript never re-bills in your main session), and the costs doc's full checklist under "Reduce token usage," including MCP overhead reduction now that tool definitions are deferred by default. Quality discipline and spend discipline are the same discipline. You do not have to choose.

In practice: where the numbers actually live

The monitoring quadrant is a short list of surfaces. Bookmark these; they are the durable part.

  • Prices and tiers: the pricing page (docs.claude.com, under About Claude) and the models overview next to it. Check both when a new model ships, because routing policies rot the same way prices do.
  • Interactive sessions: /usage inside Claude Code. The Session block shows token usage and a dollar estimate computed locally, and on subscription plans it also attributes recent usage to skills, subagents, plugins, and individual MCP servers as percentages, toggling between 24-hour and 7-day views. That attribution view is your fastest answer to "what is eating my plan."
  • Authoritative billing: the Usage and Cost pages in the Claude Console (platform.claude.com/usage). Everything computed client-side is an estimate; this is the bill.
  • Programmatic and per-feature: the Usage and Cost Admin API, which returns historical usage and cost grouped by workspace, API key, and model. Give each agent or feature its own API key or workspace and per-feature spend falls out of one request:
terminalbash
curl "https://api.anthropic.com/v1/organizations/cost_report?starting_at=2026-06-01T00:00:00Z&ending_at=2026-07-01T00:00:00Z&group_by[]=workspace_id&group_by[]=description" \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ANTHROPIC_ADMIN_KEY"
  • Per-agent, in code: the SDK's result message carries a per-model breakdown, so the agents from lesson 2.11 can log their own economics on every run:
log-spend.tstypescript
if (message.type === "result") {
for (const [model, u] of Object.entries(message.modelUsage)) {
  const reads = u.cacheReadInputTokens;
  const total = u.inputTokens + u.cacheCreationInputTokens + reads;
  const hitRatio = total > 0 ? reads / total : 0;
  console.log(model, "est $" + u.costUSD.toFixed(4), "cache hit ratio", hitRatio.toFixed(2));
}
}
  • Fleet-wide: Claude Code exports OpenTelemetry metrics, including cost and token counters with per-user attribution, once CLAUDE_CODE_ENABLE_TELEMETRY=1 is set. This is the team-scale answer; the monitoring doc covers exporters, and the same doc's "Cost monitoring" section shows the queries.

Where it breaks

The cheap-model false economy. The most common failure is optimizing the visible number. Producing a wrong answer cheaply is not cheap: you pay for the failed attempt, the retry on a bigger model, and your own time diagnosing which of the two runs to trust. Total cost of a verified outcome is the metric; per-token price is one input to it.

Price-tag routing

Every agent gets the cheapest tier because the pricing table says it is 10x cheaper. The refactoring agent produces plausible diffs that fail review twice, the billing migration plan is subtly wrong, and the retries plus your review hours cost more than frontier-tier tokens ever would.

Verified-outcome routing

Machine-verifiable tasks run cheap with an automatic check behind them; judgment-heavy tasks run frontier. Escalation is a written trigger ("failed once, and the failure was reasoning, not missing context"), so upgrades are diagnoses instead of vibes.

Cache-miss economics. Writes cost more than base input, so caching that never hits is a surcharge, not a saving. Three ways to end up there, all observable in the usage fields: a prefix that churns (dynamic content early in the system prompt invalidates everything after it), prompts under the per-model minimum cacheable length that silently skip caching, and TTL mismatch. That last one has a specific trap: sessions recurring at, say, 20-minute gaps miss a 5-minute cache every time, and the fix in the SDK cost-tracking doc, requesting 1-hour TTL via the ENABLE_PROMPT_CACHING_1H environment variable, doubles the write cost. Worth it when several runs land inside the hour; a pure loss when they do not. Compute it from your own gap distribution, never from a blog post's.

The attribution gap. One monthly number for the whole org is spend you cannot engineer, only feel bad about. If you cannot name your most expensive agent, the monitoring quadrant is where you start, not routing.

Lablab-a5Audit your own agent spend

Goal: Attribute your last month of spend, measure your cache-hit ratio, and write a routing policy grounded in your own numbers instead of memorized prices.

Prereqs: Claude Code installed and authenticated; at least a few weeks of real usage; Console access if you use the API directly.

  1. Fetch current prices first: open the pricing page and the models overview (URLs in Sources). Note today's tiers and the input/output price for each. This is the step that keeps the rest of the audit honest.
  2. In Claude Code, run /usage. Record the session block, then the attribution breakdown: which skills, subagents, plugins, and MCP servers consume your plan, on both the 24-hour and 7-day views.
  3. Get the authoritative view. Subscription: the plan usage bars in /usage. API: the Usage page at platform.claude.com/usage, filtered to the last month. If you have an Admin API key, pull the cost report grouped by workspace and description with the curl from this lesson.
  4. Compute your cache-hit ratio: cache read tokens divided by total input tokens (uncached plus cache writes plus cache reads). The Console usage view breaks out cache token types; for an SDK agent, log it with the modelUsage snippet above.
  5. List your last 15 to 20 real agent tasks from memory or session history (claude --resume shows recent sessions). Mark each one: was the output machine-verifiable, or did it need careful human review? Note which model actually ran it.
  6. Write COST-POLICY.md in your practice repo: which tier is your default, which task shapes route up, the written escalation trigger, your measured cache-hit ratio with today's date, and the URLs you will recheck monthly. Add model: haiku to one genuinely simple subagent as your first applied cut.

Verify

  • You can name your single largest spend source (a model tier, an MCP server, a subagent, or a specific agent) with a number, not a guess.
  • You have a cache-hit ratio for at least one workload, and you can say whether it is limited by prefix churn, prompt length, or TTL.
  • COST-POLICY.md exists, contains an escalation trigger phrased as a diagnosis, and every number in it carries a date and a source URL.
  • At least one task class moved to a cheaper tier with a verification check named next to it.
>Troubleshooting
  • /usage shows no attribution breakdown: it requires a recent Claude Code version (v2.1.174 or later per the costs doc) and reads local session history, so usage from other machines will not appear. Update, then rely on the Console for the cross-device picture.
  • Cache read tokens are zero everywhere: check your prompt sizes against the per-model minimum cacheable length on the caching doc, and check for dynamic content near the top of your system prompt breaking the prefix.
  • The Admin API returns an authorization error: the Usage and Cost API needs an Admin API key and is unavailable on individual accounts. Use the Console Usage and Cost pages instead; the data is the same.

Knowledge check

Knowledge check

Q1An SDK agent runs every 20 minutes against the same large system prompt. Cache read tokens are always zero, and input spend is high. What is happening, and what is the right analysis?
Q2A teammate routes every agent to the cheapest model tier and shows a 70% drop in token spend. Two weeks later the team is slower. What did the routing policy miss?
Q3Per the July 2026 ratios (5-minute cache writes at 1.25x base input, hits at 0.1x), when does caching a stable prefix start saving money?
Q4Your SDK agent's logged costUSD totals disagree with the monthly invoice by 12%, and finance wants per-feature numbers. What is the correct move?

Sources