[BUG] --max-budget-usd stops Max subscription run despite zero API cost and remaining quota
Description
claude -p terminates a Claude.ai Max subscription-backed run with:
Error: Exceeded USD budget (1)
when --max-budget-usd 1.00 is supplied, even though the CLI is authenticated through the Claude.ai subscription, no API credential/provider override is present, the Usage screen reports Total cost: $0.0000, and substantial model quota remains.
The flag is described by claude --help as:
--max-budget-usd <amount> Maximum dollar amount to spend on API calls (only works with --print)
For subscription-backed usage, no dollar amount was spent on API calls. The observed behavior appears to enforce an undisclosed estimated API-equivalent cost instead.
Steps to reproduce
- Sign in to Claude Code using a Claude.ai Max subscription (not an API key).
- Confirm
claude auth status --jsonreportsauthMethod: "claude.ai",subscriptionType: "max", andapiProvider: "firstParty". - Confirm no
ANTHROPIC_API_KEY,ANTHROPIC_AUTH_TOKEN, Bedrock, Vertex, or Foundry override is present. - Run a sufficiently involved print-mode task:
claude -p --model fable --effort high \
--permission-mode dontAsk \
--no-session-persistence \
--max-budget-usd 1.00 \
"Review a non-trivial repository change and return concise findings."
- Observe
Error: Exceeded USD budget (1). - Open
/usage; observeTotal cost: $0.0000and remaining subscription quota.
Expected behavior
One of:
- For Claude.ai subscription authentication,
--max-budget-usdlimits only actual paid API/extra-usage spend and does not terminate included subscription usage. - If the intended behavior is to cap estimated dollar-equivalent model consumption regardless of billing source, rename/reword the flag and error so it does not claim an API dollar budget was exceeded.
- At minimum, make the error distinguish actual billed spend from an estimated-equivalent safety threshold.
Actual behavior
The command terminates at an internal dollar-equivalent threshold while the product simultaneously reports zero API cost and available subscription usage. This makes automation incorrectly conclude that the user's paid subscription capacity is exhausted.
Environment
- Claude Code: 2.1.221
- Authentication: Claude.ai OAuth
- Subscription: Max
- API provider: firstParty
- API key/auth-token/cloud-provider overrides: absent
- OS: macOS
- Shell: zsh
- Invocation mode:
--print - Model: Fable
This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