[Feature]: Claude Agent SDK model provider with subscription OAuth (Codex-style)

[YongboYu]

Problem or Use Case

I want to run Hermes with Claude as the model backend while staying on my Claude subscription, but the existing anthropic provider requires a Developer Platform API key and bills separately — so Claude-subscribed users effectively pay twice (subscription + per-token API).

Starting June 15, 2026, Anthropic decouples Agent SDK and claude -p usage from interactive subscription limits and introduces a separate monthly Agent SDK credit:

Plan	Monthly Agent SDK credit
Pro	$20
Max 5x	$100
Max 20x	$200
Team (Standard / Premium)	$20 / $100
Enterprise (usage-based / Premium seats)	$20 / $200

The credit explicitly covers "third-party apps that authenticate with your Claude subscription through the Agent SDK." Source: Anthropic Help Center.

Today there's no way to route Hermes into that credit — even Pro / Max subscribers must fund an API key on top of their plan. A Claude-subscription-OAuth provider would close the gap, the same way the existing Codex OAuth credential pool already does for OpenAI subscribers.

Proposed Solution

A new model-provider plugin that wraps the Claude Agent SDK with Claude subscription OAuth, mirroring the existing Codex OAuth path. Coexists with the current anthropic (API-key) provider rather than replacing it, so users on the Developer Platform are unaffected.

Plugin layout

• New plugin at plugins/model-providers/claude-agent-sdk/, wrapping claude-agent-sdk (Python) or @anthropic-ai/claude-agent-sdk (TypeScript).
• Either a new ClaudeAgentSdkTransport under agent/transports/, or extend the existing AnthropicTransport to swap auth header / endpoint by credential type — whichever fits the ProviderTransport ABC more cleanly.

Auth integration

• Detect Claude Code OAuth credentials at ~/.claude/, paralleling the existing ~/.codex/auth.json import path.
• Reuse the Codex credential-pool plumbing for refresh, rotation, and stale-token handling.

Config / UX

• New provider option (e.g. claude_subscription) selectable in hermes model, symmetric to the Codex subscription option.
• New env var, e.g. HERMES_CLAUDE_SUBSCRIPTION_AUTH=1, or auto-detect when ~/.claude/ credentials exist and no Anthropic API key is set.
• Surface a docs / UX warning when a subscription provider is selected for shared multi-user deployments — per Anthropic, the credit is "sized for individual experimentation"; production multi-tenant automation should still use API keys.

Open implementation questions

• The Agent SDK ships its own agent loop. Since Hermes is itself an agent, the cleanest integration is likely the SDK's lower-level / non-interactive surface rather than letting both loops fight for control of tool use and context. Worth scoping during design.
• Anthropic's formal terms for subscription auth in third-party Agent SDK apps will be posted when the claim flow opens — worth re-checking against Hermes' usage pattern before merging.

References

• Help Center: https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan
• Agent SDK overview: https://code.claude.com/docs/en/agent-sdk/overview
• Claude Agent SDK (Python): https://github.com/anthropics/claude-agent-sdk-python

Alternatives Considered

• Keep the status quo (anthropic provider with API key). Works, but Claude-subscribed users pay twice. The new June 15 credit policy makes this less defensible: there's now a published, supported path for third-party apps to authenticate through the subscription.
• Route Claude via OpenRouter. Adds ~5.5% platform fee on top, still pay-per-token, and doesn't touch the new subscription credit. Useful for multi-provider flexibility, not for cost.
• Switch to Codex / OpenAI subscription via the existing Codex OAuth pool. Already supported and works today, but forces users away from Claude as the backend, which isn't a trade-off Claude-subscription users would want to make.
• Community subscription-auth shims (claude_max, claude-code-router, etc.). Technically bolt-on-able, but lives in ToS gray-area territory and is likely to break as Anthropic tightens auth flows around the formal credit program. A first-class provider plugin is cleaner and more durable.

Feature Type

Other

Scope

None

Contribution

• I'd like to implement this myself and submit a PR

Debug Report (optional)

[pokono]

Also currently everything routed through claude -p is included in the subscription.

[jacobaross]

Cross-linking a docs clarification PR: #31237

The short version: until there is explicit Anthropic approval / documented permission for this use case, the docs should not present Claude/claude.ai OAuth as the default safe path for Hermes. The PR keeps the existing mechanics documented, but marks Claude OAuth/setup-token/Claude Code credential reuse as policy-sensitive and recommends ANTHROPIC_API_KEY for normal third-party use.

It also adds a practical footgun note: if a user already has Claude Code or Hermes Anthropic OAuth credentials, they should check hermes auth list anthropic and remove/suppress OAuth entries before assuming an API key is the active credential.

[matthewpomar]

I'm currently using Codex and prefer to use Anthropic models and the $200 API credit when it is available June 15th. Hoping to see a feature that allows us to do that when the time comes. 🤞

[jonahberg]

Would love to use this and hope that the Hermes Agent team can have this ready on June 15.

[xytras1]

Is this on track for a 15 June release?

[fqx]

It's like free money to me.

[5tevebaker]

Count my vote for this being super valuable here!

[konsisumer]

This issue appears to describe the same problem as #32392. Maintainer might want to consolidate or pick one as canonical.