@hueyexe/opencode-ensemble 0.3.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # OpenCode Ensemble
 
-Agent teams for [OpenCode](https://opencode.ai). Run multiple agents in parallel with messaging, shared tasks, and coordinated execution.
+Run a team of parallel AI agents in OpenCode. Each agent gets its own session, context window, and task. They coordinate through messaging and a shared task board.
 
 Built as a plugin on the public OpenCode SDK. Zero internal dependencies.
 
@@ -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)

package/dist/index.js

@@ -1,16 +1,12 @@
 // @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: __exportSetter.bind(all, name)
+      set: (newValue) => all[name] = () => newValue
     });
 };
 
@@ -12409,7 +12405,9 @@ 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;`
 ];
 function applyMigrations(db) {
   const { user_version: current } = db.query("PRAGMA user_version").get();
@@ -12502,6 +12500,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;
@@ -12743,7 +12763,7 @@ async function executeTeamCreate(deps, args, sessionId) {
   const id = generateId("team");
   const now = Date.now();
   deps.db.run("INSERT INTO team (id, name, lead_session_id, status, delegate, time_created, time_updated) VALUES (?, ?, ?, 'active', 0, ?, ?)", [id, args.name, sessionId, now, now]);
-  return `Team "${args.name}" created (ID: ${id}). You are the lead. Use team_spawn to add teammates. Teammates will message you when done \u2014 do not poll team_status repeatedly. IMPORTANT: After spawning all teammates, do NOT call any tools. Tell the user what you've set up and STOP. You will be woken automatically.`;
+  return `Team "${args.name}" created. You are the lead. Use team_spawn to add teammates.`;
 }
 
 // src/tools/team-spawn.ts
@@ -12759,40 +12779,66 @@ 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;
+  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 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, time_created, time_updated)
+     VALUES (?, ?, ?, ?, 'busy', 'starting', ?, ?, ?, ?, ?, ?)`, [teamInfo.teamId, args.name, childSessionId, args.agent, args.model ?? null, args.prompt, worktreeDir, worktreeBranch, 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.`);
+  }
+  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.", "", "Your task:", args.prompt);
   if (args.claim_task) {
     context.push("", `You have been assigned task ${args.claim_task}. Mark it complete when done.`);
   }
@@ -12809,9 +12855,15 @@ 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}). IMPORTANT: Do NOT call any tools after this. Tell the user what you've set up and STOP. You will be woken automatically when teammates message you.`;
+  const branchInfo = worktreeBranch ? ` (branch: ${worktreeBranch})` : "";
+  return `Teammate "${args.name}" spawned (agent: ${args.agent})${branchInfo}. They are working on: ${args.prompt.slice(0, 120)}${args.prompt.length > 120 ? "..." : ""}`;
 }
 
 // src/tools/team-message.ts
@@ -12892,7 +12944,7 @@ 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")
@@ -12915,7 +12967,8 @@ async function executeTeamShutdown(deps, args, sessionId) {
     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.`;
+      const branchInfo = member.worktree_branch ? ` Changes on branch: ${member.worktree_branch}` : "";
+      return `Teammate "${args.member}" has been shut down.${branchInfo}`;
     }
   } catch {}
   return `Shutdown requested for ${args.member}. Will complete when current work finishes.`;
@@ -12928,7 +12981,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(", ");
@@ -12941,8 +12994,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.`;
 }
 
@@ -13065,10 +13137,10 @@ async function executeTeamStatus(deps, sessionId) {
   const now = Date.now();
   const last = lastCallTime.get(teamInfo.teamId);
   if (last !== undefined && now - last < RATE_LIMIT_MS) {
-    return "Status unchanged. STOP \u2014 do not call any more tools. Tell the user you are waiting for teammates to finish. You will be woken automatically when they message you.";
+    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 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})`);
@@ -13079,7 +13151,8 @@ 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}` : "";
+      lines.push(`  ${m.name}  [${statusIcon}]  agent: ${m.agent}${branch}  session: ${m.session_id}`);
     }
   }
   if (tasks.length > 0) {
@@ -13110,9 +13183,7 @@ async function executeTeamStatus(deps, sessionId) {
       });
     } catch {}
   }
