fix(claude): prefer keychain credentials

[robinebers]

Summary

• Prefer valid Claude Code Keychain credentials before falling back to the legacy .credentials.json file.
• Add regression coverage for stale file credentials shadowing a valid Keychain session.
• Update Claude provider docs for Keychain precedence and hashed service names.

Test plan

• bun run test -- plugins/claude/plugin.test.js

Closes #444

Made with Cursor

---

Note

Medium Risk
Changes credential-source precedence for OAuth tokens; mis-ordering could break authentication on macOS, but the change is small and covered by regression tests.

Overview
Fixes Claude credential resolution to prefer Keychain sessions first (including hashed service names when CLAUDE_CONFIG_DIR is set) and only fall back to ~/.claude/.credentials.json when Keychain credentials are missing/invalid, preventing stale file tokens from triggering unnecessary refresh attempts.

Adds a regression test for the stale-file-shadowing-Keychain scenario and updates Claude provider docs to reflect Keychain precedence, hashed service naming, and the expanded refresh scope including user:file_upload.

^{Reviewed by Cursor Bugbot for commit 55c5877. Bugbot is set up for automated code reviews on this repo. Configure here.}

---

Summary by cubic

Prefer macOS Keychain Claude Code credentials over the legacy file to avoid stale tokens and failed probes. Updates provider docs and adds a regression test to lock the behavior.

• Bug Fixes
  • Check Keychain first (hashed Claude Code-credentials-<sha256(CLAUDE_CONFIG_DIR).slice(0, 8)>, then Claude Code-credentials) before ~/.claude/.credentials.json.
  • Prevent using or refreshing stale file tokens when a valid Keychain session exists; add regression test.
  • Docs clarify Keychain precedence and hashed service names; OAuth scope example now includes user:file_upload.

^{Written for commit 55c5877. Summary will update on new commits. Review in cubic}

[cubic-dev-ai]

No issues found across 3 files

_{Re-trigger cubic}