The Seven-Layer Claude Code Cost System I Wish I Had Before the First Surprise Bill

Layer 3: Implement the Cache Waterfall

Prompt caching reduces input token costs by 90% for cached content. A system prompt that costs $0.30 to process once costs $0.03 every subsequent time within the cache window. At scale, this is the single largest cost reduction available.

The cache waterfall is a specific ordering of your prompt construction that maximizes the cacheable prefix:

function buildMessages(
  staticSystemContext: string,  // CLAUDE.md content, tool definitions
  conversationHistory: Message[],
  currentUserMessage: string
): Anthropic.MessageParam[] {
  return [
    {
      role: 'user',
      content: [
        {
          type: 'text',
          text: staticSystemContext,
          cache_control: { type: 'ephemeral' },  // Cache this for 1 hour
        },
        ...conversationHistory.flatMap(m => [
          { type: 'text' as const, text: `${m.role}: ${m.content}` }
        ]),
        {
          type: 'text',
          text: currentUserMessage,
          // No cache control — this is the variable suffix
        },
      ],
    },
  ]
}

The static system context — your CLAUDE.md content, tool definitions, project conventions — goes first with an explicit cache breakpoint. The variable content (current message, conversation history beyond the cached portion) goes last. Cache hit rate with this structure consistently runs above 85% on warm sessions.

Measure your actual cache hit rate using the usage fields in every API response:

const hitRate = response.usage.cache_read_input_tokens /
  (response.usage.input_tokens + response.usage.cache_read_input_tokens)

Below 70%: something is breaking your cache prefix. Above 90%: optimal. The gap between 50% and 90% cache hit rate on a 10,000 token system prompt is roughly $0.24 per session in Sonnet input costs — small per call, significant at volume.

Layer 4: Model Routing by Task Class

Running every task on Sonnet is like hiring a senior engineer to sort your email. Anthropic's model tier pricing as of May 2026:

Model	Input ($/M)	Output ($/M)	Best For
Claude Opus 4.8	$5.00	$25.00	Security-critical code, novel architecture decisions
Claude Sonnet 4.6	$3.00	$15.00	Feature implementation, debugging, code review
Claude Haiku 4.5	$1.00	$5.00	Formatting, SEO metadata, batch text transformations

A task routing system that correctly classifies 80% of tasks at the right tier reduces your average per-token cost by 40-60% compared to running everything on Sonnet.

The routing rules I use in production:

type TaskClass = 'trust-boundary' | 'implementation' | 'mechanical'

function routeTask(task: string): TaskClass {
  const trustBoundaryKeywords = [
    'payment', 'auth', 'webhook', 'security', 'vulnerability',
    'password', 'token', 'session', 'permission', 'rbac'
  ]
  const mechanicalKeywords = [
    'format', 'rename', 'capitalize', 'translate', 'summarize',
    'meta description', 'alt text', 'slug', 'csv to json'
  ]

  const taskLower = task.toLowerCase()

  if (trustBoundaryKeywords.some(k => taskLower.includes(k))) {
    return 'trust-boundary'  // → Opus
  }
  if (mechanicalKeywords.some(k => taskLower.includes(k))) {
    return 'mechanical'  // → Haiku
  }
  return 'implementation'  // → Sonnet
}

const MODEL_MAP: Record<TaskClass, string> = {
  'trust-boundary': 'claude-opus-4-8',
  'implementation': 'claude-sonnet-4-6',
  'mechanical': 'claude-haiku-4-5-20251001',
}

The keyword-based router is simple and predictable. It makes wrong classifications about 20% of the time, but those misclassifications are almost always in the "safe" direction — an implementation task routed to Opus costs more but still works. The dangerous miscalssification is a trust-boundary task routed to Haiku. Haiku misses edge cases in security code. Build in an escalation path: if Haiku or Sonnet returns a result flagged as security-relevant by the caller, re-run on Opus.

Layer 5: Hooks Guards Against Expensive Loops

The most expensive Claude Code failure mode is an agent that enters a retry loop — attempting the same approach, failing, and retrying without escalating. Left unchecked, a looping agent can consume thousands of dollars before a human notices.

Claude Code's Hooks system lets you intercept every tool call. A PreToolUse hook that counts retries and blocks execution after N attempts is the simplest effective loop guard:

#!/usr/bin/env python3
# .claude/hooks/loop-guard.py
import sys
import json
import os

COUNTER_FILE = '/tmp/claude-tool-counter.json'
MAX_CONSECUTIVE_SAME_TOOL = 8

def main():
    hook_data = json.load(sys.stdin)
    tool_name = hook_data.get('tool_name', '')

    # Load counter
    try:
        with open(COUNTER_FILE) as f:
            counters = json.load(f)
    except FileNotFoundError:
        counters = {}

    session_id = hook_data.get('session_id', 'default')
    key = f"{session_id}:{tool_name}"
    counters[key] = counters.get(key, 0) + 1

    # Save updated counter
    with open(COUNTER_FILE, 'w') as f:
        json.dump(counters, f)

    if counters[key] > MAX_CONSECUTIVE_SAME_TOOL:
        print(json.dumps({
            "decision": "block",
            "reason": f"Tool '{tool_name}' called {counters[key]} consecutive times. Possible loop. Stopping."
        }))
        sys.exit(2)

if __name__ == '__main__':
    main()

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "command": "python3 .claude/hooks/loop-guard.py"
      }
    ]
  }
}

