fix(anthropic): never refresh an API-key session into Claude Code OAuth credentials (#75641)

[kyssta-exe]

Summary

Fixes #75641: Anthropic API-key requests fail with a 429 and then a confusing OAuth "extra usage" 400 on retry.

Root cause

AIAgent._try_refresh_anthropic_client_credentials() runs before every request-client build — including the retry after a transient 429 — and calls resolve_anthropic_token(). That resolver prioritizes:

1. ANTHROPIC_TOKEN env
2. CLAUDE_CODE_OAUTH_TOKEN env
3. Claude Code credentials (~/.claude.json / ~/.claude/.credentials.json) ← wins when present
4. credential-pool OAuth entry
5. ANTHROPIC_API_KEY env

When the user explicitly selected a Console API key (the only credential in hermes auth list), but Claude Code's credential files still exist on disk (as in the report: "Claude Code's own credential files were not deleted"), the refresh swapped the API key for the Claude Code OAuth token, rebuilt the client, and the retry went out under OAuth billing — producing the 400 "Third-party apps now draw from your extra usage" error.

Fix

A plain Console API key (sk-ant-api…) never expires, so there is nothing to refresh for an API-key session. _try_refresh_anthropic_client_credentials() now returns False immediately unless the current credential is OAuth/setup-token shaped (_is_oauth_token). OAuth/setup-token sessions keep the existing refresh behavior (including the token-type-change flag updates).

Tests

• tests/run_agent/test_run_agent.py::TestOAuthFlagAfterCredentialRefresh — rewrote test_oauth_flag_updates_api_key_to_oauth to assert the corrected behavior (API-key session is preserved; no OAuth swap, flag stays False).
• test_run_agent.py refresh/oauth selection + test_anthropic_third_party_oauth_guard.py + test_anthropic_response_header_capture.py: 227 passed.

[teknium1]

Thanks for the focused fix. The current-main path confirms the reported credential-identity swap: run_agent.py:4883 invokes the refresh before each request-local Anthropic client, and run_agent.py:5194 unconditionally resolves a replacement token. The resolver gives Claude Code credential files precedence over ANTHROPIC_API_KEY in agent/anthropic_adapter.py:1345-1390.

The change in b64ca2f0ef38 uses the existing classifier, whose sk-ant-api exclusion and OAuth token recognition are defined in agent/anthropic_adapter.py:395-420. It therefore preserves OAuth refresh behavior while preventing Console API-key sessions from silently switching billing identity. The updated regression test complements the existing OAuth refresh coverage at tests/run_agent/test_run_agent.py:4884-4919.

Automated hermes-sweeper review.

[GottZ]

This was generated by AI during triage.

Summary

Twenty-two PRs address or reference this issue complex, spanning billing-error classification, Anthropic endpoint and credential selection, OAuth tool-name and system-prompt fingerprints, billing attribution, auxiliary refresh, and the API-key-to-OAuth retry identity switch isolated in #75641. The diffs therefore cover several distinct causes that produce the same 400/429 family rather than one interchangeable fix.

Related pull requests

• [codex] Clarify Anthropic extra-usage exhaustion errors #6498 [closed] best fix — (+130/-9) — best existing diagnostic fix for Anthropic Claude subscription auth returns 'You're out of extra usage' in Hermes even after restart/re-login #6475 and [Bug]: claude /login become API Error: HTTP 400 #65078: it classifies the extra-usage 400 and adds actionable fallback guidance without changing request routing, and remains relevant as a closed reference because that behavior was implemented on main through fix(classifier): treat Anthropic "out of extra usage" 400 as billing #56128.
• fix: Anthropic OAuth sends empty X-Api-Key, misclassifies billing error #6854 [closed] best fix — (+28/-13) — best existing fix for the empty-header/classification facet associated with OAuth (Claude Pro/Max): exposing memory or session_search tool schema deterministically triggers HTTP 400 "You're out of extra usage" #65365: it prevents an empty X-Api-Key beside Bearer auth and renames selected prompt terms, but its mixed beta and prompt changes do not isolate the full classifier trigger, so the closed diff remains supporting evidence rather than the current focused solution.
• fix(anthropic): sanitize oauth system prompt for Claude Max proxy #10576 [closed] best fix — (+43/-6) — best existing sanitizer fix for [Bug] Anthropic OAuth/Claude Max proxy path can misclassify full Hermes system prompt as extra-usage exhausted #10575, Anthropic Claude Code OAuth still appears to consume extra usage credits after June 16 policy rollback email #47260, OAuth (Claude Pro/Max): exposing memory or session_search tool schema deterministically triggers HTTP 400 "You're out of extra usage" #65365, and Anthropic OAuth (Claude Pro/Max subscription) hits "You're out of extra usage" on every real request — routes through pay-per-token endpoint instead of subscription quota #65564: it rewrites OAuth system-prompt trigger terms and had local end-to-end success, but it remains closed because the blocking maintainer decision rejected an open-ended classifier-evasion scrubber, so reopening it is not recommended.
• fix(anthropic): use Claude Code-compatible MCP tool prefix for OAuth #17681 [closed] best fix — (+52/-16) — best existing prefix fix for OAuth Anthropic + Pro/Max plan: mcp_ tool-name prefix triggers "out of extra usage" 400 on every tool-bearing request #28849 and Max OAuth requests rejected as third-party (HTTP 400 "extra usage") due to single-underscore mcp_ tool-name prefix #46675: it changes OAuth tool names from mcp_ to mcp__ and restores canonical names on responses, remaining relevant after closure because commit b70a4e7 implemented the broader round-trip on main.
• fix(auth): stop treating CLAUDE_CODE_OAUTH_TOKEN as Anthropic API key #19260 [closed] related — (+3/-3) — rejected credential-removal approach: it avoids the OAuth failures by disabling CLAUDE_CODE_OAUTH_TOKEN discovery rather than fixing the request, and remains relevant because the blocking maintainer response confirms that OAuth discovery is intentional.
• fix(anthropic): classify OAuth tool-use overage failures #21019 [closed] best fix — (+96/-1) — best existing recovery fix for [Bug]: On a Claude Max 20x subscription with a valid OAuth access token from ~/.claude/.credentials.json, every Hermes request to native Anthropic (provider: anthropic, https://api.anthropic.com/v1/messages) is rejected with HTTP 400 #15080, Error code: 400 | "You're out of extra usage. Add more at claude.ai/settings/usage and keep going." #20732, [Bug]: Hermes does not work through Claude CLI #29125, [Bug]: Hermes w/ Anthropic models ratelimit/extra usage #31668, [Setup]: Problem at 0Auth #37363, and [Bug]: claude /login become API Error: HTTP 400 #65078: it distinguishes tool-bearing OAuth overage failures and activates fallback guidance, while the closed diff remains relevant because ea9e8d6 and e00800f implemented that behavior on main.
• fix(anthropic): work around OAuth third-party billing-lane classifier (#15080) #24250 best fix — (+1002/-26) — best existing broad compatibility experiment for [Bug]: On a Claude Max 20x subscription with a valid OAuth access token from ~/.claude/.credentials.json, every Hermes request to native Anthropic (provider: anthropic, https://api.anthropic.com/v1/messages) is rejected with HTTP 400 #15080: despite its keep_open review, the diff replaces the system prompt during a live turn and marks confirmed extra-usage errors retryable, so it should stay open only if narrowed to a prompt-preserving, independently evidenced compatibility change.
• feat(agent): add ClaudeLocalClient subprocess shim for Claude Max OAuth accounts #26960 [closed] related — (+230/-0) — superseded subprocess prototype: it bypasses the native OAuth classifier through the official claude binary but lacks completed end-to-end tool verification and was closed in favor of the more integrated feat(providers): add Claude CLI subprocess transport #6427 and feat(providers): claude-code-acp — run Hermes on a Claude subscription, plus ACP timeout fixes #12229 approaches.
• fix(anthropic): remove mcp_ tool prefix on OAuth path that triggers overage gate #28872 [closed] best fix — (+115/-18) — best existing fix for OAuth Anthropic + Pro/Max plan: mcp_ tool-name prefix triggers "out of extra usage" 400 on every tool-bearing request #28849 at its proposal stage: despite the earlier keep_open review, its diff removes the OAuth MCP prefix wholesale, while the contributor closure records that fix(anthropic): no single-underscore mcp_ tool names on the OAuth wire (plan-limit billing) #47723 preserved tool access through mcp__ normalization and superseded this implementation.
• fix(provider): route OAuth Pro/Max credentials to /v1/messages (#32243) #32318 [closed] best fix — (+267/-5) — best existing fix for [Bug]: OAuth Pro/Max credential returns "out of extra usage" 400 immediately after fresh login, despite empty/unused account quota #32243 and [Setup]: Hermes Model - Anthropic Claude Pro - OAuth wrong routing #33192: it pins api.anthropic.com to anthropic_messages instead of the OpenAI-compatible shim, and remains relevant after closure because its commits were incorporated on main through fix(provider): route api.anthropic.com to anthropic_messages (#32243) #56214 with the sibling fallback path covered.
• fix: classify Anthropic subscription_exhausted (HTTP 400 "out of extra usage") with actionable error message #40020 [closed] best fix — (+278/-9) — best existing mixed proposal for [Bug]: Hermes does not work through Claude CLI #29125, [Bug]: Hermes w/ Anthropic models ratelimit/extra usage #31668, and Claude Code OAuth (Max/Pro plan) still hits pay-per-token API endpoint — drains 'extra usage' credits instead of using subscription quota #40014: it combines valid billing classification with an incomplete claude-code subprocess provider, so its closed status remains relevant as the reason the work was split into focused fixes.
• fix: classify Anthropic subscription_exhausted (HTTP 400 "out of extra usage") correctly #40073 [closed] best fix — (+27/-2) — best existing focused recovery fix for [Bug]: Hermes does not work through Claude CLI #29125, [Bug]: Hermes w/ Anthropic models ratelimit/extra usage #31668, [Setup]: Problem at 0Auth #37363, Claude Code OAuth (Max/Pro plan) still hits pay-per-token API endpoint — drains 'extra usage' credits instead of using subscription quota #40014, and [Bug]: claude /login become API Error: HTTP 400 #65078: it classifies the 400 as non-retryable billing and enables credential rotation, remaining relevant because the equivalent behavior landed on main in ea9e8d6.
• fix(anthropic): use double-underscore mcp__ prefix for OAuth tool names #46687 [closed] best fix — (+49/-30) — best existing mcp__ fix for OAuth Anthropic + Pro/Max plan: mcp_ tool-name prefix triggers "out of extra usage" 400 on every tool-bearing request #28849 and Max OAuth requests rejected as third-party (HTTP 400 "extra usage") due to single-underscore mcp_ tool-name prefix #46675: it symmetrically corrects outgoing and response names, but remains closed because fix(anthropic): no single-underscore mcp_ tool names on the OAuth wire (plan-limit billing) #47723 cherry-picked it and added normalization for legacy MCP-server names.
• fix(agent): send Claude Code billing-attribution system block on OAuth requests #48177 [closed] best fix — (+88/-4) — best existing billing-marker fix for [Bug]: OAuth Pro/Max/Team requests rejected with HTTP 400 "third-party / extra usage" (missing x-anthropic-billing-header system block) #48176: it prepends x-anthropic-billing-header with cc_entrypoint=sdk-cli and has a focused A/B mechanism, but the blocking maintainer policy decision rejected presenting Hermes as the first-party SDK surface, so reopening it is not recommended.
• fix(anthropic): add billing header for OAuth plan-tier routing (#48176) #48202 [closed] fixes — (+20/-7) — duplicate of fix(agent): send Claude Code billing-attribution system block on OAuth requests #48177, closed: it adds the same billing-attribution system block with less coverage, and the non-contributor approval does not outweigh the contributor duplicate finding and blocking policy decision.
• fix(anthropic): add OAuth plan billing marker #69844 best fix — (+62/-4) — best existing billing-marker fix for Claude Code OAuth (Max/Pro plan) still hits pay-per-token API endpoint — drains 'extra usage' credits instead of using subscription quota #40014, [Bug]: OAuth Pro/Max/Team requests rejected with HTTP 400 "third-party / extra usage" (missing x-anthropic-billing-header system block) #48176, and [Bug]: claude /login become API Error: HTTP 400 #65078: its keep_open review and exact-path A/B support the focused diff, but the unresolved earlier maintainer objection to cc_entrypoint=sdk-cli attribution must be addressed before it can progress.
• fix(agent): strip x-stainless headers from OAuth Anthropic requests to prevent 429 #70054 [closed] best fix — (+120/-0) — best existing proposal for Anthropic subscription OAuth token gets generic 429 through Hermes, while the genuine Claude Code binary works with the same token #70039's header-fingerprint hypothesis: it strips x-stainless-* headers, but remains closed because its tests verify header removal rather than a successful live 429 recovery and the automated close verdict found no established resolution.
• fix(anthropic): keep OAuth requests on included subscription billing #72173 best fix — (+322/-0) — best existing fix for Anthropic Claude Code OAuth still appears to consume extra usage credits after June 16 policy rollback email #47260, Claude Code / subscription OAuth requests are billed as overage (HTTP 429 "monthly spend limit") — root cause: the agent system prompt trips Anthropic's subscription billing classifier #53212, Anthropic OAuth (Claude Pro/Max subscription) hits "You're out of extra usage" on every real request — routes through pay-per-token endpoint instead of subscription quota #65564, and Anthropic OAuth: system-prompt shape routes subscription requests into the metered "extra usage" lane (root cause + bisection for #65564) #72171: it directly limits the bisected OAuth system-prompt content, but its keep_open review requires replacing destructive truncation with prompt-preserving relocation and testing the cache-decorated production shape plus breakpoint limits.
• fix(aux): discard stale credentials after auth refresh #72263 related — (+255/-3) — adjacent stale-credential fix: it clears rejected request-scoped keys before auxiliary retries but does not affect billing classification, and its keep_open review supports salvage only after making the reset provider-neutral and retaining sync and async regression coverage.
• fix(anthropic): never refresh an API-key session into Claude Code OAuth credentials (#75641) #75697 best fix — (+24/-3) — best existing fix for [Bug]: Anthropic API-key request returns 429, then retry produces OAuth extra-usage 400 #75641: it uses the existing OAuth-token classifier to prevent a Console API-key session from refreshing into discovered Claude Code credentials after a 429, exactly matching the credential-identity swap confirmed by the keep_open review.
• fix(anthropic): alias session search on OAuth wire #76669 [closed] best fix — (+97/-12) — best existing initial fix for OAuth (Claude Pro/Max): exposing memory or session_search tool schema deterministically triggers HTTP 400 "You're out of extra usage" #65365, closed after salvage: it aliases session_search on the OAuth wire and reverses it before dispatch, while fix(anthropic): alias the session_search and memory schemas on the OAuth wire #76807 carries the commit with attribution and extends the diff to memory and collision handling; the named tool_choice review finding still warrants explicit verification.
• fix(anthropic): alias the session_search and memory schemas on the OAuth wire #76807 best fix — (+319/-7) — best existing expanded fix for OAuth (Claude Pro/Max): exposing memory or session_search tool schema deterministically triggers HTTP 400 "You're out of extra usage" #65365: it aliases session_search and memory only on the OAuth wire, preserves API-key behavior, handles alias collisions and registry precedence, and round-trips responses, with named OAuth tool_choice consistency the remaining focused check.

Duplicates

#6498, #21019, #40020, and #40073 overlap on billing classification and guidance; #17681, #28872, and #46687 cover the MCP-prefix cluster with different strategies; #48177, #48202, and #69844 implement the same billing-marker mechanism; and #76669 is the direct predecessor salvaged into #76807.

Suggested consolidation

Keep #75697 open with a salvage path: retain its narrow _is_oauth_token guard and regression proving that retries preserve the explicitly selected Console API key, since it is the best existing fix for #75641 and agrees with the visible keep_open review. Treat #76807 as the separate best fix for #65365 pending named tool_choice verification, keep #69844, #72173, and #72263 constrained by their stated review conditions, and do not reopen the policy-blocked #10576, #48177, or #48202.

Complex graph

flowchart LR
    classDef open fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a
    classDef merged fill:#dcfce7,stroke:#15803d,color:#14532d
    classDef closed fill:#e5e7eb,stroke:#6b7280,color:#1f2937
    classDef unverified fill:#f3f4f6,stroke:#9ca3af,color:#374151
    classDef best stroke-width:3px,stroke:#b45309
    classDef target stroke-width:3px,stroke:#4338ca
    I75641(["issue #75641 (open)"])
    P75697["PR #75697 (open)"]
    P75697 -->|best fix| I75641
    class I75641 open
    class P75697 open
    class P75697 best
    class P75697 target
    click I75641 "https://github.com/NousResearch/hermes-agent/issues/75641"
    click P75697 "https://github.com/NousResearch/hermes-agent/pull/75697"

Loading

Graph: solid arrow = fixes / best fix, dashed arrow = partial or unverified (see edge label); boxed group = PRs duplicating each other; amber border = best fix; indigo border = target; gray node = closed (state tag in the node label).

Cross-PR triage: Reviewed 22 pull requests and 22 issues in this complex. Each diff was read against this issue; Assessment working set: 244 kB of PR diffs, 253 kB of issue/PR text, 82 kB of discussion (169 comments), 110 verify verdicts. verdicts reflect diff content, not PR titles. Part of an automated triage batch.