From 4efafa93924bf767ed8de53626ca316ea41eea3e Mon Sep 17 00:00:00 2001 From: "petar.minev" <144934217+pminev1@users.noreply.github.com> Date: Thu, 24 Sep 2026 23:05:36 +0300 Subject: [PATCH] feat(XCOD-82): configurable subagent model selection (part 1 of XCOD-82) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Resolution, first match wins: per-call (only if subagent.dynamic.enabled and on subagent.dynamic.allow; anything else is refused, never replaced) → per-type agent..model → global subagent.model → inherit. Values: "inherit", "small" (small_model, else inherit), "provider/model". - agent/subagent-model.ts: pure resolver returning the model, variant, rule and source. checkResidency() runs before the subagent session starts; a denial names the rule ("agent.qa.model → anthropic/... denied by residency policy") and is written to the residency audit log. - Reasoning variant: inherited models keep the main agent's variant; overridden models use the configured variant or the model default. This removes the silent variant drop at task.ts:209. - Resume keeps the original run's model unless the call explicitly picks another allowed model. - Task tool: `model` is only in the JSON schema when dynamic selection is enabled, as an enum of allowed models minus residency-denied ones. It is added per request in the tool registry. - Metadata: model, modelRule and modelSource on every task call. - Config: `subagent` declared in ConfigV1.Info and the v2 schema; agent..model keeps its raw spec so "small"/"inherit" survive. - Docs: agents.mdx "Choosing models for subagents", deployment guide note, CHANGELOG. Real runs (test/cli/run/subagent-model.test.ts; the scripted LLM records the model each request actually used): no config → subagent on the main model; agent.explore.model "small" → explore called small-model; subagent.model → global; dynamic allowed → per-call, off-list → tool error; residency-denied per-type model → refused before start, never called, audit line written. Removing checkResidency fails the last case. Not in this part: graduating the background flag, the monitoring surface, and lifecycle semantics. Those are the rest of XCOD-82. Co-Authored-By: Claude Opus 5.5 (1M context) --- CHANGELOG.md | 6 + docs/deployment/self-hosted.md | 1 + packages/core/src/config.ts | 4 + packages/core/src/config/subagent.ts | 28 +++ packages/core/src/v1/config/config.ts | 4 + packages/opencode/src/agent/agent.ts | 8 +- packages/opencode/src/agent/subagent-model.ts | 132 +++++++++++++ packages/opencode/src/tool/registry.ts | 15 +- packages/opencode/src/tool/task.ts | 78 +++++++- .../test/agent/subagent-model.test.ts | 90 +++++++++ .../test/cli/run/subagent-model.test.ts | 174 ++++++++++++++++++ packages/opencode/test/config/config.test.ts | 24 +++ .../__snapshots__/parameters.test.ts.snap | 4 + packages/sdk/js/src/v2/gen/types.gen.ts | 11 ++ packages/sdk/openapi.json | 33 ++++ packages/web/src/content/docs/agents.mdx | 49 +++++ 16 files changed, 653 insertions(+), 8 deletions(-) create mode 100644 packages/core/src/config/subagent.ts create mode 100644 packages/opencode/src/agent/subagent-model.ts create mode 100644 packages/opencode/test/agent/subagent-model.test.ts create mode 100644 packages/opencode/test/cli/run/subagent-model.test.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index 742b7edcc2fe..35bd7ff62a54 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,6 +25,12 @@ reasoning behind a change are published separately as **Lunos Notes**. ### Added +- **Choose which model each subagent uses.** `agent..model` now accepts `"inherit"` and + `"small"` as well as `provider/model`. The new `subagent.model` sets a default for every + subagent, and `subagent.dynamic` lets the main agent pick a model per task, from a list you allow. + Subagent models are checked against the residency policy before they start. An inherited model + keeps the main agent's reasoning variant; before this, the variant was dropped whenever a model + was configured. - **Skills can restrict the agent's tools** with `allowed-tools` in `SKILL.md`, in Claude Code's format. The restriction applies from when the skill loads to the end of the turn, through the permission system. Hook scripts now receive `LUNOS_AGENT` and `LUNOS_SKILL`. `research-mode` diff --git a/docs/deployment/self-hosted.md b/docs/deployment/self-hosted.md index 93923169d06d..5a7438c6f634 100644 --- a/docs/deployment/self-hosted.md +++ b/docs/deployment/self-hosted.md @@ -184,6 +184,7 @@ With that in place: - **Every outbound model call is recorded** to a local audit log with timestamp, provider, jurisdiction and destination host. Blocked attempts are recorded too. The log never contains request contents. - **Providers whose region cannot be verified are denied,** including ones that _could_ be EU (Azure, AWS Bedrock, Google Vertex). Their region is a choice made in your cloud account, which the software cannot inspect — so permitting them automatically would let an unverified US-region resource pass a policy claiming to enforce EU residency. You may opt in explicitly once you have verified the region. - **Providers with no recorded jurisdiction are always denied.** +- **Subagents are checked too.** A subagent's model is checked against the policy before the subagent starts. If you assign models to subagents, keep them on EU providers with per-type settings: for example `"agent": { "explore": { "model": "small" } }`, where `small_model` is also an EU provider. See "Choosing models for subagents" in the agents documentation. Full reference, including the audit log format and how to opt into configurable providers: [Data residency controls](../data-residency.md). diff --git a/packages/core/src/config.ts b/packages/core/src/config.ts index b60bfe2f180f..80faeb9b2487 100644 --- a/packages/core/src/config.ts +++ b/packages/core/src/config.ts @@ -23,6 +23,7 @@ import { ConfigPlugin } from "./config/plugin" import { ConfigProvider } from "./config/provider" import { ConfigReference } from "./config/reference" import { ConfigResidency } from "./config/residency" +import { ConfigSubagent } from "./config/subagent" import { ConfigToolOutput } from "./config/tool-output" import { ConfigWatcher } from "./config/watcher" import { ConfigV1 } from "./v1/config/config" @@ -109,6 +110,9 @@ export class Info extends Schema.Class("Config.Info")({ }), experimental: ConfigExperimental.Experimental.pipe(Schema.optional), providers: Schema.Record(Schema.String, ConfigProvider.Info).pipe(Schema.optional), + subagent: ConfigSubagent.Info.pipe(Schema.optional).annotate({ + description: "How subagents choose their model: inherit, small_model, a fixed model, or per task", + }), residency: ConfigResidency.Info.pipe(Schema.optional).annotate({ description: "Data-residency policy restricting which provider jurisdictions this deployment may use, with an audit log of outbound model calls", diff --git a/packages/core/src/config/subagent.ts b/packages/core/src/config/subagent.ts new file mode 100644 index 000000000000..04f41f0117b9 --- /dev/null +++ b/packages/core/src/config/subagent.ts @@ -0,0 +1,28 @@ +export * as ConfigSubagent from "./subagent" + +import { Schema } from "effect" + +/** + * How subagents choose their model (XCOD-82). Declared in both the v1 and v2 config schemas, so + * the live config path keeps it (the XCOD-68 / XCOD-93 lesson). + */ +export const Info = Schema.Struct({ + model: Schema.String.pipe(Schema.optional).annotate({ + description: + 'Default model for every subagent without its own agent..model: "inherit" (the main agent\'s model, the default), "small" (small_model) or "provider/model"', + }), + variant: Schema.String.pipe(Schema.optional).annotate({ + description: 'Reasoning variant for subagents whose model is overridden: "inherit" or a variant name', + }), + dynamic: Schema.Struct({ + enabled: Schema.Boolean.pipe(Schema.optional).annotate({ + description: "Let the main agent choose a model per task call, from `allow` only", + }), + allow: Schema.Array(Schema.String).pipe(Schema.optional).annotate({ + description: 'Models the main agent may choose per task call ("provider/model")', + }), + }) + .pipe(Schema.optional) + .annotate({ description: "Per-task model selection by the main agent" }), +}).annotate({ identifier: "SubagentConfig" }) +export type Info = Schema.Schema.Type diff --git a/packages/core/src/v1/config/config.ts b/packages/core/src/v1/config/config.ts index 2e6c4f3cc15c..0506a89939fa 100644 --- a/packages/core/src/v1/config/config.ts +++ b/packages/core/src/v1/config/config.ts @@ -18,6 +18,7 @@ import { ConfigServerV1 } from "./server" import { ConfigSkillsV1 } from "./skills" import { ConfigHooks } from "../../config/hooks" import { ConfigResidency } from "../../config/residency" +import { ConfigSubagent } from "../../config/subagent" export type Layout = ConfigLayoutV1.Layout @@ -92,6 +93,9 @@ export const Info = Schema.Struct({ description: "Default agent to use when none is specified. Must be a primary agent. Falls back to 'build' if not set or if the specified agent is invalid.", }), + subagent: Schema.optional(ConfigSubagent.Info).annotate({ + description: "How subagents choose their model: inherit, small_model, a fixed model, or per task", + }), subagent_depth: Schema.optional(NonNegativeInt).annotate({ description: "Maximum subagent nesting depth. Defaults to 1, which prevents subagents from launching subagents.", }), diff --git a/packages/opencode/src/agent/agent.ts b/packages/opencode/src/agent/agent.ts index 31f535c51fd2..947fa4994943 100644 --- a/packages/opencode/src/agent/agent.ts +++ b/packages/opencode/src/agent/agent.ts @@ -52,6 +52,8 @@ export const Info = Schema.Struct({ }), ), variant: Schema.optional(Schema.String), + /** Raw `agent..model` from config: `"inherit"`, `"small"` or `"provider/model"` (XCOD-82). */ + modelSpec: Schema.optional(Schema.String), prompt: Schema.optional(Schema.String), options: Schema.Record(Schema.String, Schema.Unknown), steps: Schema.optional(Schema.Finite), @@ -420,7 +422,11 @@ const layer = Layer.effect( options: {}, native: false, } - if (value.model) item.model = Provider.parseModel(value.model) + if (value.model) { + item.modelSpec = value.model + // "inherit" and "small" are resolved per task call (agent/subagent-model.ts), not here. + if (value.model !== "inherit" && value.model !== "small") item.model = Provider.parseModel(value.model) + } item.variant = value.variant ?? item.variant item.prompt = value.prompt ?? item.prompt item.description = value.description ?? item.description diff --git a/packages/opencode/src/agent/subagent-model.ts b/packages/opencode/src/agent/subagent-model.ts new file mode 100644 index 000000000000..0dc195bd7dfe --- /dev/null +++ b/packages/opencode/src/agent/subagent-model.ts @@ -0,0 +1,132 @@ +export * as SubagentModel from "./subagent-model" + +import path from "path" +import { Global } from "@opencode-ai/core/global" +import { Residency } from "@opencode-ai/core/residency" + +/** + * Which model a subagent runs on, and which rule chose it (XCOD-82). First match wins: + * + * 1. `per-call`: the main agent's `model` argument, only when `subagent.dynamic.enabled` and the + * model is on `subagent.dynamic.allow`. Anything else is refused, never silently replaced. + * 2. `per-type`: `agent..model`. + * 3. `global`: `subagent.model`. + * 4. `inherit`: the main agent's current model. This is the default and matches upstream. + * + * Values: `"inherit"` means the main agent's model, `"small"` means `small_model` (or inherit if + * that isn't set), and `"provider/model"` means that exact model. + */ + +export type Rule = "per-call" | "per-type" | "global" | "inherit" + +export interface Model { + providerID: string + modelID: string +} + +export interface Input { + readonly subagentType: string + /** The main agent's current model and reasoning variant. */ + readonly parent: Model & { variant?: string } + readonly perCall?: string + /** Raw `agent..model` / `agent..variant` from config. */ + readonly typeModel?: string + readonly typeVariant?: string + readonly config: { + readonly small_model?: string + readonly subagent?: { + readonly model?: string + readonly variant?: string + readonly dynamic?: { readonly enabled?: boolean; readonly allow?: readonly string[] } + } + } +} + +export interface Resolved { + readonly model: Model + readonly variant: string | undefined + readonly rule: Rule + /** Human-readable name of the rule, e.g. `agent.qa.model` or `subagent.model`. */ + readonly source: string +} + +export class RefusedError extends Error { + override name = "SubagentModelRefused" +} + +function parse(spec: string): Model { + const [providerID, ...rest] = spec.split("/") + return { providerID, modelID: rest.join("/") } +} + +function resolveValue(value: string, input: Input): { model: Model; inherited: boolean } { + const parent = { providerID: input.parent.providerID, modelID: input.parent.modelID } + if (value === "inherit") return { model: parent, inherited: true } + if (value === "small") { + if (input.config.small_model) return { model: parse(input.config.small_model), inherited: false } + return { model: parent, inherited: true } + } + return { model: parse(value), inherited: false } +} + +/** Models the main agent may pick per call. Empty unless dynamic selection is enabled. */ +export function allowed(config: Input["config"], residency?: Residency.Resolved): string[] { + const dynamic = config.subagent?.dynamic + if (!dynamic?.enabled) return [] + const list = [...new Set(dynamic.allow ?? [])] + if (!residency) return list + return list.filter((spec) => Residency.evaluate(parse(spec).providerID, residency.policy).allowed) +} + +export function resolve(input: Input): Resolved { + const configuredVariant = (explicit?: string) => { + const value = explicit ?? input.config.subagent?.variant + return value === undefined || value === "inherit" ? undefined : value + } + const finish = (value: string, rule: Rule, source: string, explicitVariant?: string): Resolved => { + const { model, inherited } = resolveValue(value, input) + const variant = configuredVariant(explicitVariant) + // An inherited model keeps the main agent's reasoning effort unless a variant is configured. + // An overridden model uses the configured variant, or the model's default. + return { model, variant: variant ?? (inherited ? input.parent.variant : undefined), rule, source } + } + + if (input.perCall !== undefined) { + const allow = input.config.subagent?.dynamic?.allow ?? [] + if (!input.config.subagent?.dynamic?.enabled) + throw new RefusedError(`Choosing a model per task is disabled. Set "subagent.dynamic.enabled" to allow it.`) + if (!allow.includes(input.perCall)) + throw new RefusedError( + `Model "${input.perCall}" is not on subagent.dynamic.allow. Choose one of: ${allow.join(", ") || "(none)"}.`, + ) + return finish(input.perCall, "per-call", "task model", input.typeVariant) + } + if (input.typeModel !== undefined) + return finish(input.typeModel, "per-type", `agent.${input.subagentType}.model`, input.typeVariant) + if (input.config.subagent?.model !== undefined) + return finish(input.config.subagent.model, "global", "subagent.model", input.typeVariant) + return finish("inherit", "inherit", "inherit", input.typeVariant) +} + +/** + * Check the resolved model against the residency policy before the subagent session starts. + * A denial is written to the residency audit log like any other denied call, and the error + * names the rule that chose the model. + */ +export function checkResidency(resolved: Resolved, residency: Residency.Resolved | undefined) { + if (!residency) return + try { + Residency.enforce({ + providerID: resolved.model.providerID, + baseURL: "", + resolved: residency, + defaultAuditPath: path.join(Global.Path.log, "residency-egress.log"), + fetch: undefined, + }) + } catch (error) { + if (!(error instanceof Residency.DeniedError)) throw error + throw new RefusedError( + `${resolved.source} → ${resolved.model.providerID}/${resolved.model.modelID} denied by residency policy. ${error.decision.reason}`, + ) + } +} diff --git a/packages/opencode/src/tool/registry.ts b/packages/opencode/src/tool/registry.ts index 9167cb3ea6bc..f06c744967ca 100644 --- a/packages/opencode/src/tool/registry.ts +++ b/packages/opencode/src/tool/registry.ts @@ -9,7 +9,10 @@ import { EditTool } from "./edit" import { GlobTool } from "./glob" import { GrepTool } from "./grep" import { ReadTool } from "./read" -import { TaskTool } from "./task" +import { TaskTool, withModelParameter } from "./task" +import { ToolJsonSchema } from "./json-schema" +import { Residency } from "@opencode-ai/core/residency" +import { SubagentModel } from "../agent/subagent-model" import { Database } from "@opencode-ai/core/database/database" import { TodoWriteTool } from "./todo" import { WebFetchTool } from "./webfetch" @@ -302,6 +305,10 @@ const layer = Layer.effect( return true }) + // XCOD-82: allowed per-task models, minus any the residency policy would deny. + const cfg = yield* config.get() + const subagentModels = SubagentModel.allowed(cfg, Residency.resolve(cfg.residency)) + const codeModeDescription = filtered.some((tool) => tool.id === "execute") ? yield* describeCodeMode(input) : undefined @@ -316,10 +323,14 @@ const layer = Layer.effect( jsonSchema: tool.jsonSchema, } yield* plugin.trigger("tool.definition", { toolID: tool.id }, output) - const jsonSchema = + const pluginSchema = output.parameters === tool.parameters || output.jsonSchema !== tool.jsonSchema ? output.jsonSchema : undefined + const jsonSchema = + tool.id === TaskTool.id && subagentModels.length + ? withModelParameter(pluginSchema ?? ToolJsonSchema.fromTool(tool), subagentModels) + : pluginSchema return { id: tool.id, description: [ diff --git a/packages/opencode/src/tool/task.ts b/packages/opencode/src/tool/task.ts index d8ca640cfba9..593ecae2c77d 100644 --- a/packages/opencode/src/tool/task.ts +++ b/packages/opencode/src/tool/task.ts @@ -1,6 +1,7 @@ import * as Tool from "./tool" import DESCRIPTION from "./task.txt" import { ToolJsonSchema } from "./json-schema" +import type { JSONSchema7, JSONSchema7Definition } from "@ai-sdk/provider" import { SessionV1 } from "@opencode-ai/core/v1/session" import { BackgroundJob } from "@/background/job" import { Session } from "@/session/session" @@ -14,6 +15,10 @@ import { Effect, Exit, Schema, Scope } from "effect" import { EffectBridge } from "@/effect/bridge" import { RuntimeFlags } from "@/effect/runtime-flags" import { Database } from "@opencode-ai/core/database/database" +import { Residency } from "@opencode-ai/core/residency" +import { ProviderV2 } from "@opencode-ai/core/provider" +import { ModelV2 } from "@opencode-ai/core/model" +import { SubagentModel } from "../agent/subagent-model" export interface TaskPromptOps { cancel(sessionID: SessionID): Effect.Effect @@ -49,6 +54,9 @@ const BaseParameterFields = { "This should only be set if you mean to resume a previous task (you can pass a prior task_id and the task will continue the same subagent session as before instead of creating a fresh one)", }), command: Schema.optional(Schema.String).annotate({ description: "The command that triggered this task" }), + model: Schema.optional(Schema.String).annotate({ + description: "Model for this task, from the allowed list. Only offered when subagent.dynamic is enabled.", + }), } const BaseParameters = Schema.Struct(BaseParameterFields) @@ -61,6 +69,24 @@ export const Parameters = Schema.Struct({ }), }) +/** + * The task tool's JSON schema with the `model` parameter constrained to `allowed`, or removed when + * nothing is allowed (XCOD-82). An enum, so the main agent can't invent a model id; the resolver + * still refuses anything off the list. + */ +export function withModelParameter(schema: JSONSchema7, allowed: readonly string[]): JSONSchema7 { + const properties = { ...(schema.properties ?? {}) } as Record + delete properties.model + if (allowed.length) + properties.model = { + type: "string", + enum: [...allowed], + description: + "Model for this task. Pick by the nature of the work: a cheap, fast model for broad search or simple lookups; a strong model for design, review or subtle debugging. Omit to use the configured default.", + } + return { ...schema, properties } +} + function renderOutput(input: { sessionID: SessionID state: "running" | "completed" | "error" @@ -89,6 +115,12 @@ export const TaskTool = Tool.define( const flags = yield* RuntimeFlags.Service const database = yield* Database.Service + const lastAssistant = Effect.fn("TaskTool.lastAssistant")(function* (sessionID: SessionID) { + const messages = yield* sessions.messages({ sessionID }).pipe(Effect.orElseSucceed(() => [])) + const info = messages.findLast((item) => item.info.role === "assistant")?.info + return info?.role === "assistant" ? info : undefined + }) + const run = Effect.fn("TaskTool.execute")(function* ( params: Schema.Schema.Type, ctx: Tool.Context, @@ -177,15 +209,46 @@ export const TaskTool = Tool.define( ) if (msg.info.role !== "assistant") return yield* Effect.fail(new Error("Not an assistant message")) const variant = msg.info.variant + const parentModel = { providerID: msg.info.providerID, modelID: msg.info.modelID } - const model = next.model ?? { - modelID: msg.info.modelID, - providerID: msg.info.providerID, + // XCOD-82: per-call → per-type → global → inherit. Resuming a task keeps the model of its + // original run unless this call explicitly (and allowably) overrides it. + const previous = session ? yield* lastAssistant(nextSession.id) : undefined + const resolved = yield* Effect.try({ + try: () => { + const out = SubagentModel.resolve({ + subagentType: next.name, + parent: { ...parentModel, variant }, + perCall: params.model, + typeModel: next.modelSpec, + typeVariant: next.modelSpec ? next.variant : undefined, + config: cfg, + }) + const final = + previous && params.model === undefined + ? { + ...out, + model: { providerID: previous.providerID, modelID: previous.modelID }, + variant: previous.variant, + source: "resumed task", + } + : out + SubagentModel.checkResidency(final, Residency.resolve(cfg.residency)) + return final + }, + catch: (error) => (error instanceof Error ? error : new Error(String(error))), + }) + const model = { + providerID: ProviderV2.ID.make(resolved.model.providerID), + modelID: ModelV2.ID.make(resolved.model.modelID), } const metadata = { parentSessionId: ctx.sessionID, sessionId: nextSession.id, model, + modelRule: resolved.rule, + modelSource: resolved.source, + ...(runInBackground ? { background: true } : {}), } @@ -206,7 +269,7 @@ export const TaskTool = Tool.define( modelID: model.modelID, providerID: model.providerID, }, - variant: next.model ? undefined : variant, + variant: resolved.variant, agent: next.name, parts, }) @@ -363,7 +426,12 @@ export const TaskTool = Tool.define( ? [DESCRIPTION, BACKGROUND_DESCRIPTION].join("\n\n") : DESCRIPTION, parameters: Parameters, - jsonSchema: flags.experimentalBackgroundSubagents ? undefined : ToolJsonSchema.fromSchema(BaseParameters), + // `model` is never offered by default; the registry adds it, as an enum of the allowed models, + // only when subagent.dynamic is enabled (withModelParameter). + jsonSchema: withModelParameter( + ToolJsonSchema.fromSchema(flags.experimentalBackgroundSubagents ? Parameters : BaseParameters), + [], + ), execute: (params: Schema.Schema.Type, ctx: Tool.Context) => run(params, ctx).pipe(Effect.orDie), } diff --git a/packages/opencode/test/agent/subagent-model.test.ts b/packages/opencode/test/agent/subagent-model.test.ts new file mode 100644 index 000000000000..fbba7457929f --- /dev/null +++ b/packages/opencode/test/agent/subagent-model.test.ts @@ -0,0 +1,90 @@ +import { describe, expect, test } from "bun:test" +import { SubagentModel } from "../../src/agent/subagent-model" +import { withModelParameter } from "../../src/tool/task" + +const parent = { providerID: "mistral", modelID: "mistral-large-latest", variant: "high" } +const base = { subagentType: "explore", parent, config: {} } + +describe("SubagentModel.resolve (XCOD-82)", () => { + test("no config: inherits the main agent's model and reasoning variant", () => { + expect(SubagentModel.resolve(base)).toEqual({ + model: { providerID: "mistral", modelID: "mistral-large-latest" }, + variant: "high", + rule: "inherit", + source: "inherit", + }) + }) + + test('agent.explore.model: "small" runs on small_model; others still inherit', () => { + const config = { small_model: "mistral/mistral-small-latest" } + const explore = SubagentModel.resolve({ ...base, config, typeModel: "small" }) + expect(explore).toMatchObject({ + model: { modelID: "mistral-small-latest" }, + rule: "per-type", + source: "agent.explore.model", + }) + expect(explore.variant).toBeUndefined() + expect(SubagentModel.resolve({ ...base, subagentType: "general", config }).rule).toBe("inherit") + }) + + test('"small" without small_model falls back to inherit, keeping the variant', () => { + const out = SubagentModel.resolve({ ...base, typeModel: "small" }) + expect(out.model).toEqual({ providerID: "mistral", modelID: "mistral-large-latest" }) + expect(out.variant).toBe("high") + }) + + test("subagent.model applies to every type without its own override", () => { + const config = { subagent: { model: "scaleway/llama-3.3-70b-instruct" } } + expect(SubagentModel.resolve({ ...base, config })).toMatchObject({ rule: "global", source: "subagent.model" }) + expect(SubagentModel.resolve({ ...base, config, typeModel: "mistral/codestral-latest" }).rule).toBe("per-type") + }) + + test("an overridden model uses the configured variant; inherit keeps the parent's", () => { + expect(SubagentModel.resolve({ ...base, typeModel: "mistral/codestral-latest", typeVariant: "low" }).variant).toBe( + "low", + ) + expect(SubagentModel.resolve({ ...base, typeModel: "inherit", typeVariant: "max" }).variant).toBe("max") + }) + + test("dynamic: an allowed per-call model wins; anything else is refused, never replaced", () => { + const config = { subagent: { dynamic: { enabled: true, allow: ["mistral/codestral-latest"] } } } + expect(SubagentModel.resolve({ ...base, config, perCall: "mistral/codestral-latest" }).rule).toBe("per-call") + expect(() => SubagentModel.resolve({ ...base, config, perCall: "openai/gpt-x" })).toThrow( + /not on subagent.dynamic.allow/, + ) + expect(() => SubagentModel.resolve({ ...base, perCall: "mistral/codestral-latest" })).toThrow(/disabled/) + }) + + test("residency: a denied model is refused with the rule that chose it", () => { + const out = SubagentModel.resolve({ ...base, subagentType: "qa", typeModel: "anthropic/claude-haiku-4-5" }) + expect(() => + SubagentModel.checkResidency(out, { policy: { allow: ["eu"] }, audit: false, auditPath: undefined }), + ).toThrow(/agent\.qa\.model → anthropic\/claude-haiku-4-5 denied by residency policy/) + expect(() => + SubagentModel.checkResidency(SubagentModel.resolve(base), { + policy: { allow: ["eu"] }, + audit: false, + auditPath: undefined, + }), + ).not.toThrow() + }) + + test("the dynamic allow list offered to the model excludes residency-denied entries", () => { + const config = { subagent: { dynamic: { enabled: true, allow: ["mistral/codestral-latest", "openai/gpt-x"] } } } + expect(SubagentModel.allowed(config, { policy: { allow: ["eu"] }, audit: false, auditPath: undefined })).toEqual([ + "mistral/codestral-latest", + ]) + expect(SubagentModel.allowed({})).toEqual([]) + }) +}) + +describe("task tool model parameter", () => { + const schema = { + type: "object" as const, + properties: { prompt: { type: "string" as const }, model: { type: "string" as const } }, + } + test("absent unless models are allowed, and then an enum of exactly those", () => { + expect(withModelParameter(schema, []).properties).not.toHaveProperty("model") + expect(withModelParameter(schema, ["a/b"]).properties?.model).toMatchObject({ enum: ["a/b"] }) + }) +}) diff --git a/packages/opencode/test/cli/run/subagent-model.test.ts b/packages/opencode/test/cli/run/subagent-model.test.ts new file mode 100644 index 000000000000..0fb11af27d5a --- /dev/null +++ b/packages/opencode/test/cli/run/subagent-model.test.ts @@ -0,0 +1,174 @@ +// XCOD-82: subagent model selection in a real `lunos run`. The scripted LLM records every request +// body, so each test asserts the model the subagent *actually called*, not just what the resolver +// returned, plus the rule recorded in the task tool's metadata. +import { describe, expect } from "bun:test" +import { Effect } from "effect" +import fs from "fs/promises" +import path from "path" +import { reply } from "../../lib/llm-server" +import { cliIt, type CliFixture } from "../../lib/cli-process" + +const smallModel = { + id: "small-model", + name: "Small Model", + attachment: false, + reasoning: false, + temperature: false, + tool_call: true, + release_date: "2025-01-01", + limit: { context: 100_000, output: 10_000 }, + cost: { input: 0, output: 0 }, + options: {}, +} + +// Merged with the harness's inline provider config: adds test/small-model, plus whatever the case needs. +async function configure(home: string, extra: Record) { + const dir = path.join(home, ".config", "opencode") + await fs.mkdir(dir, { recursive: true }) + await fs.writeFile( + path.join(dir, "opencode.json"), + JSON.stringify({ provider: { test: { models: { "small-model": smallModel } } }, ...extra }), + ) +} + +function runTask(fixture: CliFixture, task: Record) { + return Effect.gen(function* () { + yield* fixture.llm.push( + reply().tool("task", { description: "look", prompt: "look around", subagent_type: "explore", ...task }), + ) + yield* fixture.llm.text("subagent answer") + yield* fixture.llm.text("main done") + const result = yield* fixture.opencode.run("delegate", { permission: { "*": "allow" }, format: "json" }) + fixture.opencode.expectExit(result, 0) + const part = fixture.opencode + .parseJsonEvents(result.stdout) + .map((event) => (event as { part?: { tool?: string; state?: Record } }).part) + .find((item) => item?.tool === "task") + // Session title generation also calls the LLM (on small_model); only the agent turns matter here. + const models = (yield* fixture.llm.inputs) + .filter((input: any) => !JSON.stringify(input.messages?.[0]?.content ?? "").includes("title generator")) + .map((input) => input.model) + return { state: part?.state, models } + }) +} + +describe("subagent model selection in a real run", () => { + cliIt.live( + "no subagent config: the subagent runs on the main agent's model", + (fixture) => + Effect.gen(function* () { + yield* Effect.promise(() => configure(fixture.home, {})) + const { state, models } = yield* runTask(fixture, {}) + expect(state?.metadata).toMatchObject({ model: { modelID: "test-model" }, modelRule: "inherit" }) + expect(models).toEqual(["test-model", "test-model", "test-model"]) + }), + 90_000, + ) + + cliIt.live( + 'agent.explore.model: "small" runs explore on small_model', + (fixture) => + Effect.gen(function* () { + yield* Effect.promise(() => + configure(fixture.home, { small_model: "test/small-model", agent: { explore: { model: "small" } } }), + ) + const { state, models } = yield* runTask(fixture, {}) + expect(state?.metadata).toMatchObject({ + model: { modelID: "small-model" }, + modelRule: "per-type", + modelSource: "agent.explore.model", + }) + expect(models).toEqual(["test-model", "small-model", "test-model"]) + }), + 90_000, + ) + + cliIt.live( + "subagent.model applies to a type without its own override", + (fixture) => + Effect.gen(function* () { + yield* Effect.promise(() => configure(fixture.home, { subagent: { model: "test/small-model" } })) + const { state, models } = yield* runTask(fixture, {}) + expect(state?.metadata).toMatchObject({ model: { modelID: "small-model" }, modelRule: "global" }) + expect(models[1]).toBe("small-model") + }), + 90_000, + ) + + cliIt.live( + "dynamic: an allowed per-call model is used; one off the list is refused with a tool error", + (fixture) => + Effect.gen(function* () { + yield* Effect.promise(() => + configure(fixture.home, { subagent: { dynamic: { enabled: true, allow: ["test/small-model"] } } }), + ) + const allowed = yield* runTask(fixture, { model: "test/small-model" }) + expect(allowed.state?.metadata).toMatchObject({ model: { modelID: "small-model" }, modelRule: "per-call" }) + expect(allowed.models[1]).toBe("small-model") + + yield* fixture.llm.reset + yield* fixture.llm.push( + reply().tool("task", { + description: "look", + prompt: "look", + subagent_type: "explore", + model: "test/test-model", + }), + ) + yield* fixture.llm.text("main done") + const result = yield* fixture.opencode.run("delegate", { permission: { "*": "allow" }, format: "json" }) + const part = fixture.opencode + .parseJsonEvents(result.stdout) + .map((event) => (event as { part?: { tool?: string; state?: Record } }).part) + .find((item) => item?.tool === "task") + expect(part?.state?.status).toBe("error") + expect(part?.state?.error).toContain("not on subagent.dynamic.allow") + }), + 120_000, + ) + + cliIt.live( + "residency: a denied per-type model stops the subagent before it starts, names the rule, and is audited", + (fixture) => + Effect.gen(function* () { + const audit = path.join(fixture.home, "egress.log") + yield* Effect.promise(() => + configure(fixture.home, { + residency: { allow: ["eu"], auditPath: audit }, + // An EU-tagged provider id pointed at the scripted LLM, so the main agent is allowed. + provider: { + test: { models: { "small-model": smallModel } }, + mistral: { + npm: "@ai-sdk/openai-compatible", + models: { "eu-model": { ...smallModel, id: "eu-model", name: "EU Model" } }, + options: { apiKey: "test-key", baseURL: fixture.llm.url }, + }, + }, + agent: { explore: { model: "anthropic/claude-haiku-4-5" } }, + }), + ) + yield* fixture.llm.push(reply().tool("task", { description: "look", prompt: "look", subagent_type: "explore" })) + yield* fixture.llm.text("main done") + const result = yield* fixture.opencode.run("delegate", { + model: "mistral/eu-model", + permission: { "*": "allow" }, + format: "json", + }) + const part = fixture.opencode + .parseJsonEvents(result.stdout) + .map((event) => (event as { part?: { tool?: string; state?: Record } }).part) + .find((item) => item?.tool === "task") + expect(part?.state?.status).toBe("error") + expect(part?.state?.error).toContain( + "agent.explore.model → anthropic/claude-haiku-4-5 denied by residency policy", + ) + const models = (yield* fixture.llm.inputs).map((input) => input.model) + expect(models).not.toContain("claude-haiku-4-5") + const lines = (yield* Effect.promise(() => fs.readFile(audit, "utf8"))).trim().split("\n") + expect(lines.map((line) => JSON.parse(line))).toContainEqual( + expect.objectContaining({ providerID: "anthropic", allowed: false }), + ) + }), + 90_000, + ) +}) diff --git a/packages/opencode/test/config/config.test.ts b/packages/opencode/test/config/config.test.ts index 4a38429f2c5b..633722de5419 100644 --- a/packages/opencode/test/config/config.test.ts +++ b/packages/opencode/test/config/config.test.ts @@ -945,6 +945,30 @@ it.instance("decodes the checked-in reference deployment config on the live path }), ) +// XCOD-82: every new subagent key survives the live config path (the XCOD-68 / XCOD-93 lesson). +it.instance("keeps subagent model selection keys on the live config path", () => + Effect.gen(function* () { + const test = yield* TestInstance + yield* writeConfigEffect(test.directory, { + $schema: "https://opencode.ai/config.json", + subagent: { + model: "small", + variant: "inherit", + dynamic: { enabled: true, allow: ["mistral/codestral-latest"] }, + }, + agent: { explore: { model: "small" }, qa: { model: "inherit", variant: "high" } }, + }) + const config = yield* Config.use.get() + expect(config.subagent).toEqual({ + model: "small", + variant: "inherit", + dynamic: { enabled: true, allow: ["mistral/codestral-latest"] }, + }) + expect(config.agent?.explore?.model).toBe("small") + expect(config.agent?.qa).toMatchObject({ model: "inherit", variant: "high" }) + }), +) + it.instance("migrates mode field to agent field", () => Effect.gen(function* () { const test = yield* TestInstance diff --git a/packages/opencode/test/tool/__snapshots__/parameters.test.ts.snap b/packages/opencode/test/tool/__snapshots__/parameters.test.ts.snap index 51ff867ea44d..32e1752be05d 100644 --- a/packages/opencode/test/tool/__snapshots__/parameters.test.ts.snap +++ b/packages/opencode/test/tool/__snapshots__/parameters.test.ts.snap @@ -313,6 +313,10 @@ exports[`tool parameters JSON Schema (wire shape) task 1`] = ` "description": "A short (3-5 words) description of the task", "type": "string", }, + "model": { + "description": "Model for this task, from the allowed list. Only offered when subagent.dynamic is enabled.", + "type": "string", + }, "prompt": { "description": "The task for the agent to perform", "type": "string", diff --git a/packages/sdk/js/src/v2/gen/types.gen.ts b/packages/sdk/js/src/v2/gen/types.gen.ts index bbd71fe649fd..71a156c74ba4 100644 --- a/packages/sdk/js/src/v2/gen/types.gen.ts +++ b/packages/sdk/js/src/v2/gen/types.gen.ts @@ -1655,6 +1655,15 @@ export type ServerConfig = { cors?: Array } +export type SubagentConfig = { + model?: string + variant?: string + dynamic?: { + enabled?: boolean + allow?: Array + } +} + export type PermissionActionConfig = "ask" | "allow" | "deny" export type PermissionObjectConfig = { @@ -1947,6 +1956,7 @@ export type Config = { model?: string small_model?: string default_agent?: string + subagent?: SubagentConfig subagent_depth?: number username?: string mode?: { @@ -2377,6 +2387,7 @@ export type Agent = { providerID: string } variant?: string + modelSpec?: string prompt?: string options: { [key: string]: unknown diff --git a/packages/sdk/openapi.json b/packages/sdk/openapi.json index 5a6050acc39e..148bd1796855 100644 --- a/packages/sdk/openapi.json +++ b/packages/sdk/openapi.json @@ -20577,6 +20577,33 @@ "additionalProperties": false, "description": "Server configuration for opencode serve and web commands" }, + "SubagentConfig": { + "type": "object", + "properties": { + "model": { + "type": "string" + }, + "variant": { + "type": "string" + }, + "dynamic": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" + }, + "allow": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "additionalProperties": false + } + }, + "additionalProperties": false + }, "PermissionActionConfig": { "type": "string", "enum": ["ask", "allow", "deny"] @@ -21359,6 +21386,9 @@ "default_agent": { "type": "string" }, + "subagent": { + "$ref": "#/components/schemas/SubagentConfig" + }, "subagent_depth": { "type": "integer", "minimum": 0 @@ -22637,6 +22667,9 @@ "variant": { "type": "string" }, + "modelSpec": { + "type": "string" + }, "prompt": { "type": "string" }, diff --git a/packages/web/src/content/docs/agents.mdx b/packages/web/src/content/docs/agents.mdx index 59d4020bf284..7ce483fae44c 100644 --- a/packages/web/src/content/docs/agents.mdx +++ b/packages/web/src/content/docs/agents.mdx @@ -399,6 +399,55 @@ The model ID in your Lunos config uses the format `provider/model-id`. For examp --- +### Choosing models for subagents + +Every subagent gets a model from the first of these rules that applies: + +1. **Per task call:** the main agent picks a model for one task, but only when `subagent.dynamic.enabled` is `true`, and only from `subagent.dynamic.allow`. A model that isn't on the list is refused with an error the main agent can see. It is never silently swapped for another. +2. **Per type of work:** `agent..model`, for example `agent.explore.model`. +3. **Global default:** `subagent.model`. +4. **Inherit:** the main agent's current model. This is the default. + +Each value can be `"inherit"` (the main agent's model), `"small"` (your `small_model`, or inherit if that isn't set), or `"provider/model"`. The task tool's metadata records which model was chosen and which rule chose it. + +**Based on the main agent.** This is the default and needs no config: subagents use whatever model, and reasoning variant, the main agent is running. + +**Based on the type of work.** For example, a cheap model for broad search and a strong one for review: + +```json title="opencode.json" +{ + "model": "mistral/mistral-large-latest", + "small_model": "mistral/mistral-small-latest", + "agent": { + "explore": { "model": "small" }, + "qa": { "model": "mistral/mistral-large-latest", "variant": "high" } + } +} +``` + +**Chosen per task by the main agent,** from a list you allow: + +```json title="opencode.json" +{ + "subagent": { + "dynamic": { + "enabled": true, + "allow": ["mistral/codestral-latest", "scaleway/llama-3.3-70b-instruct"] + } + } +} +``` + +The task tool only offers a `model` argument when this is enabled, and only as a choice from `allow`. + +**Reasoning effort.** An inherited model keeps the main agent's variant. An overridden model uses the configured `variant` (per agent, or `subagent.variant`), or the model's default. + +**Data residency.** The chosen model is checked against your [residency policy](/docs/data-residency) before the subagent starts. A denial names the rule that chose the model (for example `agent.qa.model → anthropic/… denied by residency policy`) and is written to the audit log. Models on `subagent.dynamic.allow` that the policy would deny are never offered to the main agent. + +**Resuming a task.** Resuming with `task_id` keeps the model of the original run unless the call explicitly picks another allowed model. + +--- + ### Tools (deprecated) `tools` is **deprecated**. Prefer the agent's [`permission`](#permissions) field for new configs, updates and more fine-grained control.