@hueyexe/opencode-ensemble 0.10.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-460%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.10.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.10.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:
 
@@ -242,11 +250,62 @@ Teammate messages arrive in the lead's session as `[Team message from alice]: ..
 - **Spawn rollback**: if the initial prompt fails, the member, session, and worktree are all cleaned up
 - **Timeout watchdog**: teammates stuck busy beyond the TTL are automatically timed out and aborted
 - **Stall detection**: detects teammates making no progress (low output tokens or no communication) and escalates to the lead
+- **Peer-to-peer communication**: teammates can message each other directly, with idle-flush delivery and chatty agent detection
 - **Auto-merge on cleanup**: worktree branches are squash-merged into your working directory as unstaged changes for review
 - **Spawn circuit breaker**: stops retrying after 3 consecutive spawn failures
 - **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.
@@ -258,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
 }
 ```
 
@@ -274,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
 
@@ -298,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
@@ -336,7 +405,7 @@ Same coordination model (shared tasks, peer messaging, lead coordination) with s
 ```bash
 bun install
 bun run typecheck
-bun test             # 460 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(`
 `);
@@ -15987,7 +15996,28 @@ function buildTeammateSystemPrompt(db, teamId, memberName) {
   const team = db.query("SELECT name FROM team WHERE id = ?").get(teamId);
   if (!team)
     return "";
-  return `You are "${memberName}", a teammate in team "${team.name}". Use team_message to communicate. You MUST send your results to the lead via team_message before stopping.`;
+  const lines = [
+    `You are "${memberName}", a teammate in team "${team.name}". Use team_message to communicate. You MUST send your results to the lead via team_message before stopping.`
+  ];
+  const pendingMessages = db.query("SELECT id, from_name, content FROM team_message WHERE team_id = ? AND to_name = ? AND delivered = 0 ORDER BY time_created ASC").all(teamId, memberName);
+  if (pendingMessages.length > 0) {
+    lines.push("", "--- Messages for you ---");
+    const MAX_MSG = 500;
+    for (const msg of pendingMessages) {
+      const parsed = parseTaskResult(msg.content);
+      if (parsed) {
+        lines.push(formatTaskResult(msg.from_name, { ...parsed, details: truncate(parsed.details, MAX_MSG) }));
+      } else if (msg.content.length > MAX_MSG) {
+        lines.push(`[From ${msg.from_name}]: ${msg.content.slice(0, MAX_MSG)}... (truncated)`);
+      } else {
+        lines.push(`[From ${msg.from_name}]: ${msg.content}`);
+      }
+      markDelivered(db, msg.id);
+    }
+    lines.push("--- End Messages ---");
+  }
+  return lines.join(`
+`);
 }
 function buildTeamCompactionContext(db, teamId, role, memberName) {
   const team = db.query("SELECT name FROM team WHERE id = ?").get(teamId);
@@ -16065,12 +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
+  dashboardPort: 4747,
+  peerMessageLimit: 5,
+  peerMessageWindowMs: 300000,
+  defaultModel: "",
+  modelPool: [],
+  modelsByAgent: {},
+  modelAssignment: "default",
+  promptForModels: false
 };
 function readConfigFile(filePath) {
   try {
@@ -16091,6 +16128,23 @@ function readConfigFile(filePath) {
       result.rateLimitCapacity = raw.rateLimitCapacity;
     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) => 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")
@@ -16123,7 +16177,9 @@ class ProgressTracker {
   steps = new Map;
   lastMessageAt = new Map;
   lastTaskAt = new Map;
+  peerMessages = new Map;
   reported = new Set;
+  chattyReported = new Set;
   maxSteps;
   constructor(maxSteps = 10) {
     this.maxSteps = maxSteps;
@@ -16135,6 +16191,31 @@ class ProgressTracker {
       records.shift();
     this.steps.set(sessionId, records);
   }
+  recordPeerMessage(sessionId) {
+    const timestamps = this.peerMessages.get(sessionId) ?? [];
+    timestamps.push(Date.now());
+    this.peerMessages.set(sessionId, timestamps);
+  }
+  isChatty(sessionId, limit, windowMs) {
+    if (limit === 0)
+      return false;
+    const timestamps = this.peerMessages.get(sessionId);
+    if (!timestamps)
+      return false;
+    const cutoff = Date.now() - windowMs;
+    const recent = timestamps.filter((t) => t >= cutoff);
+    this.peerMessages.set(sessionId, recent);
+    return recent.length >= limit;
+  }
+  markChattyReported(sessionId) {
+    this.chattyReported.add(sessionId);
+  }
+  isChattyReported(sessionId) {
+    return this.chattyReported.has(sessionId);
+  }
+  clearChattyReport(sessionId) {
+    this.chattyReported.delete(sessionId);
+  }
   recordMessage(sessionId) {
     this.lastMessageAt.set(sessionId, Date.now());
     this.clearReport(sessionId);
@@ -16173,7 +16254,9 @@ class ProgressTracker {
     this.steps.delete(sessionId);
     this.lastMessageAt.delete(sessionId);
     this.lastTaskAt.delete(sessionId);
+    this.peerMessages.delete(sessionId);
     this.reported.delete(sessionId);
+    this.chattyReported.delete(sessionId);
   }
 }
 
@@ -16433,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">'+
@@ -16558,16 +16642,17 @@ function rActivity(t){
     const p=parseR(m.content);
     const deliv=m.delivered?(m.read?'\\u2713\\u2713':'\\u2713'):'';
     const isFromAgent=m.fromName!=='lead'&&m.fromName!=='system';
+    const isPeer=isFromAgent&&m.toName&&m.toName!=='lead'&&m.toName!=='all';
     const align=isFromAgent?'mr-6':'ml-6';
-    const bubbleBg=isFromAgent?'bg-blue-500/[0.06] border-blue-500/15':'bg-base-800/40 border-base-700/30';
+    const bubbleBg=isPeer?'bg-violet-500/[0.06] border-violet-500/15':isFromAgent?'bg-blue-500/[0.06] border-blue-500/15':'bg-base-800/40 border-base-700/30';
     const initial=m.fromName.charAt(0).toUpperCase();
-    const avatarColor=m.fromName==='system'?'bg-amber-500/20 text-amber-400':isFromAgent?'bg-blue-500/20 text-blue-400':'bg-emerald-500/20 text-emerald-400';
+    const avatarColor=m.fromName==='system'?'bg-amber-500/20 text-amber-400':isPeer?'bg-violet-500/20 text-violet-400':isFromAgent?'bg-blue-500/20 text-blue-400':'bg-emerald-500/20 text-emerald-400';
     html+='<div class="'+align+(isNew?' hl':'')+' cursor-pointer" data-msg="'+E(m.id)+'" onclick="toggleMsg(\\''+E(m.id)+'\\')">';
     html+='<div class="flex items-start gap-2">';
     html+='<span class="w-5 h-5 rounded-full '+avatarColor+' flex items-center justify-center text-[9px] font-semibold shrink-0 mt-0.5">'+E(initial)+'</span>';
     html+='<div class="flex-1 min-w-0 rounded-xl border '+bubbleBg+' px-3 py-2">';
     html+='<div class="flex items-center gap-1.5 mb-1">';
-    html+='<span class="text-[11px] font-medium '+(isFromAgent?'text-blue-400':'text-txt-300')+'">'+E(m.fromName)+'</span>';
+    html+='<span class="text-[11px] font-medium '+(isPeer?'text-violet-400':isFromAgent?'text-blue-400':'text-txt-300')+'">'+E(m.fromName)+'</span>';
     if(m.toName)html+=chip('\\u2192 '+E(m.toName),'muted');
     html+=chip(relT(m.timeCreated),'muted');
     if(deliv)html+='<span class="text-txt-500 text-[10px] ml-auto">'+deliv+'</span>';
@@ -16804,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;
 }
@@ -16927,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}".`,
@@ -16953,6 +17063,9 @@ async function executeTeamSpawn(deps, args, sessionId) {
   } else {
     context.push("", "Tools available to you:", "- team_message: send a message to the lead or another teammate", "- team_broadcast: send a message to all team members", "- team_tasks_list: view the shared team task board", "- team_tasks_add: add tasks to the shared board", "- team_tasks_complete: mark a task complete on the shared board", "- team_claim: claim a pending task from the shared board");
   }
