docs/17-subscription-passthrough.md

17 — Subscription Passthrough (post-launch)

Not available at launch. Credential modes at launch are BYO key and managed. This document describes planned work; the CLI flags and OAuth client are not live. ChatGPT sign-in needs legal sign-off.

Developers who already pay for Claude Pro/Max/Team/Enterprise or ChatGPT Plus/Pro/Business/Enterprise can sign into Picasso with their existing subscription and run the agent against the inference their plan already covers. They don't pay twice. They don't pay per token. They use the CLI they want against the subscription they already have.

Anthropic shipped this for Claude Agent SDK on June 15, 2026. OpenAI has supported the equivalent flow for Codex via "Sign in with ChatGPT" OAuth from launch. Picasso integrates both as first-class credential modes — adding a fourth path alongside managed-by-Picasso, BYO-API-key, and local-model. The whole provider abstraction, the agent loop, memory layer, /goal mode, hooks, sandbox — every harness feature — works identically across all four credential modes.

Why this matters

Two distinct audiences land here:

Existing Claude / ChatGPT subscribers who would otherwise have to pick: keep paying their $20/$100/$200 monthly subscription and use the official CLI, or move to Picasso and either pay API rates on top or take the free ad-supported path. Subscription passthrough removes the choice — they can use Picasso and keep their existing bill at zero net new cost.
Power users running both Picasso and the official CLIs who want a single tool with the harness depth, memory layer, and /goal mode of Picasso while billing inference through the subscription they already pay for.

For the business: subscription-passthrough users do not generate model-interstitial revenue, but they still see display ads on the companion dashboard (13-ads-monetization.md) and still expand our addressable market by removing the "but I already pay Anthropic / OpenAI" objection. The ad surface is unchanged for them; the model-interstitial surface (which exists only to extend budget caps on the managed free tier) does not apply.

The four credential modes

The provider abstraction (07-providers.md) supports four modes, configurable per-provider:

Mode	Who pays for inference	Premium models	Ad surfaces
`managed`	Picasso (ad-revenue funded)	Behind sponsored interstitial when budget exhausts	Display + interstitial
`subscription`	User's Claude or ChatGPT plan	Subject to plan's own model entitlements and Agent SDK credit / Codex quota	Display only
`byo-key`	User's API account	Always available, billed to user's account	Display only
`local`	User's hardware (Ollama, vLLM)	Whatever the user runs	Display only

Modes are independent per provider. A user might use subscription for Anthropic, byo-key for OpenAI, and local for embedding generation, all in the same session. Per-task routing (07-providers.md) selects between configured providers; each provider's credential mode is opaque to the loop.

Anthropic — Claude Agent SDK with subscription

What Anthropic allows

Starting June 15, 2026, Pro, Max, Team, and Enterprise plans receive a separate monthly Agent SDK credit that covers Claude Agent SDK usage, the claude -p non-interactive command, and third-party apps that authenticate against the user's Claude subscription through the Agent SDK. Picasso falls explicitly in the third category.

Plan	Monthly Agent SDK credit
Pro	$20
Max 5x	$100
Max 20x	$200
Team — Standard seats	$20
Team — Premium seats	$100
Enterprise — usage-based	$20
Enterprise — Premium seats (seat-based)	$200

The credit is per-user, refreshes monthly with the billing cycle, drains before any other inference source, and does not roll over. Past the credit, usage moves to extra usage at standard API rates only if the user has explicitly enabled extra usage — otherwise requests stop until the next cycle. Enterprise members on seat-based Standard seats are not eligible.

The credit is one-time opt-in per user; after the user claims it in their Anthropic account, it refreshes automatically.

Integration mechanism

Picasso uses the Claude Agent SDK with subscription authentication rather than an API key. This is the contract Anthropic published for "third-party apps that authenticate with your Claude subscription through the Agent SDK." Specifically, the Anthropic adapter in packages/providers runs in subscription mode when the user has chosen that credential mode, and constructs requests through the Agent SDK using OAuth-issued credentials in place of an API key.

Setup flow

Planned, not shipped: this release has no subscription flag. picasso auth provider set anthropic --mode subscription answers "Subscription sign-in is not available in this release." and exits 2. The planned flow looks like this:

$ (planned subscription sign-in for anthropic)
Opening browser to Anthropic to authorize Picasso…

After you sign in and authorize, return to this terminal.
Waiting for authorization…

✓ Authorized as [email protected]
  Plan: Claude Pro
  Monthly Agent SDK credit: $20.00
  Credit remaining this cycle: $20.00
  Extra usage: disabled (enable at console.anthropic.com)

Set Anthropic credential mode to: subscription
This means Picasso will bill Anthropic inference to your Claude Pro plan's
Agent SDK credit ($20/month). To switch back, run:
  picasso auth provider set anthropic --mode managed

