pi-anthropic-auth: Skill for Claude Code

Anthropic OAuth Compatibility

Use When

• Anthropic OAuth requests fail with You're out of extra usage.
• Pi Anthropic OAuth works for login but fails for actual requests.
• You need to compare Pi, OpenCode, and opencode-anthropic-auth behavior.
• You need to decide whether a fix belongs in before_provider_request, the streamSimple transport wrapper, or a deeper override.

Core Lessons

1. Treat Anthropic's You're out of extra usage. error as a possible disguised request rejection, not only a billing problem.
2. Prefer the thinnest fix that works.
3. Preserve Pi's built-in Anthropic behavior by default.
4. Prefer request shaping before prompt rewriting.
5. A refusal blamed on request content needs an organic-data control before it becomes a diagnosis (Issue #65).
6. Avoid streamSimple unless hooks are clearly insufficient — they are insufficient for compaction and background-agent calls, which is why this repo wraps the transport (Issue #18).

Repo-Specific Findings

Confirmed Pi upstream behavior

• Pi already handles Claude Code OAuth headers, Claude Code identity injection, native Anthropic OAuth login, and tool-name normalization.
• Pi auth storage already refreshes OAuth tokens under a lock.

Confirmed local fixes

• OAuth Anthropic payload shaping prepends an x-anthropic-billing-header system block.
• The billing block must not add cache_control, or Anthropic can reject the request for exceeding the cache-control block limit.
• Content-less role: "system" messages carrying output_config must survive system-message shaping: on managed-effort models (those pi-ai flags compat.supportsMidConvoEffort, which test/managed-effort-drift.test.ts enumerates from the installed catalog) they are the only carrier of the requested effort, since Pi pins the top-level effort to "high". Dropping them errors nowhere and silently runs every request at "high"; Anthropic accepts them with content: [] (verified live on pi 0.87.1, PR #79).
• Assistant block ordering must not be normalized: measured 2026-09-20, Anthropic returns 200 for [tool_use..., text] and [text, tool_use, text, tool_use] on sonnet-4-5, haiku-4-5, sonnet-5, fable-5, and opus-4-8. The split that used to rewrite those turns corrupted signed thinking blocks and was removed (Issue #66).
• Pi's default system prompt can act as an Anthropic fingerprint and trigger disguised rejection errors.
• Shaping runs in a thin streamSimple transport wrapper (delegating to Pi's built-in Anthropic transport, resolved from the installed pi-ai layout), gated on the sk-ant-oat token.
• The billing header's cc_version is a floor, not a fixed value: the wrapper injects an options.fetch that reads pi's own user-agent: claude-cli/<version> off the built request and rebuilds the header at pi's version when pi reports a higher one (Issue #74). An explicit PI_ANTHROPIC_AUTH_CLAUDE_CODE_VERSION override is absolute and is never raised. Measured live on pi 0.87.1 against claude-opus-5-5: with the pin forced to 2.1.260 the request succeeds; with the same value set through the env override it is rejected as claude_code_version_too_old.
• When Anthropic raises a floor above both pi and the pin, the same fetch retries once at the floor the 400 names, and remembers it for the wrapper's lifetime (Issue #75). Unrecovered rejections (override set, floor unnamed, body not rebuildable, retry rejected) reach the user with a [pi-anthropic-auth] hint appended to error.message. On pi 0.87.1 the retry is unreachable live without a patch, because pi's own 2.1.280 already meets every current floor; the live check forces the pin to 2.1.260 and disables the pi-version read in the working tree, then looks for the claude-code-version-recovery debug line.
• The wrapper covers the main loop and compaction — everything that dispatches through modelRuntime.
• It covers only the provider names this extension registers: anthropic, plus any the user names in extensions/pi-anthropic-auth/config.json (global, or a trusted project's .pi/). An Anthropic OAuth subscription another extension registers under its own name (pi-multi-pass's anthropic-2) is otherwise unshaped and fails real prompts with the extra-usage 400 (Issue #70). Reproduced live on 2026-09-24 with a second login of the same account: 400 without the config, 200 with it. Short prompts pass either way, so check /anthropic-auth:status's shaped providers line before debugging anything else.
• Background agents that pass ctx.modelRegistry.streamSimple() as their stream function (pi >=0.86.0) route through modelRuntime and are shaped; pi-observational-memory 3.1.x does this (measured live, Issue #53).
• On pi >=0.80.8, callers that dispatch through pi-ai's compat.streamSimple (passed explicitly, or reached through the setDefaultStreamFn fallback when streamFn is omitted) are confirmed uncovered, and cannot be covered from this extension (Issue #46); see docs/architecture.md for why, and for the supported path for extension authors.