// sdk-cost-tracker.ts
import { createHash } from 'crypto';

interface ExecutionRecord {
  runId: string;
  model: string;
  inputTokens: number;
  outputTokens: number;
  cacheHit: boolean;
  timestamp: number;
}

class AgentCostTracker {
  private records: ExecutionRecord[] = [];
  private monthlyCap: number;
  private currentSpend: number = 0;

  constructor(monthlyCap: number) {
    this.monthlyCap = monthlyCap;
  }

  logExecution(record: ExecutionRecord): void {
    const inputCost = (record.inputTokens / 1_000_000) * this.getModelRate(record.model, 'input');
    const outputCost = (record.outputTokens / 1_000_000) * this.getModelRate(record.model, 'output');
    const adjustedCost = record.cacheHit ? outputCost * 0.5 : inputCost + outputCost;

    this.currentSpend += adjustedCost;
    this.records.push({ ...record, timestamp: Date.now() });

    if (this.currentSpend >= this.monthlyCap) {
      this.triggerCapAlert();
    }
  }

  private getModelRate(model: string, direction: 'input' | 'output'): number {
    const rates: Record<string, Record<string, number>> = {
      'opus-4.7': { input: 5.0, output: 25.0 },
      'sonnet-4.6': { input: 3.0, output: 15.0 },
      'haiku-4.5': { input: 1.0, output: 5.0 }
    };
    return rates[model]?.[direction] ?? 0;
  }

  private triggerCapAlert(): void {
    console.warn(`[AgentCostTracker] Monthly cap reached: $${this.currentSpend.toFixed(2)}`);
    // Integrate with PagerDuty, Slack, or CI failure hooks
  }

  getMonthlySpend(): number {
    return this.currentSpend;
  }
}

export default AgentCostTracker;

aching behavior, but should be tuned to your actual hit rates. The cap alert integrates with existing incident pipelines rather than failing silently.

Step 2: Implement Cost-Aware Routing

Not all automation requires Opus-level reasoning. Route high-complexity tasks to Claude, and volume-heavy or deterministic tasks to cheaper alternatives. Hybrid routing requires explicit model selection logic and fallback chains.

// task-router.ts
import AgentCostTracker from './sdk-cost-tracker';

type TaskPriority = 'critical' | 'standard' | 'background';

interface RoutingConfig {
  critical: string;
  standard: string;
  background: string;
  fallback: string;
}

class TaskRouter {
  private config: RoutingConfig;
  private tracker: AgentCostTracker;

  constructor(config: RoutingConfig, tracker: AgentCostTracker) {
    this.config = config;
    this.tracker = tracker;
  }

  selectModel(priority: TaskPriority, contextSize: number): string {
    const baseModel = this.config[priority];
    
    // Route large contexts to cheaper models if reasoning depth isn't critical
    if (contextSize > 80000 && priority !== 'critical') {
      return this.config.background;
    }

    // Fallback if monthly spend approaches threshold
    if (this.tracker.getMonthlySpend() > this.tracker['monthlyCap'] * 0.85) {
      return this.config.fallback;
    }

    return baseModel;
  }
}

export { TaskRouter, RoutingConfig, TaskPriority };

Why this design: Routing logic lives outside the execution layer, making it testable and swappable. Context-size thresholds prevent expensive models from processing verbose logs or diffs that Haiku or Sonnet can handle. The spend threshold (0.85) provides a buffer before cap enforcement triggers, allowing graceful degradation rather than hard failures.

Step 3: Configure Overflow Safeguards

Anthropic's "extra usage" feature is opt-in and defaults to OFF. Once the monthly credit is exhausted, SDK calls return rate-limit errors unless overflow is enabled. Overflow bills at API list rates with no subscription discount. A monthly cap must be set explicitly.

# cap-enforcement.sh
#!/usr/bin/env bash
set -euo pipefail

CAP_DOLLARS="${AGENT_SDK_MONTHLY_CAP:-150}"
CURRENT_SPEND=$(curl -s "https://api.anthropic.com/v1/billing/usage" \
  -H "x-api-key: $ANTHROPIC_API_KEY" | jq '.sdk_credits_used')

if (( $(echo "$CURRENT_SPEND >= $CAP_DOLLARS" | bc -l) )); then
  echo "[CAP] SDK usage cap reached ($CURRENT_SPEND/$CAP_DOLLARS). Halting pipeline."
  exit 1
fi

echo "[CAP] Usage within bounds. Proceeding."

Why this design: Shell-level enforcement acts as a circuit breaker before CI runners or cron jobs execute. The script reads actual usage from Anthropic's billing endpoint (or your internal tracker) and fails fast. Hard exits prevent cascading API charges. The cap value is environment-configurable, allowing per-repository or per-team limits.

Pitfall Guide

1. Assuming Interactive Mode Bypasses Billing

Explanation: Launching claude without -p and feeding it a long initial prompt technically draws from subscription limits. However, unattended execution requires a TTY (tmux, screen, dtach), output capture shifts to JSONL tailing, and Anthropic reserves the right to modify or discontinue the behavior. Fix: Treat interactive mode as a temporary bridge, not a production architecture. Implement explicit SDK routing with cost tracking instead.

2. Ignoring Tokenizer Variance

