Skip to content

claude-current-baseline.md

Latest commit

 

History

History
155 lines (117 loc) · 7.12 KB

claude-current-baseline.md

File metadata and controls

155 lines (117 loc) · 7.12 KB
summary Current Claude behavior baseline before vNext refactor work.
read_when
Planning Claude refactor tickets
Changing Claude runtime/source selection
Changing Claude OAuth prompt or cooldown behavior
Changing Claude token-account routing

Claude current baseline

This document is the current-state parity reference for Claude behavior in CodexBar.

Use it when later tickets need to preserve or intentionally change Claude behavior. When the refactor plan, summary docs, and running code disagree, treat current code plus characterization coverage as authoritative, and use this document as the human-readable summary of that current state.

Scope of this baseline

This baseline captures the current behavior surface that later refactor work must preserve unless a future ticket changes it intentionally:

  • runtime/source-mode selection,
  • prompt and cooldown behavior that affects Claude OAuth repair flows,
  • token-account routing at the app and CLI edges,
  • provider siloing and web-enrichment rules,
  • the current relationship between the public Claude doc and the vNext refactor plan.

Active behavior owners

Current Claude behavior is defined by several active owners, not one central planner:

  • Sources/CodexBarCore/Providers/Claude/ClaudeProviderDescriptor.swift owns the main provider-pipeline strategy order and fallback rules.
  • Sources/CodexBarCore/Providers/Claude/ClaudeUsageFetcher.swift still owns a separate direct .auto path, delegated refresh, prompt/cooldown handling, and web-extra enrichment.
  • Sources/CodexBar/Providers/Claude/ClaudeSettingsStore.swift owns app-side token-account routing into cookie or OAuth behavior.
  • Sources/CodexBarCLI/TokenAccountCLI.swift owns CLI-side token-account routing and effective source-mode overrides.
  • Sources/CodexBarCore/TokenAccountSupport.swift owns the current string heuristics that distinguish Claude OAuth access tokens from cookie/session-key inputs.

Current runtime and source-mode behavior

Main provider pipeline

The generic provider pipeline currently resolves Claude strategies in this order:

Runtime Selected mode Ordered strategies Fallback behavior
app auto oauth -> cli -> web OAuth can fall through to CLI/Web. CLI can fall through to Web only when Web is available. Web is terminal.
app oauth oauth No fallback.
app cli cli No fallback.
app web web No fallback.
cli auto web -> cli Web can fall through to CLI. CLI is terminal.
cli oauth oauth No fallback.
cli cli cli No fallback.
cli web web No fallback.

This behavior is owned by Sources/CodexBarCore/Providers/Claude/ClaudeProviderDescriptor.swift through ProviderFetchPlan and ProviderFetchPipeline.

Other active .auto decision sites

The codebase still contains multiple active .auto decision sites:

Owner Current behavior
ClaudeProviderDescriptor.resolveUsageStrategy(...) Chooses oauth, then cli, then web, with final cli fallback when none are available.
ClaudeUsageFetcher.loadLatestUsage(.auto) Chooses oauth, then web, then cli, with final oauth fallback.

This inconsistency is intentional to record here. RAT-107 directly characterizes the active direct-fetcher branches it can reach cleanly in tests and records the remaining current-state behavior without reconciling it.

Prompt and cooldown baseline

Current behavior that later refactor work must preserve:

  • The default Claude keychain prompt mode is onlyOnUserAction.
  • Prompt policy is only applicable when the Claude OAuth read strategy is securityFramework.
  • User-initiated interaction clears a prior Claude keychain cooldown denial before retrying availability or repair.
  • Startup bootstrap prompting is allowed only when all of these are true:
    • runtime is app,
    • interaction is background,
    • refresh phase is startup,
    • prompt mode is onlyOnUserAction,
    • no cached Claude credentials exist.
  • Background delegated refresh is blocked when prompt policy is onlyOnUserAction and the caller did not explicitly allow background delegated refresh.
  • Prompt mode never blocks delegated refresh attempts.
  • Expired credential owner behavior remains owner-specific:
    • .claudeCLI: delegated refresh path,
    • .codexbar: direct refresh path,
    • .environment: no auto-refresh.

Token-account routing baseline

Accepted Claude token-account input shapes today:

  • raw OAuth access token with sk-ant-oat... prefix,
  • Bearer sk-ant-oat... input,
  • raw session key,
  • full cookie header.

Current routing rules:

  • OAuth-token-shaped inputs are not treated as cookies.
  • Cookie/header-shaped inputs are any value that already contains Cookie: or =.
  • App-side Claude snapshot behavior:
    • OAuth token account keeps the usage source setting as-is, disables cookie mode (.off), clears the manual cookie header, and relies on environment-token injection.
    • Session-key or cookie-header account keeps the usage source setting as-is, forces manual cookie mode, and normalizes raw session keys into sessionKey=<value>.
  • CLI-side Claude token-account behavior:
    • OAuth token account changes the effective source mode from auto to oauth, disables cookie mode, omits a manual cookie header, and injects CODEXBAR_CLAUDE_OAUTH_TOKEN.
    • Session-key or cookie-header account stays in cookie/manual mode.

Siloing and web-enrichment baseline

Claude Web enrichment is cost-only when the primary source is OAuth or CLI:

  • Web extras may populate providerCost when it is missing.
  • Web extras must not replace accountEmail, accountOrganization, or loginMethod from the primary source.
  • Snapshot identity remains provider-scoped to Claude.

This behavior is implemented in Sources/CodexBarCore/Providers/Claude/ClaudeUsageFetcher.swift inside applyWebExtrasIfNeeded.

Documentation contract

  • docs/claude.md is the summary doc for contributors who want an overview.
  • This file is the exact current-state baseline for contributor and refactor parity work.
  • claude-provider-vnext-locked.md is the future refactor plan and should cite this file for present behavior.

Characterization coverage

Stable automated coverage for this baseline lives in:

  • Tests/CodexBarTests/ClaudeBaselineCharacterizationTests.swift
  • Tests/CodexBarTests/ClaudeOAuthFetchStrategyAvailabilityTests.swift
  • Tests/CodexBarTests/ClaudeUsageTests.swift
  • Tests/CodexBarTests/TokenAccountEnvironmentPrecedenceTests.swift
  • Tests/CodexBarTests/SettingsStoreCoverageTests.swift

ClaudeUsageTests.swift now directly characterizes the reachable ClaudeUsageFetcher(.auto) branches for:

  • OAuth when OAuth, Web, and CLI all appear available,
  • Web before CLI when OAuth is unavailable,

The successful CLI-selected branch and the CLI-failure-to-OAuth fallback remain documented from code inspection plus surrounding Claude probe/regression coverage, because the current CLI-availability decision is sourced from process-wide binary discovery with no stable test seam that would keep RAT-107 in scope.