Exit code 2 blocks the tool call. The model receives the block reason and must either try a different approach or escalate. This hook has stopped 3 runaway loops in my production setup over 9 months — each time averting what would have been a $30-$80 runaway session.

Layer 6: Session Budget Limits

Claude Code does not have a native per-session token budget with automatic stop. You implement this via the API by tracking token usage across the session and stopping when the budget is exceeded.

For programmatic agent sessions (not interactive), this is straightforward:

class BudgetedSession {
  private totalInputTokens = 0
  private totalOutputTokens = 0
  private readonly inputBudget: number
  private readonly outputBudget: number

  constructor(
    private readonly client: Anthropic,
    options: { inputBudget: number; outputBudget: number }
  ) {
    this.inputBudget = options.inputBudget
    this.outputBudget = options.outputBudget
  }

  async send(messages: Anthropic.MessageParam[], options: Omit<Anthropic.MessageCreateParams, 'messages'>): Promise<Anthropic.Message> {
    const remainingInput = this.inputBudget - this.totalInputTokens
    const remainingOutput = this.outputBudget - this.totalOutputTokens

    if (remainingInput <= 0 || remainingOutput <= 0) {
      throw new Error(`Session budget exceeded. Input used: ${this.totalInputTokens}/${this.inputBudget}, Output used: ${this.totalOutputTokens}/${this.outputBudget}`)
    }

    const response = await this.client.messages.create({
      ...options,
      messages,
      max_tokens: Math.min(options.max_tokens ?? 4096, remainingOutput),
    })

    this.totalInputTokens += response.usage.input_tokens
    this.totalOutputTokens += response.usage.output_tokens

    return response
  }

  getCostEstimate(inputPricePerM: number, outputPricePerM: number): number {
    return (
      (this.totalInputTokens * inputPricePerM) / 1_000_000 +
      (this.totalOutputTokens * outputPricePerM) / 1_000_000
    )
  }
}

// Usage
const session = new BudgetedSession(client, {
  inputBudget: 100_000,   // ~$0.30 at Sonnet rates
  outputBudget: 10_000,   // ~$0.15 at Sonnet rates
})

Set budgets based on expected task complexity. A blog post draft: 50K input, 4K output. A codebase analysis: 200K input, 20K output. A security audit: 500K input, 50K output. Any session that exceeds its budget surfaces as an exception to investigate — not as a line item on next month's bill.

Layer 7: Cross-Provider Audit Routing

The counterintuitive cost control: spend a small amount on cross-provider review to avoid expensive mistakes. This layer targets trust-boundary code — payment handlers, authentication logic, webhook verification — where errors have real financial and security consequences.

After Claude Code completes trust-boundary work, route the diff to a second model (I use OpenAI Codex via the API) for independent review. Two different model families have different blind spots. In May 2026, a Codex review caught a cache header ordering bug in my Next.js config that had been live for weeks and that multiple Claude reviews had not flagged. The bug was making checkout pages publicly cacheable at Cloudflare's edge. The cost of the Codex review: $0.08. The cost of that bug continuing undetected: potentially significant in a security audit or breach scenario.

async function crossProviderReview(diff: string): Promise<{ issues: string[]; severity: 'clean' | 'warnings' | 'critical' }> {
  const openai = new OpenAI()
  const response = await openai.chat.completions.create({
    model: 'gpt-4.1',
    messages: [
      {
        role: 'system',
        content: 'You are a security-focused code reviewer. Review this diff for: authentication bypasses, authorization flaws, injection vulnerabilities, insecure data exposure, timing attacks. Be specific about line numbers and exact risks. Return JSON only.',
      },
      {
        role: 'user',
        content: `Review this diff:

${diff}`,
      },
    ],
    response_format: { type: 'json_object' },
  })

  return JSON.parse(response.choices[0].message.content ?? '{}')
}

Budget $5-$10/month for cross-provider review. Route only trust-boundary diffs — everything touching authentication, payments, and data access. For everything else, Claude's self-review is sufficient.

The Compounding Effect

Each layer independently reduces cost. Together, they compound:

Layer	Typical Savings	Setup Time
MAX_THINKING_TOKENS cap	20-40%	2 minutes
Model version pinning	5-15% (cache stability)	5 minutes
Cache waterfall	30-60%	1-2 hours
Model routing	30-50%	2-4 hours
Hooks loop guard	Variable (prevents runaway)	30 minutes
Session budgets	Variable (prevents overrun)	2-3 hours
Cross-provider audit	Negative (-$5-10/mo), prevents larger costs	1-2 days

Layers 1 through 3 take under 3 hours to implement and typically cut bills by 60-70%. Layers 4 through 6 add another 15-25%. Layer 7 does not reduce the bill — it protects against costs that do not appear on an API invoice but matter more.

The developer who posted the $900 weekend bill needed Layers 1 (thinking cap), 5 (loop guard), and 6 (session budget). Three layers. Under 4 hours of work. $832 saved on that single session alone.

Start with Layer 1. Implement it in the next 10 minutes. The others follow naturally as you understand your usage patterns better.

The AI API Cost Calculator at wowhow.cloud can model the impact of each layer against your actual usage volume before you commit the implementation time.

---

Sources

1. Prompt Caching Documentation — Anthropic (2026)
2. Claude Code Hooks Reference — Anthropic (2026)
3. Claude Model Pricing — Anthropic (2026)
4. Claude Code Settings Reference — Anthropic (2026)