The flow is OAuth 2.0 authorization-code with PKCE against Anthropic's OAuth endpoint. Tokens are stored in OS keychain (see 11-auth-and-accounts.md). Refresh is automatic during active sessions; expired refresh tokens prompt re-login.

Credit metering

Every Anthropic inference call in subscription mode includes the user's Agent SDK credential, which causes Anthropic to attribute the cost to the user's monthly credit. Picasso's own cost tracking (in 07-providers.md and the session metadata) records the same call as credentialMode: 'subscription'; the UI shows the subscription plan name and the share of monthly credit remaining — never a dollar amount.

The TUI status line (10-tui.md) shows:

3 tools · 12.4K tokens · Claude Pro credit · 97% remaining · safe mode · ▶ ready

The dashboard's account view shows a meter for the user's current-cycle Agent SDK credit consumption, refreshed in real time on every billable call.

Behavior when credit exhausts

When the credit is drained:

If extra usage is enabled on the user's Anthropic account, calls continue at API rates billed to that account. Picasso displays a banner so the user knows they have moved past the included credit.
If extra usage is not enabled, calls fail with a structured error and the loop pauses. The user is offered three paths: (1) enable extra usage in their Anthropic console and resume, (2) switch credential mode to managed for the rest of the cycle and accept ad-supported managed inference, (3) abort.

Goals that span credit boundaries (e.g., a 24-hour /goal that crosses a billing-cycle reset) handle this gracefully — the credit refresh is detected mid-run and the goal continues without user intervention.

OpenAI — Codex with ChatGPT subscription

What OpenAI allows

OpenAI's Codex CLI supports "Sign in with ChatGPT" as a primary authentication mode. Plus, Pro, Business, and Enterprise plans include Codex usage. The OAuth flow against auth.openai.com is the documented mechanism, and third-party tools (OpenCode, OpenClaw, others) already use the same flow under personal-use terms for individual developers.

Important legal note

OpenAI's published policy is explicit about Codex CLI use under ChatGPT sign-in. Use of "Sign in with ChatGPT" by third-party CLIs for personal-use authentication is broadly practiced but is not, as of writing, accompanied by an explicit blanket commercial license for redistributed third-party CLIs. Picasso ships subscription passthrough for OpenAI as a personal-use authentication mode, with the following guardrails:

One subscription per user, authenticated by that user's own browser flow. No multi-user proxying. No credential pooling. No automation that aggregates many users behind one subscription. These are all banned in the implementation and would be cause for de-listing a user.
Pre-launch legal review of "Sign in with ChatGPT" terms by Picasso's counsel against the most current OpenAI policy text, with sign-off documented in the launch checklist (checklist.md).
A documented fallback to BYO-API-key if OpenAI publishes any restriction on third-party CLI use of subscription OAuth. The byo-key mode is always available as a continuity path.

If OpenAI publishes an explicit commercial third-party-tool policy in the future, that policy supersedes the personal-use framing and Picasso updates the in-product disclosure accordingly.

Integration mechanism

The OpenAI subscription adapter follows the same OAuth contract Codex CLI uses:

