@hueyexe/opencode-ensemble 0.11.0 → 0.12.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/@hueyexe/opencode-ensemble.svg)](https://www.npmjs.com/package/@hueyexe/opencode-ensemble)
 [![npm downloads](https://img.shields.io/npm/dm/@hueyexe/opencode-ensemble.svg)](https://www.npmjs.com/package/@hueyexe/opencode-ensemble)
-[![tests](https://img.shields.io/badge/tests-471%20passing-brightgreen.svg)]()
+[![tests](https://img.shields.io/badge/tests-477%20passing-brightgreen.svg)]()
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)]()
 [![OpenCode SDK](https://img.shields.io/badge/deps-OpenCode%20SDK%20only-blue.svg)]()
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
@@ -11,6 +11,16 @@ Run parallel AI agents in OpenCode. Each agent gets its own session, context win
 
 Plugin built on the public OpenCode SDK. No internal dependencies.
 
+## Quick Start
+
+```json
+{
+  "plugin": ["@hueyexe/opencode-ensemble@0.12.0"]
+}
+```
+
+Add to your `opencode.json`, restart OpenCode, and ask it to do something that benefits from parallel work. The agent handles the rest. See [Install](#install) for full setup including worktree permissions.
+
 ## What actually happens
 
 You ask the agent to do something complex. It creates a team, spawns teammates, and they work in parallel. Each teammate runs in its own OpenCode session with a fresh context window.
@@ -126,7 +136,7 @@ Add to your OpenCode config with a pinned version. Project-level or global.
 
 ```json
 {
-  "plugin": ["@hueyexe/opencode-ensemble@0.11.0"]
+  "plugin": ["@hueyexe/opencode-ensemble@0.12.0"]
 }
 ```
 
@@ -134,7 +144,7 @@ Add to your OpenCode config with a pinned version. Project-level or global.
 
 ```json
 {
-  "plugin": ["@hueyexe/opencode-ensemble@0.11.0"]
+  "plugin": ["@hueyexe/opencode-ensemble@0.12.0"]
 }
 ```
 
@@ -170,17 +180,15 @@ This is required. Without it, you'll see "Permission required — Access externa
 
 ### Local development
 
-For working on the plugin itself, create `.opencode/plugins/ensemble.ts` in your project:
+To test a local build, point your plugin config at the built output:
 
-```ts
-export { default } from "@hueyexe/opencode-ensemble"
+```json
+{
+  "plugin": ["/path/to/opencode-ensemble/dist/index.js"]
+}
 ```
 
-Or point directly at the source checkout:
-
-```ts
-export { default } from "/path/to/opencode-ensemble/src/index.ts"
-```
+Build with `bun run build`, then restart OpenCode to pick up changes.
 
 ## Tools
 
@@ -217,7 +225,7 @@ export { default } from "/path/to/opencode-ensemble/src/index.ts"
 
 ## What you see in the TUI
 
-The plugin works within OpenCode's existing TUI. No custom team panel (that requires core TUI changes, which are [in progress upstream](https://github.com/sst/opencode)).
+The plugin works within OpenCode's existing TUI. For deeper visibility, open the [dashboard](#dashboard) at `http://localhost:4747`.
 
 What you get:
 
@@ -248,6 +256,56 @@ Teammate messages arrive in the lead's session as `[Team message from alice]: ..
 - **Graceful shutdown**: busy teammates receive a shutdown message and finish their current work. Use `force: true` to abort immediately.
 - **Rate limiting**: token bucket (configurable via config file or `OPENCODE_ENSEMBLE_RATE_LIMIT`, default 10 tokens/sec)
 
+## Model Selection
+
+Control which AI models your agents use. By default, agents use whatever model OpenCode is configured with. You can override this per-agent, per-agent-type, or with automatic rotation.
+
+**All agents use the same model:**
+```json
+{
+  "defaultModel": "anthropic/claude-sonnet-4-6"
+}
+```
+
+**Different models for different agent types:**
+```json
+{
+  "modelsByAgent": {
+    "build": "anthropic/claude-opus-4-6",
+    "explore": "opencode/gpt-5-nano"
+  }
+}
+```
+
+**Rotate through a pool for diverse perspectives:**
+```json
+{
+  "modelPool": ["anthropic/claude-opus-4-6", "anthropic/claude-sonnet-4-6", "openai/gpt-5.4"],
+  "modelAssignment": "rotate"
+}
+```
+
+**Ask the user before spawning:**
+```json
+{
+  "promptForModels": true,
+  "modelPool": ["anthropic/claude-opus-4-6", "opencode/big-pickle", "opencode/gpt-5-nano"]
+}
+```
+
+When `promptForModels` is true, the lead uses the question tool to ask which models to use before spawning any agents. The user can pick the same model for all agents, mix from the pool, or choose per agent.
+
+**Resolution order** — when an agent is spawned, the model is determined by:
+1. Explicit `model` param on `team_spawn` (lead or user chose it)
+2. `modelsByAgent` mapping for this agent type
+3. `modelAssignment` strategy (`rotate` or `random` from `modelPool`)
+4. `defaultModel`
+5. OpenCode's default model
+
+The lead can always override by passing `model` directly on `team_spawn`, regardless of config.
+
+Model IDs use the `provider/model` format from [models.dev](https://models.dev) (e.g. `anthropic/claude-opus-4-6`, `openai/gpt-5.4`). For OpenCode Zen models, use the `opencode/` prefix (e.g. `opencode/big-pickle`).
+
 ## Configuration
 
 Configure via JSON files, environment variables, or both. Project config overrides global config. Env vars override everything.
@@ -259,12 +317,17 @@ Configure via JSON files, environment variables, or both. Project config overrid
 ```json
 {
   "mergeOnCleanup": true,
-  "stallThresholdMs": 180000,
-  "stallMinSteps": 3,
-  "stallTokenThreshold": 500,
+  "stallThresholdMs": 300000,
+  "stallMinSteps": 5,
+  "stallTokenThreshold": 200,
   "timeoutMs": 1800000,
   "rateLimitCapacity": 10,
-  "dashboardPort": 4747
+  "dashboardPort": 4747,
+  "defaultModel": "anthropic/claude-sonnet-4-6",
+  "modelPool": ["anthropic/claude-opus-4-6", "anthropic/claude-sonnet-4-6", "openai/gpt-5.4"],
+  "modelsByAgent": {},
+  "modelAssignment": "default",
+  "promptForModels": false
 }
 ```
 
@@ -275,12 +338,17 @@ All fields are optional. Missing fields use defaults.
 | Key | Default | Description |
 |-----|---------|-------------|
 | `mergeOnCleanup` | `true` | Auto-merge worktree branches on cleanup (squash + unstage) |
-| `stallThresholdMs` | `180000` (3 min) | Time without communication before stall escalation. `0` disables. |
-| `stallMinSteps` | `3` | Min model steps before token-based stall check kicks in |
-| `stallTokenThreshold` | `500` | Output tokens per step below which the agent is considered stalled |
+| `stallThresholdMs` | `300000` (5 min) | Time without communication before stall escalation. `0` disables. |
+| `stallMinSteps` | `5` | Min model steps before token-based stall check kicks in |
+| `stallTokenThreshold` | `200` | Output tokens per step below which the agent is considered stalled |
 | `timeoutMs` | `1800000` (30 min) | Hard timeout for busy teammates. `0` disables. |
 | `rateLimitCapacity` | `10` | Token bucket capacity for team tool calls. `0` disables. |
 | `dashboardPort` | `4747` | Dashboard server port. `0` disables. |
+| `defaultModel` | `""` | Default model for all agents (e.g. `"anthropic/claude-sonnet-4-6"`). Empty = OpenCode's default. |
+| `modelPool` | `[]` | List of models for rotation/random assignment. |
+| `modelsByAgent` | `{}` | Map agent type to model (e.g. `{"build": "anthropic/claude-opus-4-6"}`). |
+| `modelAssignment` | `"default"` | How to assign models: `"default"`, `"rotate"`, or `"random"`. |
+| `promptForModels` | `false` | Lead asks user about model preferences before spawning. |
 
 ### Environment variables
 
@@ -299,7 +367,7 @@ OPENCODE_ENSEMBLE_RATE_LIMIT=20
 # Disable rate limiting
 OPENCODE_ENSEMBLE_RATE_LIMIT=0
 
-# Adjust stall detection threshold (default: 180000ms = 3 minutes)
+# Adjust stall detection threshold (default: 300000ms = 5 minutes)
 STALL_THRESHOLD_MS=300000
 
 # Disable stall detection
@@ -337,7 +405,7 @@ Same coordination model (shared tasks, peer messaging, lead coordination) with s
 ```bash
 bun install
 bun run typecheck
-bun test             # 471 tests
+bun test             # 477 tests
 bun run build
 ```
 

package/dist/index.js

@@ -15927,7 +15927,7 @@ var STATUS_DISPLAY = {
   shutdown: "shut down",
   error: "error"
 };
-function buildLeadSystemPrompt(db, teamId) {
+function buildLeadSystemPrompt(db, teamId, config2) {
   const team = db.query("SELECT name FROM team WHERE id = ?").get(teamId);
   if (!team)
     return "";
@@ -15979,6 +15979,15 @@ function buildLeadSystemPrompt(db, teamId) {
     }
     lines.push("--- End Messages ---");
   }
+  if (config2?.promptForModels) {
+    const poolOptions = config2.modelPool && config2.modelPool.length > 0 ? config2.modelPool.map((m) => `      { label: "${m}", description: "" }`).join(`,
+`) : "";
+    lines.push("", "MODEL SELECTION:", "Before spawning teammates, use the question tool to ask the user about model preferences.", "Do NOT spawn any agents until the user confirms their model preference.", "Keep descriptions simple and clear \u2014 explain what each option means in plain language.", "Example question tool call:", '  question({ questions: [{ question: "Which AI models should your team agents use?", header: "Agent models", options: [', `    { label: "Same as me (Recommended)", description: "Every agent uses the same model I'm running on. Simplest option \u2014 no extra setup needed." },`, '    { label: "Mix of models", description: "Each agent gets a different model from your configured pool. Useful for getting diverse perspectives on the same problem." },', `    { label: "I'll choose per agent", description: "You pick the exact model for each agent as I spawn them. Most control, but requires a choice per agent." }`, "  ]}]})");
+    if (poolOptions) {
+      lines.push('If user picks "Mix of models", ask which models with multiple: true:', '  question({ questions: [{ question: "Which models should agents rotate through? Pick all that apply.", header: "Model pool", multiple: true, options: [', poolOptions, "  ]}]})");
+    }
+    lines.push(`If user picks "I'll choose per agent", ask for each agent's model individually before each team_spawn call.`, "Pass the chosen model via the model parameter on each team_spawn call.");
+  }
   lines.push("", "CRITICAL: Spawn teammates ONE AT A TIME. Send only ONE team_spawn call per response.", "Wait for the tool result before spawning the next teammate.", "Multiple team_spawn calls in a single response will cause timeouts.", "", "Teammates work asynchronously and message you when done.", "Do NOT poll team_status or team_tasks_list repeatedly \u2014 wait for messages.", "After spawning all teammates, tell the user what you've set up and wait.", "When all teammates finish, summarize results and suggest next steps.", "", "MERGE WORKFLOW:", "After a teammate finishes and you shut them down, use team_merge to merge their branch.", "Do NOT tell teammates to commit \u2014 they handle that themselves.", "Do NOT run git merge manually \u2014 use team_merge which handles stashing and unstaging.", "team_cleanup will safety-net merge any branches you forgot, but prefer explicit team_merge.", "", "Before calling team_cleanup, verify teammates have committed their work.", "team_shutdown will warn you if a teammate has uncommitted changes.", "team_cleanup will block if any worktree has uncommitted changes \u2014 merge or commit first.");
   return lines.join(`
 `);
@@ -16086,14 +16095,19 @@ import { readFileSync } from "fs";
 import path2 from "path";
 var DEFAULT_CONFIG = {
   mergeOnCleanup: true,
-  stallThresholdMs: 180000,
-  stallMinSteps: 3,
-  stallTokenThreshold: 500,
+  stallThresholdMs: 300000,
+  stallMinSteps: 5,
+  stallTokenThreshold: 200,
   timeoutMs: 30 * 60 * 1000,
   rateLimitCapacity: 10,
   dashboardPort: 4747,
   peerMessageLimit: 5,
-  peerMessageWindowMs: 300000
+  peerMessageWindowMs: 300000,
+  defaultModel: "",
+  modelPool: [],
+  modelsByAgent: {},
+  modelAssignment: "default",
+  promptForModels: false
 };
 function readConfigFile(filePath) {
   try {
@@ -16118,6 +16132,19 @@ function readConfigFile(filePath) {
       result.peerMessageLimit = raw.peerMessageLimit;
     if (typeof raw.peerMessageWindowMs === "number")
       result.peerMessageWindowMs = raw.peerMessageWindowMs;
+    if (typeof raw.defaultModel === "string")
+      result.defaultModel = raw.defaultModel;
+    if (Array.isArray(raw.modelPool) && raw.modelPool.every((m) => typeof m === "string"))
+      result.modelPool = raw.modelPool;
+    if (typeof raw.modelsByAgent === "object" && raw.modelsByAgent !== null && !Array.isArray(raw.modelsByAgent)) {
+      const valid = Object.entries(raw.modelsByAgent).every(([, v]) => typeof v === "string");
+      if (valid)
+        result.modelsByAgent = raw.modelsByAgent;
+    }
+    if (typeof raw.modelAssignment === "string" && ["default", "rotate", "random"].includes(raw.modelAssignment))
+      result.modelAssignment = raw.modelAssignment;
+    if (typeof raw.promptForModels === "boolean")
+      result.promptForModels = raw.promptForModels;
     return result;
   } catch (err) {
     if (err && typeof err === "object" && "code" in err && err.code === "ENOENT")
@@ -16489,6 +16516,7 @@ function rAgents(t){
         '<span class="text-[10px] px-1.5 py-[1px] rounded '+s.t+' bg-base-800/80 shrink-0">'+s.l+'</span>'+
         spark+
         '<span class="text-[10px] text-txt-500 ml-auto shrink-0">'+E(m.agent)+'</span>'+
+        (m.model?chip(E(m.model),'muted'):'')+
       '</div>'+
       (tr?'<div class="mt-2 text-[13px] text-txt-200 leading-snug truncate">'+E(tr)+'</div>':'')+
       '<div class="mt-2 flex items-center gap-1.5 flex-wrap">'+
@@ -16861,6 +16889,27 @@ function requireTeamMember(deps, sessionId) {
 
 // src/tools/team-spawn.ts
 var spawnFailures = new Map;
+function parseModelId(model) {
+  const slash = model.indexOf("/");
+  if (slash <= 0 || slash === model.length - 1)
+    return;
+  return { providerID: model.slice(0, slash), modelID: model.slice(slash + 1) };
+}
+function resolveModel(explicitModel, agentType, teamMemberCount, config2) {
+  if (explicitModel)
+    return explicitModel;
+  if (config2.modelsByAgent[agentType])
+    return config2.modelsByAgent[agentType];
+  if (config2.modelAssignment === "rotate" && config2.modelPool.length > 0) {
+    return config2.modelPool[teamMemberCount % config2.modelPool.length];
+  }
+  if (config2.modelAssignment === "random" && config2.modelPool.length > 0) {
+    return config2.modelPool[Math.floor(Math.random() * config2.modelPool.length)];
+  }
+  if (config2.defaultModel)
+    return config2.defaultModel;
+  return;
+}
 function getSpawnTimeout() {
   return Number(process.env.SPAWN_TIMEOUT_MS) || 120000;
 }
@@ -16984,8 +17033,12 @@ async function executeTeamSpawn(deps, args, sessionId) {
   }
   const planApproval = usePlanApproval ? "pending" : "none";
   const now = Date.now();
+  const memberCount = deps.db.query("SELECT COUNT(*) as c FROM team_member WHERE team_id = ?").get(teamInfo.teamId).c;
+  const resolvedModel = resolveModel(args.model, args.agent, memberCount, deps.config);
+  if (resolvedModel)
+    log(`spawn:model name=${args.name} model=${resolvedModel}`);
   deps.db.run(`INSERT INTO team_member (team_id, name, session_id, agent, status, execution_status, model, prompt, worktree_dir, worktree_branch, workspace_id, plan_approval, time_created, time_updated)
-     VALUES (?, ?, ?, ?, 'busy', 'starting', ?, ?, ?, ?, ?, ?, ?, ?)`, [teamInfo.teamId, args.name, childSessionId, args.agent, args.model ?? null, args.prompt, worktreeDir, worktreeBranch, workspaceId, planApproval, now, now]);
+     VALUES (?, ?, ?, ?, 'busy', 'starting', ?, ?, ?, ?, ?, ?, ?, ?)`, [teamInfo.teamId, args.name, childSessionId, args.agent, resolvedModel ?? null, args.prompt, worktreeDir, worktreeBranch, workspaceId, planApproval, now, now]);
   deps.registry.register(teamInfo.teamId, args.name, childSessionId);
   const context = [
     `You are "${args.name}", a teammate in team "${teamInfo.teamName}".`,
@@ -17037,13 +17090,19 @@ async function executeTeamSpawn(deps, args, sessionId) {
   }
   const contextStr = context.join(`
 `);
+  const modelParam = resolvedModel ? parseModelId(resolvedModel) : undefined;
+  if (resolvedModel && !modelParam) {
+    log(`spawn:model:invalid name=${args.name} model=${resolvedModel} \u2014 expected "provider/model" format, falling back to default`);
+  }
   log(`spawn:promptAsync:fire name=${args.name} sessionId=${childSessionId}`);
   deps.client.session.promptAsync({
     sessionID: childSessionId,
     parts: [{ type: "text", text: contextStr }],
-    agent: args.agent
-  }).catch(() => {
-    log(`spawn:promptAsync:failed name=${args.name} \u2014 rolling back`);
+    agent: args.agent,
+    ...modelParam ? { model: modelParam } : {}
+  }).catch((err) => {
+    const errMsg = err instanceof Error ? err.message : String(err);
+    log(`spawn:promptAsync:failed name=${args.name} err=${errMsg} \u2014 rolling back`);
     try {
       deps.db.run("DELETE FROM team_member WHERE team_id = ? AND session_id = ?", [teamInfo.teamId, childSessionId]);
       deps.registry.unregister(childSessionId);
@@ -17054,17 +17113,18 @@ async function executeTeamSpawn(deps, args, sessionId) {
       if (worktreeDir) {
         deps.client.worktree.remove({ worktreeRemoveInput: { directory: worktreeDir } }).catch(() => {});
       }
+      const modelInfo = resolvedModel ? ` (model: ${resolvedModel})` : "";
       deps.client.tui.showToast({
         title: "Team",
-        message: `Teammate "${args.name}" failed to start and was removed`,
+        message: `Teammate "${args.name}" failed to start${modelInfo}: ${errMsg}`,
         variant: "error",
-        duration: 5000
+        duration: 8000
       }).catch(() => {});
       sendMessage(deps.db, {
         teamId: teamInfo.teamId,
         from: "system",
         to: "lead",
-        content: `Teammate "${args.name}" failed to start and was removed. You may retry the spawn.`
+        content: `Teammate "${args.name}" failed to start and was removed${modelInfo}. Error: ${errMsg}. You may retry the spawn.`
       });
     } catch {}
   });
@@ -17821,7 +17881,7 @@ var plugin = async (input) => {
   const rawClient = new OpencodeClient({ client: pluginTransport });
   initLog(rawClient);
   const client3 = wrapThrowingClient(rawClient);
-  const deps = { db, registry: registry2, tracker, client: client3, directory: input.directory };
+  const deps = { db, registry: registry2, tracker, client: client3, directory: input.directory, config: config2 };
   if (!isWorktreeInstance(input.directory)) {
     log("init:recovery:start (main instance)");
     const recovery = await recoverStaleMembers(db, client3, input.directory);
@@ -17881,6 +17941,31 @@ var plugin = async (input) => {
             notifyTeamEvent(client3, "shutdown", { memberName: transition.memberName });
           } else if (transition.to === "ready" && transition.from === "busy") {
             notifyTeamEvent(client3, "completed", { memberName: transition.memberName });
+            const fastIdleKey = `fastidle:${transition.teamId}:${transition.memberName}`;
+            if (!nudgedMembers.has(fastIdleKey)) {
+              const memberInfo = db.query("SELECT time_created, model FROM team_member WHERE team_id = ? AND name = ?").get(transition.teamId, transition.memberName);
+              if (memberInfo) {
+                const spawnAge = Date.now() - memberInfo.time_created;
+                const msgCount = db.query("SELECT COUNT(*) as c FROM team_message WHERE team_id = ? AND from_name = ?").get(transition.teamId, transition.memberName).c;
+                if (spawnAge < 15000 && msgCount === 0) {
+                  nudgedMembers.add(fastIdleKey);
+                  const modelInfo = memberInfo.model ? ` (model: ${memberInfo.model})` : "";
+                  log(`fast-idle: ${transition.memberName} went idle ${Math.round(spawnAge / 1000)}s after spawn with 0 messages${modelInfo}`);
+                  sendMessage(db, {
+                    teamId: transition.teamId,
+                    from: "system",
+                    to: "lead",
+                    content: `Warning: Teammate "${transition.memberName}" went idle immediately after spawning with no output${modelInfo}. This usually means the model failed to start (authentication error, invalid model, or provider issue). Check your API key and model configuration, then retry the spawn.`
+                  });
+                  client3.tui.showToast({
+                    title: "Team",
+                    message: `${transition.memberName} failed to produce output${modelInfo}`,
+                    variant: "warning",
+                    duration: 8000
+                  }).catch(() => {});
+                }
+              }
+            }
             const nudgeKey = `${transition.teamId}:${transition.memberName}`;
             if (!nudgedMembers.has(nudgeKey) && shouldNudgeIdleMember(db, transition.teamId, transition.memberName)) {
               nudgedMembers.add(nudgeKey);
@@ -17983,7 +18068,7 @@ var plugin = async (input) => {
       if (!teamInfo)
         return;
       log(`system-prompt:transform role=${teamInfo.role} session=${input2.sessionID}`);
-      const prompt = teamInfo.role === "lead" ? buildLeadSystemPrompt(db, teamInfo.teamId) : buildTeammateSystemPrompt(db, teamInfo.teamId, teamInfo.memberName ?? "unknown");
+      const prompt = teamInfo.role === "lead" ? buildLeadSystemPrompt(db, teamInfo.teamId, config2) : buildTeammateSystemPrompt(db, teamInfo.teamId, teamInfo.memberName ?? "unknown");
       log(`system-prompt:injected role=${teamInfo.role} len=${prompt.length}`);
       output.system.push(prompt);
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hueyexe/opencode-ensemble",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Agent teams for OpenCode — parallel agents with peer-to-peer communication, shared tasks, and coordinated execution",
   "module": "src/index.ts",
   "main": "dist/index.js",

package/src/config.ts

@@ -21,19 +21,34 @@ export interface EnsembleConfig {
   peerMessageLimit?: number
   /** Time window for peer message rate limiting in ms (default: 300000 = 5 min) */
   peerMessageWindowMs?: number
+  /** Default model for all agents (e.g. "opencode/zen-sonnet-4-6") */
+  defaultModel?: string
+  /** Pool of models for rotation/random assignment */
+  modelPool?: string[]
+  /** Map agent type to specific model e.g. {"build": "anthropic/claude-opus-4-6"} */
+  modelsByAgent?: Record<string, string>
+  /** How to assign models: "default" | "rotate" | "random" (default: "default") */
+  modelAssignment?: "default" | "rotate" | "random"
+  /** Lead asks user about model preferences before spawning (default: false) */
+  promptForModels?: boolean
 }
 
 /** Default configuration values. */
 export const DEFAULT_CONFIG: Required<EnsembleConfig> = {
   mergeOnCleanup: true,
-  stallThresholdMs: 180_000,
-  stallMinSteps: 3,
-  stallTokenThreshold: 500,
+  stallThresholdMs: 300_000,
+  stallMinSteps: 5,
+  stallTokenThreshold: 200,
   timeoutMs: 30 * 60 * 1000,
   rateLimitCapacity: 10,
   dashboardPort: 4747,
   peerMessageLimit: 5,
   peerMessageWindowMs: 300_000,
+  defaultModel: "",
+  modelPool: [],
+  modelsByAgent: {},
+  modelAssignment: "default",
+  promptForModels: false,
 }
 
 /** Read a JSON config file, returning an empty object on missing/invalid. */
@@ -52,6 +67,14 @@ function readConfigFile(filePath: string): Partial<EnsembleConfig> {
     if (typeof raw.dashboardPort === "number") result.dashboardPort = raw.dashboardPort
     if (typeof raw.peerMessageLimit === "number") result.peerMessageLimit = raw.peerMessageLimit
     if (typeof raw.peerMessageWindowMs === "number") result.peerMessageWindowMs = raw.peerMessageWindowMs
+    if (typeof raw.defaultModel === "string") result.defaultModel = raw.defaultModel
+    if (Array.isArray(raw.modelPool) && raw.modelPool.every((m: unknown) => typeof m === "string")) result.modelPool = raw.modelPool as string[]
+    if (typeof raw.modelsByAgent === "object" && raw.modelsByAgent !== null && !Array.isArray(raw.modelsByAgent)) {
+      const valid = Object.entries(raw.modelsByAgent as Record<string, unknown>).every(([, v]) => typeof v === "string")
+      if (valid) result.modelsByAgent = raw.modelsByAgent as Record<string, string>
+    }
+    if (typeof raw.modelAssignment === "string" && ["default", "rotate", "random"].includes(raw.modelAssignment)) result.modelAssignment = raw.modelAssignment as "default" | "rotate" | "random"
+    if (typeof raw.promptForModels === "boolean") result.promptForModels = raw.promptForModels
     return result
   } catch (err) {
     if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") return {}

package/src/dashboard-js-part2.ts

@@ -64,6 +64,7 @@ function rAgents(t){
         '<span class="text-[10px] px-1.5 py-[1px] rounded '+s.t+' bg-base-800/80 shrink-0">'+s.l+'</span>'+
         spark+
         '<span class="text-[10px] text-txt-500 ml-auto shrink-0">'+E(m.agent)+'</span>'+
+        (m.model?chip(E(m.model),'muted'):'')+
       '</div>'+
       (tr?'<div class="mt-2 text-[13px] text-txt-200 leading-snug truncate">'+E(tr)+'</div>':'')+
       '<div class="mt-2 flex items-center gap-1.5 flex-wrap">'+

package/src/index.ts

@@ -10,6 +10,7 @@ import { MemberRegistry, DescendantTracker } from "./state"
 import { isWorktreeInstance } from "./util"
 import { handleSessionStatusEvent, handleSessionCreatedEvent, checkToolIsolation, shouldNudgeIdleMember } from "./hooks"
 import { notifyTeamEvent, notifyWorkingProgress } from "./notify"
+import { sendMessage } from "./messaging"
 import { buildLeadSystemPrompt, buildTeammateSystemPrompt, buildTeamCompactionContext } from "./system-prompt"
 import { log, initLog } from "./log"
 import { findTeamBySession } from "./types"
@@ -66,7 +67,7 @@ const plugin: Plugin = async (input) => {
   const rawClient = new OpencodeClient({ client: pluginTransport })
   initLog(rawClient)
   const client = wrapThrowingClient(rawClient)
-  const deps: ToolDeps = { db, registry, tracker, client, directory: input.directory }
+  const deps: ToolDeps = { db, registry, tracker, client, directory: input.directory, config }
 
   // Recovery only runs for the main project instance — NOT for teammate worktree instances.
   // Worktree instances are created during session.create. Running recovery there makes HTTP
@@ -141,6 +142,39 @@ const plugin: Plugin = async (input) => {
             notifyTeamEvent(client, "shutdown", { memberName: transition.memberName })
           } else if (transition.to === "ready" && transition.from === "busy") {
             notifyTeamEvent(client, "completed", { memberName: transition.memberName })
+
+            // Fast-idle detection: if agent went idle within 15s of spawn with zero messages,
+            // the model likely failed silently (auth error, invalid model, etc.)
+            const fastIdleKey = `fastidle:${transition.teamId}:${transition.memberName}`
+            if (!nudgedMembers.has(fastIdleKey)) {
+              const memberInfo = db.query(
+                "SELECT time_created, model FROM team_member WHERE team_id = ? AND name = ?"
+              ).get(transition.teamId, transition.memberName) as { time_created: number; model: string | null } | null
+              if (memberInfo) {
+                const spawnAge = Date.now() - memberInfo.time_created
+                const msgCount = (db.query(
+                  "SELECT COUNT(*) as c FROM team_message WHERE team_id = ? AND from_name = ?"
+                ).get(transition.teamId, transition.memberName) as { c: number }).c
+                if (spawnAge < 15_000 && msgCount === 0) {
+                  nudgedMembers.add(fastIdleKey)
+                  const modelInfo = memberInfo.model ? ` (model: ${memberInfo.model})` : ""
+                  log(`fast-idle: ${transition.memberName} went idle ${Math.round(spawnAge / 1000)}s after spawn with 0 messages${modelInfo}`)
+                  sendMessage(db, {
+                    teamId: transition.teamId,
+                    from: "system",
+                    to: "lead",
+                    content: `Warning: Teammate "${transition.memberName}" went idle immediately after spawning with no output${modelInfo}. This usually means the model failed to start (authentication error, invalid model, or provider issue). Check your API key and model configuration, then retry the spawn.`,
+                  })
+                  client.tui.showToast({
+                    title: "Team",
+                    message: `${transition.memberName} failed to produce output${modelInfo}`,
+                    variant: "warning",
+                    duration: 8000,
+                  }).catch(() => { /* TUI may not be available */ })
+                }
+              }
+            }
+
             // Nudge teammate if they went idle without reporting to the lead (once only)
             const nudgeKey = `${transition.teamId}:${transition.memberName}`
             if (!nudgedMembers.has(nudgeKey) && shouldNudgeIdleMember(db, transition.teamId, transition.memberName)) {
@@ -270,7 +304,7 @@ const plugin: Plugin = async (input) => {
       if (!teamInfo) return
       log(`system-prompt:transform role=${teamInfo.role} session=${input.sessionID}`)
       const prompt = teamInfo.role === "lead"
-        ? buildLeadSystemPrompt(db, teamInfo.teamId)
+        ? buildLeadSystemPrompt(db, teamInfo.teamId, config)
         : buildTeammateSystemPrompt(db, teamInfo.teamId, teamInfo.memberName ?? "unknown")
       log(`system-prompt:injected role=${teamInfo.role} len=${prompt.length}`)
       output.system.push(prompt)

package/src/system-prompt.ts

@@ -1,6 +1,7 @@
 import type { Database } from "bun:sqlite"
 import { markDelivered } from "./messaging"
 import { parseTaskResult, formatTaskResult } from "./result-parser"
+import type { EnsembleConfig } from "./config"
 
 /** Truncate a string to maxLen chars, appending "..." if truncated. */
 function truncate(s: string, maxLen: number): string {
@@ -20,7 +21,7 @@ const STATUS_DISPLAY: Record<string, string> = {
  * Build the system prompt injected into the lead's session.
  * Includes team name, member statuses, task counts, and anti-polling guidance.
  */
-export function buildLeadSystemPrompt(db: Database, teamId: string): string {
+export function buildLeadSystemPrompt(db: Database, teamId: string, config?: Required<EnsembleConfig>): string {
   const team = db.query("SELECT name FROM team WHERE id = ?").get(teamId) as { name: string } | null
   if (!team) return ""
 
@@ -98,6 +99,38 @@ export function buildLeadSystemPrompt(db: Database, teamId: string): string {
     lines.push("--- End Messages ---")
   }
 
+  // Model selection guidance (only when promptForModels is enabled)
+  if (config?.promptForModels) {
+    const poolOptions = (config.modelPool && config.modelPool.length > 0)
+      ? config.modelPool.map(m => `      { label: "${m}", description: "" }`).join(",\n")
+      : ""
+    lines.push(
+      "",
+      "MODEL SELECTION:",
+      "Before spawning teammates, use the question tool to ask the user about model preferences.",
+      "Do NOT spawn any agents until the user confirms their model preference.",
+      "Keep descriptions simple and clear — explain what each option means in plain language.",
+      "Example question tool call:",
+      '  question({ questions: [{ question: "Which AI models should your team agents use?", header: "Agent models", options: [',
+      '    { label: "Same as me (Recommended)", description: "Every agent uses the same model I\'m running on. Simplest option — no extra setup needed." },',
+      '    { label: "Mix of models", description: "Each agent gets a different model from your configured pool. Useful for getting diverse perspectives on the same problem." },',
+      '    { label: "I\'ll choose per agent", description: "You pick the exact model for each agent as I spawn them. Most control, but requires a choice per agent." }',
+      "  ]}]})",
+    )
+    if (poolOptions) {
+      lines.push(
+        'If user picks "Mix of models", ask which models with multiple: true:',
+        "  question({ questions: [{ question: \"Which models should agents rotate through? Pick all that apply.\", header: \"Model pool\", multiple: true, options: [",
+        poolOptions,
+        "  ]}]})",
+      )
+    }
+    lines.push(
+      'If user picks "I\'ll choose per agent", ask for each agent\'s model individually before each team_spawn call.',
+      "Pass the chosen model via the model parameter on each team_spawn call.",
+    )
+  }
+
   lines.push(
     "",
     "CRITICAL: Spawn teammates ONE AT A TIME. Send only ONE team_spawn call per response.",

package/src/tools/team-spawn.ts

@@ -3,10 +3,40 @@ import { validateMemberName } from "../util"
 import { requireLead } from "./shared"
 import { sendMessage } from "../messaging"
 import { log } from "../log"
+import type { EnsembleConfig } from "../config"
 
 /** Tracks consecutive spawn failures per team for circuit breaker. */
 export const spawnFailures = new Map<string, { count: number; lastError: string }>()
 
+/** Parse "provider/model" string into { providerID, modelID } for the SDK. */
+function parseModelId(model: string): { providerID: string; modelID: string } | undefined {
+  const slash = model.indexOf("/")
+  if (slash <= 0 || slash === model.length - 1) return undefined
+  return { providerID: model.slice(0, slash), modelID: model.slice(slash + 1) }
+}
+
+/**
+ * Resolve which model to use for a spawned agent.
+ * Priority: explicit arg > modelsByAgent > rotation/random > defaultModel > undefined.
+ */
+export function resolveModel(
+  explicitModel: string | undefined,
+  agentType: string,
+  teamMemberCount: number,
+  config: Required<EnsembleConfig>,
+): string | undefined {
+  if (explicitModel) return explicitModel
+  if (config.modelsByAgent[agentType]) return config.modelsByAgent[agentType]
+  if (config.modelAssignment === "rotate" && config.modelPool.length > 0) {
+    return config.modelPool[teamMemberCount % config.modelPool.length]
+  }
+  if (config.modelAssignment === "random" && config.modelPool.length > 0) {
+    return config.modelPool[Math.floor(Math.random() * config.modelPool.length)]
+  }
+  if (config.defaultModel) return config.defaultModel
+  return undefined
+}
+
 /** Timeout for worktree.create and session.create to prevent hanging on git lock contention. */
 function getSpawnTimeout(): number {
   return Number(process.env.SPAWN_TIMEOUT_MS) || 120_000
@@ -182,10 +212,15 @@ export async function executeTeamSpawn(
   // Register in DB
   const planApproval = usePlanApproval ? "pending" : "none"
   const now = Date.now()
+  // Resolve model before DB insert so the stored value matches what promptAsync uses
+  const memberCount = (deps.db.query("SELECT COUNT(*) as c FROM team_member WHERE team_id = ?").get(teamInfo.teamId) as { c: number }).c
+  const resolvedModel = resolveModel(args.model, args.agent, memberCount, deps.config)
+  if (resolvedModel) log(`spawn:model name=${args.name} model=${resolvedModel}`)
+
   deps.db.run(
     `INSERT INTO team_member (team_id, name, session_id, agent, status, execution_status, model, prompt, worktree_dir, worktree_branch, workspace_id, plan_approval, time_created, time_updated)
      VALUES (?, ?, ?, ?, 'busy', 'starting', ?, ?, ?, ?, ?, ?, ?, ?)`,
-    [teamInfo.teamId, args.name, childSessionId, args.agent, args.model ?? null, args.prompt, worktreeDir, worktreeBranch, workspaceId, planApproval, now, now]
+    [teamInfo.teamId, args.name, childSessionId, args.agent, resolvedModel ?? null, args.prompt, worktreeDir, worktreeBranch, workspaceId, planApproval, now, now]
   )
 
   // Register in memory
@@ -316,16 +351,23 @@ export async function executeTeamSpawn(
 
   const contextStr = context.join("\n")
 
+  // Model was already resolved before DB insert — just parse for promptAsync
+  const modelParam = resolvedModel ? parseModelId(resolvedModel) : undefined
+  if (resolvedModel && !modelParam) {
+    log(`spawn:model:invalid name=${args.name} model=${resolvedModel} — expected "provider/model" format, falling back to default`)
+  }
+
   // Fire-and-forget: send prompt to teammate session.
   log(`spawn:promptAsync:fire name=${args.name} sessionId=${childSessionId}`)
   deps.client.session.promptAsync({
     sessionID: childSessionId,
     parts: [{ type: "text", text: contextStr }],
     agent: args.agent,
-  }).catch(() => {
-    log(`spawn:promptAsync:failed name=${args.name} — rolling back`)
+    ...(modelParam ? { model: modelParam } : {}),
+  }).catch((err) => {
+    const errMsg = err instanceof Error ? err.message : String(err)
+    log(`spawn:promptAsync:failed name=${args.name} err=${errMsg} — rolling back`)
     try {
-      // Async rollback: clean up DB (by session_id to avoid deleting a re-spawned member with the same name), registry, session, and worktree
       deps.db.run("DELETE FROM team_member WHERE team_id = ? AND session_id = ?", [teamInfo.teamId, childSessionId])
       deps.registry.unregister(childSessionId)
       deps.client.session.abort({ sessionID: childSessionId }).catch(() => { /* best effort */ })
@@ -335,20 +377,18 @@ export async function executeTeamSpawn(
       if (worktreeDir) {
         deps.client.worktree.remove({ worktreeRemoveInput: { directory: worktreeDir } }).catch(() => { /* best effort */ })
       }
-      // Notify user that spawn failed so the lead doesn't think the teammate is active
+      const modelInfo = resolvedModel ? ` (model: ${resolvedModel})` : ""
       deps.client.tui.showToast({
         title: "Team",
-        message: `Teammate "${args.name}" failed to start and was removed`,
+        message: `Teammate "${args.name}" failed to start${modelInfo}: ${errMsg}`,
         variant: "error",
-        duration: 5000,
+        duration: 8000,
       }).catch(() => { /* TUI may not be available */ })
-      // Notify the lead model so it can react (retry, adjust plan, etc.)
-      // Message delivered via system prompt transform on the lead's next turn.
       sendMessage(deps.db, {
         teamId: teamInfo.teamId,
         from: "system",
         to: "lead",
-        content: `Teammate "${args.name}" failed to start and was removed. You may retry the spawn.`,
+        content: `Teammate "${args.name}" failed to start and was removed${modelInfo}. Error: ${errMsg}. You may retry the spawn.`,
       })
     } catch { /* rollback failed — watchdog will clean up stale member */ }
   })

package/src/types.ts

@@ -1,5 +1,6 @@
 import type { Database } from "bun:sqlite"
 import type { MemberRegistry, DescendantTracker } from "./state"
+import type { EnsembleConfig } from "./config"
 
 /**
  * Shared dependencies injected into every tool's execute function.
@@ -13,6 +14,8 @@ export interface ToolDeps {
   client: PluginClient
   /** The project root directory — used for reading AGENTS.md and other project files. */
   directory: string
+  /** Plugin configuration. */
+  config: Required<EnsembleConfig>
 }
 
 /** A single permission rule for session-level enforcement. */