+  if (otherMembers.length > 0) {
+    context.push("", "Collaboration:", "- Check team_tasks_list to see what other teammates are working on.", "- If you need information another teammate has, message them directly via team_message.", "- If you discover something relevant to another teammate's task, share it with them.", "- Use team_broadcast for updates that affect the whole team.", "- Keep peer messages focused and actionable \u2014 coordinate, don't chat.");
+  }
   context.push("", "When you finish your task:");
   if (!isReadOnly && worktreeBranch) {
     context.push(`1. Commit your changes: git add -A && git commit -m "your summary"`);
@@ -16977,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);
@@ -16994,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 {}
   });
@@ -17020,6 +17140,19 @@ async function executeTeamMessage(deps, args, sessionId) {
   const teamInfo = requireTeamMember(deps, sessionId);
   const senderName = teamInfo.role === "lead" ? "lead" : teamInfo.memberName ?? "unknown";
   const recipientSessionId = resolveRecipientSession(deps.db, deps.registry, teamInfo.teamId, args.to);
+  if (!recipientSessionId && args.to !== "lead") {
+    if (args.approve || args.reject) {
+      throw new Error(`Cannot approve/reject plan for "${args.to}" \u2014 they haven't been spawned yet.`);
+    }
+    sendMessage(deps.db, {
+      teamId: teamInfo.teamId,
+      from: senderName,
+      to: args.to,
+      content: args.text
+    });
+    log(`team_message:queued from=${senderName} to=${args.to} (recipient not yet spawned)`);
+    return `Message queued for ${args.to} \u2014 they haven't been spawned yet. It will be delivered when they join the team.`;
+  }
   if (!recipientSessionId)
     throw new Error(`Recipient "${args.to}" not found in team "${teamInfo.teamName}"`);
   let messageText = args.text;
@@ -17580,6 +17713,8 @@ class Watchdog {
   stallMinSteps;
   stallTokenThreshold;
   cwd;
+  peerMessageLimit;
+  peerMessageWindowMs;
   timer;
   constructor(opts) {
     this.db = opts.db;
@@ -17592,6 +17727,8 @@ class Watchdog {
     this.stallMinSteps = opts.stallMinSteps ?? 3;
     this.stallTokenThreshold = opts.stallTokenThreshold ?? 500;
     this.cwd = opts.cwd;
+    this.peerMessageLimit = opts.peerMessageLimit ?? 0;
+    this.peerMessageWindowMs = opts.peerMessageWindowMs ?? 300000;
   }
   static STALE_THRESHOLD_MS = Number(process.env.STALE_WORKTREE_THRESHOLD_MS) || 300000;
   async cleanupStaleWorktrees() {
@@ -17649,9 +17786,36 @@ class Watchdog {
       } catch {}
     }
   }
+  async checkChatty() {
+    if (!this.progressTracker || this.peerMessageLimit === 0)
+      return;
+    const busy = this.db.query(`SELECT tm.team_id, tm.name, tm.session_id
+       FROM team_member tm
+       JOIN team t ON tm.team_id = t.id
+       WHERE t.status = 'active' AND tm.status = 'busy'`).all();
+    for (const member of busy) {
+      if (this.progressTracker.isChattyReported(member.session_id))
+        continue;
+      if (!this.progressTracker.isChatty(member.session_id, this.peerMessageLimit, this.peerMessageWindowMs))
+        continue;
+      this.progressTracker.markChattyReported(member.session_id);
+      this.client.session.promptAsync({
+        sessionID: member.session_id,
+        parts: [{ type: "text", text: "[System]: You've sent several messages to teammates. Focus on completing your task and send your results to the lead via team_message." }]
+      }).catch(() => {});
+      sendMessage(this.db, {
+        teamId: member.team_id,
+        from: "system",
+        to: "lead",
+        content: `Agent "${member.name}" is sending many peer messages and may be over-coordinating. Consider checking on them.`
+      });
+      log(`watchdog:chatty member=${member.name} limit=${this.peerMessageLimit}`);
+    }
+  }
   async check() {
     await this.cleanupStaleWorktrees();
     await this.checkStalled();
+    await this.checkChatty();
     if (this.ttlMs === 0)
       return;
     const cutoff = Date.now() - this.ttlMs;
@@ -17717,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);
@@ -17761,7 +17925,9 @@ var plugin = async (input) => {
     stallThresholdMs: config2.stallThresholdMs,
     stallMinSteps: config2.stallMinSteps,
     stallTokenThreshold: config2.stallTokenThreshold,
-    cwd: input.directory
+    cwd: input.directory,
+    peerMessageLimit: config2.peerMessageLimit,
+    peerMessageWindowMs: config2.peerMessageWindowMs
   });
   watchdog.start();
   return {
@@ -17775,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);
@@ -17829,6 +18020,22 @@ var plugin = async (input) => {
               });
             }
           }
