feat: add variant support for subagents (#7138) [alt of #7140]

.opencode/agent/duplicate-pr.md

@@ -3,6 +3,7 @@ mode: primary
 hidden: true
 model: opencode/claude-haiku-4-5
 color: "#E67E22"
+variant: "high"
 tools:
   "*": false
   "github-pr-search": true

.opencode/agent/triage.md

@@ -3,6 +3,7 @@ mode: primary
 hidden: true
 model: opencode/claude-haiku-4-5
 color: "#44BA81"
+variant: "high"
 tools:
   "*": false
   "github-triage": true

packages/app/src/components/prompt-input.tsx

@@ -1231,7 +1231,7 @@ export const PromptInput: Component<PromptInputProps> = (props) => {
       providerID: currentModel.provider.id,
     }
     const agent = currentAgent.name
-    const variant = local.model.variant.current()
+    const variant = local.model.variant.effective()
 
     const clearInput = () => {
       prompt.reset()
@@ -1961,7 +1961,7 @@ export const PromptInput: Component<PromptInputProps> = (props) => {
                       class="text-text-base _hidden group-hover/prompt-input:inline-block capitalize text-12-regular"
                       onClick={() => local.model.variant.cycle()}
                     >
-                      {local.model.variant.current() ?? language.t("common.default")}
+                      {local.model.variant.effective() ?? language.t("common.default")}
                     </Button>
                   </TooltipKeybind>
                 </Show>

packages/app/src/context/local.tsx

@@ -216,6 +216,9 @@ export const { use: useLocal, provider: LocalProvider } = createSimpleContext({
             if (!m) return undefined
             return models.variant.get({ providerID: m.provider.id, modelID: m.id })
           },
+          effective() {
+            return this.current() ?? agent.current()?.variant
+          },
           list() {
             const m = current()
             if (!m) return []
@@ -230,12 +233,12 @@ export const { use: useLocal, provider: LocalProvider } = createSimpleContext({
           cycle() {
             const variants = this.list()
             if (variants.length === 0) return
-            const currentVariant = this.current()
-            if (!currentVariant) {
+            const effective = this.effective()
+            if (!effective) {
               this.set(variants[0])
               return
             }
-            const index = variants.indexOf(currentVariant)
+            const index = variants.indexOf(effective)
             if (index === -1 || index === variants.length - 1) {
               this.set(undefined)
               return

packages/opencode/src/agent/agent.ts

@@ -38,6 +38,7 @@ export namespace Agent {
         })
         .optional(),
       prompt: z.string().optional(),
+      variant: z.string().optional(),
       options: z.record(z.string(), z.any()),
       steps: z.number().int().positive().optional(),
     })
@@ -214,6 +215,7 @@ export namespace Agent {
           native: false,
         }
       if (value.model) item.model = Provider.parseModel(value.model)
+      if (value.variant) item.variant = value.variant
       item.prompt = value.prompt ?? item.prompt
       item.description = value.description ?? item.description
       item.temperature = value.temperature ?? item.temperature

packages/opencode/src/cli/cmd/run.ts

@@ -89,7 +89,7 @@ export const RunCommand = cmd({
       })
       .option("variant", {
         type: "string",
-        describe: "model variant (provider-specific reasoning effort, e.g., high, max, minimal)",
+        describe: "model variant (provider-specific reasoning effort, e.g., none, low, medium, high, xhigh, max)",
       })
   },
   handler: async (args) => {

packages/opencode/src/cli/cmd/tui/app.tsx

@@ -247,6 +247,9 @@ function App() {
           })
         local.model.set({ providerID, modelID }, { recent: true })
       }
+      if (args.variant) {
+        local.model.variant.set(args.variant)
+      }
       if (args.sessionID) {
         route.navigate({
           type: "session",

packages/opencode/src/cli/cmd/tui/component/dialog-agent.tsx

@@ -9,10 +9,12 @@ export function DialogAgent() {
 
   const options = createMemo(() =>
     local.agent.list().map((item) => {
+      const desc = item.native ? "native" : item.description
+      const variant = item.variant ? ` (${item.variant})` : ""
       return {
         value: item.name,
         title: item.name,
-        description: item.native ? "native" : item.description,
+        description: desc ? desc + variant : variant.trim(),
       }
     }),
   )

packages/opencode/src/cli/cmd/tui/component/prompt/index.tsx

@@ -706,8 +706,8 @@ export function Prompt(props: PromptProps) {
   const showVariant = createMemo(() => {
     const variants = local.model.variant.list()
     if (variants.length === 0) return false
-    const current = local.model.variant.current()
-    return !!current
+    const effective = local.model.variant.effective()
+    return !!effective
   })
 
   const spinnerDef = createMemo(() => {
@@ -956,7 +956,7 @@ export function Prompt(props: PromptProps) {
                   <Show when={showVariant()}>
                     <text fg={theme.textMuted}>·</text>
                     <text>
-                      <span style={{ fg: theme.warning, bold: true }}>{local.model.variant.current()}</span>
+                      <span style={{ fg: theme.warning, bold: true }}>{local.model.variant.effective()}</span>
                     </text>
                   </Show>
                 </box>

packages/opencode/src/cli/cmd/tui/context/args.tsx

@@ -3,6 +3,7 @@ import { createSimpleContext } from "./helper"
 export interface Args {
   model?: string
   agent?: string
+  variant?: string
   prompt?: string
   continue?: boolean
   sessionID?: string

packages/opencode/src/cli/cmd/tui/context/local.tsx

@@ -323,6 +323,9 @@ export const { use: useLocal, provider: LocalProvider } = createSimpleContext({
             const key = `${m.providerID}/${m.modelID}`
             return modelStore.variant[key]
           },
+          effective() {
+            return this.current() ?? agent.current().variant
+          },
           list() {
             const m = currentModel()
             if (!m) return []
@@ -341,12 +344,12 @@ export const { use: useLocal, provider: LocalProvider } = createSimpleContext({
           cycle() {
             const variants = this.list()
             if (variants.length === 0) return
-            const current = this.current()
-            if (!current) {
+            const effective = this.effective()
+            if (!effective) {
               this.set(variants[0])
               return
             }
-            const index = variants.indexOf(current)
+            const index = variants.indexOf(effective)
             if (index === -1 || index === variants.length - 1) {
               this.set(undefined)
               return

packages/opencode/src/cli/cmd/tui/routes/session/index.tsx

@@ -1278,7 +1278,13 @@ function AssistantMessage(props: { message: AssistantMessage; parts: Part[]; las
                 ▣{" "}
               </span>{" "}
               <span style={{ fg: theme.text }}>{Locale.titlecase(props.message.mode)}</span>
-              <span style={{ fg: theme.textMuted }}> · {props.message.modelID}</span>
+              <span style={{ fg: theme.textMuted }}>
+                {" "}
+                · {props.message.providerID}/{props.message.modelID}
+              </span>
+              <Show when={props.message.variant}>
+                <span style={{ fg: theme.textMuted }}> · {props.message.variant}</span>
+              </Show>
               <Show when={duration()}>
                 <span style={{ fg: theme.textMuted }}> · {Locale.duration(duration())}</span>
               </Show>

packages/opencode/src/cli/cmd/tui/thread.ts

@@ -71,6 +71,10 @@ export const TuiThreadCommand = cmd({
       .option("agent", {
         type: "string",
         describe: "agent to use",
+      })
+      .option("variant", {
+        type: "string",
+        describe: "model variant (provider-specific reasoning effort, e.g., none, low, medium, high, xhigh, max)",
       }),
   handler: async (args) => {
     // Resolve relative paths against PWD to preserve behavior when using --cwd flag
@@ -149,6 +153,7 @@ export const TuiThreadCommand = cmd({
         sessionID: args.session,
         agent: args.agent,
         model: args.model,
+        variant: args.variant,
         prompt,
       },
       onExit: async () => {

packages/opencode/src/config/config.ts

@@ -562,6 +562,7 @@ export namespace Config {
   export const Agent = z
     .object({
       model: z.string().optional(),
+      variant: z.string().optional().describe("Default variant to use for this agent"),
       temperature: z.number().optional(),
       top_p: z.number().optional(),
       prompt: z.string().optional(),
@@ -593,6 +594,7 @@ export namespace Config {
       const knownKeys = new Set([
         "name",
         "model",
+        "variant",
         "prompt",
         "description",
         "temperature",

packages/opencode/src/session/llm.ts

@@ -98,8 +98,8 @@ export namespace LLM {
       system.push(header, rest.join("\n"))
     }
 
-    const variant =
-      !input.small && input.model.variants && input.user.variant ? input.model.variants[input.user.variant] : {}
+    const selectedVariant = input.user.variant ?? input.agent.variant
+    const variant = !input.small && input.model.variants && selectedVariant ? input.model.variants[selectedVariant] : {}
     const base = input.small
       ? ProviderTransform.smallOptions(input.model)
       : ProviderTransform.options({

packages/opencode/src/session/message-v2.ts

@@ -386,6 +386,7 @@ export namespace MessageV2 {
       }),
     }),
     finish: z.string().optional(),
+    variant: z.string().optional(),
   }).meta({
     ref: "AssistantMessage",
   })

packages/opencode/src/session/prompt.ts

@@ -339,6 +339,7 @@ export namespace SessionPrompt {
           },
           modelID: taskModel.id,
           providerID: taskModel.providerID,
+          variant: lastUser.variant,
           time: {
             created: Date.now(),
           },
@@ -542,6 +543,7 @@ export namespace SessionPrompt {
           },
           modelID: model.id,
           providerID: model.providerID,
+          variant: lastUser.variant,
           time: {
             created: Date.now(),
           },
@@ -837,7 +839,7 @@ export namespace SessionPrompt {
       agent: agent.name,
       model: input.model ?? agent.model ?? (await lastModel(input.sessionID)),
       system: input.system,
-      variant: input.variant,
+      variant: input.variant ?? agent.variant,
     }
 
     const parts = await Promise.all(

packages/opencode/src/tool/task.ts

@@ -18,6 +18,8 @@ const parameters = z.object({
   subagent_type: z.string().describe("The type of specialized agent to use for this task"),
   session_id: z.string().describe("Existing Task session to continue").optional(),
   command: z.string().describe("The command that triggered this task").optional(),
+  model: z.string().describe("Override the subagent's model (format: providerID/modelID)").optional(),
+  variant: z.string().describe("Override the subagent's variant (e.g. 'low', 'medium', 'high')").optional(),
 })
 
 export const TaskTool = Tool.define("task", async (ctx) => {
@@ -99,10 +101,23 @@ export const TaskTool = Tool.define("task", async (ctx) => {
       const msg = await MessageV2.get({ sessionID: ctx.sessionID, messageID: ctx.messageID })
       if (msg.info.role !== "assistant") throw new Error("Not an assistant message")
 
-      const model = agent.model ?? {
-        modelID: msg.info.modelID,
-        providerID: msg.info.providerID,
-      }
+      // Model priority: param override > agent config > parent context
+      const model = (() => {
+        if (params.model) {
+          const [providerID, ...rest] = params.model.split("/")
+          const modelID = rest.join("/")
+          if (!providerID || !modelID) {
+            throw new Error(`Invalid model format: ${params.model}. Expected: providerID/modelID`)
+          }
+          return { providerID, modelID }
+        }
+        return (
+          agent.model ?? {
+            modelID: msg.info.modelID,
+            providerID: msg.info.providerID,
+          }
+        )
+      })()
 
       ctx.metadata({
         title: params.description,
@@ -152,6 +167,10 @@ export const TaskTool = Tool.define("task", async (ctx) => {
           providerID: model.providerID,
         },
         agent: agent.name,
+        // Variant priority: param override > subagent's configured variant > undefined.
+        // Model priority: param override > subagent's configured model > parent's model.
+        // This allows orchestrator agents to dynamically assign model+variant per task.
+        variant: params.variant ?? agent.variant,
         tools: {
           todowrite: false,
           todoread: false,

packages/opencode/src/tool/task.txt

@@ -5,6 +5,12 @@ Available agent types and the tools they have access to:
 
 When using the Task tool, you must specify a subagent_type parameter to select which agent type to use.
 
+Optional override parameters:
+- model: Override the subagent's default model (format: providerID/modelID, e.g. "anthropic/claude-haiku-4-5")
+- variant: Override the subagent's default variant (e.g. "low", "medium", "high")
+
+These overrides take priority over the agent's configured defaults, allowing dynamic model/variant selection per task.
+
 When to use the Task tool:
 - When you are instructed to execute custom slash commands. Use the Task tool with the slash command invocation as the entire prompt. The slash command can take arguments. For example: Task(description="Check the file", prompt="/check-file path/to/file.py")
 

packages/sdk/js/src/v2/gen/types.gen.ts

@@ -197,6 +197,7 @@ export type AssistantMessage = {
     }
   }
   finish?: string
+  variant?: string
 }
 
 export type Message = UserMessage | AssistantMessage
@@ -1383,6 +1384,10 @@ export type PermissionConfig =
 
 export type AgentConfig = {
   model?: string
+  /**
+   * Default variant to use for this agent
+   */
+  variant?: string
   temperature?: number
   top_p?: number
   prompt?: string
@@ -2123,6 +2128,7 @@ export type Agent = {
     providerID: string
   }
   prompt?: string
+  variant?: string
   options: {
     [key: string]: unknown
   }

packages/sdk/openapi.json

@@ -6334,6 +6334,9 @@
           },
           "finish": {
             "type": "string"
+          },
+          "variant": {
+            "type": "string"
           }
         },
         "required": [
@@ -8995,6 +8998,10 @@
           "model": {
             "type": "string"
           },
+          "variant": {
+            "description": "Default variant to use for this agent",
+            "type": "string"
+          },
           "temperature": {
             "type": "number"
           },
@@ -10765,6 +10772,9 @@
           "prompt": {
             "type": "string"
           },
+          "variant": {
+            "type": "string"
+          },
           "options": {
             "type": "object",
             "propertyNames": {