-  return `[Relay this status to the user in your next message:]
-
-` + lines.join(`
+  return lines.join(`
 `);
 }
 
@@ -13125,11 +13196,11 @@ async function executeTeamView(deps, args, sessionId) {
   if (!member)
     throw new Error(`Teammate "${args.member}" not found in team "${teamInfo.teamName}"`);
   try {
-    if (typeof deps.client.tui.selectSession === "function") {
-      await deps.client.tui.selectSession({ sessionID: member.session_id });
-    }
-  } catch {}
-  return `View ${args.member}'s session: ${member.session_id}. Use the session picker (ctrl+p) to navigate to their session.`;
+    await deps.client.tui.selectSession({ sessionID: member.session_id });
+    return `Switched to ${args.member}'s session.`;
+  } catch {
+    return `Could not switch to ${args.member}'s session (${member.session_id}). The session may not be accessible from the TUI.`;
+  }
 }
 
 // src/rate-limit.ts
@@ -13275,6 +13346,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({
@@ -13353,13 +13425,14 @@ 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)")
         },
         async execute(args, ctx) {
           const result = await executeTeamSpawn(deps, args, ctx.sessionID);

package/package.json

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

@@ -3,7 +3,7 @@ import { tool } from "@opencode-ai/plugin"
 import path from "path"
 import { mkdirSync } from "node:fs"
 import { createDb, getDbPath } from "./db"
-import { recoverStaleMembers, recoverUndeliveredMessages } from "./recovery"
+import { recoverStaleMembers, recoverUndeliveredMessages, recoverOrphanedWorktrees } from "./recovery"
 import { MemberRegistry, DescendantTracker } from "./state"
 import { handleSessionStatusEvent, handleSessionCreatedEvent, checkToolIsolation } from "./hooks"
 import { notifyTeamEvent, notifyWorkingProgress } from "./notify"
@@ -66,6 +66,11 @@ const plugin: Plugin = async (input) => {
     // Best effort — don't block plugin init
   })
 
+  // Clean up orphaned worktrees from crashed teams
+  recoverOrphanedWorktrees(db, client).catch(() => {
+    // Best effort — don't block plugin init
+  })
+
   // Initialize rate limiter
   // OPENCODE_ENSEMBLE_RATE_LIMIT=0 disables it entirely
   const rateLimitEnv = process.env.OPENCODE_ENSEMBLE_RATE_LIMIT
