steipete--codexbar/docs/refactor/claude-provider-vnext-locked.md

---
summary: "Locked implementation plan for Claude provider vNext: resolved source-selection contracts, typed credential rules, siloing guarantees, and phase gates."
supersedes: "Initial vNext draft (removed)"
created: "2026-02-18"
status: "Locked for implementation"
---

# Claude provider vNext (locked plan)

This is the implementation-locked vNext plan.

It preserves the original architecture direction, but removes ambiguity in behavior-critical areas before refactor work starts.

Current-state parity reference for present behavior:

- [docs/refactor/claude-current-baseline.md](claude-current-baseline.md)

Use the baseline doc for present behavior. This vNext plan defines what the refactor should preserve and how it should
be staged; it is not the sole source of truth for current implementation details, and RAT-107 does not re-approve the
rest of the future architecture below.

## Assessment snapshot

- **Approach score:** `8.4/10`.
- **Why not 9+ yet:** the original plan left runtime ordering, token-account credential typing behavior, and compatibility mapping under-specified.
- **How this doc closes the gap:** explicit contracts + resolved decisions + phase exit gates + risk checklist.
- **Validated gap coverage in this version:** explicit `.auto` inconsistency handling, `ClaudeUsageFetcher` decomposition, stronger parity gates, TaskLocal-to-DI migration, and OAuth decomposition sub-phases.

## Locked behavioral contracts

These behaviors are **non-negotiable** during refactor unless this doc is explicitly updated.

### 1) Runtime + source-mode contract

`ClaudeSourcePlanner` must reproduce this matrix exactly:

| Runtime | Selected mode | Ordered attempts | Fallback rules |
| --- | --- | --- | --- |
| app | auto | oauth -> cli -> web | oauth fallback allowed; cli fallback to web only when web available; web terminal |
| app | oauth | oauth | no fallback |
| app | cli | cli | no fallback |
| app | web | web | no fallback |
| cli | auto | web -> cli | web fallback allowed to cli; cli terminal |
| cli | oauth | oauth | no fallback |
| cli | cli | cli | no fallback |
| cli | web | web | no fallback |

Notes:
- `sourceLabel` remains the final step label for successful fetch output.
- Planner diagnostics must include ordered steps and inclusion reasons.
- Planner output must feed the existing generic provider fetch pipeline; do not introduce a second Claude-only
  execution stack alongside `ProviderFetchPlan` / `ProviderFetchPipeline`.

### 1a) `.auto` inconsistency characterization contract (must-do before reconciliation)

Current code has three `.auto` decision sites with inconsistent app ordering:

- Strategy pipeline resolve order (app): `oauth -> cli -> web`.
- `resolveUsageStrategy` helper order: `oauth -> cli -> web -> cli fallback`.
- `ClaudeUsageFetcher.loadLatestUsage(.auto)` order: `oauth -> web -> cli -> oauth fallback`.

Phase 0 must characterize these paths with tests where they are reachable through stable seams, and otherwise defer to
the baseline doc before deleting any path.
Phase 2 must reconcile this into planner-only source selection.

### 2) Prompt/cooldown contract

The planner must use one explicit `ClaudePromptDecision` equivalent, but outcome parity with current behavior is required:

- User-initiated actions can clear prior keychain cooldown denial.
- Startup bootstrap prompt is only allowed when all are true:
  - runtime is app
  - interaction is background
  - refresh phase is startup
  - prompt mode is `onlyOnUserAction`
  - no cached credentials
- Background delegated refresh is blocked when:
  - prompt policy is `onlyOnUserAction`
  - caller does not explicitly allow background delegated refresh
- Prompt mode `never` blocks delegated refresh attempts.

### 3) Credential typing + routing contract

Typed credentials must be introduced at the settings snapshot edge, with behavior parity:

- `ClaudeManualCredential.sessionKey`
- `ClaudeManualCredential.cookieHeader`
- `ClaudeManualCredential.oauthAccessToken`

Accepted Claude token-account inputs must continue to work:

- Raw OAuth token (including `Bearer ...` input)
- Raw session key
- Full cookie header

Routing parity requirements:

- OAuth token account values must route to OAuth path (not cookie mode).
- Cookie/session-key account values must route to web cookie path.
- CLI token-account behavior must remain consistent in both app and `CodexBarCLI`.
- Scope note: current string heuristics are mostly edge-routing logic, not deep OAuth credential decoding internals.

### 4) Ownership and refresh contract

Credential owner behavior must remain identical:

