feat: auth-aware source model resolution (#348)

* docs(plans): add auth-aware source model resolution plan

Plan for expanding SOURCE_CATEGORY_MODEL_DEFAULTS from a single
provider/model string per category to an ordered array, resolved at
plugin config(cfg) time by reading OpenCode's auth.json and selecting
the first array entry whose provider is authenticated.

4 implementation units:
1. Expand source-default shape and update validators
2. Add auth-file reader and auth-aware resolver
3. Wire the auth-aware resolver into the config hook
4. Document the new behavior

Origin: docs/brainstorms/2026-05-09-auth-aware-source-model-resolution-requirements.md
(gitignored, local-only per project convention).

Document review: 3 reviewers (coherence, feasibility, security-lens),
10 findings, all addressed before commit. Confidence check passed
without deepening — local patterns abundant, brainstorm research
exhaustive.

* feat(agent-overlays): expand source category defaults to ordered arrays

Change SOURCE_CATEGORY_MODEL_DEFAULTS shape from Record<CategoryId, string>
to Record<CategoryId, readonly string[]>. Each array is an ordered
preference list, most preferred first.

This commit is shape-only — getSourceCategoryModel(category) still
returns the first array entry, preserving current zero-config behavior.
The auth-aware resolution that picks based on which provider is
authenticated lands in a follow-up commit.

validateSourceCategoryModelDefaults now rejects non-arrays and empty
arrays explicitly, and iterates each entry with indexed key paths
(source category model defaults.${category}[${index}]) for clearer
error messages.

* feat(agent-overlays): add auth-aware source model resolver

Add getAuthenticatedProviders() that reads OpenCode's auth.json
synchronously using the XDG_DATA_HOME path convention. Returns the
top-level keys as a ReadonlySet<string>. Treats missing files as
'no providers authenticated' silently; emits a single stderr
diagnostic for unreadable or malformed files without leaking
contents. Reads only Object.keys; nested values (API keys, OAuth
tokens) are never inspected, logged, persisted, or transmitted.

Extend getSourceCategoryModel(category, authedProviders?) with an
optional second parameter. When provided, the resolver returns the
first array entry whose provider ID (substring before the first /)
is in the authenticated set. Falls back to array[0] when no entry
matches or when no auth set is supplied (backward compat).

Tests: 15 new scenarios including a real-token leak fixture that
captures stderr/stdout and asserts no secret-shaped strings appear,
and a file-not-modified contract verified via mtime + sha256.

* feat(config-handler): wire auth-aware resolver into config hook

Read OpenCode's authenticated providers once per config(cfg) hook
invocation in createConfigHandler, thread the ReadonlySet through
collectAgents and applyAgentOverlays, and pass it to
getSourceCategoryModel(category, authedProviders) so source
defaults pick the first array entry whose provider is authenticated.

Overlay precedence is unchanged: source default -> category overlay
-> exact overlay. Auth-aware resolution only affects the source
default; user/category/exact overlays still win as today.

Add ConfigHandlerDeps.getAuthenticatedProviders for test injection.

Tests:
- 6 new unit tests in tests/unit/config-handler.test.ts covering
  no-auth zero-config, single-provider match, multi-provider
  first-match-wins, category-overlay-wins, exact-overlay-wins, and
  the read-once contract via injected counting spy.
- 2 new integration scenarios in tests/integration/opencode.test.ts
  using the existing homeDir fixture: single-provider auth and
  multi-provider auth, asserting emitted models match per-category
  expectations.

* docs: explain auth-aware source model resolution

Document that SOURCE_CATEGORY_MODEL_DEFAULTS is now an ordered
preference array per category and that the resolver reads OpenCode's
auth.json at config(cfg) time to pick the first array entry whose
provider is authenticated. Falls back to the first array entry when
no match is found.

Make the resolution precedence explicit: user agents.<key>.model >
user categories.<id>.model > source-default-resolver > bundled
markdown > OpenCode inheritance. User overlays remain scalar
provider/model strings; arrays are not accepted in user config in
this iteration.

Document two known limitations: (1) autoload-true providers like
AWS Bedrock that load from environment variables may not appear
in auth.json and may be skipped by the resolver — pin via category
or exact overlay; (2) a tiny race window exists with 'opencode
auth login' that resolves on next OpenCode restart.

Preserve the existing 'Systematic does not support fallback_models'
sentence — the arrays are a preference list, not a runtime fallback
chain.

* Address PR review feedback (#348)

- Fix CodeQL js/file-system-race in tests/unit/agent-overlays.test.ts
  by removing the redundant second fs.readFileSync; mtime + size
  comparison is sufficient to prove the file wasn't touched.
- Narrow isSystemError type assertion from Record<string, unknown>
  to { code: unknown } per Fro Bot NBC.
- Replace the nested-form provider-extraction test with a focused
  public-API assertion of the slashIndex logic, naming the false-match
  guarantee in the test description.
- Add 3 XDG_DATA_HOME branch tests covering absolute path, empty
  fallback, and non-absolute fallback.
- Mark plan units 1-4 as completed and flip plan status to completed.

Net: +3 tests, 562 unit tests pass.

Author: marcusrbrown

README.md

@@ -338,6 +338,8 @@ Systematic separates config-source precedence from overlay precedence. Config fi
 
 Source category model defaults are primary model choices only — they are not fallback chains. Systematic does not support `fallback_models`, inherited retry semantics, runtime fallback behavior, or fallback to the parent model when a source model is unavailable. Explicit and source model IDs are structurally validated and may still fail at OpenCode runtime if the provider or model is unavailable.
 
+Source category model defaults are now ordered preference arrays per category rather than single strings. At plugin load, Systematic reads OpenCode's authentication state from `auth.json` and selects the first array entry whose provider is authenticated. For example, the `review` category defaults to `['anthropic/claude-opus-4.7', 'openai/gpt-5.5']` — a user authenticated only to OpenAI receives `openai/gpt-5.5` (first match), while a user authenticated to Anthropic (or both) receives the more preferred `anthropic/claude-opus-4.7`. If no array entry's provider is authenticated, the first entry is used as the default. The arrays are an ordered preference list, not a runtime fallback chain — `fallback_models` is still not supported.
+
 If you want to restore OpenCode parent-model inheritance for a bundled agent or category (opting out of the source default), set `"model": null` in high-trust user or `$OPENCODE_CONFIG_DIR/systematic.json` config. Project config cannot use `model: null` — project config cannot set, erase, or shadow `model` at any value.
 
 The source defaults are:

docs/plans/2026-05-09-004-feat-auth-aware-source-model-resolution-plan.md

@@ -119,6 +119,40 @@ This only works from high-trust config (user or `$OPENCODE_CONFIG_DIR/systematic
 
 Native OpenCode agents with the same emitted key are full replacements. If `config.agent.security-sentinel` already exists in OpenCode config, `agents.security-sentinel` or `agents.review/security-sentinel` conflicts because ownership would be ambiguous. Category overlays skip native replacements and continue applying to the remaining Systematic-owned bundled agents in that category.
 
+#### Auth-Aware Resolution
+
+Source category model defaults are now ordered preference arrays per category rather than single strings. At plugin load, Systematic reads OpenCode's authentication state and selects the first array entry whose provider is authenticated.
+
+```jsonc
+// The built-in defaults for each category (code-owned, not user-configurable).
+// The resolver picks the first entry whose provider is in the auth set.
+{
+  "design":           ["openai/gpt-5.5", "anthropic/claude-opus-4.7"],
+  "docs":             ["openai/gpt-5.4-mini", "anthropic/claude-haiku-4-5"],
+  "document-review":  ["anthropic/claude-opus-4.7", "openai/gpt-5.5"],
+  "research":         ["openai/gpt-5.5", "anthropic/claude-opus-4.7"],
+  "review":           ["anthropic/claude-opus-4.7", "openai/gpt-5.5"],
+  "workflow":         ["openai/gpt-5.4-mini", "anthropic/claude-haiku-4-5"]
+}
+```
+
+The authentication file is read from `${XDG_DATA_HOME:-~/.local/share}/opencode/auth.json`. Systematic reads only the top-level keys of this file — it never inspects, logs, persists, or transmits the nested credential values.
+
+**Precedence:** The auth-aware resolver only applies when no stronger user override exists. Full precedence for a bundled agent's model:
+
+1. `agents.<key>.model` (user or `$OPENCODE_CONFIG_DIR/systematic.json`)
+2. `categories.<id>.model` (user or `$OPENCODE_CONFIG_DIR/systematic.json`)
+3. Source category model default resolved against authenticated providers
+4. Bundled markdown/frontmatter defaults (unused — bundled agents omit `model`)
+5. OpenCode inherited defaults
+
+User-supplied `agents.<key>.model` and `categories.<id>.model` remain single `provider/model` strings in this iteration — arrays are not accepted in user config. If you supply a scalar model string, the auth-aware resolver is skipped for that agent or category and your overlay is used as-is.
+
+**Limitations:**
+
+- **Environment-variable providers.** Providers that load credentials from environment variables (e.g., AWS Bedrock, with `autoload: true` in OpenCode's provider registry) may not appear in `auth.json`. The resolver skips them and falls back to the first array entry. To override, pin a model via `categories.<id>.model` or `agents.<key>.model`.
+- **Auth-file race window.** OpenCode writes `auth.json` non-atomically; the resolver reads it once at plugin load. If you authenticate after starting OpenCode, restart OpenCode to refresh the resolved model.
+
 ## Project-Specific Content
 
 One of Systematic's most powerful features is the ability to add your own skills and agents that live alongside (or override) the bundled ones.

docs/src/content/docs/getting-started/configuration.mdx

@@ -1,4 +1,5 @@
 import fs from 'node:fs'
+import os from 'node:os'
 import path from 'node:path'
 import type { SourcedOverlayConfigMap } from './config.js'
 import { isAgentMode, isPermissionSetting, isRecord } from './validation.js'
@@ -49,14 +50,17 @@ export interface ResolvedAgentOverlaySet {
   categoriesByKey: Map<string, ValidatedCategoryOverlay>
 }
 
+// Ordered preference lists, most preferred first. The resolver picks the
+// first array entry whose provider is authenticated; entries are not a
+// runtime fallback chain. Keep arrays non-empty.
 const SOURCE_CATEGORY_MODEL_DEFAULTS = {
-  design: 'openai/gpt-5.5',
-  docs: 'openai/gpt-5.4-mini',
-  'document-review': 'anthropic/claude-opus-4.7',
-  research: 'openai/gpt-5.5',
-  review: 'anthropic/claude-opus-4.7',
-  workflow: 'openai/gpt-5.4-mini',
-} as const satisfies Record<string, string>
+  design: ['openai/gpt-5.5', 'anthropic/claude-opus-4.7'],
+  docs: ['openai/gpt-5.4-mini', 'anthropic/claude-haiku-4-5'],
+  'document-review': ['anthropic/claude-opus-4.7', 'openai/gpt-5.5'],
+  research: ['openai/gpt-5.5', 'anthropic/claude-opus-4.7'],
+  review: ['anthropic/claude-opus-4.7', 'openai/gpt-5.5'],
+  workflow: ['openai/gpt-5.4-mini', 'anthropic/claude-haiku-4-5'],
+} as const satisfies Record<string, readonly string[]>
 
 const ALLOWED_OVERLAY_FIELDS = new Set([
   'model',
@@ -178,13 +182,88 @@ export function inferBuiltInTemperature(
   return 0.3
 }
 
+/**
+ * Read which providers are authenticated from OpenCode's auth.json.
+ *
+ * Reads only top-level keys (provider IDs). Nested values are NEVER
+ * inspected, logged, persisted, or transmitted. This is a hard contract:
+ * the auth file holds API keys and OAuth tokens, and Systematic must
+ * never expose them via stderr, telemetry, or any other channel.
+ *
+ * Intended for one invocation per plugin config(cfg) cycle. Repeated
+ * calls trigger repeated file reads and, on malformed input, repeated
+ * stderr diagnostics.
+ *
+ * @param rootDirOverride - Optional path override for tests. When
+ *   non-empty, the auth file is resolved as
+ *   `path.join(rootDirOverride, 'opencode', 'auth.json')`. When
+ *   omitted, resolution follows XDG_DATA_HOME -> ~/.local/share
+ *   convention.
+ * @returns A readonly set of authenticated provider IDs (empty set on
+ *   any failure).
+ */
+export function getAuthenticatedProviders(
+  rootDirOverride?: string,
+): ReadonlySet<string> {
+  const xdgDataHome = process.env.XDG_DATA_HOME?.trim()
+  const rootDir =
+    rootDirOverride ||
+    (xdgDataHome && path.isAbsolute(xdgDataHome)
+      ? xdgDataHome
+      : path.join(os.homedir(), '.local/share'))
+  const authPath = path.join(rootDir, 'opencode', 'auth.json')
+
+  let raw: string
+  try {
+    raw = fs.readFileSync(authPath, 'utf8')
+  } catch (err: unknown) {
+    if (isSystemError(err) && err.code === 'ENOENT') {
+      return new Set()
+    }
+    console.warn(`[systematic] auth.json unreadable at ${authPath}; ignoring`)
+    return new Set()
+  }
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    console.warn(`[systematic] auth.json malformed at ${authPath}; ignoring`)
+    return new Set()
+  }
+
+  if (!isRecord(parsed)) {
+    console.warn(`[systematic] auth.json malformed at ${authPath}; ignoring`)
+    return new Set()
+  }
+
+  return new Set(Object.keys(parsed))
+}
+
 export function getSourceCategoryModel(
   category: string | undefined,
+  authedProviders?: ReadonlySet<string>,
 ): string | undefined {
   if (!category) return undefined
-  return (SOURCE_CATEGORY_MODEL_DEFAULTS as Record<string, string | undefined>)[
-    category
-  ]
+  const candidates = (
+    SOURCE_CATEGORY_MODEL_DEFAULTS as Record<
+      string,
+      readonly string[] | undefined
+    >
+  )[category]
+  if (!candidates || candidates.length === 0) return undefined
+  if (!authedProviders || authedProviders.size === 0) return candidates[0]
+
+  for (const entry of candidates) {
+    const slashIndex = entry.indexOf('/')
+    if (slashIndex <= 0) continue
+    const providerId = entry.slice(0, slashIndex)
+    if (authedProviders.has(providerId)) {
+      return entry
+    }
+  }
+
+  return candidates[0]
 }
 
 export function assertSourceCategoryModelCoverage(categories: string[]): void {
@@ -204,12 +283,24 @@ export function assertSourceCategoryModelCoverage(categories: string[]): void {
 export function validateSourceCategoryModelDefaults(
   defaults: Record<string, unknown> = SOURCE_CATEGORY_MODEL_DEFAULTS,
 ): void {
-  for (const [category, model] of Object.entries(defaults)) {
-    validateModel(
-      'source category model defaults',
-      `source category model defaults.${category}`,
-      model,
-    )
+  for (const [category, value] of Object.entries(defaults)) {
+    if (!Array.isArray(value)) {
+      throw new Error(
+        `Source category model defaults: ${category} must be a non-empty array of provider/model strings`,
+      )
+    }
+    if (value.length === 0) {
+      throw new Error(
+        `Source category model defaults: ${category} must be a non-empty array of provider/model strings`,
+      )
+    }
+    for (const [index, model] of value.entries()) {
+      validateModel(
+        'source category model defaults',
+        `source category model defaults.${category}[${index}]`,
+        model,
+      )
+    }
   }
 }
 
@@ -637,3 +728,12 @@ function throwConfigError(
     `Invalid Systematic config in ${sourcePath}: ${keyPath} ${message}`,
   )
 }
+
+function isSystemError(err: unknown): err is { code: string } {
+  return (
+    typeof err === 'object' &&
+    err !== null &&
+    'code' in err &&
+    typeof (err as { code: unknown }).code === 'string'
+  )
+}

src/lib/agent-overlays.ts

@@ -3,6 +3,7 @@ import type { AgentConfig } from '@opencode-ai/sdk'
 import {
   assertSourceCategoryModelCoverage,
   buildBundledAgentInventory,
+  getAuthenticatedProviders,
   getSourceCategoryModel,
   inferBuiltInTemperature,
   type ResolvedAgentOverlaySet,
@@ -23,6 +24,8 @@ export interface ConfigHandlerDeps {
   bundledSkillsDir: string
   bundledAgentsDir: string
   bundledCommandsDir: string
+  /** Override for authenticated provider reader; for testing. */
+  getAuthenticatedProviders?: (rootDirOverride?: string) => ReadonlySet<string>
 }
 
 type CommandConfig = NonNullable<Config['command']>[string]
@@ -157,6 +160,7 @@ function collectAgents(
   disabledAgents: string[],
   nativeAgents: Record<string, unknown>,
   overlays: ResolvedAgentOverlaySet,
+  authedProviders: ReadonlySet<string>,
 ): NonNullable<Config['agent']> {
   const agents: NonNullable<Config['agent']> = {}
   const agentList = findAgentsInDir(dir)
@@ -174,7 +178,12 @@ function collectAgents(
 
     const config = loadAgentAsConfig(agentInfo)
     if (config) {
-      agents[agentInfo.name] = applyAgentOverlays(config, agentInfo, overlays)
+      agents[agentInfo.name] = applyAgentOverlays(
+        config,
+        agentInfo,
+        overlays,
+        authedProviders,
+      )
     }
   }
 
@@ -185,6 +194,7 @@ function applyAgentOverlays(
   config: AgentConfig,
   agentInfo: { name: string; category?: string },
   overlays: ResolvedAgentOverlaySet,
+  authedProviders: ReadonlySet<string>,
 ): AgentConfig {
   const id = agentInfo.category
     ? `${agentInfo.category}/${agentInfo.name}`
@@ -213,7 +223,10 @@ function applyAgentOverlays(
   // high-trust overlays apply. Precedence: exact overlay > category overlay
   // > source model default > markdown / inheritance.
   if (agentInfo.category) {
-    const sourceModel = getSourceCategoryModel(agentInfo.category)
+    const sourceModel = getSourceCategoryModel(
+      agentInfo.category,
+      authedProviders,
+    )
     if (sourceModel) {
       result.model = sourceModel
     }
@@ -421,6 +434,8 @@ function collectEnabledSkillNames(
 export function createConfigHandler(deps: ConfigHandlerDeps) {
   const { directory, bundledSkillsDir, bundledAgentsDir, bundledCommandsDir } =
     deps
+  const readAuthProviders =
+    deps.getAuthenticatedProviders ?? getAuthenticatedProviders
 
   return async (config: Config): Promise<void> => {
     const { config: systematicConfig, overlays } =
@@ -449,11 +464,13 @@ export function createConfigHandler(deps: ConfigHandlerDeps) {
     })
     const resolvedOverlays = resolveAgentOverlaySet(validatedOverlays)
 
+    const authedProviders = readAuthProviders()
     const bundledAgents = collectAgents(
       bundledAgentsDir,
       systematicConfig.disabled_agents,
       existingAgents,
       resolvedOverlays,
+      authedProviders,
     )
 
     const bundledCommands = collectCommands(

src/lib/config-handler.ts

@@ -128,6 +128,7 @@ describe('SystematicPlugin config hook integration', () => {
     os.homedir = originalHomedir
     _resetPluginSingleton()
     delete process.env.OPENCODE_CONFIG_DIR
+    delete process.env.XDG_DATA_HOME
     fs.rmSync(tempDir, { recursive: true, force: true })
   })
 
@@ -427,6 +428,49 @@ describe('SystematicPlugin config hook integration', () => {
       'nonexistent-provider/nonexistent-model',
     )
   })
+
+  test('auth-aware: single auth provider selects matching model from source defaults', async () => {
+    const authDir = path.join(homeDir, '.local/share', 'opencode')
+    fs.mkdirSync(authDir, { recursive: true })
+    fs.writeFileSync(
+      path.join(authDir, 'auth.json'),
+      JSON.stringify({ openai: { type: 'api', key: 'sk-test' } }),
+    )
+
+    const config: Config = {}
+    await runConfigHook(config)
+
+    // review category: ['anthropic/claude-opus-4.7', 'openai/gpt-5.5']
+    // With openai auth, resolver picks openai/gpt-5.5
+    expect(config.agent?.['correctness-reviewer']?.model).toBe('openai/gpt-5.5')
+  })
+
+  test('auth-aware: multi-provider auth picks correct models per category', async () => {
+    const authDir = path.join(homeDir, '.local/share', 'opencode')
+    fs.mkdirSync(authDir, { recursive: true })
+    fs.writeFileSync(
+      path.join(authDir, 'auth.json'),
+      JSON.stringify({
+        'github-copilot': { type: 'api' },
+        anthropic: { type: 'api' },
+      }),
+    )
+
+    const config: Config = {}
+    await runConfigHook(config)
+
+    // review category: ['anthropic/claude-opus-4.7', 'openai/gpt-5.5']
+    // With anthropic authed, picks anthropic/claude-opus-4.7 (first match)
+    expect(config.agent?.['correctness-reviewer']?.model).toBe(
+      'anthropic/claude-opus-4.7',
+    )
+
+    // docs category: ['openai/gpt-5.4-mini', 'anthropic/claude-haiku-4-5']
+    // openai not authed, anthropic is → picks anthropic/claude-haiku-4-5
+    expect(config.agent?.['ankane-readme-writer']?.model).toBe(
+      'anthropic/claude-haiku-4-5',
+    )
+  })
 })
 
 describe.skipIf(!OPENCODE_AVAILABLE)('opencode integration', () => {