Authorize endpoint: https://auth.openai.com/oauth/authorize
Token endpoint: https://auth.openai.com/oauth/token
Redirect URI: http://localhost:1455/auth/callback
Scopes: the same scopes Codex CLI requests for "Sign in with ChatGPT"
Token storage: OS keychain (consistent with the rest of Picasso's credential handling). The ~/.codex/auth.json plaintext file the Codex CLI maintains is not used by Picasso.

The local callback server lives only for the duration of the authorize flow (typically <60 seconds), refuses any other requests, and exits as soon as the authorization code arrives. Token refresh is handled by the adapter using the refresh token issued at first authorization.

Device-code fallback

When the local callback fails (remote SSH session, headless environment, restricted network), the adapter falls back to device-code authentication, mirroring Codex's codex login --device-auth pattern. The fallback path requires the user to enable device-code authentication in their ChatGPT account or workspace permissions.

Setup flow

Planned, not shipped (same "not available in this release" answer today):

$ (planned subscription sign-in for openai)
Opening browser to ChatGPT to authorize Picasso…

After you sign in and authorize, return to this terminal.
Waiting for authorization on localhost:1455…

✓ Authorized as [email protected]
  Plan: ChatGPT Plus
  Codex models available: gpt-5.3-codex

Set OpenAI credential mode to: subscription
This means Picasso will route OpenAI inference through your ChatGPT Plus
subscription. To switch back, run:
  picasso auth provider set openai --mode byo-key
  picasso auth provider set openai --mode managed

Behind the scenes the adapter opens the browser to the authorize URL, runs the localhost callback server, exchanges the returned code at the token endpoint, and writes the access + refresh tokens to OS keychain. Total elapsed time under 30 seconds in normal conditions.

Behavior when subscription rate-limits

ChatGPT subscriptions have their own rate limits that vary by plan and by model. When the user hits a rate limit:

Picasso displays a clear banner identifying the rate-limit class (model rate limit, account rate limit, workspace rate limit).
The loop pauses with the same three options as the Anthropic credit-exhaust flow.
The provider fallback chain (07-providers.md) can be configured to route to a different provider on rate-limit error — e.g., automatically fall through to Anthropic via subscription credit if ChatGPT is rate-limited.

Models routed through subscription

The OpenAI subscription adapter exposes the models the user's plan entitles them to. Free / Go tier users see whatever Codex includes at no charge in those tiers (subject to rate limits). Plus/Pro/Business/Enterprise users see their plan's full Codex model set. The adapter does not attempt to access models the user's plan does not entitle them to.

Common architecture

Both subscription adapters share infrastructure in packages/auth and packages/providers:

┌────────────────────────────────────────────────────────────┐
│                                                            │
│   packages/auth                                            │
│   ├── OAuthClient                  (RFC 6749 + PKCE)       │
│   ├── LocalCallbackServer          (per-flow, port 1455)   │
│   ├── DeviceCodeFlow               (fallback)              │
│   ├── KeychainStore                (OS keychain abstraction)│
│   └── TokenRefresher               (background scheduler)  │
│                                                            │
│   packages/providers                                       │
│   ├── AnthropicSubscriptionAdapter                         │
│   │   └── uses Claude Agent SDK with OAuth credentials     │
│   ├── OpenAISubscriptionAdapter                            │
│   │   └── uses Codex backend with ChatGPT OAuth            │
│   ├── ManagedAdapter (existing)                            │
│   ├── BYOKeyAdapter (existing)                             │
│   └── LocalAdapter (existing)                              │
│                                                            │
└────────────────────────────────────────────────────────────┘

Credential mode selection is per-provider, persisted in ~/.picasso/credentials.yaml:

providers:
  anthropic:
    mode: subscription
    subscriptionAccount: [email protected]
    plan: Claude Pro
    creditCycle: 2026-06-15..2026-07-14
  openai:
    mode: subscription
    subscriptionAccount: [email protected]
    plan: ChatGPT Plus
  google:
    mode: byo-key
  embeddings:
    mode: local
    endpoint: ollama://localhost:11434

Mode switches are atomic — a single command flips the mode for the next inference call without interrupting in-flight sessions, but in-flight goals checkpoint and resume cleanly against the new credential.

CLI surface

picasso auth provider list                              # all providers + current modes
picasso auth provider add <provider> --api-key          # BYO key (or --key-stdin)
picasso auth provider add <provider> --managed          # default; managed by Picasso
picasso auth provider set <provider> --mode <mode>      # switch mode
picasso auth provider remove <provider>                 # revoke credentials, clear keychain entries
picasso auth provider refresh <provider>                # force token refresh
picasso auth provider status                            # show credential mode, account, plan, remaining credit

A subscription mode for auth provider add is planned; it is not in this release.

In the TUI, /auth opens an interactive credential management panel.

Dashboard surface

The account section of the dashboard surfaces:

Per-provider credential mode badge.
For Anthropic subscription users: a live meter showing the share of current-cycle Agent SDK credit remaining (percent of monthly credit).
For ChatGPT subscription users: model entitlement list and observed rate-limit status.
For BYO-key users: connection status and entitlements; spend-to-date stays on the provider's own billing portal — the dashboard does not render dollar amounts.
A switch-credential-mode flow that mirrors the CLI.

The memory inspector, goal monitor, session replay, and plan editor work identically regardless of credential mode. The ad surfaces (13-ads-monetization.md) render identically — display ads on the dashboard for all users; sponsored model interstitials only for managed-mode users hitting budget caps.

Privacy and data flow

Subscription credentials are end-user assets. They live in the user's OS keychain. They are never transmitted to Picasso servers. The Picasso API never sees the user's Anthropic or OpenAI credentials.

Specifically:

Inference calls in subscription mode go from the user's machine directly to the provider's API endpoint, authenticated with the user's OAuth credential. The Picasso cloud is not in the inference path.
Session events (06-sessions.md) and memory entries (15-memory.md) sync to the Picasso cloud as normal — these are first-party data, owned by the user and synced with their account, identical to managed-mode behavior.
Cost/credit consumption is computed locally from provider response headers and metadata, displayed in the TUI and dashboard. The displayed numbers are derived from what the provider reports.
The user's provider account identity (e.g., the email Anthropic OAuth returns) is stored only locally; it is not synced to Picasso's cloud unless the user has cloud sync enabled and explicitly chooses to display it cross-device.

Per-user enforcement

Subscription credentials are strictly per-user. The runtime enforces:

One subscription per provider per Picasso account.
No credential transfer between Picasso accounts.
No automation that proxies multiple Picasso accounts through one provider subscription.
No API surface to programmatically share or pool subscription credentials across users.

These constraints are enforced both client-side (the credential store refuses to accept a second OAuth credential for the same provider without removing the first) and server-side (the API rejects session events that report inconsistent credential-attribution metadata for a single Picasso account).

For organizations that want pooled inference across many seats, the path is BYO-API-key for the organization-owned API account, not subscription passthrough. This matches Anthropic's published guidance — production automation at organizational scale belongs on the Claude Developer Platform, not on per-user Agent SDK credits.

Integration with managed-tier monetization

Subscription users do not see sponsored model interstitials. The interstitial mechanic in 13-ads-monetization.md exists for managed-tier users who exhaust their free-tier daily budget; subscription users have their own bill-paying mechanism (their subscription) and the interstitial does not apply.

Subscription users do see dashboard display ads — header banner, sidebar, in-feed, replay interstitial. These render identically and follow identical disclosure rules. The dashboard remains the primary monetization surface; subscription passthrough does not exempt a user from that.

Interaction with `/goal` mode

Long-horizon /goal runs work identically across all four credential modes. For subscription mode, the goal's budget cap is implicit (the user's monthly Agent SDK credit, the ChatGPT subscription's rate limits). Explicit per-goal cost caps still apply on top — a user can run a goal with maxCostUSD: 5 against their subscription, and the goal will pause at $5 of consumed credit even if their monthly allowance still has $15 left, giving them a checkpoint to confirm continuation.

The sponsored-interstitial extension flow (16-goals.md) does not apply to subscription-mode goals. When a subscription user's credit exhausts mid-goal, the standard exhaust flow (extra usage / mode switch / abort) applies.

Acceptance criteria

Anthropic subscription OAuth flow completes end-to-end in under 60 seconds (browser open → token in keychain → first successful inference call).
ChatGPT subscription OAuth flow completes end-to-end in under 60 seconds via localhost callback, or 90 seconds via device-code fallback.
Token refresh runs in the background without user-visible disruption for sessions longer than the access-token TTL.
Credit-consumption meter in the TUI is accurate to within 5% of the provider's reported value at session end.
Mode switch (subscription ↔ byo-key ↔ managed) completes in under one second without dropping the in-flight session.
Per-user enforcement prevents a single Picasso account from holding more than one active credential per provider.
Cross-device sync correctly preserves the credential mode metadata (which mode is active per provider) without ever transmitting the actual credentials.
Goals crossing a billing-cycle reset resume cleanly when the new credit becomes available.
Adversarial pooling test (simulated attempt to share one subscription across many Picasso accounts) is detected and rejected.

Dependencies

packages/auth — OAuth client, local callback server, device-code fallback, keychain store, token refresher.
packages/providers — AnthropicSubscriptionAdapter, OpenAISubscriptionAdapter.
Anthropic Claude Agent SDK — the upstream SDK used by the AnthropicSubscriptionAdapter.
OpenAI Codex backend OAuth — the upstream contract used by the OpenAISubscriptionAdapter.
apps/dashboard — account-section credit meter and credential-mode UI.
apps/cli — picasso auth provider subcommand tree.

Open questions

Should Picasso warn the user when their subscription credit is approaching exhaustion (50%, 80%, 95%) the same way /goal budget alerts work? _Current proposal: yes, the same thresholds, same notification channels._
Should subscription mode work for Google Gemini and xAI Grok when those providers offer equivalent subscription-OAuth contracts? _Current proposal: yes when published; the SubscriptionAdapter interface is generic. No active integrations until those providers publish a third-party-tool contract._
Should Picasso offer a "use my subscription for this session only, then revert" mode for users who want to keep managed as their default? _Current proposal: yes, via picasso run --provider anthropic:subscription "..." per-session override. Persistent default remains the configured mode._
Should we surface to the user that subscription mode is not the same legal contract as BYO-API-key mode (especially the per-user / no-pooling constraints)? _Current proposal: yes, displayed once at first setup with link to the relevant policy doc per provider._

17 — Subscription Passthrough (post-launch)

Why this matters

The four credential modes

Anthropic — Claude Agent SDK with subscription

What Anthropic allows

Integration mechanism

Setup flow

Credit metering

Behavior when credit exhausts

OpenAI — Codex with ChatGPT subscription

What OpenAI allows

Important legal note

Integration mechanism

Device-code fallback

Setup flow

Behavior when subscription rate-limits

Models routed through subscription

Common architecture

CLI surface

Dashboard surface

Privacy and data flow

Per-user enforcement

Integration with managed-tier monetization

Interaction with /goal mode

Acceptance criteria

Dependencies

Open questions

Interaction with `/goal` mode