- `.claudeCLI` expired credentials: delegated refresh path.
- `.codexbar` expired credentials: direct refresh endpoint path.
- `.environment` expired credentials: no auto-refresh.

Refresh failure-gate semantics must remain unchanged.

### 5) Provider siloing + enrichment contract

Hard invariant:

- Never merge Claude Web identity into OAuth/CLI snapshots.
- Web extras may enrich **cost only**.
- Snapshot identity must always remain provider-scoped to `.claude` when persisted/displayed.

### 6) Plan inference compatibility contract

Canonical plan inference can live behind the existing `loginMethod` compatibility surface, but outward
compatibility must be preserved:

- Existing detectable plans continue mapping to display strings:
  - `Claude Max`
  - `Claude Pro`
  - `Claude Team`
  - `Claude Enterprise`
- Subscription detection behavior must remain compatible with current UI logic, including existing `Ultra` detection
  semantics until that behavior is explicitly changed.

### 7) Documentation + diagnostics contract

- During refactor, characterization coverage plus
  [docs/refactor/claude-current-baseline.md](claude-current-baseline.md)
  are the source of truth when docs and code disagree.
- `docs/claude.md` must be updated as part of Phase 0 after characterization lands so it no longer presents divergent
  runtime ordering as settled behavior.
- Debug surfaces must consume planner-derived diagnostics instead of recomputing Claude source decisions separately.

## Resolved decisions (from open questions)

### Web identity fill-ins

- **Decision:** do not use Web identity to fill missing OAuth/CLI identity fields.
- **Allowed:** Web cost enrichment only.

### CLI runtime fallback ordering

- **Decision:** keep current CLI ordering in `auto`: `web -> cli`.
- Planner must encode this explicitly and not rely on incidental strategy ordering.

### Startup bootstrap prompt in `onlyOnUserAction`

- **Decision:** keep support exactly under the startup bootstrap constraints listed above.
- Any expansion/restriction requires explicit doc update and tests.

### Runtime policy unification timing

- **Decision:** do not unify app and CLI `auto` ordering before this refactor.
- First consolidate to one planner implementation with current runtime-specific behavior preserved.
- Any runtime-policy unification is a separate, explicit behavior-change follow-up.

### Planner integration timing

- **Decision:** `ClaudeSourcePlanner` must be integrated into the existing provider descriptor / fetch pipeline rather
  than added as a parallel orchestration layer.
- Reuse current `ProviderFetchContext` / `ProviderFetchPlan` plumbing where possible.

### Dependency seam timing

- **Decision:** introduce dependency-container seams for newly extracted planner/executor components as they are
  created.
- Full TaskLocal cleanup can remain later, but new components should not deepen TaskLocal coupling.

## Locked migration plan with exit gates

### Phase 0: Baseline lock

Deliverables:
- Add `docs/refactor/claude-current-baseline.md` as the current-state behavior reference.
- Add/refresh characterization tests for runtime/source matrix and prompt-decision parity.
- Add explicit characterization tests for existing `.auto` decision paths where they are reachable through stable seams,
  and defer remaining current-state details to the baseline doc until later reconciliation.
- Update `docs/claude.md` after tests land so documented ordering matches characterized behavior.

Exit gate:
- Behavior matrix tests pass for app and cli runtimes.
- `.auto` characterization coverage plus the baseline doc record current divergence explicitly without forcing new
  production seams in Phase 0.
- `docs/claude.md` no longer contradicts characterized runtime/source behavior.

### Phase 1: Canonical plan resolver

Deliverables:
- Introduce `ClaudePlan` + one resolver used by OAuth/Web/CLI mapping and downstream UI consumers.

Exit gate:
- Plan mapping tests cover tier/billing/status-derived hints, compatibility display strings, and current UI subscription
  detection compatibility.

### Phase 1b: Typed credentials at the snapshot edge

Deliverables:
- Parse manual Claude credentials once at the app + CLI snapshot edges into a typed model.
- Remove duplicated edge-routing heuristics for OAuth-vs-cookie decisions across settings snapshots and token-account
  CLI code.

Exit gate:
- Token account parity tests pass for app + CLI.
- Snapshot-edge routing no longer duplicates Claude OAuth-token detection logic in multiple call sites.

### Phase 2: Single source planner

Deliverables:
- Introduce `ClaudeSourcePlanner` + explicit `ClaudeFetchPlan`.
- Integrate planner outputs into the existing provider pipeline / descriptor flow.
- Remove duplicate `.auto` policy branches from lower layers.
- Reconcile and remove `ClaudeUsageFetcher` internal `.auto` source selection.
- Move debug/diagnostic surfaces to planner-derived attempt ordering instead of helper-specific recomputation.