+          const member = db.query(`SELECT tm.team_id, tm.name FROM team_member tm
+             JOIN team t ON tm.team_id = t.id
+             WHERE tm.session_id = ? AND t.status = 'active'`).get(sessionID);
+          if (member) {
+            const staleThreshold = Date.now() - 5000;
+            const peerMsgs = db.query("SELECT COUNT(*) as c FROM team_message WHERE team_id = ? AND to_name = ? AND delivered = 0 AND time_created < ?").get(member.team_id, member.name, staleThreshold);
+            if (peerMsgs.c > 0) {
+              log(`wake-peer: ${member.name} has ${peerMsgs.c} pending peer messages`);
+              client3.session.promptAsync({
+                sessionID,
+                parts: [{ type: "text", text: `[System: ${peerMsgs.c} new message(s) from teammates]` }]
+              }).catch((err) => {
+                log(`wake-peer:failed err=${err instanceof Error ? err.message : String(err)}`);
+              });
+            }
+          }
         }
       }
       if (event.type === "session.created") {
@@ -17861,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);
     },
@@ -17931,6 +18138,8 @@ var plugin = async (input) => {
         async execute(args, ctx) {
           const result = await executeTeamMessage(deps, args, ctx.sessionID);
           progressTracker.recordMessage(ctx.sessionID);
+          if (args.to !== "lead")
+            progressTracker.recordPeerMessage(ctx.sessionID);
           ctx.metadata({ title: `Message \u2192 ${args.to}` });
           return result;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hueyexe/opencode-ensemble",
-  "version": "0.10.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

@@ -17,17 +17,38 @@ export interface EnsembleConfig {
   rateLimitCapacity?: number
   /** Dashboard server port (default: 4747, 0 to disable) */
   dashboardPort?: number
+  /** Max peer messages per agent per window before nudge (default: 5, 0 to disable) */
+  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. */
@@ -44,6 +65,16 @@ function readConfigFile(filePath: string): Partial<EnsembleConfig> {
     if (typeof raw.timeoutMs === "number") result.timeoutMs = raw.timeoutMs
     if (typeof raw.rateLimitCapacity === "number") result.rateLimitCapacity = raw.rateLimitCapacity
     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">'+
@@ -189,16 +190,17 @@ function rActivity(t){
     const p=parseR(m.content);
     const deliv=m.delivered?(m.read?'\\u2713\\u2713':'\\u2713'):'';
     const isFromAgent=m.fromName!=='lead'&&m.fromName!=='system';
+    const isPeer=isFromAgent&&m.toName&&m.toName!=='lead'&&m.toName!=='all';
     const align=isFromAgent?'mr-6':'ml-6';
-    const bubbleBg=isFromAgent?'bg-blue-500/[0.06] border-blue-500/15':'bg-base-800/40 border-base-700/30';
+    const bubbleBg=isPeer?'bg-violet-500/[0.06] border-violet-500/15':isFromAgent?'bg-blue-500/[0.06] border-blue-500/15':'bg-base-800/40 border-base-700/30';
     const initial=m.fromName.charAt(0).toUpperCase();
-    const avatarColor=m.fromName==='system'?'bg-amber-500/20 text-amber-400':isFromAgent?'bg-blue-500/20 text-blue-400':'bg-emerald-500/20 text-emerald-400';
+    const avatarColor=m.fromName==='system'?'bg-amber-500/20 text-amber-400':isPeer?'bg-violet-500/20 text-violet-400':isFromAgent?'bg-blue-500/20 text-blue-400':'bg-emerald-500/20 text-emerald-400';
     html+='<div class="'+align+(isNew?' hl':'')+' cursor-pointer" data-msg="'+E(m.id)+'" onclick="toggleMsg(\\''+E(m.id)+'\\')">';
     html+='<div class="flex items-start gap-2">';
     html+='<span class="w-5 h-5 rounded-full '+avatarColor+' flex items-center justify-center text-[9px] font-semibold shrink-0 mt-0.5">'+E(initial)+'</span>';
     html+='<div class="flex-1 min-w-0 rounded-xl border '+bubbleBg+' px-3 py-2">';
     html+='<div class="flex items-center gap-1.5 mb-1">';
-    html+='<span class="text-[11px] font-medium '+(isFromAgent?'text-blue-400':'text-txt-300')+'">'+E(m.fromName)+'</span>';
+    html+='<span class="text-[11px] font-medium '+(isPeer?'text-violet-400':isFromAgent?'text-blue-400':'text-txt-300')+'">'+E(m.fromName)+'</span>';
     if(m.toName)html+=chip('\\u2192 '+E(m.toName),'muted');
     html+=chip(relT(m.timeCreated),'muted');
     if(deliv)html+='<span class="text-txt-500 text-[10px] ml-auto">'+deliv+'</span>';

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
@@ -122,6 +123,8 @@ const plugin: Plugin = async (input) => {
     stallMinSteps: config.stallMinSteps,
     stallTokenThreshold: config.stallTokenThreshold,
     cwd: input.directory,
+    peerMessageLimit: config.peerMessageLimit,
+    peerMessageWindowMs: config.peerMessageWindowMs,
   })
   watchdog.start()
 
@@ -139,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)) {
@@ -206,6 +242,29 @@ const plugin: Plugin = async (input) => {
               })
             }
           }
