fix(anthropic): keep OAuth requests on included subscription billing

[mguttmann]

Fixes #72171
Addresses #65564

Problem

Anthropic's OAuth billing classifier inspects the request payload and decides from its shape which billing lane applies. Hermes already handles two facets of this in build_anthropic_kwargs():

• step 1 — prepend the Claude Code identity block

• step 3 — normalize mcp_ → mcp__ tool names, with this comment already in the tree:

  […] treats a single-underscore mcp_ tool name as a third-party-app fingerprint and rejects the request with HTTP 400 "Third-party apps now draw from extra usage, not plan limits" (verified empirically […])

The system prompt body is the unguarded third facet. Everything Hermes injects (skill_manage, session_search, Computer Use guidance, delegation rules, mid-turn steering, …) goes out verbatim — 17,000+ chars on a real deployment. The classifier fingerprints that as raw API usage and routes the request to the pay-per-token "extra usage" pool instead of the subscription's included quota, so users see:

HTTP 400  You're out of extra usage. Add more at claude.ai/settings/usage
HTTP 429  monthly spend limit

…while claude.ai shows the subscription barely used. Full analysis, bisection table and impact assessment in #72171.

Key evidence — same length, opposite outcome:

System prompt	Length	Result
identity + generic filler	~17,000	✅ subscription
identity + real Hermes instructions	~17,000	❌ 400 out of extra usage
identity + Hermes instructions, trimmed	~3,000	✅ subscription

Not a token-count limit — content fingerprinting.

Change

Extends the existing "make the OAuth payload Claude-Code-shaped" logic to the system prompt body: cap the Hermes-specific portion; the Claude Code identity block (index 0) is never touched.

providers:
  anthropic:
    oauth_system_budget_chars: 3000   # 0 disables

Two files, +320 lines, no deletions:

• agent/anthropic_adapter.py — _resolve_oauth_system_budget() + step 2b in build_anthropic_kwargs()
• tests/agent/test_anthropic_oauth_system_budget.py — new suite

Design notes