Exit gate:
- One authoritative planner path for mode/runtime ordering.
- Fallback attempt logs still show expected sequence and source labels.
- No surviving `.auto` source-order logic outside planner.
- No surviving debug-only source-order recomputation outside planner diagnostics.
- Old-vs-new planner parity tests pass before old branches are removed.

### Phase 2b: `ClaudeUsageFetcher` decomposition

Deliverables:
- Split `ClaudeUsageFetcher` into smaller executor-focused components.
- Extract delegated OAuth retry/recovery flow into dedicated units.
- Remove embedded prompt-policy/source-selection ownership from fetcher; keep it execution-only.

Exit gate:
- Fetcher no longer owns source-selection policy.
- Delegated OAuth retry behavior is covered by dedicated tests and remains parity-compatible.

### Phase 3: Test injection cleanup

Deliverables:
- Prefer dependency seams on extracted units instead of adding new TaskLocal-only override points.
 - Avoid expanding TaskLocal-only test hooks while decomposition work lands.

Exit gate:
- New fetcher tests rely on explicit dependency seams where practical.

### Phase 4: OAuth decomposition

Deliverables (sub-phases):

- **Phase 4a (repository extraction):**
  - Extract IO + caching + owner/source loading into repository surface.
  - Keep prompt-gate semantics unchanged.
- **Phase 4b (refresher extraction):**
  - Extract network refresh + failure gating to refresher component.
  - Keep owner-based refresh behavior unchanged.
- **Phase 4c (delegated controller extraction):**
  - Extract delegated CLI touch + keychain-change observation + cooldown behavior.
  - Keep delegated retry outcomes unchanged.

Exit gate:
- Existing OAuth delegated refresh / prompt policy / cooldown suites pass without behavior deltas at each sub-phase.
- Owner semantics parity remains intact across all sub-phases (`claudeCLI`, `codexbar`, `environment`).

### Phase 5: Test injection migration (TaskLocal -> DI)

Deliverables:
- Move test injection from TaskLocal-heavy overrides to `ClaudeFetchDependencies` and explicit protocol stubs.
- Keep compatibility shims temporarily where needed, then remove them.

Exit gate:
- Core planner/executor tests run without TaskLocal injection dependencies.
- Legacy TaskLocal-only override surfaces are either removed or isolated to compatibility adapters with deletion TODOs.

### Phase 6: Web decomposition (optional)

Deliverables:
- Separate cookie acquisition from web usage client.
- Keep probe tooling isolated behind debug/tool surface.

Exit gate:
- Web parsing and account mapping tests remain green.

## Implementation PR plan (stacked)

Use this sequence to keep each PR reviewable without turning the rollout into unnecessary PR overhead.

| PR | Title | Scope | Primary risks | Must-pass gate before merge |
| --- | --- | --- | --- | --- |
| PR-01 | Baseline characterization + doc correction | Lock current matrix behavior, characterize `.auto` paths through stable seams, defer remaining lower-level current-state details to the baseline doc, characterize prompt bootstrap/cooldown and token-account routing, then update docs to match reality. | R1, R2, R5, R6, R10 | No production behavior changes; characterization suites green; docs no longer contradict tests or the baseline. |
| PR-02 | Canonical plan resolver | Introduce `ClaudePlan` and central resolver; map OAuth/Web/CLI/UI compatibility through one model while preserving current `loginMethod` projections. | R8 | Plan compatibility tests green (`Max/Pro/Team/Enterprise` + current subscription compatibility). |
| PR-03 | Typed credentials at the edge | Parse manual credentials once (`sessionKey`, `cookieHeader`, `oauthAccessToken`) in app + CLI snapshot shaping. | R6 | Token-account routing parity tests green in app + CLI contexts. |
| PR-04 | Source planner introduction + cutover | Add `ClaudeSourcePlanner`, prove parity against old path, then remove duplicate `.auto` selection branches once parity is proven. | R1, R5, R10 | One `.auto` authority remains; attempt/source-label diagnostics remain parity-compatible. |
| PR-05 | `ClaudeUsageFetcher` decomposition | Split fetcher into execution/retry-focused units; remove embedded source-selection ownership. | R2, R10 | Delegated OAuth retry/recovery tests green with no behavior deltas. |
| PR-06 | OAuth decomposition | Extract repository, refresher, and delegated-controller seams from `ClaudeOAuthCredentialsStore` while preserving owner semantics. | R3, R4, R7, R9 | Cache/fingerprint/prompt/owner suites green (`claudeCLI`, `codexbar`, `environment`). |
| PR-07 (optional) | TaskLocal -> DI migration | Move remaining tests and seams to `ClaudeFetchDependencies`, keep temporary compat adapters, then remove. | R9 | Core planner/executor tests run without TaskLocal globals. |
| PR-08 (optional) | Web decomposition | Split cookie acquisition from web usage client and keep tooling isolated. | R8, R10 | Web parsing/account mapping suites remain green. |

