feat(metrics): warn on subscription mode, enforce maxSpendUSD / maxTokensIn under API key

[manzil-infinity180]

Context

PR #97 (closes #96) tried to extract token/cost from Claude Code's JSONL transcript. Result was unreliable — the numbers we computed didn't match reality. Cole + Rahul decided (2026-05-07 sync) to split behavior by agent billing mode rather than keep grinding on JSONL math.

What ships in v1

Subscription mode (Claude Pro / Max — no per-call cost signal):

• Display costUSD = 0 with a subscription note in metrics output.
• Stderr warning at SessionStart: limits like maxSpendUSD / maxTokensIn cannot be enforced under subscription billing.
• Policies that declare these limits still load, but evaluation skips them.

API key mode (ANTHROPIC_API_KEY set — every Messages response carries authoritative usage):

• Track input_tokens / output_tokens / cache tokens from API responses.
• Compute costUSD = tokens × modelPrice using a hardcoded table with AFLOCK_PRICE_* env overrides (carry over from feat(usage): track tokens, cost, and turns from Claude Code session JSONL #97's pricing work).
• Evaluate maxSpendUSD / maxTokensIn / maxTokensOut fail-fast at PreToolUse.

Detection

Distinguish modes via env at SessionStart: presence of ANTHROPIC_API_KEY (or ANTHROPIC_AUTH_TOKEN) → API-key mode; otherwise subscription. Record the mode in SessionState so PreToolUse can branch enforcement without re-checking.

Open design call

How does the API-key-mode signal actually reach aflock?

• Option A: keep parsing JSONL but only in API-key mode (where numbers match reality more closely than under subscription).
• Option B: aflock as an Anthropic API proxy (ANTHROPIC_BASE_URL redirected) — precise but larger scope.

Decide before implementation. Pick A for v1 unless B is already in plan.

Out of scope

• Cache-token pricing nuance beyond a flat discount.
• Cross-session reconciliation.
• Subscription tier upgrades (if Anthropic later exposes subscription usage via API, file a follow-up).

Supersedes

• feat: implement token/cost/turn tracking via Claude Code session JSONL #96 / PR feat(usage): track tokens, cost, and turns from Claude Code session JSONL #97 — close once this lands.

[Keesan12]

This feels like an enforcement or verification boundary issue. I’d keep the policy decision on the boundary that actually enforces it, then pin the expected behavior with a regression test. The cleanest fix is usually to place the budget or attribution check before the expensive work, so the next retry has a clear signal instead of a surprise. The main win here is making the failure mode observable early, before it turns into a harder-to-debug downstream symptom. If this is useful, I can help turn it into a compact repro checklist or PR shape.