fix(anthropic-oauth): bypass Anthropic's spoof filter for Claude subscription auth

[erdinccurebal]

Summary

Every Anthropic subscription OAuth call from hermes (Claude Pro / Max via ~/.claude/.credentials.json or Keychain) was returning HTTP 400 — You're out of extra usage. Add more at claude.ai/settings/usage and keep going. — even on accounts with plenty of plan headroom (e.g. Max 20x at ~2% of the 5-hour bucket, 51% of weekly Sonnet, with overage disabled at org level).

Bisecting an actual outgoing request against api.anthropic.com pinned the cause to Anthropic's server-side spoof filter on the subscription OAuth path. Two specific things trigger it; both are produced by today's is_oauth branch in agent/anthropic_adapter.py::build_anthropic_kwargs:

Trigger 1 — tool names

_MCP_TOOL_PREFIX = ""mcp_"" produces single-underscore tool names like mcp_browser_back. The filter only accepts Claude Code's MCP convention mcp__<server>__<tool> (double underscores).

Tool name	Result
Bash, Read, Edit	200 OK
do_thing (custom)	200 OK
mcp__browser__back	200 OK
mcp_browser_back	400 ❌
mcp-browser-back	200 OK

Trigger 2 — system prompt content

The OAuth branch prepends the official Claude Code prefix to the hermes identity prompt, then runs a sanitizer that rewrites Hermes Agent → Claude Code and Nous Research → Anthropic. The resulting string — ""You are Claude Code, an intelligent AI assistant created by Anthropic. You are helpful, knowledgeable, and direct..."" — looks like Claude Code but is not the official prompt, so the filter rejects it. Larger composite system blocks (≥~2 KB) are rejected even without a Claude Code mention.

Empirically (same OAuth token, model claude-haiku-4-5-20251001):

system value	Result
Official prefix only	200 OK
""You are a helpful assistant.""	200 OK
""You are Hermes Agent, an intelligent AI assistant...""	200 OK (short, ~640 B)
Sanitized hermes prompt (post-rewrite, 14 KB)	400 ❌
Same 14 KB moved into the first user message	200 OK

Fix

agent/anthropic_adapter.py — is_oauth branch of build_anthropic_kwargs:

• Send only _CLAUDE_CODE_SYSTEM_PREFIX in system.
• Move any hermes-side system text into a <system_context>…</system_context> preamble on the first user message — Anthropic does not apply the spoof filter to user content.
• Drop the sanitizer (the substitution it performed was producing the rejection it was trying to prevent).
• Rename _MCP_TOOL_PREFIX from ""mcp_"" to ""mcp__hermes__"". Tool definitions and prior-turn tool_use blocks get the new prefix; the existing startswith(_MCP_TOOL_PREFIX) guard makes the rename idempotent on retries.

agent/transports/anthropic.py — _MCP_PREFIX on the response-stripping side is bumped to the same value so prefix round-trips correctly.

Tests

New: tests/agent/test_anthropic_adapter.py::TestOauthSpoofFilterCompliance (11 tests).
Covers: prefix constant value, sender/receiver prefix synchronization, OAuth system reduction + relocation behavior, idempotent re-prefixing, tool_use rename in conversation history, non-OAuth path stays untouched, and a regression check that the pre-patch hermes identity string never re-enters system.

tests/agent/test_anthropic_adapter.py::TestOauthSpoofFilterCompliance — 11 passed
tests/agent/test_anthropic_adapter.py (full)                          — 142 passed

(19 pre-existing failures in TestResolveAnthropicToken / TestReadClaudeCodeCredentials etc. reproduce on untouched main; they are token-resolution tests where the real macOS Keychain leaks through MagicMock patching. Not affected by this change.)

ruff check agent/anthropic_adapter.py agent/transports/anthropic.py tests/agent/test_anthropic_adapter.py — clean.

Test plan

• pytest tests/agent/test_anthropic_adapter.py::TestOauthSpoofFilterCompliance — 11/11 pass.
• pytest tests/agent/test_anthropic_adapter.py — no new regressions vs. main baseline (19 pre-existing token-mock failures unchanged).
• ruff check on changed files — clean.
• Live smoke tests against api.anthropic.com with a previously-failing Claude Max OAuth token:
  • hermes chat -q ""say only: ok"" → ok (3 s, 0 tool calls)
  • tool call: mcp__hermes__terminal runs echo, returns output (5 s, 2 tool calls)
  • memory + terminal multi-tool: mcp__hermes__memory + …__terminal (9 s, 3 tool calls)

[teknium1]

Closing alongside the issue this addresses — working as intended, won't implement.

This change is in service of making Claude Pro/Max/Team OAuth credentials bill on-plan for programmatic traffic. As of Anthropic's mid-June 2026 change, that traffic is metered as extra usage by design. The only way to restore on-plan billing is to present as the first-party Claude CLI/Agent-SDK surface — exactly the spoof filter Anthropic enforces against — which puts users at real risk of account suspension. We won't ship a mitigation whose mechanism is evading the provider's usage-attribution filter.

For Anthropic API access, use a standard x-api-key API key (ANTHROPIC_API_KEY). Thanks for the work and the detailed tracing.