+
+          // Also flush peer messages for teammates that just went idle
+          // Only flush messages older than 5s to avoid double-delivery with the direct promptAsync path
+          const member = db.query(
+            `SELECT tm.team_id, tm.name FROM team_member tm
+             JOIN team t ON tm.team_id = t.id
+             WHERE tm.session_id = ? AND t.status = 'active'`
+          ).get(sessionID) as { team_id: string; name: string } | null
+          if (member) {
+            const staleThreshold = Date.now() - 5000
+            const peerMsgs = db.query(
+              "SELECT COUNT(*) as c FROM team_message WHERE team_id = ? AND to_name = ? AND delivered = 0 AND time_created < ?"
+            ).get(member.team_id, member.name, staleThreshold) as { c: number }
+            if (peerMsgs.c > 0) {
+              log(`wake-peer: ${member.name} has ${peerMsgs.c} pending peer messages`)
+              client.session.promptAsync({
+                sessionID,
+                parts: [{ type: "text", text: `[System: ${peerMsgs.c} new message(s) from teammates]` }],
+              }).catch((err) => {
+                log(`wake-peer:failed err=${err instanceof Error ? err.message : String(err)}`)
+              })
+            }
+          }
         }
       }
 
@@ -245,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)
@@ -325,6 +384,8 @@ const plugin: Plugin = async (input) => {
           const result = await executeTeamMessage(deps, args, ctx.sessionID)
           // Track message activity for stall detection
           progressTracker.recordMessage(ctx.sessionID)
+          // Track peer messages for chatty detection
+          if (args.to !== "lead") progressTracker.recordPeerMessage(ctx.sessionID)
           ctx.metadata({ title: `Message → ${args.to}` })
           return result
         },

