@hueyexe/opencode-ensemble 0.3.1 → 0.5.0

package/README.md

@@ -163,9 +163,10 @@ Teammate messages arrive in the lead's session as `[Team message from alice]: ..
 
 - **SQLite** (`bun:sqlite`, WAL mode) for teams, members, tasks, and messages
 - **promptAsync** for message delivery: injects a message and starts the prompt loop in one call
+- **Git worktree isolation**: each teammate gets their own worktree by default, so multiple agents can edit files without conflicts. The lead merges branches after cleanup. Opt out with `worktree: false` for read-only agents.
 - **Sub-agent isolation**: teammates' sub-agents can't use team tools (parent chain tracking, max depth 10)
-- **Crash recovery**: stale busy members marked as errored on restart, orphaned sessions aborted, undelivered messages redelivered
-- **Spawn rollback**: if the initial prompt fails, the member is cleaned up and the session aborted
+- **Crash recovery**: stale busy members marked as errored on restart, orphaned sessions aborted, orphaned worktrees cleaned up, undelivered messages redelivered
+- **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
 - **Shutdown resilience**: abort failures handled gracefully, busy-after-shutdown triggers re-abort
 - **Rate limiting**: token bucket (configurable via `OPENCODE_ENSEMBLE_RATE_LIMIT`, default 10 tokens/sec)
@@ -186,6 +187,28 @@ OPENCODE_ENSEMBLE_TIMEOUT=3600000
 OPENCODE_ENSEMBLE_TIMEOUT=0
 ```
 
+### Best practices
+
+- Start with 2-4 teammates for most tasks. More agents means more coordination overhead.
+- Give each teammate 3-5 specific, self-contained tasks. Vague prompts produce vague results.
+- Start with research before implementation — spawn an explore agent first to understand the codebase, then spawn build agents with that context.
+- Use `worktree: false` for read-only agents (research, review, code analysis). They don't need file isolation.
+- Use `plan_approval: true` for risky changes — the teammate sends a plan first, you review and approve before they write any code.
+- Let the lead coordinate. Don't micromanage teammates — they message you when done or when they're blocked.
+- After spawning, tell the user what you've set up and wait for results. Don't poll `team_status` in a loop.
+
+### How this differs from Claude Code agent teams
+
+Claude Code has built-in agent teams. This plugin takes the same coordination model (shared tasks, peer messaging, lead coordination) and adds:
+
+- **Git worktree isolation by default** — each teammate gets their own branch, no merge conflicts between parallel agents
+- **System prompt injection** — the lead's system prompt is updated with team state (member statuses, task progress) so it stays aware across turns
+- **Compaction safety** — team context is preserved when sessions get long and OpenCode compacts the conversation
+- **Team-aware shell environment** — teammate shells get `ENSEMBLE_TEAM`, `ENSEMBLE_MEMBER`, `ENSEMBLE_ROLE`, and `ENSEMBLE_BRANCH` variables
+- **Graceful shutdown** — teammates finish their current work before stopping, with a force flag for emergencies
+- **Plan approval mode** — review teammate plans before they write code, useful for risky or unfamiliar changes
+- **Works today as a plugin** — no waiting for upstream features, install and go
+
 ## Development
 
 ```bash

package/dist/index.js

@@ -1,12 +1,16 @@
 // @bun
 var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, {
       get: all[name],
       enumerable: true,
       configurable: true,
-      set: (newValue) => all[name] = () => newValue
+      set: __exportSetter.bind(all, name)
     });
 };
 
@@ -12331,7 +12335,7 @@ function tool(input) {
 }
 tool.schema = exports_external;
 // src/index.ts
-import path2 from "path";
+import path3 from "path";
 import { mkdirSync } from "fs";
 
 // src/db.ts