Explanation: Opus 4.7's tokenizer inflates token counts by 32–47% for identical text compared to earlier revisions. Budgeting based on raw character length or older model baselines will underestimate costs. Fix: Measure actual token consumption per run during staging. Apply a 1.4x multiplier to Opus 4.7 estimates until caching stabilizes hit rates.

3. Leaving Extra Usage Unconfigured

Explanation: The overflow toggle defaults to OFF. When credits deplete, SDK calls fail silently in CI unless you monitor exit codes. Enabling overflow without a cap risks uncapped invoices. Fix: Enable extra usage only after setting a hard monthly dollar cap. Document the cap in runbooks and alert on threshold breaches.

4. Swapping Models Without Validation

Explanation: Replacing Sonnet with GPT-5.5, Codex, or Cerebras-hosted models changes prompt behavior, tool-call schemas, and failure modes. Voice drift and schema mismatches break downstream parsers. Fix: Run a validation suite against candidate models. Test prompt templates, tool definitions, and output parsing on a non-trivial sample before flipping production routing.

5. Overlooking Edge Cases in Interactive Sessions

Explanation: Hooks, subagents (Task tool), and MCP tool calls invoked inside interactive sessions lack published billing boundaries. Assuming they remain subscription-billed is risky. Fix: Audit all interactive session extensions. If load-bearing, treat them as SDK-billed until Anthropic publishes explicit guidance. Isolate them in separate execution contexts.

6. Neglecting Prompt Caching Optimization

Explanation: Caching extends effective capacity by 2–3x, but only if system prompts, repository context, and tool schemas are structured for cache hits. Randomized or highly dynamic prompts defeat caching. Fix: Stabilize prompt prefixes. Use deterministic system instructions. Enable cache headers in SDK calls. Monitor cache hit rates and adjust prompt structure accordingly.

7. Hardcoding Rate Limits Instead of Dynamic Throttling

Explanation: The $200 envelope lacks published per-minute or per-hour caps. Backoff behavior under load is unspecified. Hardcoded delays waste compute or trigger unnecessary retries. Fix: Implement exponential backoff with jitter. Monitor SDK response headers for rate-limit signals. Throttle dynamically based on actual API feedback rather than static intervals.

Production Bundle

Action Checklist

• Inventory all claude -p, GitHub Actions, cron jobs, and third-party SDK integrations tied to your subscription.
• Estimate monthly token spend at API list rates using a representative week multiplied by 4.3.
• Decide on a migration path: hard cap, hybrid routing, or pure API billing. Document the decision.
• Validate model swaps on a non-trivial sample. Check prompt behavior, tool-call schemas, and output parsing.
• Enable extra usage and set a hard monthly dollar cap. Write the cap into your runbook.
• Instrument SDK calls with cost tracking and cache hit logging.
• Monitor Anthropic's help center for clarifications on hooks, subagents, and MCP billing boundaries.
• Implement dynamic throttling and exponential backoff for SDK rate limits.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Low-volume automation (<200 runs/mo)	Stay on Claude with hard cap	Minimal engineering overhead, predictable spend	$0–$50/mo over credit
High-volume deterministic tasks	Hybrid routing to cheaper models	Reduces API rate exposure, preserves Claude for complex reasoning	40–70% reduction in token costs
Existing API-key billing	Pure API path	June 15 policy does not affect direct API billing	No change; credit not claimable
Interactive-heavy teams	Maintain subscription, isolate SDK workloads	Keeps chat/interactive limits intact, prevents cross-contamination	Stable subscription cost, explicit SDK budget
Unvalidated model swap	Delay deployment, run validation suite	Prevents pipeline breakage, schema drift, and silent failures	Avoids rework costs and incident response

Configuration Template

# agent-sdk-config.yaml
billing:
  monthly_cap_usd: 150
  extra_usage_enabled: true
  alert_threshold_percent: 85

routing:
  critical: "opus-4.7"
  standard: "sonnet-4.6"
  background: "haiku-4.5"
  fallback: "sonnet-4.6"
  context_threshold_tokens: 80000

instrumentation:
  track_cache_hits: true
  log_model_selection: true
  export_format: "jsonl"

safety:
  circuit_breaker_enabled: true
  max_concurrent_sdk_calls: 3
  backoff_strategy: "exponential_jitter"
  base_delay_ms: 1000
  max_delay_ms: 30000

Quick Start Guide

1. Audit your automation surface: Run grep -r "claude -p\|claude --resume\|anthropic/claude-code-action" . across repositories. Document every invocation point.
2. Deploy the cost tracker: Integrate AgentCostTracker into your CI runner or cron orchestrator. Log model, tokens, and cache status per execution.
3. Set the overflow cap: Navigate to your Anthropic account settings, enable extra usage, and set a monthly dollar limit matching your budget. Verify the toggle state.
4. Route by priority: Update your automation scripts to call TaskRouter.selectModel() before execution. Pass context size and priority level.
5. Validate and monitor: Run a staging batch. Check JSONL logs for cache hit rates, model selection accuracy, and spend accumulation. Adjust thresholds before June 15.

The transition from implicit subscription subsidies to explicit programmatic billing is a structural shift, not a temporary adjustment. Teams that instrument, route, and cap their SDK usage will maintain pipeline reliability. Teams that ignore the boundary will face either silent failures or uncapped invoices. The architecture is straightforward; the discipline is what separates production-ready automation from experimental scripts.