fix(anthropic): alias session search on OAuth wire

[konsisumer]

What does this PR do?

Fixes the deterministic Anthropic OAuth billing-classifier failure in #65365. OAuth requests now replace the session_search token with chat_history_lookup in the system prompt and tool schemas, while response normalization restores session_search before Hermes dispatches the call. API-key requests remain unchanged.

Related Issue

Fixes #65365

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• agent/anthropic_adapter.py: alias session_search in OAuth-only system text, tool names, descriptions, and replayed tool-use names.
• agent/transports/anthropic.py: reverse the OAuth alias before generic registry lookup so calls reach the canonical session_search handler.
• tests/agent/test_anthropic_mcp_prefix_strip.py: cover the OAuth request shape, response round-trip, and non-OAuth passthrough.

How to Test

1. Run /opt/homebrew/bin/timeout -k 30 480 sh -c 'pytest tests/ -q -x --timeout=60 "$@"' sh.
2. Run /opt/homebrew/bin/timeout -k 30 480 pytest tests/agent/test_anthropic_mcp_prefix_strip.py -q --timeout=60.
3. Run python scripts/check-windows-footguns.py.

What platforms tested on

• macOS (Darwin arm64)

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: macOS (Darwin arm64)

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A

For New Skills

Not applicable.

Screenshots / Logs

Not applicable.

[teknium1]

Thanks for targeting the narrowly isolated OAuth request-shape failure documented in #65365. Current remote main still injects SESSION_SEARCH_GUIDANCE when the tool is enabled (agent/system_prompt.py:230-233), and its OAuth transform has no aliasing step (agent/anthropic_adapter.py:2783-2833).

Problems

• The new schema alias at agent/anthropic_adapter.py:2823 makes session_search advertise as mcp__chat_history_lookup, but named tool_choice remains canonical at agent/anthropic_adapter.py:2858. agent/auxiliary_client.py:1438 accepts a named function choice and forwards it at agent/auxiliary_client.py:1461, so this valid OAuth request shape can name a tool that is no longer advertised.

Suggested changes

• Normalize a named OAuth tool_choice through _to_oauth_wire_name, and add OAuth/non-OAuth assertions for tool_choice="session_search".

Automated hermes-sweeper review.

[teknium1]

This aliases the advertised schema name, but the later named tool_choice branch still emits the canonical session_search string. Normalize named OAuth choices through _to_oauth_wire_name too, then add a regression test for tool_choice="session_search".

[alt-glitch]

This was generated by AI during triage.

Related: this patch aliases only session_search, while #65365 also identifies memory and #24250 takes a broader all-tool approach. Current head also leaves named OAuth tool_choice canonical while its schema advertises the aliased wire name. Please choose the intended scope and normalize named tool_choice with focused OAuth/non-OAuth coverage.

[konsisumer]

Thanks for the review. I confirmed the mismatch: the OAuth schema advertises mcp__chat_history_lookup, while a named tool_choice="session_search" is still emitted canonically.

I would keep this PR limited to the bisection-backed session_search alias: the #65365 follow-up reports that memory alone is not the trigger and that aliasing session_search breaks the prompt fingerprint. #24250 is described here as a broader all-tool approach.

I could not verify #24250's current state or contents because the GitHub API is unreachable from this worker. Should this PR proceed with the focused OAuth/non-OAuth tool_choice round-trip repair, or be deferred to #24250?

[kshitijk4poor]

Salvaged in #76807 — your commit was cherry-picked with authorship preserved (rebase-merge), so it lands on main under your name.

Good catch on the mechanism: aliasing the tool schema on the OAuth wire and reversing it in normalize_response is exactly the right layer, and it sits cleanly alongside the existing mcp__ normalization from GH-25255. Verified end-to-end during review — the round-trip dispatches back to session_search correctly, non-OAuth requests are untouched, and old cached conversations still resolve.

Three follow-up commits on top:

• memory is aliased too. OAuth (Claude Pro/Max): exposing memory or session_search tool schema deterministically triggers HTTP 400 "You're out of extra usage" #65365's A/B repro isolates two independent triggers — base + session_search → 400 and base + memory → 400. With only the first covered, anyone on the default toolset still hit the rejection, so the issue would have stayed open.
• Split the alias dict by purpose, and match prose on word boundaries. memory is ordinary English throughout the system prompt and its own parameter docs, so only its name is aliased — a blanket replace there would corrupt the target enum documentation and steer the model to emit invalid values. The word-boundary regex also protects user-supplied system text: a project AGENTS.md mentioning tools/session_search_tool.py was being rewritten into a path that doesn't exist.
• Restored the [Bug]: Anthropic OAuth strips mcp_ prefix from Hermes-native MCP tool names, breaking registry lookup #25255 registry-precedence contract, and guarded the outbound side. The reverse-alias lookup ran before the registry check, so a real MCP tool named mcp_chat_history_lookup would have been misrouted; and on the request side two tools could land on the same wire name, which Anthropic rejects with a hard 400. Both now yield to the genuinely registered tool.

One honest note on verification: nobody in this review could confirm the billing lane changed, only that the request shape no longer carries the fingerprinted tokens — HTTP 200 doesn't prove which bucket was charged, only the Anthropic dashboard does. If you're on a subscription account and can watch plan-vs-overage utilization after this lands, that datapoint would be genuinely useful.

Closing this in favor of the merged salvage. Thanks for the contribution — the diagnosis was the hard part.