package/src/progress.ts

@@ -12,7 +12,9 @@ export class ProgressTracker {
   private steps = new Map<string, StepRecord[]>()
   private lastMessageAt = new Map<string, number>()
   private lastTaskAt = new Map<string, number>()
+  private peerMessages = new Map<string, number[]>()
   private reported = new Set<string>()
+  private chattyReported = new Set<string>()
   private readonly maxSteps: number
 
   constructor(maxSteps = 10) {
@@ -27,6 +29,40 @@ export class ProgressTracker {
     this.steps.set(sessionId, records)
   }
 
+  /** Record a peer message (not to lead). Used for chatty detection. */
+  recordPeerMessage(sessionId: string): void {
+    const timestamps = this.peerMessages.get(sessionId) ?? []
+    timestamps.push(Date.now())
+    this.peerMessages.set(sessionId, timestamps)
+  }
+
+  /** Check if agent is chatty: more than `limit` peer messages within `windowMs`. */
+  isChatty(sessionId: string, limit: number, windowMs: number): boolean {
+    if (limit === 0) return false
+    const timestamps = this.peerMessages.get(sessionId)
+    if (!timestamps) return false
+    const cutoff = Date.now() - windowMs
+    const recent = timestamps.filter(t => t >= cutoff)
+    // Prune old timestamps
+    this.peerMessages.set(sessionId, recent)
+    return recent.length >= limit
+  }
+
+  /** Mark chatty as reported (avoid spam). */
+  markChattyReported(sessionId: string): void {
+    this.chattyReported.add(sessionId)
+  }
+
+  /** Check if chatty already reported. */
+  isChattyReported(sessionId: string): boolean {
+    return this.chattyReported.has(sessionId)
+  }
+
+  /** Clear chatty report (e.g., when agent sends result to lead). */
+  clearChattyReport(sessionId: string): void {
+    this.chattyReported.delete(sessionId)
+  }
+
   /** Record that this member sent a team_message. Clears stall report. */
   recordMessage(sessionId: string): void {
     this.lastMessageAt.set(sessionId, Date.now())
@@ -80,6 +116,8 @@ export class ProgressTracker {
     this.steps.delete(sessionId)
     this.lastMessageAt.delete(sessionId)
     this.lastTaskAt.delete(sessionId)
+    this.peerMessages.delete(sessionId)
     this.reported.delete(sessionId)
+    this.chattyReported.delete(sessionId)
   }
 }

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.",
@@ -125,13 +158,39 @@ export function buildLeadSystemPrompt(db: Database, teamId: string): string {
 
 /**
  * Build the system prompt injected into a teammate's session.
- * Short role reminder with name, team name, and communication tool.
+ * Includes role reminder and delivers any pending peer messages.
  */
 export function buildTeammateSystemPrompt(db: Database, teamId: string, memberName: string): string {
   const team = db.query("SELECT name FROM team WHERE id = ?").get(teamId) as { name: string } | null
   if (!team) return ""
 
-  return `You are "${memberName}", a teammate in team "${team.name}". Use team_message to communicate. You MUST send your results to the lead via team_message before stopping.`
+  const lines = [
+    `You are "${memberName}", a teammate in team "${team.name}". Use team_message to communicate. You MUST send your results to the lead via team_message before stopping.`,
+  ]
+
+  // Deliver pending peer messages addressed to this teammate
+  const pendingMessages = db.query(
+    "SELECT id, from_name, content FROM team_message WHERE team_id = ? AND to_name = ? AND delivered = 0 ORDER BY time_created ASC"
+  ).all(teamId, memberName) as Array<{ id: string; from_name: string; content: string }>
+
+  if (pendingMessages.length > 0) {
+    lines.push("", "--- Messages for you ---")
+    const MAX_MSG = 500
+    for (const msg of pendingMessages) {
+      const parsed = parseTaskResult(msg.content)
+      if (parsed) {
+        lines.push(formatTaskResult(msg.from_name, { ...parsed, details: truncate(parsed.details, MAX_MSG) }))
+      } else if (msg.content.length > MAX_MSG) {
+        lines.push(`[From ${msg.from_name}]: ${msg.content.slice(0, MAX_MSG)}... (truncated)`)
+      } else {
+        lines.push(`[From ${msg.from_name}]: ${msg.content}`)
+      }
+      markDelivered(db, msg.id)
+    }
+    lines.push("--- End Messages ---")
+  }
+
+  return lines.join("\n")
 }
 
 /**

package/src/tools/team-message.ts

@@ -18,6 +18,22 @@ export async function executeTeamMessage(
   const senderName = teamInfo.role === "lead" ? "lead" : (teamInfo.memberName ?? "unknown")
 
   const recipientSessionId = resolveRecipientSession(deps.db, deps.registry, teamInfo.teamId, args.to)
+
+  // If recipient not found, store the message for later delivery (they may not be spawned yet)
+  // Reject approve/reject flags for unspawned recipients — plan approval requires the member to exist
+  if (!recipientSessionId && args.to !== "lead") {
+    if (args.approve || args.reject) {
+      throw new Error(`Cannot approve/reject plan for "${args.to}" — they haven't been spawned yet.`)
+    }
+    sendMessage(deps.db, {
+      teamId: teamInfo.teamId,
+      from: senderName,
+      to: args.to,
+      content: args.text,
+    })
+    log(`team_message:queued from=${senderName} to=${args.to} (recipient not yet spawned)`)
+    return `Message queued for ${args.to} — they haven't been spawned yet. It will be delivered when they join the team.`
+  }
   if (!recipientSessionId) throw new Error(`Recipient "${args.to}" not found in team "${teamInfo.teamName}"`)
 
   // Handle plan approval/rejection

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
@@ -253,6 +288,19 @@ export async function executeTeamSpawn(
     )
   }
 
+  // Collaboration guidance for peer-to-peer communication
+  if (otherMembers.length > 0) {
+    context.push(
+      "",
+      "Collaboration:",
+      "- Check team_tasks_list to see what other teammates are working on.",
+      "- If you need information another teammate has, message them directly via team_message.",
+      "- If you discover something relevant to another teammate's task, share it with them.",
+      "- Use team_broadcast for updates that affect the whole team.",
+      "- Keep peer messages focused and actionable — coordinate, don't chat.",
+    )
+  }
+
   context.push("", "When you finish your task:")
   if (!isReadOnly && worktreeBranch) {
     context.push(`1. Commit your changes: git add -A && git commit -m "your summary"`)
@@ -303,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 */ })
@@ -322,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. */

package/src/watchdog.ts

@@ -24,6 +24,10 @@ interface WatchdogOpts {
   stallTokenThreshold?: number
   /** Project directory for git operations. */
   cwd?: string
+  /** Max peer messages per agent per window before nudge. 0 disables. */
+  peerMessageLimit?: number
+  /** Time window for peer message rate limiting in ms. */
+  peerMessageWindowMs?: number
 }
 
 /**
@@ -41,6 +45,8 @@ export class Watchdog {
   private readonly stallMinSteps: number
   private readonly stallTokenThreshold: number
   private readonly cwd?: string
+  private readonly peerMessageLimit: number
+  private readonly peerMessageWindowMs: number
   private timer: ReturnType<typeof setInterval> | undefined
 
   constructor(opts: WatchdogOpts) {
@@ -54,6 +60,8 @@ export class Watchdog {
     this.stallMinSteps = opts.stallMinSteps ?? 3
     this.stallTokenThreshold = opts.stallTokenThreshold ?? 500
     this.cwd = opts.cwd
+    this.peerMessageLimit = opts.peerMessageLimit ?? 0
+    this.peerMessageWindowMs = opts.peerMessageWindowMs ?? 300_000
   }
 
   private static STALE_THRESHOLD_MS = Number(process.env.STALE_WORKTREE_THRESHOLD_MS) || 300_000
@@ -133,10 +141,46 @@ export class Watchdog {
     }
   }
 
+  /** Check for chatty agents sending too many peer messages. */
+  async checkChatty(): Promise<void> {
+    if (!this.progressTracker || this.peerMessageLimit === 0) return
+
+    const busy = this.db.query(
+      `SELECT tm.team_id, tm.name, tm.session_id
+       FROM team_member tm
+       JOIN team t ON tm.team_id = t.id
+       WHERE t.status = 'active' AND tm.status = 'busy'`
+    ).all() as Array<{ team_id: string; name: string; session_id: string }>
+
+    for (const member of busy) {
+      if (this.progressTracker.isChattyReported(member.session_id)) continue
+      if (!this.progressTracker.isChatty(member.session_id, this.peerMessageLimit, this.peerMessageWindowMs)) continue
+
+      this.progressTracker.markChattyReported(member.session_id)
+
+      // Nudge the agent
+      this.client.session.promptAsync({
+        sessionID: member.session_id,
+        parts: [{ type: "text", text: "[System]: You've sent several messages to teammates. Focus on completing your task and send your results to the lead via team_message." }],
+      }).catch(() => { /* best effort */ })
+
+      // Notify the lead
+      sendMessage(this.db, {
+        teamId: member.team_id,
+        from: "system",
+        to: "lead",
+        content: `Agent "${member.name}" is sending many peer messages and may be over-coordinating. Consider checking on them.`,
+      })
+
+      log(`watchdog:chatty member=${member.name} limit=${this.peerMessageLimit}`)
+    }
+  }
+
   /** Run a single check for stale busy members. */
   async check(): Promise<void> {
     await this.cleanupStaleWorktrees()
     await this.checkStalled()
+    await this.checkChatty()
     if (this.ttlMs === 0) return
 
     const cutoff = Date.now() - this.ttlMs