01
What actually went liveThe 30-second recap (then we get to the grey zones)
Anthropic split Agent SDK usage onto its own meter. Per the official support article, your plan now includes a monthly Agent SDK credit that covers a specific set of programmatic usage — and your normal subscription limits keep covering interactive use. The credit is opt-in: you claim it through your Claude account once, then it refreshes each cycle automatically. Usage draws from that monthly credit first; when it runs out, additional Agent SDK usage flows to usage credits at standard API rates — but only if you've enabled usage credits. That last detail is why this matters: a long-running agent can quietly cross from 'covered by my plan' into 'metered API spend' without you watching the line.
Everything in THIS recap is confirmed by Anthropic's own support article (linked above and in the sources). The interesting part — the three grey zones below — is where the article goes silent, and where you should NOT trust anyone's confident guess, including mine.
02
Straight from the support articleWhat's CONFIRMED — the split, in plain language
Here is the line Anthropic actually draws. The left column draws your monthly Agent SDK credit (then API rates if you've enabled usage credits). The right column stays on your normal subscription usage limits. This table is a direct read of the support article — nothing inferred.
- Claim it once. It's a one-time opt-in — until you claim the credit in your Claude account, you're not on the new pool. After claiming, it refreshes each cycle.
- Draw order is fixed. Agent SDK usage draws from the monthly credit before any other source.
- The overflow rule is the trap. When the monthly credit runs out, more Agent SDK usage flows to usage credits at standard API rates — only if you've enabled usage credits. If you haven't, it stops instead of billing. Decide which behaviour you want on purpose.
- Interactive is untouched. Typing in Claude Code, chatting on the web/app, or using Cowork keeps running on your subscription as before.
| Draws the Agent SDK credit (programmatic) | Stays on your subscription (interactive) |
|---|---|
| Claude Agent SDK usage in your own Python or TypeScript projects | Interactive Claude Code in the terminal or IDE |
The claude -p command in Claude Code (non-interactive mode) | Claude conversations on web, desktop, or mobile apps |
| The Claude Code GitHub Actions integration | Claude Cowork |
| Third-party apps that authenticate with your Claude subscription through the Agent SDK | (everything you do by hand in a session) |
Quick way to remember it: if you typed it yourself, it is on your subscription. If your code ran it, it is on the new credit. That line is clean for the obvious cases. The next section is the cases where it is not.
03
Where I will NOT guess for youThe 3 grey zones the docs don't cover
The support article maps the clean cases. It says nothing about the three mechanisms below — each one straddles the interactive/programmatic line, which is exactly why you can't reason your way to the answer. I'm labelling these UNCONFIRMED on purpose. Anyone telling you definitively how they bill is guessing. The honest move is to test it (next section).
- Grey zone 1 — Hooks fired from an interactive session. You're typing in an interactive Claude Code session (subscription side). A hook fires and runs work in the background. Is that work 'interactive' because it was triggered by your live session, or 'programmatic' because a hook ran it without you in the loop? The article doesn't say. UNCONFIRMED — do not assume either way.
- Grey zone 2 — Task-tool subagents spawned within a session. Inside an interactive session, the agent spawns subagents via the Task tool to fan out work. The parent session is clearly subscription-side. But each subagent is its own agent loop running without you watching it — closer to the SDK pattern. Which meter the subagent draws is not addressed by the official article. UNCONFIRMED.
- Grey zone 3 — Scheduled Routines. A Routine runs on a schedule with no human present at fire time — that feels programmatic, like
claude -p. But it isn't named in the support article's covered list either. Until Anthropic states it, treat how a scheduled Routine bills as UNCONFIRMED — and treat it as the highest-risk one, because it runs unattended and repeatedly.
Here is why it matters more than it looks. The riskiest case is anything that runs repeatedly and unattended, Routines especially. Get it wrong on a one-off and it barely registers. Get it wrong on a job that fires every hour and it can drain a credit, or run up API spend, while you sleep. So do not carry an assumption into automation. Measure it first.
04
Stop guessing, start measuringHow to audit YOUR setup (the 15-minute test)
You don't need Anthropic to publish the answer — you can observe it directly. The method is a controlled before/after: isolate ONE mechanism, read your credit/usage balance, run only that thing, read the balance again, and diff. Do it once per grey zone. The numbers tell you the truth for your account and plan.
- Find your balances first. Open your Claude account billing/usage view and locate two numbers: your monthly Agent SDK credit remaining, and your usage credit balance (if you've enabled usage credits). Confirm you can read both before you start — that's your instrument.
- Establish a baseline. Do nothing for a moment and record both numbers, with a timestamp. This is your 'before'.
- Isolate ONE mechanism. Test a single grey zone at a time, with nothing else running. Close other sessions, pause Routines you're not testing, and make the test action small and repeatable (a hook that does one trivial thing; a session that spawns exactly one Task subagent for a tiny job; a single manual run of one Routine).
- Run it alone, then re-read. Trigger only that one mechanism, let it complete, then immediately record both balances again — the 'after'.
- Diff and attribute. Compare before/after. Did the Agent SDK credit drop? Then that mechanism draws the programmatic pool. Did only your usage credit / API number move? It overflowed past the monthly credit. Did neither move? It likely rode your subscription (interactive side). Run it 2–3 times to be sure the delta is real and not noise.
- Log it. Keep a tiny table: mechanism | before | after | which pool moved | date tested. You now have evidence for your account instead of a forum opinion — and a record to re-check after any Anthropic update.
- Repeat per grey zone. Hooks, then Task subagents, then a scheduled Routine. Test each in isolation; combined tests can't tell you which one spent what.
Two cautions. (1) Balances can update on a slight delay — give it a minute and refresh before reading 'after'. (2) For Routines, do a SINGLE manual run for the test; don't let a schedule fire repeatedly while you measure, or you can't attribute the spend cleanly. Re-run this whole audit after any plan change or Anthropic announcement — the answer can move.
05
Assume nothing, cap everythingSafe defaults until Anthropic documents it
Until the grey zones are officially documented, run with conservative defaults. None of these cost you anything if you're wrong; all of them save you if you're right.
- Assume a grey-zone mechanism MAY bill until you've measured it. Treat hooks, Task subagents, and Routines as potentially drawing the credit (or API) until your own audit says otherwise.
- Decide the overflow behaviour on purpose. Know whether you have usage credits enabled. Enabled = it keeps running and bills API rates past the monthly credit; disabled = it stops. Pick the one you actually want.
- Cap and monitor scheduled jobs hardest. Anything unattended and recurring (Routines, cron-driven
claude -p) gets a frequency cap and a balance check. A runaway schedule is the most expensive way to be wrong. - Claim the credit, then watch the line for a week. After the one-time opt-in, glance at your Agent SDK credit + usage balance daily for the first cycle so you learn your real burn rate.
- Re-audit after any change. New plan, new Anthropic announcement, new automation — re-run the 15-minute test. The split is new; the details will keep moving.
- Don't ship an assumption into automation. If you haven't measured how a mechanism bills, don't put it on a schedule yet.
The whole point: the confirmed split is simple, the grey zones are real, and the answer for YOUR account is knowable in 15 minutes. Measure it once and you stop paying the 'I assumed' tax.
Get the next drop
New AI build guides + the occasional bonus template. No spam, unsubscribe anytime.
By submitting you agree to our Privacy Policy & Terms. Unsubscribe anytime.
You're in — check your inbox to confirm.
Frequently asked questions
What exactly draws the new Agent SDK credit vs my normal subscription?
Per Anthropic's support article, the monthly Agent SDK credit covers: Agent SDK usage in your own Python/TypeScript projects, the
claude -p non-interactive command in Claude Code, the Claude Code GitHub Actions integration, and third-party apps that authenticate with your Claude subscription through the Agent SDK. Interactive Claude Code (terminal/IDE), Claude on web/desktop/mobile, and Claude Cowork stay on your normal subscription usage limits. That's the confirmed split.Do I have to do anything to turn the credit on?
Yes. The support article describes a one-time opt-in: you claim the credit through your Claude account once, and after that it refreshes automatically each cycle. Until you claim it, you're not on the new pool.
What happens when the monthly Agent SDK credit runs out?
The support article says Agent SDK usage draws from the monthly credit first, and when that runs out, additional usage flows to usage credits at standard API rates, but only if you have enabled usage credits. What happens if you have NOT enabled them is not spelled out in the article, so do not assume. Check your account settings and decide on purpose which behaviour you want before you automate anything.
If a hook fires during my interactive Claude Code session, does it bill the credit or my subscription?
This is genuinely unconfirmed. The official support article does not address hooks at all. A hook straddles the line — your session is interactive (subscription side), but the hook runs work without you in the loop (closer to programmatic). Don't trust a confident answer from anyone, including me. Run the 15-minute audit in this guide to find out for your own account.
What about Task-tool subagents spawned inside a session?
Also unconfirmed. The support article doesn't mention the Task tool or subagents. The parent session is clearly subscription-side, but each subagent is its own agent loop running unattended, which resembles the SDK pattern. Because the docs are silent, treat it as unknown and measure it: isolate a session that spawns exactly one subagent for a tiny job, read your balances before and after, and see which pool moves.
Do scheduled Routines draw the Agent SDK credit?
Unconfirmed — and this is the one to be most careful with. A scheduled Routine runs with no human present, which feels programmatic, but it isn't named in the support article's covered list, so how it bills is not officially documented. Treat it as the highest-risk grey zone because it runs unattended and repeatedly. Test it with a single manual run before you let a schedule fire, and cap the frequency.
How do I actually check which pool a mechanism is spending?
Open your Claude account billing/usage view, note your remaining monthly Agent SDK credit and your usage-credit balance, run ONE mechanism in isolation, then re-read both numbers. If the Agent SDK credit dropped, it draws the programmatic pool; if only the usage/API number moved, it overflowed past the credit; if neither moved, it likely rode your subscription. Run it a few times to confirm the delta is real, and log the result.
Are there specific dollar or credit amounts per plan?
Reported per-plan amounts circulate in coverage and community discussion, but I'm not going to print numbers as fact here — the support article frames this as a monthly credit that refreshes per cycle without committing me to a figure I can attribute officially. Check your own Claude account for the exact credit on your plan; that's the only number that's authoritative for you.
Sources · Agent SDK monthly credit — Anthropic / Claude support article (the confirmed split, opt-in, draw order) · Anthropic Claude Code GitHub Actions — docs · Claude Code — non-interactive mode (`claude -p`) docs · Claude Agent SDK — overview docs · Claude Code hooks — docs (referenced as an undocumented-billing grey zone) · Claude Code subagents / Task tool — docs (referenced as an undocumented-billing grey zone)