Authentication docs don't state which usage pool `claude -p` draws from

Status Open

Reported on v2.1.220

Maintainer reply None cached

Activity 0 comments · opened Jul 27, 2026

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan

Section/Topic

Authentication precedence / which usage pool non-interactive (claude -p) execution consumes under subscription auth

Current Documentation

The authentication docs document the credential precedence order (gateway
session > API key > CLAUDE_CODE_OAUTH_TOKEN > subscription OAuth from
/login), and state that ANTHROPIC_API_KEY takes precedence over an active
subscription. They do not state which usage pool claude -p consumes from
when subscription auth is active.

Help Center article 15036540 carries a "June 15" update banner stating that
the Agent SDK credit change is paused, and that Agent SDK, claude -p, and
third-party app usage still draw from subscription usage limits. Directly
below the banner, the entire pre-June-15 article body is preserved and
labelled as no longer taking effect. The page's last-updated date is
June 16, 2026.

What's Wrong or Missing?

Two problems, one in each document.

1. The authentication docs are silent on billing routing.

They explain which credential wins, but not what that means for usage
accounting. A reader running scheduled or CI workloads on a subscription has
no in-docs answer to "does -p consume my subscription limits?" — the answer
currently lives only in a Help Center article that is itself in an ambiguous
state.

2. The Help Center banner has no effective date.

The banner says "for now, nothing has changed," but "now" is undated. The page
metadata shows June 16, 2026, so a reader in late July cannot tell whether the
status was re-confirmed or simply never revisited. A reader landing mid-page
also sees the superseded body describing the credit pool as active.

This is producing measurable downstream errors.

Multiple third-party articles now carry update banners claiming the change
took effect on July 10, 2026. None cite a primary source. One of them lists
Zed's blog post in its sources while contradicting it — Zed's post was updated
June 16 to state the change is not in effect. These articles rank well in
search and are being ingested as reference material.

The practical consequence is not cosmetic. Readers are making architecture and
cost decisions (subscription auth vs. API key for scheduled agents, CI, and
GitHub Actions) based on contradictory information about which pool their
usage lands in.

Suggested Improvement

For the authentication docs, add a short subsection under the precedence
list, for example:

### Which usage pool applies Billing routing follows the authentication method, not the execution mode. When authenticated with a Pro, Max, Team, or Enterprise subscription — including via CLAUDE_CODE_OAUTH_TOKEN — both interactive sessions and non-interactive claude -p runs draw from your subscription's usage limits. When ANTHROPIC_API_KEY is set, both route to API pay-as-you-go billing instead. Run /status to confirm which method is active.

For the Help Center banner, add an effective date and a link anchor, for
example:

Current as of <date>. We're pausing the changes described below. […]

Even without re-confirming the status on a schedule, a single dated line makes
the page citable and removes the ambiguity that secondary sources are
currently filling in incorrectly.

Optionally, collapse or move the superseded body behind a disclosure element
so readers landing mid-page don't encounter it as current guidance.

Impact

High - Prevents users from using a feature

Additional Context

Verified as of 2026-07-27, from a Claude Max subscription:

Help Center 15036540, EN and JA: pause banner present, last updated

June 16, 2026. No revised plan announced.

Claude Apps release notes (July 9, 10, 14, 24): no Agent SDK billing entry.
Claude Platform release notes (June 25, 26, July 17, 22): no such entry.
Zed's blog post on the change, updated June 16: states it is not in effect.
Local environment: Claude Code 2.1.220, subscription auth, no

ANTHROPIC_API_KEY set. /status shows no API key row. The Usage tab shows
session and weekly pools only, with no Agent SDK credit pool. Usage credits
are off, and scheduled claude -p jobs continue to run — which is only
consistent with subscription-pool consumption.

Related docs:

View original on GitHub ↗