pantheon-opencode 1.6.0-beta.1 → 1.6.0-beta.11

package/src/pantheon/v2-delegation-enforce.ts

@@ -0,0 +1,214 @@
+/** V2 caller/target policy and one-shot host tool-origin correlation. */
+
+export const PANTHEON_AGENTS: ReadonlySet<string> = new Set([
+  'zeus',
+  'athena',
+  'apollo',
+  'hermes',
+  'aphrodite',
+  'demeter',
+  'themis',
+  'prometheus',
+  'hephaestus',
+  'nyx',
+  'gaia',
+  'iris',
+  'mnemosyne',
+  'talos',
+])
+
+export interface V2PermissionEvent {
+  sessionID?: unknown
+  action?: unknown
+  resources?: unknown
+  /** Optional event identity is cross-checked against the host tool event. */
+  agent?: unknown
+  source?: unknown
+  /** Mutable decision fields exposed by OpenCode V2's evaluate hook. */
+  effect?: unknown
+  message?: unknown
+}
+
+export interface V2SubagentOrigin {
+  sessionID: string
+  messageID: string
+  callID: string
+  caller: string
+  target: string
+}
+
+interface StoredV2SubagentOrigin extends V2SubagentOrigin {
+  capturedAt: number
+}
+
+const ORIGIN_TTL_MS = 60_000
+const MAX_PENDING_ORIGINS = 256
+
+function originKey(sessionID: string, messageID: string, callID: string): string {
+  return JSON.stringify([sessionID, messageID, callID])
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined
+  const trimmed = value.trim()
+  return trimmed.length === 0 ? undefined : trimmed
+}
+
+/**
+ * One-shot correlation between the host's tool.execute.before event and the
+ * permission evaluation emitted from inside that same native tool call.
+ * Entries are short-lived and bounded; missing, stale, or uncorrelated origin
+ * data can only make admission fail closed.
+ */
+export class V2SubagentOriginRegistry {
+  private readonly entries = new Map<string, StoredV2SubagentOrigin>()
+
+  capture(rawEvent: unknown, now = Date.now()): V2SubagentOrigin | undefined {
+    this.prune(now)
+    if (rawEvent === null || typeof rawEvent !== 'object' || Array.isArray(rawEvent)) {
+      return undefined
+    }
+    const event = rawEvent as {
+      tool?: unknown
+      sessionID?: unknown
+      messageID?: unknown
+      id?: unknown
+      agent?: unknown
+      input?: unknown
+    }
+    if (event.tool !== 'subagent' || event.input === null || typeof event.input !== 'object') {
+      return undefined
+    }
+    const input = event.input as { agent?: unknown }
+    const sessionID = nonEmptyString(event.sessionID)
+    const messageID = nonEmptyString(event.messageID)
+    const callID = nonEmptyString(event.id)
+    const caller = agentName(event.agent)
+    const target = agentName(input.agent)
+    if (
+      sessionID === undefined ||
+      messageID === undefined ||
+      callID === undefined ||
+      caller === undefined ||
+      target === undefined ||
+      !PANTHEON_AGENTS.has(target) ||
+      this.entries.size >= MAX_PENDING_ORIGINS
+    ) {
+      return undefined
+    }
+
+    const origin = { sessionID, messageID, callID, caller, target }
+    this.entries.set(originKey(sessionID, messageID, callID), { ...origin, capturedAt: now })
+    return origin
+  }
+
+  /** Remove and return the matching origin, so one tool event authorizes once. */
+  consume(event: V2PermissionEvent, now = Date.now()): V2SubagentOrigin | undefined {
+    this.prune(now)
+    const source = event.source as { type?: unknown; messageID?: unknown; id?: unknown } | undefined
+    if (source?.type !== 'tool') return undefined
+    const sessionID = nonEmptyString(event.sessionID)
+    const messageID = nonEmptyString(source.messageID)
+    const callID = nonEmptyString(source.id)
+    if (sessionID === undefined || messageID === undefined || callID === undefined) return undefined
+    const key = originKey(sessionID, messageID, callID)
+    const origin = this.entries.get(key)
+    this.entries.delete(key)
+    if (origin === undefined) return undefined
+    const { capturedAt: _capturedAt, ...result } = origin
+    return result
+  }
+
+  /** Cleanup when a subagent tool exits without reaching permission.evaluate. */
+  forget(rawEvent: unknown): void {
+    if (rawEvent === null || typeof rawEvent !== 'object' || Array.isArray(rawEvent)) return
+    const event = rawEvent as {
+      tool?: unknown
+      sessionID?: unknown
+      messageID?: unknown
+      id?: unknown
+    }
+    if (event.tool !== 'subagent') return
+    const sessionID = nonEmptyString(event.sessionID)
+    const messageID = nonEmptyString(event.messageID)
+    const callID = nonEmptyString(event.id)
+    if (sessionID === undefined || messageID === undefined || callID === undefined) return
+    this.entries.delete(originKey(sessionID, messageID, callID))
+  }
+
+  private prune(now: number): void {
+    for (const [key, origin] of this.entries) {
+      if (now - origin.capturedAt > ORIGIN_TTL_MS) this.entries.delete(key)
+    }
+  }
+}
+
+export interface AuthoritativeSession {
+  id?: unknown
+  parentID?: unknown
+}
+
+export type V2DelegationDecision = 'allow' | 'deny' | 'passthrough' | 'preserve-deny'
+
+function agentName(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined
+  const valueNormalized = value.trim().toLowerCase()
+  return valueNormalized.length === 0 ? undefined : valueNormalized
+}
+
+/** Extract the target from the host's resource string or `{ target }` entry. */
+export function v2ResourceTarget(resource: unknown): string | undefined {
+  if (typeof resource === 'string') return agentName(resource)
+  if (resource === null || typeof resource !== 'object' || Array.isArray(resource)) return undefined
+  return agentName((resource as { target?: unknown }).target)
+}
+
+/**
+ * Decide whether a permission evaluation is a Pantheon-managed delegation.
+ * Native/custom-to-native/custom calls are left entirely to host permissions.
+ */
+export function evaluateV2Delegation(
+  event: V2PermissionEvent,
+  session: AuthoritativeSession | undefined,
+  existingStatus?: unknown,
+  origin?: V2SubagentOrigin,
+): V2DelegationDecision {
+  if (existingStatus === 'deny') return 'preserve-deny'
+
+  if (!Array.isArray(event.resources) || event.resources.length === 0) return 'deny'
+  const rawTargets = event.resources.map(v2ResourceTarget)
+  if (rawTargets.some((target) => target === undefined)) return 'deny'
+  const targets = rawTargets.filter((target): target is string => target !== undefined)
+  const pantheonTargets = targets.filter((target) => PANTHEON_AGENTS.has(target))
+  if (pantheonTargets.length === 0) return 'passthrough'
+  if (event.action !== 'subagent' || targets.length !== 1 || origin === undefined) return 'deny'
+  const sessionID = typeof event.sessionID === 'string' ? event.sessionID : undefined
+  const caller = agentName(origin.caller)
+  if (
+    sessionID === undefined ||
+    session === undefined ||
+    session.id !== sessionID ||
+    caller === undefined ||
+    origin.sessionID !== sessionID ||
+    origin.target !== pantheonTargets[0]
+  ) {
+    return 'deny'
+  }
+  const source = event.source as { type?: unknown; messageID?: unknown; id?: unknown } | undefined
+  if (
+    source?.type !== 'tool' ||
+    source.messageID !== origin.messageID ||
+    source.id !== origin.callID
+  ) {
+    return 'deny'
+  }
+  const eventCaller = agentName(event.agent)
+  if (eventCaller !== undefined && eventCaller !== caller) return 'deny'
+  if (session.parentID !== undefined && session.parentID !== null) {
+    return 'deny'
+  }
+
+  const callerMayTarget = (target: string): boolean =>
+    caller === 'zeus' || ((caller === 'athena' || caller === 'hermes') && target === 'apollo')
+  return pantheonTargets.every(callerMayTarget) ? 'allow' : 'deny'
+}