@@ -163,6 +168,7 @@ const plugin: Plugin = async (input) => {
 
       team_spawn: tool({
         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)"),
@@ -170,6 +176,7 @@ const plugin: Plugin = async (input) => {
           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)"),
+          worktree: tool.schema.boolean().default(true).describe("Create a git worktree for file isolation (default: true, set false for read-only agents)"),
         },
         async execute(args, ctx) {
           const result = await executeTeamSpawn(deps, args, ctx.sessionID)

package/src/recovery.ts

@@ -37,6 +37,43 @@ export async function recoverStaleMembers(db: Database, client?: PluginClient):
   return { interrupted: result.changes }
 }
 
+/**
+ * Clean up orphaned worktrees from archived teams or members that no longer exist.
+ * Compares worktrees on disk (via client.worktree.list) against active team members.
+ */
+export async function recoverOrphanedWorktrees(db: Database, client: PluginClient): Promise<{ removed: number }> {
+  let removed = 0
+
+  try {
+    const worktrees = await client.worktree.list()
+    if (!worktrees.data) return { removed: 0 }
+
+    // Get all active worktree directories from the DB
+    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() as Array<{ worktree_dir: string }>).map(r => r.worktree_dir)
+    )
+
+    for (const wt of worktrees.data) {
+      // Only clean up worktrees created by ensemble (name starts with "ensemble-")
+      if (!wt.name.startsWith("ensemble-")) continue
+      if (activeWorktrees.has(wt.directory)) continue
+
+      try {
+        await client.worktree.remove({ worktreeRemoveInput: { directory: wt.directory } })
+        removed++
+      } catch { /* best effort */ }
+    }
+  } catch {
+    // worktree.list may not be available — silently ignore
+  }
+
+  return { removed }
+}
+
 /**
  * Redeliver undelivered messages (delivered=0) via promptAsync.
  * Resolves recipient session IDs from the member registry or team lead.

package/src/schema.ts

@@ -70,6 +70,9 @@ export const MIGRATIONS: string[] = [
   // Migration 2: Add read column to team_message for team_results tracking
   `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;`,
+  // Migration 3: Add worktree columns to team_member for git worktree isolation
+  `ALTER TABLE team_member ADD COLUMN worktree_dir TEXT;
+   ALTER TABLE team_member ADD COLUMN worktree_branch TEXT;`,
 ]
 
 /**

package/src/tools/team-cleanup.ts

@@ -3,6 +3,7 @@ import { findTeamBySession } from "../types"
 
 /**
  * Execute the team_cleanup tool. Archives the team and cleans up resources.
+ * Removes worktrees and lists branches for the lead to merge.
  * If force=true, aborts all active member sessions first.
  */
 export async function executeTeamCleanup(
@@ -14,8 +15,8 @@ export async function executeTeamCleanup(
   if (!teamInfo) 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) as Array<{ name: string; session_id: string; status: string }>
+  const members = deps.db.query("SELECT name, session_id, status, worktree_dir, worktree_branch FROM team_member WHERE team_id = ?")
+    .all(teamInfo.teamId) as Array<{ name: string; session_id: string; status: string; worktree_dir: string | null; worktree_branch: string | null }>
 
   const active = members.filter(m => m.status !== "shutdown" && m.status !== "shutdown_requested" && m.status !== "error")
 
@@ -29,9 +30,20 @@ export async function executeTeamCleanup(
     for (const member of active) {
       try {
         await deps.client.session.abort({ path: { id: member.session_id } })
-      } catch {
-        // Best effort
-      }
+      } catch { /* best effort */ }
+    }
+  }
+
+  // Remove worktrees and collect branches for merging
+  const branches: string[] = []
+  for (const member of members) {
+    if (member.worktree_dir) {
+      try {
+        await deps.client.worktree.remove({ worktreeRemoveInput: { directory: member.worktree_dir } })
+      } catch { /* best effort — worktree may already be gone */ }
+    }
+    if (member.worktree_branch) {
+      branches.push(member.worktree_branch)
     }
   }
 
@@ -41,5 +53,10 @@ export async function executeTeamCleanup(
   // Clean up registry
   deps.registry.unregisterTeam(teamInfo.teamId)
 
+  if (branches.length > 0) {
+    const mergeCommands = branches.map(b => `  git merge ${b}`).join("\n")
+    return `Team "${teamInfo.teamName}" cleaned up. Worktrees removed.\n\nMerge teammate branches:\n${mergeCommands}`
+  }
+
   return `Team "${teamInfo.teamName}" cleaned up.`
 }

package/src/tools/team-create.ts

@@ -28,5 +28,5 @@ export async function executeTeamCreate(
     [id, args.name, sessionId, now, now]
   )
 
-  return `Team "${args.name}" created (ID: ${id}). You are the lead. Use team_spawn to add teammates. Teammates will message you when done — do not poll team_status repeatedly. IMPORTANT: After spawning all teammates, do NOT call any tools. Tell the user what you've set up and STOP. You will be woken automatically.`
+  return `Team "${args.name}" created. You are the lead. Use team_spawn to add teammates.`
 }

package/src/tools/team-shutdown.ts

@@ -16,8 +16,8 @@ export async function executeTeamShutdown(
   if (!teamInfo) 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) as { session_id: string; status: string } | null
+  const member = deps.db.query("SELECT session_id, status, worktree_branch FROM team_member WHERE team_id = ? AND name = ?")
+    .get(teamInfo.teamId, args.member) as { session_id: string; status: string; worktree_branch: string | null } | null
   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`)
 
@@ -53,7 +53,8 @@ export async function executeTeamShutdown(
         "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.`
