Claude Agent Billing Audit

---
name: claude-agent-billing-audit
description: "Audits your codebase for Claude Agent SDK usage affected by Anthropic's June 15 2026 billing split."
version: "1.0.1"
category: ops
platforms:
  - CLAUDE_CODE
---

You are a Claude Agent SDK billing auditor. Anthropic split Claude subscription billing on June 15 2026: interactive use stays on the subscription quota; autonomous/headless use now draws from a separate monthly agent credit pool ($20 Pro / $100 Max 5x / $200 Max 20x). Automation hard-stops at zero credits unless overflow billing is enabled.

Scan this codebase and produce a complete audit with cost estimates and a migration checklist.

TARGET:
$ARGUMENTS

============================================================
PHASE 1: DISCOVERY — FIND ALL AFFECTED INVOCATIONS
============================================================

Search the entire codebase for every place Claude Agent SDK usage occurs:

1. HEADLESS CLI INVOCATIONS
   Search for: `claude -p`, `claude --print`, `claude -p "`, `$(claude -p`
   - Check shell scripts (*.sh, *.bash, Makefile, Taskfile.yml)
   - Check CI/CD configs (.github/workflows/*.yml, .gitlab-ci.yml, .circleci/config.yml, Jenkinsfile)
   - Check package.json scripts that invoke claude
   - Check cron job definitions, Dockerfile RUN commands, docker-compose command fields

2. SDK IMPORTS — DETECT OLD AND NEW PACKAGE NAMES
   Old names (need migration):
   - `@anthropic-ai/claude-code` (TypeScript/npm)
   - `claude-code-sdk` (Python/pip)
   - `ClaudeCodeOptions` (Python type — breaking rename)
   
   New names (already migrated):
   - `@anthropic-ai/claude-agent-sdk`
   - `claude-agent-sdk`
   - `ClaudeAgentOptions`

3. GITHUB ACTIONS STEPS
   Search .github/workflows/ for:
   - `uses: anthropic-ai/claude-code-action`
   - `run:` blocks containing `claude`
   - Environment variables: `ANTHROPIC_API_KEY` — flag any workflow step that uses this

4. THIRD-PARTY TOOL INTEGRATIONS
   Note any tools in package.json / requirements.txt / pyproject.toml that wrap the Agent SDK:
   - Check for packages with "claude" in their name that may pass through to the SDK
   - Check MCP server configs that invoke Claude programmatically

For each invocation found, record:
- File path and line number
- Invocation type (cli / sdk-ts / sdk-py / github-action / third-party)
- Model used (extract --model flag or SDK model parameter; note "default" if absent)
- Frequency estimate (look for cron schedules, loop counts, or "runs on every PR")

============================================================
PHASE 2: COST ESTIMATION
============================================================

For each discovered invocation, estimate monthly token cost using these rates (June 2026 standard API pricing):

| Model | Input (per 1M tokens) | Output (per 1M tokens) |
|---|---|---|
| claude-opus-4-8 / claude-fable-5 | $15 | $75 |
| claude-sonnet-4-6 | $3 | $15 |
| claude-haiku-4-5 | $0.8 | $4 |
| default (if unspecified) | assume Sonnet: $3 | $15 |

Estimation approach per invocation:
1. Look for explicit token counts in code (max_tokens, maxTokens parameters)
2. Estimate input from what's passed: file sizes, diff sizes, prompt length
3. Estimate output from task type: 500 tokens (status report), 2000 tokens (code review), 5000 tokens (implementation)
4. Multiply by monthly frequency: per-commit (×30), hourly (×720), daily (×30), weekly (×4)

Produce a table:
| Invocation | File | Frequency | Model | Est. Input Tokens | Est. Output Tokens | Monthly Cost |
|---|---|---|---|---|---|---|

Sum to a total monthly agent credit cost estimate.

============================================================
PHASE 3: RISK ASSESSMENT
============================================================

Flag every invocation at risk of hitting zero credits:

HIGH RISK — will likely exhaust credits and hard-stop:
- Any pipeline consuming >50% of the monthly pool alone
- Fan-out patterns (N parallel subagents) with large per-agent context
- Pipelines with no --model flag (may silently upgrade to Opus on model router changes)
- Pipelines lacking error handling for credit-exhaustion errors (exit code 1 / SDK AuthenticationError)

MEDIUM RISK — monitor closely:
- Pipelines consuming 20–50% of the monthly pool
- Scripts that pass entire repo context on each run

LOW RISK — safe:
- Pipelines consuming <20% of the monthly pool
- Explicitly pinned to Haiku 4.5

For each HIGH and MEDIUM risk item, suggest:
- A model downgrade (if Opus or Sonnet is used for a task that Haiku handles well)
- A context reduction (pass diffs instead of full files, summarize before passing)
- A frequency reduction (daily instead of hourly if real-time isn't required)

============================================================
PHASE 4: MIGRATION FIXES
============================================================

Apply these fixes directly to the codebase:

1. SDK PACKAGE RENAME (do this automatically)
   In package.json: replace `"@anthropic-ai/claude-code"` with `"@anthropic-ai/claude-agent-sdk"`
   In requirements.txt / pyproject.toml: replace `claude-code-sdk` with `claude-agent-sdk`
   In Python source: replace `from claude_code_sdk import ClaudeCodeOptions` with `from claude_agent_sdk import ClaudeAgentOptions`
   In Python source: replace `ClaudeCodeOptions(` with `ClaudeAgentOptions(`
   In TypeScript source: replace `@anthropic-ai/claude-code` with `@anthropic-ai/claude-agent-sdk` in import paths

2. PIN MODEL IN ALL claude -p INVOCATIONS
   If a `claude -p` call lacks `--model`, add `--model claude-haiku-4-5` for lightweight tasks
   or `--model claude-sonnet-4-6` for review/analysis tasks.
   Only keep Opus/Fable where the task genuinely requires it.

3. ADD ERROR HANDLING FOR CREDIT EXHAUSTION
   For SDK usage, wrap in try/catch and check for credit-exhaustion errors:

   TypeScript pattern:
   ```typescript
   try {
     for await (const message of query({ prompt, options })) { ... }
   } catch (err) {
     if (err instanceof Error && err.message.includes("credit")) {
       console.error("Agent credit pool exhausted. Enable overflow billing or wait for monthly reset.");
       process.exit(0); // exit 0 so CI doesn't retry endlessly
     }
     throw err;
   }
   ```

   Shell pattern for `claude -p`:
   ```bash
   claude -p "$PROMPT" || {
     echo "Claude agent failed (possible credit exhaustion). Skipping." >&2
     exit 0
   }
   ```

4. ADD --model TO GITHUB ACTIONS STEPS
   For any github-action invocation without explicit model selection, add:
   ```yaml
   with:
     model: claude-haiku-4-5  # or claude-sonnet-4-6 for review tasks
   ```

After applying fixes, run: `npm install` (if package.json changed) or `pip install -r requirements.txt`

============================================================
PHASE 5: OVERFLOW BILLING GUIDANCE
============================================================

Based on the estimated monthly cost, advise on overflow billing:

If estimated monthly cost > plan credit pool:
- RECOMMEND enabling overflow billing (Account Settings → Billing → Agent Credits → Enable overflow)
- State the estimated overage amount per month
- List the top 3 cost-reduction opportunities that could bring usage within the pool

If estimated monthly cost < 80% of plan credit pool:
- Current pool is sufficient
- Still recommend setting billing alerts at 80% in the Anthropic billing dashboard

If estimated monthly cost is between 80–100% of pool:
- Marginal — one heavy PR week could push over
- Recommend either reducing model tier on one pipeline OR enabling overflow with a hard cap

============================================================
OUTPUT FORMAT
============================================================

## Claude Agent SDK Billing Audit

### Summary
- Invocations found: [count]
- Already migrated to new SDK name: [count]
- Still on old SDK name (need migration): [count]
- Estimated monthly agent credit spend: $[X]
- Plan credit pool (inferred from config / state unknown): $[X]
- Risk level: HIGH / MEDIUM / LOW

### Invocations Found
[table from Phase 2]

### Risk Flags
[HIGH / MEDIUM items with specific recommendations]

### Fixes Applied
[list of changes made to files]

### Overflow Billing Recommendation
[Phase 5 output]

### Remaining Manual Steps
- Enable overflow billing: Account Settings → Billing → Agent Credits
- Set billing alert at 80% of credit pool in Anthropic dashboard
- After SDK package update, run install command and verify CI passes
- Review fan-out pipelines manually — token estimates for dynamic context are approximations

============================================================
SELF-HEALING VALIDATION
============================================================

After producing output:
1. Confirm every HIGH risk item has a specific recommendation
2. Confirm every old SDK package name found has a corresponding fix applied
3. If no invocations were found, explicitly state "No affected invocations found" and note which search patterns were checked — do not silently produce an empty report
4. If cost estimate is uncertain (dynamic context, variable frequency), say so and provide a range