feat(agent): pin_anthropic_token — let a static setup-token win over a refreshable Claude Code credential

[adurham]

Summary

resolve_anthropic_token() already prefers a refreshable Claude Code credential (~/.claude/.credentials.json or macOS Keychain) over a static ANTHROPIC_TOKEN/CLAUDE_CODE_OAUTH_TOKEN env var, so a stale persisted token never silently blocks auto-refresh. That's the right default — but it has no escape hatch for a real, common setup: a dedicated long-lived claude setup-token for Hermes, on a machine where the user also runs interactive claude CLI logins for daily-driver Claude Code work.

macOS Keychain isn't scoped by CLAUDE_CONFIG_DIR, so both credentials collide in the same Keychain slot — every interactive claude login silently overwrites Hermes's dedicated setup-token, and there was no config lever to tell resolve_anthropic_token() "keep using my static token on this machine regardless of what the interactive login just wrote."

Fix

Adds an opt-in agent.pin_anthropic_token: true config key (default false, preserving the existing safety-net behavior). When set, the resolver skips the refreshable-credential preference check for both env var sources (ANTHROPIC_TOKEN and CLAUDE_CODE_OAUTH_TOKEN) and returns the static token directly.

Test plan

• 4 new tests in tests/agent/test_anthropic_adapter.py::TestResolveAnthropicToken:
  • pin_anthropic_token: true makes the static token win over a refreshable credential
  • pin_anthropic_token: false (default) is unaffected — regression guard confirming the opt-in doesn't change existing behavior
  • a config-load exception degrades to the safe default (prefer refresh) rather than propagating
• The pin=true test confirmed to fail against pre-fix code via git stash.
• ruff check clean.
• 97/97 passed in test_anthropic_adapter.py.
• 93/93 passed across adjacent credential-resolution test files: test_runtime_provider_resolution.py, test_credential_pool_oat_authtype.py, test_minimax_provider.py, test_anthropic_token_scope_isolation.py, test_anthropic_third_party_oauth_guard.py, test_hermetic_side_effect_guards.py.

Searched existing issues/PRs first — no existing report or competing PR for this specific gap.

[spfcraze]

This was generated by AI during triage.

Summary:
resolve_anthropic_token() calls _pin_static_anthropic_token() — and through it load_config() — on every invocation, although the helper's docstring says the config read is paid only "unless the user opts in".

Problems:

• pin_static = _pin_static_anthropic_token() runs before the env-var checks in agent/anthropic_adapter.py, so load_config() is called on every resolution, including when no static token is set and the pin cannot apply.
• load_config() is the deepcopy variant — hermes_cli/config.py documents its cache-hit cost at ~265us per call and provides load_config_readonly() for read-only callers; the diff reads config via load_config().

Solution:
Read the pin inside the if token: / if cc_token: branches — the only places pin_static is consulted — and use load_config_readonly() for the lookup.

---

Checked against 636d4b8 — the tip of upstream-pr/pin-anthropic-token when this was written — and 61515e8, main at the same moment.