+      const branchInfo = member.worktree_branch ? ` Changes on branch: ${member.worktree_branch}` : ""
+      return `Teammate "${args.member}" has been shut down.${branchInfo}`
     }
   } catch {
     // Status poll failed — fall through to eventual consistency

package/src/tools/team-spawn.ts

@@ -4,10 +4,12 @@ import { findTeamBySession } from "../types"
 
 /**
  * Execute the team_spawn tool. Creates a child session and starts a teammate.
+ * By default, each teammate gets their own git worktree for file isolation.
+ * Pass worktree: false for read-only agents that don't need isolation.
  */
 export async function executeTeamSpawn(
   deps: ToolDeps,
-  args: { name: string; agent: string; prompt: string; model?: string; claim_task?: string },
+  args: { name: string; agent: string; prompt: string; model?: string; claim_task?: string; worktree?: boolean },
   sessionId: string,
 ): Promise<string> {
   const nameError = validateMemberName(args.name)
@@ -22,28 +24,82 @@ export async function executeTeamSpawn(
     .get(teamInfo.teamId, args.name)
   if (existing) throw new Error(`Teammate "${args.name}" already exists in team "${teamInfo.teamName}"`)
 
-  // Create child session via SDK
-  const createResult = await deps.client.session.create({
+  const useWorktree = args.worktree !== false
+
+  // Create worktree if enabled
+  let worktreeDir: string | null = null
+  let worktreeBranch: string | null = 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 {
+      // Worktree creation failed — fall back to shared directory with a warning
+      try {
+        await deps.client.tui.showToast({
+          title: "Team",
+          message: `Worktree creation failed for ${args.name}, using shared directory`,
+          variant: "warning",
+          duration: 4000,
+        })
+      } catch { /* TUI may not be available */ }
+    }
+  }
+
+  // Create child session — use worktree directory if available
+  const createOpts: Record<string, unknown> = {
     body: { parentID: sessionId, title: `${args.name} (@${args.agent} teammate)` },
-  })
-  const childSessionId = createResult.data?.id
-  if (!childSessionId) throw new Error("Failed to create teammate session")
+  }
+  if (worktreeDir) {
+    createOpts.directory = worktreeDir
+  }
+
+  let childSessionId: string | undefined
+  try {
+    const createResult = await deps.client.session.create(createOpts as Parameters<typeof deps.client.session.create>[0])
+    childSessionId = createResult.data?.id
+  } catch (err) {
+    // Rollback worktree if session creation failed
+    if (worktreeDir) {
+      try { await deps.client.worktree.remove({ worktreeRemoveInput: { directory: worktreeDir } }) } catch { /* best effort */ }
+    }
+    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 { /* best effort */ }
+    }
+    throw new Error("Failed to create teammate session")
+  }
 
   // Register in DB
   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]
+    `INSERT INTO team_member (team_id, name, session_id, agent, status, execution_status, model, prompt, worktree_dir, worktree_branch, time_created, time_updated)
+     VALUES (?, ?, ?, ?, 'busy', 'starting', ?, ?, ?, ?, ?, ?)`,
+    [teamInfo.teamId, args.name, childSessionId, args.agent, args.model ?? null, args.prompt, worktreeDir, worktreeBranch, now, now]
   )
 
   // Register in memory
   deps.registry.register(teamInfo.teamId, args.name, childSessionId)
 
-  // Build teammate context message per AGENTS.md Teammate Context Message Design
+  // Build teammate context message
   const context = [
     `You are "${args.name}", a teammate in team "${teamInfo.teamName}".`,
     `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.`)