@@ -12405,7 +12409,11 @@ var MIGRATIONS = [
     WHERE delivered = 0;
   `,
   `ALTER TABLE team_message ADD COLUMN read INTEGER NOT NULL DEFAULT 0;
-   CREATE INDEX IF NOT EXISTS team_message_unread_idx ON team_message(team_id, read) WHERE read = 0;`
+   CREATE INDEX IF NOT EXISTS team_message_unread_idx ON team_message(team_id, read) WHERE read = 0;`,
+  `ALTER TABLE team_member ADD COLUMN worktree_dir TEXT;
+   ALTER TABLE team_member ADD COLUMN worktree_branch TEXT;`,
+  `ALTER TABLE team_member ADD COLUMN plan_approval TEXT NOT NULL DEFAULT 'none'
+     CHECK(plan_approval IN ('none', 'pending', 'approved', 'rejected'));`
 ];
 function applyMigrations(db) {
   const { user_version: current } = db.query("PRAGMA user_version").get();
@@ -12498,6 +12506,28 @@ async function recoverStaleMembers(db, client) {
   }
   return { interrupted: result.changes };
 }
+async function recoverOrphanedWorktrees(db, client) {
+  let removed = 0;
+  try {
+    const worktrees = await client.worktree.list();
+    if (!worktrees.data)
+      return { removed: 0 };
+    const activeWorktrees = new Set(db.query(`SELECT tm.worktree_dir FROM team_member tm
+         JOIN team t ON tm.team_id = t.id
+         WHERE tm.worktree_dir IS NOT NULL AND t.status = 'active'`).all().map((r) => r.worktree_dir));
+    for (const wt of worktrees.data) {
+      if (!wt.name.startsWith("ensemble-"))
+        continue;
+      if (activeWorktrees.has(wt.directory))
+        continue;
+      try {
+        await client.worktree.remove({ worktreeRemoveInput: { directory: wt.directory } });
+        removed++;
+      } catch {}
+    }
+  } catch {}
+  return { removed };
+}
 async function recoverUndeliveredMessages(db, client, registry2) {
   const teams = db.query("SELECT id, lead_session_id FROM team WHERE status = 'active'").all();
   let redelivered = 0;
@@ -12703,6 +12733,71 @@ async function notifyWorkingProgress(client, db, teamId) {
   } catch {}
 }
 