package/src/pantheon/v2-execute-after.ts

@@ -0,0 +1,186 @@
+/**
+ * V2 `execute.after` parity adapter — reproduces the V1 post-tool chain on the
+ * V2 tool-event surface.
+ *
+ * V1 (`src/plugin.ts`) wires a single `tool.execute.after` handler that runs,
+ * in order:
+ *   1. task-result-guard — an empty native `task()` result becomes an explicit
+ *      error so the parent LLM cannot read silence as success;
+ *   2. context-sandbox   — oversized read/grep/glob/webfetch output is truncated
+ *      with a marker + metadata;
+ *   3. read-enhancer     — a `read` result gains per-line hashline tags
+ *      (`N#TAG|content`) so `hashline_edit` refs resolve.
+ *
+ * On a V2-only install (`opencode.json` `plugins` declares only `plugin-v2`),
+ * `src/plugin.ts` is NOT loaded, so that chain does not exist. `plugin-v2.ts`
+ * registered an `execute.after` hook but with an empty body, so the chain was
+ * dead on V2. This module rebuilds it against the REAL V2 event shape.
+ *
+ * The V2 event (opencode 2.0.x `ToolHooks["execute.after"]`) is ONE object:
+ *
+ *   { tool, sessionID, agent, messageID, id, input } & (
+ *       { status: 'completed'; result: Tool.Result } |
+ *       { status: 'error'; error: Tool.Error } )
+ *
+ * where `Tool.Result = { output?, content?, metadata? }`. This adapter only
+ * acts on `status === 'completed'`; an ERROR event is left untouched — V1's own
+ * behaviour on a tool error was never verified, so this module does not claim
+ * after-on-error semantics.
+ *
+ * Fail-safe: every path is wrapped so an unexpected shape can never break the
+ * tool result the host is about to surface.
+ *
+ * @module pantheon/v2-execute-after
+ */
+
+import {
+  type ContextSandboxConfig,
+  createContextSandbox,
+  resolveSandboxConfig,
+  DEFAULT_CONFIG as SANDBOX_DEFAULT_CONFIG,
+} from './context-sandbox.ts'
+import { createReadEnhancer } from './hashline/read-enhancer.ts'
+import { createTaskResultGuard } from './task-result-guard.ts'
+
+/** The `Tool.Result` fields this adapter reads and writes back. */
+export interface V2ToolResult {
+  output?: unknown
+  content?: unknown
+  metadata?: unknown
+}
+
+/** The completed, non-error `execute.after` event as the 2.0.x host dispatches it. */
+export interface V2ExecuteAfterEvent {
+  tool?: unknown
+  sessionID?: unknown
+  id?: unknown
+  input?: unknown
+  status?: unknown
+  result?: unknown
+}
+
+/** Options for {@link createV2ExecuteAfter}. */
+export interface V2ExecuteAfterOptions {
+  /**
+   * Sandbox config, normally derived from `ctx.options.context_sandbox` via
+   * {@link resolveSandboxConfig}. Defaults to the shared defaults.
+   */
+  sandbox?: ContextSandboxConfig
+}
+
+/** Which `Tool.Result` field carries the (mutable) text this adapter enhances. */
+type TextField = 'output' | 'content' | 'content-array'
+
+/**
+ * Extract the mutable text from a `Tool.Result`.
+ *
+ * Preference order mirrors what a session renders: a declared string `output`
+ * first, then a string `content`, then the concatenation of `content` text
+ * parts. A `content` array containing non-text (file) parts is deliberately NOT
+ * enhanced — replacing it would corrupt the structured payload, so it is
+ * reported as unextractable and the whole event becomes a no-op.
+ *
+ * @returns `{ text, field }` or `null` when there is nothing to enhance.
+ */
+function extractText(result: V2ToolResult): { text: string; field: TextField } | null {
+  if (typeof result.output === 'string') return { text: result.output, field: 'output' }
+  if (typeof result.content === 'string') return { text: result.content, field: 'content' }
+  if (Array.isArray(result.content)) {
+    const parts = result.content
+    const allText = parts.every(
+      (part) => typeof part === 'string' || (part as { type?: unknown })?.type === 'text',
+    )
+    if (!allText || parts.length === 0) return null
+    const text = parts
+      .map((part) => (typeof part === 'string' ? part : ((part as { text?: string }).text ?? '')))
+      .join('\n')
+    return { text, field: 'content-array' }
+  }
+  return null
+}
+
+/**
+ * Write enhanced text back into the SAME field it came from, preserving the
+ * result's other fields.
+ */
+function writeText(result: V2ToolResult, field: TextField, text: string): void {
+  if (field === 'output') {
+    result.output = text
+  } else if (field === 'content') {
+    result.content = text
+  } else {
+    result.content = [{ type: 'text', text }]
+  }
+}
+
+/**
+ * Build the V2 `execute.after` handler that runs the V1 parity chain.
+ *
+ * @param options - see {@link V2ExecuteAfterOptions}
+ * @returns a handler suitable for `ctx.tool.hook('execute.after', …)`
+ */
+export function createV2ExecuteAfter(
+  options: V2ExecuteAfterOptions = {},
+): (event: unknown) => Promise<void> {
+  const taskResultGuard = createTaskResultGuard()
+  const sandbox = createContextSandbox(options.sandbox ?? SANDBOX_DEFAULT_CONFIG)
+  const readEnhancer = createReadEnhancer()
+
+  return async function v2ExecuteAfter(event: unknown): Promise<void> {
+    try {
+      if (event === null || typeof event !== 'object' || Array.isArray(event)) return
+      const payload = event as V2ExecuteAfterEvent
+      // Only a completed result has a result to augment; an error event is left
+      // untouched (no after-on-error semantics are claimed).
+      if (payload.status !== 'completed') return
+
+      const result = payload.result
+      if (result === null || typeof result !== 'object' || Array.isArray(result)) return
+
+      const tool = typeof payload.tool === 'string' ? payload.tool : ''
+      const sessionID = typeof payload.sessionID === 'string' ? payload.sessionID : ''
+      const callID = typeof payload.id === 'string' ? payload.id : ''
+
+      const extracted = extractText(result as V2ToolResult)
+      // A `task` result may carry no text at all — that IS the empty-result
+      // failure the guard exists to surface, so synthesize an empty string and
+      // let the guard replace it. Other tools with no text are a no-op.
+      if (extracted === null && tool !== 'task') return
+      const original = extracted === null ? { text: '', field: 'output' as TextField } : extracted
+
+      const input = { tool, sessionID, callID, args: payload.input }
+      const output: {
+        output: string
+        metadata?: Record<string, unknown>
+      } = { output: original.text }
+
+      await taskResultGuard(input, output)
+      await sandbox(input, output)
+      await readEnhancer(input, output)
+
+      if (output.output !== original.text) {
+        writeText(result as V2ToolResult, original.field, output.output)
+      }
+      // Surface sandbox metadata onto the result (merge, never replace). It is
+      // only present when the sandbox actually truncated something.
+      if (output.metadata && Object.keys(output.metadata).length > 0) {
+        ;(result as V2ToolResult).metadata = {
+          ...((result as V2ToolResult).metadata as Record<string, unknown> | undefined),
+          ...output.metadata,
+        }
+      }
+    } catch {
+      // Fail-safe: an unexpected shape must never break the tool result.
+    }
+  }
+}
+
+/**
+ * Resolve a sandbox config from a V2 plugin's `ctx.options.context_sandbox`.
+ * Exposed so `plugin-v2.ts` resolves it the SAME way V1's config hook does,
+ * rather than silently constructing defaults.
+ */
+export function resolveV2SandboxConfig(options: unknown): ContextSandboxConfig {
+  const raw = (options as { context_sandbox?: unknown } | null | undefined)?.context_sandbox
+  return resolveSandboxConfig(raw)
+}