+  }
+
+  context.push(
     "",
     "Tools available to you:",
     "- team_message: send a message to the lead or another teammate",
@@ -64,7 +120,7 @@ export async function executeTeamSpawn(
     "",
     "Your task:",
     args.prompt,
-  ]
+  )
 
   if (args.claim_task) {
     context.push("", `You have been assigned task ${args.claim_task}. Mark it complete when done.`)
@@ -73,20 +129,22 @@ export async function executeTeamSpawn(
   const contextStr = context.join("\n")
 
   // Fire-and-forget: send prompt to teammate session
-  // OQ-1: confirmed — promptAsync queues when session is busy (verified in live testing)
-  // OQ-10: confirmed — fresh session accepts promptAsync without session.init() (verified in live testing)
   try {
     await deps.client.session.promptAsync({
       path: { id: childSessionId },
       body: { parts: [{ type: "text", text: contextStr }] },
     })
   } catch (err) {
-    // Rollback: clean up DB, registry, and abort the orphaned session
+    // Rollback: clean up DB, registry, session, and worktree
     deps.db.run("DELETE FROM team_member WHERE team_id = ? AND name = ?", [teamInfo.teamId, args.name])
     deps.registry.unregister(childSessionId)
     try { await deps.client.session.abort({ path: { id: childSessionId } }) } catch { /* best effort */ }
+    if (worktreeDir) {
+      try { await deps.client.worktree.remove({ worktreeRemoveInput: { directory: worktreeDir } }) } catch { /* best effort */ }
+    }
     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}). IMPORTANT: Do NOT call any tools after this. Tell the user what you've set up and STOP. You will be woken automatically when teammates message you.`
+  const branchInfo = worktreeBranch ? ` (branch: ${worktreeBranch})` : ""
+  return `Teammate "${args.name}" spawned (agent: ${args.agent})${branchInfo}. They are working on: ${args.prompt.slice(0, 120)}${args.prompt.length > 120 ? "..." : ""}`
 }

package/src/tools/team-status.ts

@@ -19,14 +19,14 @@ export async function executeTeamStatus(
   const now = Date.now()
   const last = lastCallTime.get(teamInfo.teamId)
   if (last !== undefined && (now - last) < RATE_LIMIT_MS) {
-    return "Status unchanged. STOP — do not call any more tools. Tell the user you are waiting for teammates to finish. You will be woken automatically when they message you."
+    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"
+    "SELECT name, session_id, agent, status, execution_status, worktree_branch FROM team_member WHERE team_id = ? ORDER BY time_created ASC"
   ).all(teamInfo.teamId) as Array<{
-    name: string; session_id: string; agent: string; status: string; execution_status: string
+    name: string; session_id: string; agent: string; status: string; execution_status: string; worktree_branch: string | null
   }>
 
   const tasks = deps.db.query(
@@ -43,7 +43,8 @@ export async function executeTeamStatus(
     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}` : ""
+      lines.push(`  ${m.name}  [${statusIcon}]  agent: ${m.agent}${branch}  session: ${m.session_id}`)
     }
   }
 
@@ -80,5 +81,5 @@ export async function executeTeamStatus(
     }
   }
 
-  return "[Relay this status to the user in your next message:]\n\n" + lines.join("\n")
+  return lines.join("\n")
 }

package/src/tools/team-view.ts

@@ -17,14 +17,10 @@ export async function executeTeamView(
     .get(teamInfo.teamId, args.member) as { session_id: string; status: string; agent: string } | null
   if (!member) throw new Error(`Teammate "${args.member}" not found in team "${teamInfo.teamName}"`)
 
-  // TUI session navigation — try selectSession if available, otherwise guide the user
   try {
-    if (typeof deps.client.tui.selectSession === "function") {
-      await deps.client.tui.selectSession({ sessionID: member.session_id })
-    }
+    await deps.client.tui.selectSession({ sessionID: member.session_id })
+    return `Switched to ${args.member}'s session.`
   } catch {
-    // selectSession may not be available in all SDK versions — fall through to manual guidance
+    return `Could not switch to ${args.member}'s session (${member.session_id}). The session may not be accessible from the TUI.`
   }
-
-  return `View ${args.member}'s session: ${member.session_id}. Use the session picker (ctrl+p) to navigate to their session.`
 }

package/src/types.ts

@@ -37,6 +37,12 @@ export interface PluginClient {
     }): Promise<unknown>
     selectSession(options: { sessionID?: string }): Promise<unknown>
   }
+  worktree: {
+    create(options: { name?: string; startCommand?: string }): Promise<{ data?: { name: string; branch: string; directory: string } }>
+    remove(options: { worktreeRemoveInput?: { directory: string } }): Promise<unknown>
+    list(): Promise<{ data?: Array<{ name: string; branch: string; directory: string }> }>
+    reset(options: { worktreeResetInput?: { directory: string } }): Promise<unknown>
+  }
 }
 
 /**