Stacking rules:

1. Keep each PR scoped to one risk cluster and one merge gate.
2. Do not remove old branches until a prior PR has old-vs-new parity tests in CI.
3. If a PR intentionally changes behavior, update this locked doc in the same PR and call it out in summary.
4. Prefer 6 core PRs unless parity risk forces a temporary split; do not fragment the rollout further without a
   concrete rollback or reviewability reason.

## Mandatory test additions

Add these test groups before or during Phases 1-3, then extend for later phases:

1. Planner matrix tests:
   - `(runtime x selected mode x interaction x refresh phase x availability)` -> exact step order + fallback.
2. `.auto` divergence characterization tests:
   - Lock current behavior of strategy pipeline vs `resolveUsageStrategy` helper vs fetcher-direct `.auto`.
   - Use as guardrails while consolidating to planner-only logic.
3. Typed credential parsing tests:
   - OAuth token, bearer token, session key, cookie header, malformed strings.
4. Cross-provider identity isolation tests:
   - Ensure `.claude` identity does not leak via snapshot scoping/merging.
5. Source-label and attempt diagnostics tests:
   - Validate final source label and attempt list parity.
6. CLI token-account parity tests:
   - `TokenAccountCLIContext` and app settings snapshot behavior match for OAuth-vs-cookie routing.
7. Old-vs-new parity tests:
   - Compare old path and planner path outputs before branch removals in Phase 2 and Phase 2b.
8. DI migration tests:
   - Ensure new dependency container can drive planner/executor tests without TaskLocal globals.

## Risk checklist (implementation review)

Use these risk IDs in refactor PR checklists/reviews.

| Risk ID | Severity | Risk | Detail |
| --- | --- | --- | --- |
| R1 | Critical | Auto-ordering reconciliation | Three `.auto` paths are inconsistent today. Characterize strategy pipeline vs `resolveUsageStrategy` helper vs fetcher-direct `.auto` before deleting any path. |
| R2 | High | Prompt policy consolidation | Prompt policy exists across strategy availability, fetcher flow, and credentials store gates. Preserve startup bootstrap constraints exactly to avoid prompt storms or silent OAuth suppression. |
| R3 | High | `ClaudeOAuthCredentialsStore` decomposition | Large lock-protected state + layered caches + fingerprint invalidation + security calls. Splits can break cache coherence, invalidation timing, or prompt gating order. |
| R4 | High | Owner semantics drift | Preserve exact owner-to-refresh mapping: `.claudeCLI` delegated, `.codexbar` direct refresh, `.environment` no refresh. |
| R5 | Medium | CLI runtime parity | Preserve runtime-specific policy: CLI `auto` remains `web -> cli`; OAuth is available only when explicitly selected as `sourceMode=.oauth`. Do not accidentally default CLI runtime to app ordering. |
| R6 | Medium | Token-account OAuth-vs-cookie misrouting | Keep routing parity for OAuth token vs session key vs full cookie header, including `Bearer sk-ant-oat...` normalization. |
| R7 | Medium | Cache invalidation regressions | Preserve credentials file/keychain fingerprint semantics and stale-cache guards during repository extraction. |
| R8 | Low-Medium | Plan inference heuristic drift | Preserve web-specific plan inference fallback (`billing_type` + `rate_limit_tier`) when unifying plan resolution. |
| R9 | Medium | Strict concurrency / `@Sendable` regressions | Maintain thread-safe behavior from current NSLock-based state while moving to DI/decomposed components under Swift 6 strict concurrency. |
| R10 | Low | Debug/diagnostic drift | Keep source labels, attempt sequences, and debug output aligned with real planner decisions after consolidation. |

## Change-control rule

Any refactor PR that intentionally changes one of the locked contracts above must:

1. Update this document.
2. Add/adjust tests proving the new behavior.
3. Call out the behavior change explicitly in the PR summary.