Claude Code OAuth (Max/Pro plan) still hits pay-per-token API endpoint — drains 'extra usage' credits instead of using subscription quota

[harsh-matchmyflight]

Problem

When using Claude Code OAuth credentials (sk-ant-oat01-...) with a Claude Max plan subscription, Hermes still routes API calls through https://api.anthropic.com/v1/messages — the pay-per-token endpoint. This burns through the account's "extra usage" add-on credits rather than the included subscription quota.

Error received:
```
HTTP 400: You're out of extra usage. Add more at claude.ai/settings/usage and keep going.
```

This happens even though:

• hermes auth list correctly shows claude_code oauth as linked
• hermes model confirms "Claude Code credentials: ✓ (auto-detected)"
• The OAuth token was freshly generated via claude setup-token

Expected behaviour

A Claude Max plan subscriber using Claude Code OAuth should consume their included subscription quota, not pay-per-token API credits. The whole point of using OAuth (vs an ANTHROPIC_API_KEY) is to leverage the subscription.

Root cause (from code review)

agent/anthropic_adapter.py (lines 700–761) builds an Anthropic SDK client using the OAuth token but sends requests to the standard API endpoint — which treats all tokens as pay-per-token regardless of how they were obtained.

An unused helper already exists: run_oauth_setup_token() in anthropic_adapter.py:1146–1183 spawns the claude CLI subprocess to use Claude Code's credential store directly. This is the correct path for subscription-based auth but it isn't wired into the main request flow.

Proposed fix

In hermes_cli/runtime_provider.py (the credential resolution layer): when Claude Code credentials are detected, route inference through the claude CLI subprocess (same pattern as run_oauth_setup_token) instead of making direct SDK calls to api.anthropic.com. This way subscription quota is consumed, not API credits.

Environment

• Hermes Agent v0.15.1 (2026.5.29)
• macOS 15.x arm64
• Claude Max plan (monthly subscription)
• Model: claude-opus-4-8
• Auth method: claude_code oauth (via claude setup-token)

Workarounds (none clean)

• Switch to OpenRouter provider — bypasses the issue but loses native Anthropic routing
• Add Anthropic API key separately — defeats the purpose of having Max plan OAuth
• Wait for subscription quota reset — not viable for daily use

[harsh-matchmyflight]

Additional context after reviewing CONTRIBUTING.md:

This also qualifies as a robustness/graceful degradation issue (contribution priority #4). When a Max plan subscriber's included quota is consumed, Hermes silently falls through to the "extra usage" add-on tier instead of:

• Detecting that the credential type is claude_code oauth (subscription-backed)
• Warning the user that subscription quota is exhausted
• Suggesting the correct resolution (wait for reset vs add credits)

The current silent fallthrough to pay-per-token is a UX regression for any user who chose OAuth specifically to avoid per-token billing.

Happy to submit a PR for the runtime_provider.py fix if the maintainers confirm the intended behaviour.

[ahmadsadaqat]

yes same thing happening with me i have authenticated with Oauth but hermes agent is falling to API keys i have pro subscription but hermes is falling back to API key instead of Oauth

[xiaoyaner0201]

I did a pass over the recent Anthropic/Claude Code OAuth reports and related PRs. I think it may help to separate two failure classes that are currently getting mixed together:

1. OAuth login/token exchange is broken for some users

   • Tracked by Anthropic OAuth login (auth add anthropic --type oauth) fails with 404 — login flow uses stale token endpoint #45250.
   • Fixes: fix(auth): iterate token endpoints in Anthropic OAuth login flow #45254 / fix(anthropic): use platform.claude.com for OAuth token exchange #46251 / fix(anthropic): OAuth login token exchange falls back to platform.claude.com (console 404) #47333.
   • Root cause: initial authorization-code exchange still posts to the old console.anthropic.com/v1/oauth/token; refresh already tries platform.claude.com first. This is a login/setup issue.

2. OAuth succeeds, but requests are classified into the extra-usage / third-party billing lane

   • This issue, [Bug]: OAuth Pro/Max credential returns "out of extra usage" 400 immediately after fresh login, despite empty/unused account quota #32243, [Bug]: Hermes w/ Anthropic models ratelimit/extra usage #31668, Max OAuth requests rejected as third-party (HTTP 400 "extra usage") due to single-underscore mcp_ tool-name prefix #46675, and the June-16 rollback report Anthropic Claude Code OAuth still appears to consume extra usage credits after June 16 policy rollback email #47260 all look like this class.
   • The important signal from Max OAuth requests rejected as third-party (HTTP 400 "extra usage") due to single-underscore mcp_ tool-name prefix #46675 is the tool-bearing vs tool-less split: OAuth requests without tools can be plan-eligible, while tool-bearing Hermes turns hit HTTP 400 "Third-party apps now draw from your extra usage...".
   • In current origin/main, the OAuth path still rewrites all tool names to a single-underscore mcp_... shape in agent/anthropic_adapter.py, and also leaves concrete tool_choice names unencoded. That seems consistent with Anthropic's classifier treating the request as non-Claude-Code / third-party agent traffic rather than the intended Claude Code OAuth lane.

Among the open fixes, #23361 looks like the most complete request-shape fix to me because it covers more than just changing the prefix:

• changes the wire tool-name encoding to a Claude-Code-style mcp__... scheme;
• escapes embedded underscores (read_file -> mcp__read__file) so mcp_ substrings don't survive inside encoded tool names;
• keeps tool_choice aligned with the encoded tool schema names;
• updates response-side decoding / prefix stripping;
• keeps the changes gated to is_oauth=True so API-key and third-party Anthropic-compatible providers should not inherit the Claude Code prompt/tool-name vocabulary.

#46687 is a narrower version of the same direction (mcp_ -> mcp__) and #28872 takes the opposite approach of removing the prefix entirely. I would lean toward making one canonical fix rather than merging competing variants, and then validating with a small live matrix if possible:

• OAuth + no tools -> should remain plan/subscription lane.
• OAuth + a simple built-in tool -> should not hit extra usage.
• OAuth + a tool with embedded underscores, e.g. read_file / web_search -> should not contain any single-underscore mcp_ trigger in the outbound wire name.
• OAuth + concrete tool_choice -> tool_choice name should exactly match the advertised encoded tool name.
• API-key Anthropic path and third-party Anthropic-compatible endpoints -> unchanged request shape.

So my read is: the June 16 Anthropic email/policy rollback does not contradict the reports here. It means the intended Claude Code / Agent SDK lane should still be subscription-backed, but Hermes can still be misclassified into extra usage if its direct OAuth request shape differs from official Claude Code. That makes this a Hermes request-shape/routing bug, not simply an Anthropic quota exhaustion message.

[Fosol]

This issue is blocking me from using Hermes for orchestration. I have a Claude Max account, but Hermes is burning the API instead of the cli.