+// src/system-prompt.ts
+var STATUS_DISPLAY = {
+  busy: "working",
+  ready: "idle",
+  shutdown_requested: "shutting down",
+  shutdown: "shut down",
+  error: "error"
+};
+function buildLeadSystemPrompt(db, teamId) {
+  const team = db.query("SELECT name FROM team WHERE id = ?").get(teamId);
+  if (!team)
+    return "";
+  const members = db.query("SELECT name, status FROM team_member WHERE team_id = ?").all(teamId);
+  const taskCounts = db.query("SELECT status, COUNT(*) as count FROM team_task WHERE team_id = ? GROUP BY status").all(teamId);
+  const countMap = {};
+  for (const row of taskCounts) {
+    countMap[row.status] = row.count;
+  }
+  const completed = countMap["completed"] ?? 0;
+  const inProgress = countMap["in_progress"] ?? 0;
+  const pending = countMap["pending"] ?? 0;
+  const memberList = members.map((m) => `${m.name} [${STATUS_DISPLAY[m.status] ?? m.status}]`).join(", ");
+  const teammateLine = members.length > 0 ? `Teammates: ${memberList}` : "Teammates: none";
+  return [
+    `You are leading team "${team.name}" with ${members.length} active teammates.`,
+    teammateLine,
+    `Tasks: ${completed} completed, ${inProgress} in progress, ${pending} pending`,
+    "",
+    "Teammates work asynchronously and message you when done.",
+    "Do NOT poll team_status or team_tasks_list repeatedly \u2014 wait for messages.",
+    "After spawning teammates, tell the user what you've set up and wait.",
+    "When all teammates finish, summarize results and suggest next steps."
+  ].join(`
+`);
+}
+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.`;
+}
+function buildTeamCompactionContext(db, teamId, role, memberName) {
+  const team = db.query("SELECT name FROM team WHERE id = ?").get(teamId);
+  if (!team)
+    return "";
+  const members = db.query("SELECT name, status FROM team_member WHERE team_id = ?").all(teamId);
+  const taskCounts = db.query("SELECT status, COUNT(*) as count FROM team_task WHERE team_id = ? GROUP BY status").all(teamId);
+  const countMap = {};
+  for (const row of taskCounts) {
+    countMap[row.status] = row.count;
+  }
+  const completed = countMap["completed"] ?? 0;
+  const inProgress = countMap["in_progress"] ?? 0;
+  const pending = countMap["pending"] ?? 0;
+  const roleLine = role === "lead" ? `[Team Context] You are the lead of team "${team.name}".` : `[Team Context] You are a teammate named "${memberName}" in team "${team.name}".`;
+  const memberList = members.map((m) => `${m.name} (${STATUS_DISPLAY[m.status] ?? m.status})`).join(", ");
+  const membersLine = members.length > 0 ? `Members: ${memberList}` : "Members: none";
+  return [
+    roleLine,
+    membersLine,
+    `Tasks: ${completed} completed, ${inProgress} in progress, ${pending} pending`
+  ].join(`
+`);
+}
+
 // src/types.ts
 function findTeamBySession(db, registry2, sessionId) {
   const entry = registry2.getBySession(sessionId);
@@ -12743,6 +12838,7 @@ async function executeTeamCreate(deps, args, sessionId) {
 }
 
 // src/tools/team-spawn.ts
+import path2 from "path";
 async function executeTeamSpawn(deps, args, sessionId) {
   const nameError = validateMemberName(args.name);
   if (nameError)
@@ -12755,40 +12851,82 @@ async function executeTeamSpawn(deps, args, sessionId) {
   const existing = deps.db.query("SELECT name FROM team_member WHERE team_id = ? AND name = ?").get(teamInfo.teamId, args.name);
   if (existing)
     throw new Error(`Teammate "${args.name}" already exists in team "${teamInfo.teamName}"`);
-  const createResult = await deps.client.session.create({
+  const useWorktree = args.worktree !== false;
+  const usePlanApproval = args.plan_approval === true;
+  let worktreeDir = null;
+  let worktreeBranch = null;
+  if (useWorktree) {
+    const worktreeName = `ensemble-${teamInfo.teamName}-${args.name}`;
+    try {
+      const result = await deps.client.worktree.create({ name: worktreeName });
+      if (result.data) {
+        worktreeDir = result.data.directory;
+        worktreeBranch = result.data.branch;
+      }
+    } catch {
+      try {
+        await deps.client.tui.showToast({
+          title: "Team",
+          message: `Worktree creation failed for ${args.name}, using shared directory`,
+          variant: "warning",
+          duration: 4000
+        });
+      } catch {}
+    }
+  }
+  const createOpts = {
     body: { parentID: sessionId, title: `${args.name} (@${args.agent} teammate)` }
-  });
-  const childSessionId = createResult.data?.id;
-  if (!childSessionId)
+  };
+  if (worktreeDir) {
+    createOpts.directory = worktreeDir;
+  }
+  let childSessionId;
+  try {
+    const createResult = await deps.client.session.create(createOpts);
+    childSessionId = createResult.data?.id;
+  } catch (err) {
+    if (worktreeDir) {
+      try {
+        await deps.client.worktree.remove({ worktreeRemoveInput: { directory: worktreeDir } });
+      } catch {}
+    }
+    throw new Error(`Failed to create session for teammate "${args.name}": ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (!childSessionId) {
+    if (worktreeDir) {
+      try {
+        await deps.client.worktree.remove({ worktreeRemoveInput: { directory: worktreeDir } });
+      } catch {}
+    }
     throw new Error("Failed to create teammate session");
+  }
+  const planApproval = usePlanApproval ? "pending" : "none";
   const now = Date.now();