• config.yaml, not an env var. This is behavioral configuration; per AGENTS.md .env is for secrets only. My earlier attempt (fix(anthropic): keep subscription OAuth requests on included billing + auxiliary OAuth fallback #53213) was correctly closed for introducing HERMES_OAUTH_SYSTEM_BUDGET — this follows the documented path via load_config_readonly() (the same read-only fast path get_provider_request_timeout uses, so no per-turn cost).
• Opt-out preserved. oauth_system_budget_chars: 0 restores current behavior byte for byte.
• API-key requests untouched. They bill per token and legitimately keep the full prompt — covered by a test.
• Prompt caching preserved. A trimmed-to-empty block must not stay on the wire: Anthropic rejects empty text blocks, and an empty block carrying cache_control is always invalid (cache_control cannot be set for empty text blocks). If a dropped block held the cache marker it migrates to the last surviving text block — otherwise every request would silently lose its cached prefix. Two dedicated tests guard this.
• Cut on a line boundary (rfind("\n") before the budget, hard cut only if that would drop more than half), so instructions are not truncated mid-sentence.
• Never raises. A malformed or unreadable config falls back to the default rather than breaking request building.

Testing

tests/agent/test_anthropic_oauth_system_budget.py ..............  14 passed

• 14/14 pass with the fix; 7 fail without it (assert 16800 <= 3000 — verified by stashing the adapter change and re-running, so the suite is not a no-op).
• Neighbouring suites — test_anthropic_adapter.py, test_anthropic_mcp_prefix_strip.py, test_auxiliary_client.py: 572 passed.
• 3 pre-existing failures in TestRunOauthSetupToken are present identically on unmodified main (verified by stash/compare) and are unrelated to this change.

Coverage: config resolution (set / unset / zero / malformed / unreadable), trimming (long / short / custom budget / identity preserved / opt-out), wire safety (no empty block, no empty block with cache_control, line-boundary cut), and the non-OAuth path.

Scope / trade-off

This is a mitigation, not a cure. It trims instructions the agent would otherwise receive. The cure would be Anthropic classifying subscription clients by credential rather than payload shape, or a first-class subscription-OAuth provider (#25267). Until then the practical choice is a slightly shorter system prompt versus an agent that does not work at all on a subscription. In production here (long-running helpdesk deployment) a 3,000-char cap produced no observable behavior regression while the 400/429 failures stopped entirely.

A strictly better follow-up, deliberately not in this PR: relocate the Hermes-specific instructions out of the system prompt into the first user message or a tool result, where the classifier does not appear to look — preserving the full instruction set. Larger change, separate discussion.

Also worth a separate look: website/docs/integrations/providers.md:112-115 currently documents Anthropic OAuth as requiring Max extra-usage credits. Per the bisection in #72171 that describes this bug's symptom rather than an Anthropic policy — happy to send a docs PR if maintainers agree with the diagnosis.

Happy to iterate on the shape of the mitigation, including dropping truncation entirely in favour of relocation, if you prefer a different direction.

[alt-glitch]

This was generated by AI during triage.

Related to #68839: both address Anthropic OAuth subscription billing classification, but this patch caps Hermes-specific system text while #68839 relocates the full prompt to the first user message. Maintainer selection is needed; neither is marked duplicate.

[teknium1]

Thanks for isolating the OAuth request-shape path. Current main still places the full extracted system prompt beside the Claude Code identity block on OAuth requests (agent/anthropic_adapter.py:2761-2769), so the targeted payload shape remains present.

Problems

• The new default budget removes all instruction text after the retained prefix. That changes agent behavior for every OAuth user with a system prompt over 3,000 characters, rather than preserving the prompt. The distinct relocation implementation in ab7b4edcc6 keeps the complete prompt while moving it out of system[].
• The added tests do not cover the production cache-decorated system shape. apply_anthropic_cache_control() creates two cache-marked system text blocks when a stable prefix is available (agent/prompt_caching.py:100-116), but the PR helper supplies only a string system prompt. The cache-marker migration and breakpoint-cap claims therefore remain untested.

Suggested changes

• Re-scope to a prompt-preserving relocation strategy, or demonstrate why truncation is preferable.
• Add an end-to-end adapter test through apply_anthropic_cache_control() and assert valid blocks and the four-breakpoint limit.

Automated hermes-sweeper review.

[GottZ]

This was generated by AI during triage.

Summary

Twenty-two PRs address or reference this Anthropic OAuth extra-usage complex, spanning error classification, endpoint and credential routing, MCP normalization, billing attribution, subprocess transports, system-prompt fingerprints, and retry identity. For #72173, the cause-matched diff caps the bisected OAuth system-prompt content, while narrower aliases preserve more prompt semantics and the remaining PRs address separate causes or recovery layers.

Related pull requests

• [codex] Clarify Anthropic extra-usage exhaustion errors #6498 [closed] best fix — (+130/-9) — n/a: Classifies the Anthropic extra-usage 400 and adds fallback guidance without changing request shape; closed but relevant because equivalent handling later landed 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) — n/a: Combines empty X-Api-Key prevention, billing classification, beta changes, and prompt-term substitutions; closed but relevant as a mixed precursor to the prompt-fingerprint fixes.
• fix(anthropic): sanitize oauth system prompt for Claude Max proxy #10576 [closed] best fix — (+43/-6) — n/a: Sanitizes OAuth system text containing session_search, skill_manage, and related phrases, directly matching the prompt-sensitive cause; closed because the contributor decision rejected maintaining this classifier-evasion scrubber upstream.
• fix(anthropic): use Claude Code-compatible MCP tool prefix for OAuth #17681 [closed] best fix — (+52/-16) — n/a: Changes OAuth tool names from mcp_ to mcp__ and restores canonical response names; closed as implemented more broadly on main by b70a4e7.
• fix(auth): stop treating CLAUDE_CODE_OAUTH_TOKEN as Anthropic API key #19260 [closed] related — (+3/-3) — n/a: Removes Claude Code OAuth credential discovery instead of correcting the failing request shape; closed after the contributor documented that this credential source is intentional.
• fix(anthropic): classify OAuth tool-use overage failures #21019 [closed] best fix — (+96/-1) — n/a: Classifies tool-bearing OAuth extra-usage failures for immediate fallback and guidance without changing the triggering payload; closed as implemented on main by ea9e8d6 and e00800f.
• fix(anthropic): work around OAuth third-party billing-lane classifier (#15080) #24250 best fix — (+1002/-26) — n/a: Broadly renames tools and can replace the live system prompt with FULL_STEALTH; consistent with its keep_open review, salvage requires a narrow prompt-preserving change because the current diff violates byte-stable caching and retries billing exhaustion.
• feat(agent): add ClaudeLocalClient subprocess shim for Claude Max OAuth accounts #26960 [closed] related — (+230/-0) — n/a: Adds an isolated Claude CLI subprocess shim that bypasses the native OAuth request but lacks completed provider integration and tool verification; closed as overlapping 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.
• fix(anthropic): remove mcp_ tool prefix on OAuth path that triggers overage gate #28872 [closed] best fix — (+115/-18) — n/a: Removes OAuth MCP prefixing wholesale; despite its earlier keep_open review, it was closed in favor of fix(anthropic): no single-underscore mcp_ tool names on the OAuth wire (plan-limit billing) #47723, which preserves tool access through symmetric mcp__ normalization.
• fix(provider): route OAuth Pro/Max credentials to /v1/messages (#32243) #32318 [closed] best fix — (+267/-5) — n/a: Pins api.anthropic.com to native anthropic_messages across runtime paths, fixing a distinct endpoint-routing cause; closed after its commits were incorporated through fix(provider): route api.anthropic.com to anthropic_messages (#32243) #56214.
• fix: classify Anthropic subscription_exhausted (HTTP 400 "out of extra usage") with actionable error message #40020 [closed] best fix — (+278/-9) — n/a: Bundles useful billing classification with an incomplete Claude CLI subprocess provider, improving diagnosis or bypassing native OAuth rather than fixing the prompt fingerprint; closed so the unrelated scopes could be split.
• fix: classify Anthropic subscription_exhausted (HTTP 400 "out of extra usage") correctly #40073 [closed] best fix — (+27/-2) — n/a: Maps the 400 to non-retryable billing recovery, credential rotation, fallback, and guidance; closed because equivalent behavior landed through fix(classifier): treat Anthropic "out of extra usage" 400 as billing #56128 using the existing billing reason.
• fix(anthropic): use double-underscore mcp__ prefix for OAuth tool names #46687 [closed] best fix — (+49/-30) — n/a: Implements symmetric mcp_ to mcp__ request and response normalization but leaves a legacy MCP-server gap; closed after fix(anthropic): no single-underscore mcp_ tool names on the OAuth wire (plan-limit billing) #47723 cherry-picked and extended it with authorship preserved.
• fix(agent): send Claude Code billing-attribution system block on OAuth requests #48177 [closed] best fix — (+88/-4) — n/a: Prepends x-anthropic-billing-header with cc_entrypoint=sdk-cli to obtain plan routing; closed under the blocking contributor decision against first-party identity spoofing and its account-suspension risk.
• fix(anthropic): add billing header for OAuth plan-tier routing (#48176) #48202 [closed] fixes — (+20/-7) — n/a: Implements the same billing-attribution block as fix(agent): send Claude Code billing-attribution system block on OAuth requests #48177 with less coverage; closed as its duplicate, and the non-contributor approval does not outweigh the blocking contributor policy decision.
• fix(anthropic): add OAuth plan billing marker #69844 best fix — (+62/-4) — n/a: Adds the same OAuth billing marker as fix(agent): send Claude Code billing-attribution system block on OAuth requests #48177/fix(anthropic): add billing header for OAuth plan-tier routing (#48176) #48202 and has a current-main exact-path A/B; consistent with its keep_open review, it still requires explicit resolution of the earlier contributor policy block.
• fix(agent): strip x-stainless headers from OAuth Anthropic requests to prevent 429 #70054 [closed] best fix — (+120/-0) — n/a: Strips x-stainless SDK headers to test a client-fingerprint hypothesis, but its tests prove only header removal; closed because the issue verdict found no evidence that the diff resolves the reported 429.
• fix(anthropic): keep OAuth requests on included subscription billing #72173 best fix — (+322/-0) — n/a: Caps the OAuth system prompt at 3,000 characters, directly targeting the bisected content trigger but discarding remaining instructions; consistent with its keep_open review, salvage requires prompt-preserving relocation and production cache-block coverage.
• fix(aux): discard stale credentials after auth refresh #72263 [closed] related — (+255/-3) — n/a: Clears stale request-scoped credentials after auxiliary refresh, addressing a separate retry defect; despite its keep_open review it is now closed and remains relevant as the narrower overlap with provider-neutral fix(auxiliary): discard stale credentials after auth refresh #62008.
• fix(anthropic): never refresh an API-key session into Claude Code OAuth credentials (#75641) #75697 best fix — (+24/-3) — n/a: Prevents an explicitly selected Console API-key session from refreshing into discovered Claude Code OAuth credentials after a 429; its keep_open review confirms this distinct credential-identity swap on current main.
• fix(anthropic): alias session search on OAuth wire #76669 [closed] best fix — (+97/-12) — n/a: Aliases session_search on the OAuth wire and reverses it before dispatch; despite its keep_open review it was closed after its commit was salvaged with attribution into fix(anthropic): alias the session_search and memory schemas on the OAuth wire #76807, which extends the scope.
• fix(anthropic): alias the session_search and memory schemas on the OAuth wire #76807 best fix — (+319/-7) — n/a: Extends fix(anthropic): alias session search on OAuth wire #76669 with OAuth-only session_search and memory aliases, collision handling, prose-boundary protection, and canonical response dispatch, while named OAuth tool_choice parity remains absent from the shown diff.

Duplicates

#6498, #21019, #40020, and #40073 overlap on extra-usage classification and guidance now implemented through #56128; #17681, #28872, and #46687 form the MCP-prefix chain superseded by #47723; #48177, #48202, and #69844 share the billing-marker mechanism; #76669 was salvaged into and superseded by #76807; #72263 overlaps provider-neutral #62008.

Suggested consolidation

Keep #72173 open with a salvage path: replace default prompt truncation with the prompt-preserving relocation identified by its keep_open review, then add an end-to-end test through apply_anthropic_cache_control() covering the production two-block shape, cache-marker migration, and four-breakpoint limit. Keep the closed sanitizer #10576 closed under its contributor policy block, keep #76807 separate as the narrower alias approach, and do not consolidate the policy-blocked billing-marker chain #48177/#48202/#69844 into #72173.

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
    I47260(["issue #47260 (open)"])
    I53212(["issue #53212 (closed)"])
    I65365(["issue #65365 (open)"])
    I65564(["issue #65564 (open)"])
    I72171(["issue #72171 (open)"])
    P72173["PR #72173 (open)"]
    P72173 -->|best fix| I47260
    P72173 -->|best fix| I53212
    P72173 -.->|partial| I65365
    P72173 -->|best fix| I65564
    P72173 -->|best fix| I72171
    class I47260 open
    class I53212 closed
    class I65365 open
    class I65564 open
    class I72171 open
    class P72173 open
    class P72173 best
    class P72173 best
    class P72173 best
    class P72173 best
    class P72173 target
    click I47260 "https://github.com/NousResearch/hermes-agent/issues/47260"
    click I53212 "https://github.com/NousResearch/hermes-agent/issues/53212"
    click I65365 "https://github.com/NousResearch/hermes-agent/issues/65365"
    click I65564 "https://github.com/NousResearch/hermes-agent/issues/65564"
    click I72171 "https://github.com/NousResearch/hermes-agent/issues/72171"
    click P72173 "https://github.com/NousResearch/hermes-agent/pull/72173"

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, 86 kB of discussion (170 comments), 112 verify verdicts. verdicts reflect diff content, not PR titles. Part of an automated triage batch.