package/src/pantheon/v2-model-overrides.ts

@@ -0,0 +1,275 @@
+import { closeSync, constants, fstatSync, openSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { KNOWN_AGENTS } from './model-agents.ts'
+import { capabilityEntry, normalizeCapability } from './presets.mjs'
+
+export interface V2ModelOverride {
+  model: string
+  variant?: 'low' | 'medium' | 'high'
+}
+
+export interface V2ModelConfiguration {
+  overrides: Record<string, V2ModelOverride>
+  legacyPresetMarker: { source: 'env' | 'file' } | null
+  warnings: string[]
+}
+
+export interface V2AgentDraftLike {
+  list(): readonly { id: string }[]
+  update(id: string, update: (agent: { id: string; model?: unknown }) => void): void
+}
+
+interface AgentModelLike {
+  id: string
+  model?: unknown
+}
+
+const MODEL_REF_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._:+-]*$/
+const VARIANTS = new Set(['low', 'medium', 'high'])
+const KNOWN_AGENTS_SET = new Set<string>(KNOWN_AGENTS)
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function isVariant(value: unknown): value is NonNullable<V2ModelOverride['variant']> {
+  return typeof value === 'string' && VARIANTS.has(value)
+}
+
+function isSupportedModelChoice(model: unknown, variant: unknown): model is string {
+  if (typeof model !== 'string' || !MODEL_REF_PATTERN.test(model)) return false
+  if (variant !== undefined && !isVariant(variant)) return false
+  try {
+    capabilityEntry(model)
+    if (variant === undefined) return true
+    const normalized = normalizeCapability(model, variant)
+    return !normalized.clamped && normalized.variant === variant
+  } catch {
+    return false
+  }
+}
+
+interface PresetFileSystem {
+  openSync(path: string, flags: number): number
+  fstatSync(fileDescriptor: number): { isFile(): boolean }
+  readFileSync(fileDescriptor: number, encoding: 'utf8'): string
+  closeSync(fileDescriptor: number): void
+}
+
+class SecurePresetReadUnavailableError extends Error {
+  constructor() {
+    super('Secure preset-file opening is unavailable')
+  }
+}
+
+class NonRegularPresetFileError extends Error {
+  constructor() {
+    super('Preset file is not a regular file')
+  }
+}
+
+/** Open and read a regular preset file without following links or blocking on special files. */
+export function readV2PresetFile(
+  candidate: string,
+  fileSystem: PresetFileSystem = { openSync, fstatSync, readFileSync, closeSync },
+): string {
+  const noFollowFlag = constants.O_NOFOLLOW
+  const nonBlockFlag = constants.O_NONBLOCK
+  if (
+    noFollowFlag === undefined ||
+    noFollowFlag === 0 ||
+    nonBlockFlag === undefined ||
+    nonBlockFlag === 0
+  ) {
+    throw new SecurePresetReadUnavailableError()
+  }
+
+  let fileDescriptor: number | undefined
+  try {
+    fileDescriptor = fileSystem.openSync(
+      candidate,
+      constants.O_RDONLY | noFollowFlag | nonBlockFlag,
+    )
+    if (!fileSystem.fstatSync(fileDescriptor).isFile()) {
+      throw new NonRegularPresetFileError()
+    }
+    return fileSystem.readFileSync(fileDescriptor, 'utf8')
+  } finally {
+    if (fileDescriptor !== undefined) fileSystem.closeSync(fileDescriptor)
+  }
+}
+
+function parseOverrides(
+  value: Record<string, unknown>,
+  warnings: string[],
+): Record<string, V2ModelOverride> {
+  const parsed: Record<string, V2ModelOverride> = {}
+  for (const [agent, raw] of Object.entries(value)) {
+    if (!KNOWN_AGENTS_SET.has(agent)) {
+      warnings.push(
+        'Override entry ignored for an unsupported agent; use one of the canonical Pantheon agent IDs.',
+      )
+      continue
+    }
+    const entry = isRecord(raw) ? raw : undefined
+    const hasVariant = entry !== undefined && Object.hasOwn(entry, 'variant')
+    const variant = hasVariant ? entry?.variant : entry?.reasoning_effort
+    const model = entry?.model
+    if (!entry || (hasVariant && !isVariant(variant)) || !isSupportedModelChoice(model, variant)) {
+      warnings.push(
+        'Override entry ignored because its model or variant is unsupported; choose a supported model and reasoning variant.',
+      )
+      continue
+    }
+    const override: V2ModelOverride = { model }
+    if (isVariant(variant)) override.variant = variant
+    parsed[agent] = override
+  }
+  return parsed
+}
+
+function defaultCandidates(): string[] {
+  return [join(process.cwd(), '.pantheon', 'active-preset.json')]
+}
+
+/** Read explicit per-agent project overrides only; global files are ignored in V2. */
+export function readV2ModelConfiguration(
+  options: { candidates?: string[]; env?: NodeJS.ProcessEnv } = {},
+): V2ModelConfiguration {
+  const env = options.env ?? process.env
+  const envName = env.PANTHEON_MODEL_PRESET?.trim()
+  let fileMarkerPresent = false
+  const configurations: Array<Record<string, V2ModelOverride>> = []
+  const warnings: string[] = []
+  let readFailure = false
+
+  // `model-command` passes project before global candidates. Keep this reader
+  // project-only even if a caller supplies the legacy candidate list.
+  const candidates = options.candidates ?? defaultCandidates()
+  for (const candidate of candidates.slice(0, 1)) {
+    let rawContent: string
+    try {
+      rawContent = readV2PresetFile(candidate)
+    } catch (error: unknown) {
+      if (error instanceof Error && 'code' in error && error.code === 'ENOENT') continue
+      if (error instanceof SecurePresetReadUnavailableError) {
+        warnings.push(
+          'V2 project model configuration cannot be read securely on this platform; manual overrides were not applied.',
+        )
+        readFailure = true
+        break
+      }
+      if (
+        error instanceof NonRegularPresetFileError ||
+        (error instanceof Error && 'code' in error && error.code === 'ELOOP')
+      ) {
+        warnings.push(
+          'V2 project model configuration is not a regular file or is a symlink; check active-preset.json. Manual overrides were not applied.',
+        )
+        readFailure = true
+        break
+      }
+      warnings.push(
+        'V2 project model configuration could not be read; check active-preset.json file access. Manual overrides were not applied.',
+      )
+      readFailure = true
+      break
+    }
+
+    let raw: unknown
+    try {
+      raw = JSON.parse(rawContent)
+    } catch {
+      warnings.push(
+        'V2 project model configuration contains invalid JSON; correct active-preset.json. Manual overrides were not applied.',
+      )
+      readFailure = true
+      break
+    }
+    if (!isRecord(raw)) {
+      warnings.push(
+        'V2 project model configuration has an invalid shape; correct active-preset.json. Manual overrides were not applied.',
+      )
+      readFailure = true
+      break
+    }
+
+    if (Object.hasOwn(raw, 'preset')) fileMarkerPresent = true
+    let parsedOverrides: Record<string, V2ModelOverride> = {}
+    if (Object.hasOwn(raw, 'overrides')) {
+      if (!isRecord(raw.overrides)) {
+        warnings.push(
+          'V2 project model configuration has an invalid `overrides` object; expected an object in active-preset.json. The project file contributed no manual overrides.',
+        )
+      } else if (Object.hasOwn(raw.overrides, 'agents')) {
+        if (!isRecord(raw.overrides.agents)) {
+          warnings.push(
+            'V2 project model configuration has invalid `overrides.agents`; expected an object in active-preset.json. The project file contributed no manual overrides.',
+          )
+        } else {
+          parsedOverrides = parseOverrides(raw.overrides.agents, warnings)
+        }
+      }
+    }
+    configurations.push(parsedOverrides)
+  }
+
+  const envMarkerPresent = typeof envName === 'string' && envName.length > 0
+  const markerSource: 'env' | 'file' | null = envMarkerPresent
+    ? 'env'
+    : fileMarkerPresent
+      ? 'file'
+      : null
+
+  // A project-file read/parse failure fails closed. Malformed entries warn but
+  // leave other valid project entries available.
+  const overrides: Record<string, V2ModelOverride> = {}
+  if (!readFailure) {
+    Object.assign(overrides, configurations[0] ?? {})
+  }
+  return {
+    overrides,
+    legacyPresetMarker: markerSource === null ? null : { source: markerSource },
+    warnings,
+  }
+}
+
+/** Apply one explicit model override while leaving all other agent settings intact. */
+export function applyV2ModelOverride(
+  agent: AgentModelLike,
+  override: V2ModelOverride | undefined,
+): void {
+  if (
+    !KNOWN_AGENTS_SET.has(agent.id) ||
+    !override ||
+    !isSupportedModelChoice(override.model, override.variant)
+  ) {
+    return
+  }
+  const separator = override.model.indexOf('/')
+  const previous = isRecord(agent.model) ? agent.model : {}
+  const model: Record<string, unknown> = {
+    ...previous,
+    providerID: override.model.slice(0, separator),
+    id: override.model.slice(separator + 1),
+  }
+  if (override.variant !== undefined) {
+    model.variant = override.variant
+  } else {
+    delete model.variant
+  }
+  agent.model = model
+}
+
+/** Apply explicit overrides to matching agents and leave unmatched host defaults untouched. */
+export function applyV2ModelOverrides(
+  draft: V2AgentDraftLike,
+  overrides: Record<string, V2ModelOverride>,
+): void {
+  for (const agent of draft.list()) {
+    if (!KNOWN_AGENTS_SET.has(agent.id)) continue
+    const override = overrides[agent.id]
+    if (!override) continue
+    draft.update(agent.id, (current) => applyV2ModelOverride(current, override))
+  }
+}