-  deps.db.run(`INSERT INTO team_member (team_id, name, session_id, agent, status, execution_status, model, prompt, time_created, time_updated)
-     VALUES (?, ?, ?, ?, 'busy', 'starting', ?, ?, ?, ?)`, [teamInfo.teamId, args.name, childSessionId, args.agent, args.model ?? null, args.prompt, now, now]);
+  deps.db.run(`INSERT INTO team_member (team_id, name, session_id, agent, status, execution_status, model, prompt, worktree_dir, worktree_branch, plan_approval, time_created, time_updated)
+     VALUES (?, ?, ?, ?, 'busy', 'starting', ?, ?, ?, ?, ?, ?, ?)`, [teamInfo.teamId, args.name, childSessionId, args.agent, args.model ?? null, args.prompt, worktreeDir, worktreeBranch, planApproval, now, now]);
   deps.registry.register(teamInfo.teamId, args.name, childSessionId);
   const context = [
     `You are "${args.name}", a teammate in team "${teamInfo.teamName}".`,
-    `Your agent type is "${args.agent}".`,
-    "",
-    "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",
-    "",
-    "When you finish your task:",
-    "1. If you claimed a task, mark it complete using team_tasks_complete.",
-    "2. Send ONE message to the lead with your findings using team_message.",
-    "3. STOP. Do not send follow-up confirmations, status updates, or 'standing by' messages.",
-    "",
-    "If you are blocked, send ONE message to the lead describing the specific blocker.",
-    "",
-    "Your plain text output is NOT visible to the team. You MUST use team_message to communicate.",
-    "",
-    "Your task:",
-    args.prompt
+    `Your agent type is "${args.agent}".`
   ];
+  if (worktreeBranch) {
+    context.push(`You are working on branch "${worktreeBranch}" in your own worktree. Your changes are isolated from other teammates.`);
+  }
+  if (usePlanApproval) {
+    context.push("", "IMPORTANT: You are in PLAN MODE.", "Read and explore the codebase, then send your implementation plan to the lead via team_message.", "Do NOT write or modify any files until the lead approves your plan.", "Wait for the lead's approval message before proceeding with implementation.");
+  }
+  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", "", "When you finish your task:", "1. If you claimed a task, mark it complete using team_tasks_complete.", "2. Send ONE message to the lead with your findings using team_message.", "3. STOP. Do not send follow-up confirmations, status updates, or 'standing by' messages.", "", "If you are blocked, send ONE message to the lead describing the specific blocker.", "", "Your plain text output is NOT visible to the team. You MUST use team_message to communicate.");
+  try {
+    const agentsPath = path2.join(deps.directory, "AGENTS.md");
+    const file2 = Bun.file(agentsPath);
+    if (await file2.exists()) {
+      const content = await file2.text();
+      const truncated = content.length > 2000 ? content.slice(0, 2000) + `
+...(truncated)` : content;
+      context.push("", "Project guidelines (from AGENTS.md):", truncated);
+    }
+  } catch {}
+  context.push("", "Your task:", args.prompt);
   if (args.claim_task) {
     context.push("", `You have been assigned task ${args.claim_task}. Mark it complete when done.`);
   }
@@ -12805,9 +12943,16 @@ async function executeTeamSpawn(deps, args, sessionId) {
     try {
       await deps.client.session.abort({ path: { id: childSessionId } });
     } catch {}
+    if (worktreeDir) {
+      try {
+        await deps.client.worktree.remove({ worktreeRemoveInput: { directory: worktreeDir } });
+      } catch {}
+    }
     throw new Error(`Failed to send initial prompt to teammate "${args.name}": ${err instanceof Error ? err.message : String(err)}`);
   }
-  return `Teammate "${args.name}" spawned (agent: ${args.agent}). They are working on: ${args.prompt.slice(0, 120)}${args.prompt.length > 120 ? "..." : ""}`;
+  const branchInfo = worktreeBranch ? ` (branch: ${worktreeBranch})` : "";
+  const planInfo = usePlanApproval ? " [plan mode \u2014 will send plan for approval]" : "";
+  return `Teammate "${args.name}" spawned (agent: ${args.agent})${branchInfo}${planInfo}. They are working on: ${args.prompt.slice(0, 120)}${args.prompt.length > 120 ? "..." : ""}`;
 }
 
 // src/tools/team-message.ts
