PR #12 shipped oauthToken support with optimistic framing, but testing
revealed @anthropic-ai/claude-agent-sdk has a macOS-specific bug: the
SDK isolates CLAUDE_CONFIG_DIR per invocation and tries to copy
~/.claude/.credentials.json, which doesn't exist on macOS (creds live
in the Keychain). The OAuth token gets misclassified as an API key
and requests are billed against API credits instead of the
subscription — subscribers without API credits see "Credit balance is
too low" errors.
Direct `claude -p` works fine, so the upstream SDK is the broken layer.
Changes:
- README Claude Code section: lead with the macOS status note and
point subscribers at ClaudeProvider + ANTHROPIC_API_KEY as the
current workaround.
- JSDoc on ClaudeCodeProvider: same status note.
- billing_error message: explain the bug and recommend the workaround
so users can self-diagnose from the error alone.
No code removal — when the SDK fix lands upstream, oauthToken users
will Just Work without any code changes here.
Jan-Marlon Leibl
956ca21f54