@@ -12819,20 +12964,40 @@ async function executeTeamMessage(deps, args, sessionId) {
   const recipientSessionId = resolveRecipientSession(deps.db, deps.registry, teamInfo.teamId, args.to);
   if (!recipientSessionId)
     throw new Error(`Recipient "${args.to}" not found in team "${teamInfo.teamName}"`);
+  let messageText = args.text;
+  if (args.approve || args.reject) {
+    if (args.approve && args.reject) {
+      throw new Error("Cannot both approve and reject a plan.");
+    }
+    if (teamInfo.role !== "lead") {
+      throw new Error("Only the lead can approve or reject plans.");
+    }
+    const recipient = deps.db.query("SELECT plan_approval FROM team_member WHERE team_id = ? AND name = ?").get(teamInfo.teamId, args.to);
+    if (!recipient || recipient.plan_approval !== "pending") {
+      throw new Error(`Recipient "${args.to}" is not in plan approval mode (plan_approval is not pending).`);
+    }
+    if (args.approve) {
+      deps.db.run("UPDATE team_member SET plan_approval = 'approved', time_updated = ? WHERE team_id = ? AND name = ?", [Date.now(), teamInfo.teamId, args.to]);
+      messageText = `[Plan Approved] ${args.text}`;
+    } else {
+      deps.db.run("UPDATE team_member SET plan_approval = 'rejected', time_updated = ? WHERE team_id = ? AND name = ?", [Date.now(), teamInfo.teamId, args.to]);
+      messageText = `[Plan Rejected: ${args.reject}] ${args.text}`;
+    }
+  }
   const msgId = sendMessage(deps.db, {
     teamId: teamInfo.teamId,
     from: senderName,
     to: args.to,
-    content: args.text
+    content: messageText
   });
   const isToLead = args.to === "lead";
   const MAX_LEAD_MSG = 500;
   let deliveryText;
-  if (isToLead && args.text.length > MAX_LEAD_MSG) {
-    const truncated = args.text.slice(0, MAX_LEAD_MSG);
+  if (isToLead && messageText.length > MAX_LEAD_MSG) {
+    const truncated = messageText.slice(0, MAX_LEAD_MSG);
     deliveryText = `[Team message from ${senderName}]: ${truncated}... (use team_results to read full message)`;
   } else {
-    deliveryText = `[Team message from ${senderName}]: ${args.text}`;
+    deliveryText = `[Team message from ${senderName}]: ${messageText}`;
   }
   await deps.client.session.promptAsync({
     path: { id: recipientSessionId },
@@ -12888,33 +13053,47 @@ async function executeTeamShutdown(deps, args, sessionId) {
     throw new Error("This session is not in a team.");
   if (teamInfo.role !== "lead")
     throw new Error("Only the team lead can shut down teammates.");
-  const member = deps.db.query("SELECT session_id, status FROM team_member WHERE team_id = ? AND name = ?").get(teamInfo.teamId, args.member);
+  const member = deps.db.query("SELECT session_id, status, worktree_branch FROM team_member WHERE team_id = ? AND name = ?").get(teamInfo.teamId, args.member);
   if (!member)
     throw new Error(`Teammate "${args.member}" not found in team "${teamInfo.teamName}"`);
   if (member.status === "shutdown")
     throw new Error(`Teammate "${args.member}" is already shut down`);
-  deps.db.run("UPDATE team_member SET status = 'shutdown_requested', time_updated = ? WHERE team_id = ? AND name = ?", [Date.now(), teamInfo.teamId, args.member]);
-  try {
-    await deps.client.session.abort({ path: { id: member.session_id } });
-  } catch {
-    try {
-      await deps.client.tui.showToast({
-        title: "Team",
-        message: `Failed to abort ${args.member} session \u2014 will rely on event hook`,
-        variant: "warning",
-        duration: 4000
-      });
-    } catch {}
+  const force = args.force ?? false;
+  if (member.status === "shutdown_requested") {
+    await abortAndShutdown(deps, teamInfo.teamId, args.member, member.session_id);
+    const branchInfo = member.worktree_branch ? ` Changes on branch: ${member.worktree_branch}` : "";
+    return `Force shut down "${args.member}".${branchInfo}`;
   }
+  let isIdle = false;
   try {
     const statuses = await deps.client.session.status();
     const sessionStatus = statuses.data?.[member.session_id];
-    if (!sessionStatus || sessionStatus.type === "idle") {
-      deps.db.run("UPDATE team_member SET status = 'shutdown', execution_status = 'idle', time_updated = ? WHERE team_id = ? AND name = ?", [Date.now(), teamInfo.teamId, args.member]);
-      return `Teammate "${args.member}" has been shut down.`;
-    }
+    isIdle = !sessionStatus || sessionStatus.type === "idle";
+  } catch {}
+  if (isIdle || force) {
+    await abortAndShutdown(deps, teamInfo.teamId, args.member, member.session_id);
+    const branchInfo = member.worktree_branch ? ` Changes on branch: ${member.worktree_branch}` : "";
+    return `Teammate "${args.member}" has been shut down.${branchInfo}`;
+  }
+  try {
+    await deps.client.session.promptAsync({
+      path: { id: member.session_id },
+      body: {
+        parts: [{
+          type: "text",
+          text: `[Shutdown requested]: The lead has requested you shut down. Finish your current task, send your final findings to the lead via team_message, then stop.`
+        }]
+      }
+    });
   } catch {}
-  return `Shutdown requested for ${args.member}. Will complete when current work finishes.`;
+  deps.db.run("UPDATE team_member SET status = 'shutdown_requested', time_updated = ? WHERE team_id = ? AND name = ?", [Date.now(), teamInfo.teamId, args.member]);
+  return `Shutdown requested for ${args.member}. They will finish current work and shut down. Call team_shutdown with force: true to abort immediately.`;
+}
+async function abortAndShutdown(deps, teamId, memberName, sessionId) {
+  try {
+    await deps.client.session.abort({ path: { id: sessionId } });
+  } catch {}
+  deps.db.run("UPDATE team_member SET status = 'shutdown', execution_status = 'idle', time_updated = ? WHERE team_id = ? AND name = ?", [Date.now(), teamId, memberName]);
 }
 
 // src/tools/team-cleanup.ts
@@ -12924,7 +13103,7 @@ async function executeTeamCleanup(deps, args, sessionId) {
     throw new Error("This session is not in a team.");
   if (teamInfo.role !== "lead")
     throw new Error("Only the team lead can clean up the team.");
-  const members = deps.db.query("SELECT name, session_id, status FROM team_member WHERE team_id = ?").all(teamInfo.teamId);
+  const members = deps.db.query("SELECT name, session_id, status, worktree_dir, worktree_branch FROM team_member WHERE team_id = ?").all(teamInfo.teamId);
   const active = members.filter((m) => m.status !== "shutdown" && m.status !== "shutdown_requested" && m.status !== "error");
   if (active.length > 0 && !args.force) {
     const names = active.map((m) => m.name).join(", ");
@@ -12937,8 +13116,27 @@ async function executeTeamCleanup(deps, args, sessionId) {
       } catch {}
     }
   }
+  const branches = [];
+  for (const member of members) {
+    if (member.worktree_dir) {
+      try {
+        await deps.client.worktree.remove({ worktreeRemoveInput: { directory: member.worktree_dir } });
+      } catch {}
+    }
+    if (member.worktree_branch) {
+      branches.push(member.worktree_branch);
+    }
+  }
   deps.db.run("UPDATE team SET status = 'archived', time_updated = ? WHERE id = ?", [Date.now(), teamInfo.teamId]);
   deps.registry.unregisterTeam(teamInfo.teamId);
+  if (branches.length > 0) {
+    const mergeCommands = branches.map((b) => `  git merge ${b}`).join(`
+`);
+    return `Team "${teamInfo.teamName}" cleaned up. Worktrees removed.
+
+Merge teammate branches:
+${mergeCommands}`;
+  }
   return `Team "${teamInfo.teamName}" cleaned up.`;
 }
 
@@ -13064,7 +13262,7 @@ async function executeTeamStatus(deps, sessionId) {
     return "No changes since last check.";
   }
   lastCallTime.set(teamInfo.teamId, now);
-  const members = deps.db.query("SELECT name, session_id, agent, status, execution_status FROM team_member WHERE team_id = ? ORDER BY time_created ASC").all(teamInfo.teamId);
+  const members = deps.db.query("SELECT name, session_id, agent, status, execution_status, worktree_branch, plan_approval FROM team_member WHERE team_id = ? ORDER BY time_created ASC").all(teamInfo.teamId);
   const tasks = deps.db.query("SELECT status FROM team_task WHERE team_id = ?").all(teamInfo.teamId);
   const lines = [];
   lines.push(`Team: ${teamInfo.teamName} (you are the ${teamInfo.role})`);
@@ -13075,7 +13273,9 @@ async function executeTeamStatus(deps, sessionId) {
     lines.push("Members:");
     for (const m of members) {
       const statusIcon = m.status === "busy" ? "working" : m.status === "ready" ? "idle" : m.status;
-      lines.push(`  ${m.name}  [${statusIcon}]  agent: ${m.agent}  session: ${m.session_id}`);
+      const branch = m.worktree_branch ? `  branch: ${m.worktree_branch}` : "";
+      const plan = m.plan_approval !== "none" ? `, plan: ${m.plan_approval}` : "";
+      lines.push(`  ${m.name}  [${statusIcon}${plan}]  agent: ${m.agent}${branch}  session: ${m.session_id}`);
     }
   }
   if (tasks.length > 0) {
@@ -13255,12 +13455,12 @@ var DEFAULT_WATCHDOG_TTL_MS = 30 * 60 * 1000;
 var DEFAULT_WATCHDOG_CHECK_MS = 60 * 1000;
 var plugin = async (input) => {
   const dbPath = getDbPath();
-  mkdirSync(path2.dirname(dbPath), { recursive: true });
+  mkdirSync(path3.dirname(dbPath), { recursive: true });
   const db = createDb(dbPath);
   const registry2 = new MemberRegistry;
   const tracker = new DescendantTracker;
   const client = input.client;
-  const deps = { db, registry: registry2, tracker, client };
+  const deps = { db, registry: registry2, tracker, client, directory: input.directory };
   const recovery = await recoverStaleMembers(db, client);
   if (recovery.interrupted > 0) {
     const members = 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'").all();
@@ -13269,6 +13469,7 @@ var plugin = async (input) => {
     }
   }
   recoverUndeliveredMessages(db, client, registry2).catch(() => {});
+  recoverOrphanedWorktrees(db, client).catch(() => {});
   const rateLimitEnv = process.env.OPENCODE_ENSEMBLE_RATE_LIMIT;
   const rateLimitCapacity = rateLimitEnv === "0" ? 0 : parseInt(rateLimitEnv ?? "", 10) || DEFAULT_RATE_LIMIT_CAPACITY;
   const rateLimiter = new TokenBucket({
@@ -13334,6 +13535,38 @@ var plugin = async (input) => {
         }
       }
     },
+    "experimental.chat.system.transform": async (input2, output) => {
+      if (!input2.sessionID)
+        return;
+      const teamInfo = findTeamBySession(db, registry2, input2.sessionID);
+      if (!teamInfo)
+        return;
+      const prompt = teamInfo.role === "lead" ? buildLeadSystemPrompt(db, teamInfo.teamId) : buildTeammateSystemPrompt(db, teamInfo.teamId, teamInfo.memberName);
+      output.system.push(prompt);
+    },
+    "experimental.session.compacting": async (input2, output) => {
+      const teamInfo = findTeamBySession(db, registry2, input2.sessionID);
+      if (!teamInfo)
+        return;
+      const context = buildTeamCompactionContext(db, teamInfo.teamId, teamInfo.role, teamInfo.memberName);
+      output.context.push(context);
+    },
+    "shell.env": async (input2, output) => {
+      if (!input2.sessionID)
+        return;
+      const teamInfo = findTeamBySession(db, registry2, input2.sessionID);
+      if (!teamInfo)
+        return;
+      output.env.ENSEMBLE_TEAM = teamInfo.teamName;
+      output.env.ENSEMBLE_ROLE = teamInfo.role;
+      if (teamInfo.memberName) {
+        output.env.ENSEMBLE_MEMBER = teamInfo.memberName;
+        const member = db.query("SELECT worktree_branch FROM team_member WHERE team_id = ? AND name = ?").get(teamInfo.teamId, teamInfo.memberName);
+        if (member?.worktree_branch) {
+          output.env.ENSEMBLE_BRANCH = member.worktree_branch;
+        }
+      }
+    },
     tool: {
       team_create: tool({
         description: "Create a new agent team. You become the team lead. Use this before spawning teammates.",
@@ -13347,13 +13580,15 @@ var plugin = async (input) => {
         }
       }),
       team_spawn: tool({
-        description: "Spawn a new teammate that works in parallel. The teammate starts immediately with the given prompt. " + "Teammates work asynchronously and will message you when done. Do not poll for their status.",
+        description: "Spawn a new teammate that works in parallel. The teammate starts immediately with the given prompt. " + "Each teammate gets their own git worktree for file isolation. " + "Teammates work asynchronously and will message you when done. Do not poll for their status.",
         args: {
           name: tool.schema.string().describe("Teammate name (lowercase alphanumeric with hyphens)"),
           agent: tool.schema.string().default("build").describe("Agent type (e.g. 'build', 'plan', 'explore')"),
           prompt: tool.schema.string().describe("Task instructions for the teammate"),
           model: tool.schema.string().optional().describe("Model in provider/model format (optional, uses default)"),
-          claim_task: tool.schema.string().optional().describe("Task ID to auto-claim for this teammate (optional)")
+          claim_task: tool.schema.string().optional().describe("Task ID to auto-claim for this teammate (optional)"),
+          worktree: tool.schema.boolean().default(true).describe("Create a git worktree for file isolation (default: true, set false for read-only agents)"),
+          plan_approval: tool.schema.boolean().default(false).describe("Require teammate to send a plan for approval before writing files (default: false)")
         },
         async execute(args, ctx) {
           const result = await executeTeamSpawn(deps, args, ctx.sessionID);
@@ -13365,7 +13600,9 @@ var plugin = async (input) => {
         description: "Send a message to a specific teammate or to the lead. Use 'lead' to message the team lead.",
         args: {
           to: tool.schema.string().describe("Recipient name ('lead' or teammate name)"),
-          text: tool.schema.string().describe("Message content (max 10KB)")
+          text: tool.schema.string().describe("Message content (max 10KB)"),
+          approve: tool.schema.boolean().optional().describe("Approve a teammate's plan (only when recipient has plan_approval='pending')"),
+          reject: tool.schema.string().optional().describe("Reject a teammate's plan with reason (only when recipient has plan_approval='pending')")
         },
         async execute(args, ctx) {
           const result = await executeTeamMessage(deps, args, ctx.sessionID);
@@ -13444,9 +13681,10 @@ var plugin = async (input) => {
         }
       }),
       team_shutdown: tool({
-        description: "Request a teammate to shut down. The teammate finishes current work then stops.",
+        description: "Request a teammate to shut down. The teammate finishes current work then stops. " + "Pass force: true to abort immediately without waiting.",
         args: {
-          member: tool.schema.string().describe("Teammate name to shut down")
+          member: tool.schema.string().describe("Teammate name to shut down"),
+          force: tool.schema.boolean().default(false).describe("Force immediate abort without waiting for current work to finish")
         },
         async execute(args, ctx) {
           const result = await executeTeamShutdown(deps, args, ctx.sessionID);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hueyexe/opencode-ensemble",
-  "version": "0.3.1",
+  "version": "0.5.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",
@@ -38,7 +38,7 @@
     "typescript": "^5"
   },
   "dependencies": {
-    "@opencode-ai/plugin": "^1.2.26",
-    "@opencode-ai/sdk": "^1.2.26"
+    "@opencode-ai/plugin": "^1.2.27",
+    "@opencode-ai/sdk": "^1.2.27"
   }
 }