@hueyexe/opencode-ensemble 0.6.5 → 0.7.1

package/README.md

@@ -79,7 +79,11 @@ Lead: "All validation and tests are complete. 5 endpoints validated,
 
 ## Install
 
-Add the plugin to your OpenCode config. Project-level or global.
+Two steps: add the plugin, then allowlist worktree paths.
+
+### 1. Add the plugin
+
+Add to your OpenCode config. Project-level or global.
 
 **Project-level** (`opencode.json` in your project root):
 
@@ -99,6 +103,24 @@ Add the plugin to your OpenCode config. Project-level or global.
 
 OpenCode auto-installs npm plugins at startup (cached in `~/.cache/opencode/node_modules/`). No `npm install` needed.
 
+### 2. Allow worktree directory access
+
+Teammates work in git worktrees outside your project directory. Without this permission, OpenCode will prompt you to approve every file operation in a teammate's worktree.
+
+Add to your OpenCode config (`~/.config/opencode/opencode.json`):
+
+```json
+{
+  "permission": {
+    "external_directory": {
+      "~/.local/share/opencode/worktree/**": "allow"
+    }
+  }
+}
+```
+
+This is required. Without it, you'll see "Permission required — Access external directory" prompts constantly.
+
 ### Local development
 
 For working on the plugin itself, create `.opencode/plugins/ensemble.ts` in your project:
@@ -221,7 +243,7 @@ Same coordination model (shared tasks, peer messaging, lead coordination) with s
 ```bash
 bun install
 bun run typecheck
-bun test             # 286 tests
+bun test             # 377 tests
 bun run build
 ```
 

package/dist/index.js

@@ -15675,6 +15675,13 @@ function checkToolIsolation(registry2, tracker, toolName, sessionId) {
     throw new Error("Team tools are not available to sub-agents. Report findings to your parent teammate via your normal output.");
   }
 }
+function shouldNudgeIdleMember(db, teamId, memberName) {
+  const member = db.query("SELECT status FROM team_member WHERE team_id = ? AND name = ?").get(teamId, memberName);
+  if (!member || member.status !== "ready")
+    return false;
+  const msg = db.query("SELECT id FROM team_message WHERE team_id = ? AND from_name = ? AND (to_name = 'lead' OR to_name IS NULL) LIMIT 1").get(teamId, memberName);
+  return !msg;
+}
 
 // src/notify.ts
 var TOAST_CONFIG = {
@@ -15776,7 +15783,7 @@ function buildLeadSystemPrompt(db, teamId) {
     }
     lines.push("--- End Messages ---");
   }
-  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.");
+  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.", "", "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(`
 `);
 }
@@ -15784,7 +15791,7 @@ 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.`;
+  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.`;
 }
 function buildTeamCompactionContext(db, teamId, role, memberName) {
   const team = db.query("SELECT name FROM team WHERE id = ?").get(teamId);
@@ -15802,11 +15809,15 @@ function buildTeamCompactionContext(db, teamId, role, memberName) {
   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 [
+  const lines = [
     roleLine,
     membersLine,
     `Tasks: ${completed} completed, ${inProgress} in progress, ${pending} pending`
-  ].join(`
+  ];
+  if (role === "member") {
+    lines.push("IMPORTANT: You MUST send your results to the lead via team_message before stopping.");
+  }
+  return lines.join(`
 `);
 }
 
@@ -15860,10 +15871,41 @@ async function executeTeamCreate(deps, args, sessionId) {
   return `Team "${args.name}" created. You are the lead. Use team_spawn to add teammates.`;
 }
 
+// src/tools/shared.ts
+async function checkWorktreeDirty(dir) {
+  try {
+    const proc = Bun.spawn(["git", "-C", dir, "status", "--porcelain"], { stdout: "pipe", stderr: "pipe" });
+    const output = await new Response(proc.stdout).text();
+    const exitCode = await proc.exited;
+    if (exitCode !== 0)
+      return false;
+    return output.trim().length > 0;
+  } catch {
+    return false;
+  }
+}
+function requireLead(deps, sessionId) {
+  const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId);
+  if (!teamInfo)
+    throw new Error("This session is not in a team. Use team_create first.");
+  if (teamInfo.role !== "lead")
+    throw new Error("Only the team lead can use this tool.");
+  return { teamId: teamInfo.teamId, teamName: teamInfo.teamName };
+}
+function requireTeamMember(deps, sessionId) {
+  const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId);
+  if (!teamInfo)
+    throw new Error("This session is not in a team.");
+  return teamInfo;
+}
+
 // src/tools/team-spawn.ts
 function getSpawnTimeout() {
   return Number(process.env.SPAWN_TIMEOUT_MS) || 120000;
 }
+function isWorktreeDirectory(dir) {
+  return dir.includes("/opencode/worktree/");
+}
 function withTimeout(promise2, ms, label) {
   let timer;
   return Promise.race([
@@ -15877,15 +15919,11 @@ async function executeTeamSpawn(deps, args, sessionId) {
   const nameError = validateMemberName(args.name);
   if (nameError)
     throw new Error(nameError);
-  const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId);
-  if (!teamInfo)
-    throw new Error("This session is not in a team. Use team_create first.");
-  if (teamInfo.role !== "lead")
-    throw new Error("Only the team lead can spawn teammates.");
+  const teamInfo = requireLead(deps, 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 useWorktree = args.worktree !== false;
+  const useWorktree = args.worktree !== false && !isWorktreeDirectory(deps.directory);
   const usePlanApproval = args.plan_approval === true;
   log(`spawn:start name=${args.name} agent=${args.agent} worktree=${useWorktree}`);
   let worktreeDir = null;
@@ -15927,18 +15965,24 @@ async function executeTeamSpawn(deps, args, sessionId) {
   }
   const isReadOnly = args.agent === "plan" || args.agent === "explore";
   const TEAM_TOOLS = ["team_message", "team_broadcast", "team_tasks_list", "team_tasks_add", "team_tasks_complete", "team_claim"];
-  const permission = isReadOnly ? [
-    { permission: "edit", pattern: "*", action: "deny" },
-    { permission: "bash", pattern: "*", action: "deny" },
-    ...TEAM_TOOLS.map((t) => ({ permission: t, pattern: "*", action: "allow" }))
-  ] : undefined;
+  const permission = [];
+  if (worktreeDir) {
+    permission.push({ permission: "edit", pattern: `${worktreeDir}/**`, action: "allow" });
+    if (!isReadOnly) {
+      permission.push({ permission: "bash", pattern: "*", action: "allow" });
+    }
+  }
+  if (isReadOnly) {
+    permission.push({ permission: "edit", pattern: "*", action: "deny" }, { permission: "bash", pattern: "*", action: "deny" });
+  }
+  permission.push(...TEAM_TOOLS.map((t) => ({ permission: t, pattern: "*", action: "allow" })));
   let childSessionId;
   try {
     log(`spawn:session:start name=${args.name}`);
     const createResult = await withTimeout(deps.client.session.create({
       parentID: sessionId,
       title: `${args.name} (@${args.agent} teammate)`,
-      ...permission ? { permission } : {},
+      permission,
       ...workspaceId ? { workspaceID: workspaceId } : {}
     }), getSpawnTimeout(), `session.create for "${args.name}"`);
     childSessionId = createResult.data?.id;
@@ -15989,7 +16033,29 @@ async function executeTeamSpawn(deps, args, sessionId) {
   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.");
+  if (isReadOnly) {
+    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");
+  } 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");
+  }
+  context.push("", "When you finish your task:");
+  if (!isReadOnly && worktreeBranch) {
+    context.push(`1. Commit your changes: git add -A && git commit -m "your summary"`);
+    context.push("2. If you claimed a task, mark it complete using team_tasks_complete.");
+    context.push("3. Send ONE message to the lead using team_message with this format:");
+  } else if (!isReadOnly) {
+    context.push("1. If you claimed a task, mark it complete using team_tasks_complete.");
+    context.push("2. Send ONE message to the lead using team_message with this format:");
+  } else {
+    context.push("1. Send ONE message to the lead using team_message with this format:");
+  }
+  context.push("<task-result>", "<status>completed or failed</status>", "<summary>One-line summary of what you did</summary>", "<details>Full findings or changes made</details>");
+  if (worktreeBranch) {
+    context.push(`<branch>${worktreeBranch}</branch>`);
+  }
+  context.push("</task-result>");
+  const lastStep = !isReadOnly && worktreeBranch ? "4" : !isReadOnly ? "3" : "2";
+  context.push(`${lastStep}. 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.");
   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.`);
@@ -16035,9 +16101,7 @@ async function executeTeamSpawn(deps, args, sessionId) {
 
 // src/tools/team-message.ts
 async function executeTeamMessage(deps, args, sessionId) {
-  const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId);
-  if (!teamInfo)
-    throw new Error("This session is not in a team. Use team_create first.");
+  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)
@@ -16093,9 +16157,7 @@ async function executeTeamMessage(deps, args, sessionId) {
 
 // src/tools/team-broadcast.ts
 async function executeTeamBroadcast(deps, args, sessionId) {
-  const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId);
-  if (!teamInfo)
-    throw new Error("This session is not in a team. Use team_create first.");
+  const teamInfo = requireTeamMember(deps, sessionId);
   const senderName = teamInfo.role === "lead" ? "lead" : teamInfo.memberName ?? "unknown";
   const msgId = broadcastMessage(deps.db, {
     teamId: teamInfo.teamId,
@@ -16131,13 +16193,9 @@ async function executeTeamBroadcast(deps, args, sessionId) {
 }
 
 // src/tools/team-shutdown.ts
-async function executeTeamShutdown(deps, args, sessionId) {
-  const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId);
-  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, worktree_branch FROM team_member WHERE team_id = ? AND name = ?").get(teamInfo.teamId, args.member);
+async function executeTeamShutdown(deps, args, sessionId, isDirty = checkWorktreeDirty) {
+  const teamInfo = requireLead(deps, sessionId);
+  const member = deps.db.query("SELECT session_id, status, worktree_branch, worktree_dir 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")
@@ -16146,7 +16204,8 @@ async function executeTeamShutdown(deps, args, sessionId) {
   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}`;
+    const dirtyWarning = await getDirtyWarning(member.worktree_dir, args.member, isDirty);
+    return `Force shut down "${args.member}".${branchInfo}${dirtyWarning}`;
   }
   let isIdle = false;
   try {
@@ -16157,7 +16216,8 @@ async function executeTeamShutdown(deps, args, sessionId) {
   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}`;
+    const dirtyWarning = await getDirtyWarning(member.worktree_dir, args.member, isDirty);
+    return `Teammate "${args.member}" has been shut down.${branchInfo}${dirtyWarning}`;
   }
   try {
     await deps.client.session.promptAsync({
@@ -16177,20 +16237,50 @@ async function abortAndShutdown(deps, teamId, memberName, 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]);
 }
+async function getDirtyWarning(worktreeDir, memberName, isDirty) {
+  if (!worktreeDir)
+    return "";
+  try {
+    if (await isDirty(worktreeDir)) {
+      return `
+
+Warning: ${memberName} has uncommitted changes in their worktree. Commit or merge before calling team_cleanup.`;
+    }
+  } catch {}
+  return "";
+}
 
 // src/tools/team-cleanup.ts
-async function executeTeamCleanup(deps, args, sessionId) {
-  const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId);
-  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.");
+async function executeTeamCleanup(deps, args, sessionId, isDirty = checkWorktreeDirty) {
+  const teamInfo = requireLead(deps, sessionId);
   const members = deps.db.query("SELECT name, session_id, status, worktree_dir, worktree_branch, workspace_id 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(", ");
     throw new Error(`Cannot clean up team "${teamInfo.teamName}": ${active.length} member(s) still active: ${names}. Use team_shutdown on each member first, or call team_cleanup with force: true to abort them immediately.`);
   }
+  if (!args.acknowledge_uncommitted) {
+    const dirty = [];
+    for (const member of members) {
+      if (member.worktree_dir) {
+        try {
+          if (await isDirty(member.worktree_dir)) {
+            dirty.push({ name: member.name, branch: member.worktree_branch ?? "unknown" });
+          }
+        } catch {
+          log(`cleanup:dirty-check:failed name=${member.name}`);
+        }
+      }
+    }
+    if (dirty.length > 0) {
+      const warnings = dirty.map((d) => `  - ${d.name} (branch: ${d.branch})`).join(`
+`);
+      return `Warning: ${dirty.length} teammate(s) have uncommitted changes in their worktrees:
+${warnings}
+
+Commit or merge their work first, then call team_cleanup with acknowledge_uncommitted: true to proceed.`;
+    }
+  }
   if (args.force) {
     for (const member of active) {
       try {
@@ -16231,9 +16321,7 @@ ${mergeCommands}`;
 
 // src/tools/team-tasks-list.ts
 async function executeTeamTasksList(deps, sessionId) {
-  const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId);
-  if (!teamInfo)
-    throw new Error("This session is not in a team.");
+  const teamInfo = requireTeamMember(deps, sessionId);
   const tasks = deps.db.query("SELECT * FROM team_task WHERE team_id = ? ORDER BY time_created ASC").all(teamInfo.teamId);
   if (tasks.length === 0)
     return "No tasks on the board.";
@@ -16243,9 +16331,7 @@ async function executeTeamTasksList(deps, sessionId) {
 
 // src/tools/team-tasks-add.ts
 async function executeTeamTasksAdd(deps, args, sessionId) {
-  const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId);
-  if (!teamInfo)
-    throw new Error("This session is not in a team.");
+  const teamInfo = requireTeamMember(deps, sessionId);
   const ids = [];
   const now = Date.now();
   for (const task of args.tasks) {
@@ -16268,9 +16354,7 @@ async function executeTeamTasksAdd(deps, args, sessionId) {
 
 // src/tools/team-tasks-complete.ts
 async function executeTeamTasksComplete(deps, args, sessionId) {
-  const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId);
-  if (!teamInfo)
-    throw new Error("This session is not in a team.");
+  const teamInfo = requireTeamMember(deps, sessionId);
   const task = deps.db.query("SELECT * FROM team_task WHERE id = ? AND team_id = ?").get(args.task_id, teamInfo.teamId);
   if (!task)
     throw new Error(`Task "${args.task_id}" not found`);
@@ -16301,9 +16385,7 @@ async function executeTeamTasksComplete(deps, args, sessionId) {
 
 // src/tools/team-claim.ts
 async function executeTeamClaim(deps, args, sessionId) {
-  const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId);
-  if (!teamInfo)
-    throw new Error("This session is not in a team.");
+  const teamInfo = requireTeamMember(deps, sessionId);
   const claimerName = teamInfo.role === "lead" ? "lead" : teamInfo.memberName ?? "unknown";
   const task = deps.db.query("SELECT * FROM team_task WHERE id = ? AND team_id = ?").get(args.task_id, teamInfo.teamId);
   if (!task)
@@ -16323,9 +16405,7 @@ async function executeTeamClaim(deps, args, sessionId) {
 
 // src/tools/team-results.ts
 async function executeTeamResults(deps, args, sessionId) {
-  const team = findTeamBySession(deps.db, deps.registry, sessionId);
-  if (!team)
-    throw new Error("not in a team");
+  const team = requireTeamMember(deps, sessionId);
   const rows = args.from ? deps.db.query("SELECT id, from_name, content, time_created FROM team_message WHERE team_id = ? AND read = 0 AND from_name = ? ORDER BY time_created ASC").all(team.teamId, args.from) : deps.db.query("SELECT id, from_name, content, time_created FROM team_message WHERE team_id = ? AND read = 0 ORDER BY time_created ASC").all(team.teamId);
   if (rows.length === 0)
     return "No unread messages.";
@@ -16342,16 +16422,14 @@ ${r.content}
 var lastCallTime = new Map;
 var RATE_LIMIT_MS = 30000;
 async function executeTeamStatus(deps, sessionId) {
-  const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId);
-  if (!teamInfo)
-    throw new Error("This session is not in a team.");
+  const teamInfo = requireTeamMember(deps, sessionId);
   const now = Date.now();
   const last = lastCallTime.get(teamInfo.teamId);
   if (last !== undefined && now - last < RATE_LIMIT_MS) {
     return "No changes since last check.";
   }
   lastCallTime.set(teamInfo.teamId, now);
-  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 members = deps.db.query("SELECT name, session_id, agent, status, execution_status, worktree_branch, worktree_dir, 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})`);
@@ -16365,6 +16443,9 @@ async function executeTeamStatus(deps, sessionId) {
       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 (m.worktree_dir) {
+        lines.push(`    worktree: ${m.worktree_dir}`);
+      }
     }
   }
   if (tasks.length > 0) {
@@ -16401,9 +16482,7 @@ async function executeTeamStatus(deps, sessionId) {
 
 // src/tools/team-view.ts
 async function executeTeamView(deps, args, sessionId) {
-  const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId);
-  if (!teamInfo)
-    throw new Error("This session is not in a team.");
+  const teamInfo = requireTeamMember(deps, sessionId);
   const member = deps.db.query("SELECT session_id, status, agent 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}"`);
@@ -16493,7 +16572,28 @@ class Watchdog {
     this.ttlMs = opts.ttlMs;
     this.checkIntervalMs = opts.checkIntervalMs ?? 60000;
   }
+  static STALE_THRESHOLD_MS = Number(process.env.STALE_WORKTREE_THRESHOLD_MS) || 300000;
+  async cleanupStaleWorktrees() {
+    const cutoff = Date.now() - Watchdog.STALE_THRESHOLD_MS;
+    const stale = this.db.query(`SELECT tm.team_id, tm.name, tm.worktree_dir, tm.workspace_id
+       FROM team_member tm
+       JOIN team t ON tm.team_id = t.id
+       WHERE t.status = 'active'
+         AND tm.status IN ('shutdown', 'error')
+         AND tm.worktree_dir IS NOT NULL
+         AND tm.time_updated < ?`).all(cutoff);
+    for (const m of stale) {
+      try {
+        if (m.workspace_id) {
+          await this.client.workspace.remove({ id: m.workspace_id });
+        }
+        await this.client.worktree.remove({ worktreeRemoveInput: { directory: m.worktree_dir } });
+        this.db.run("UPDATE team_member SET worktree_dir = NULL, worktree_branch = NULL, workspace_id = NULL WHERE team_id = ? AND name = ?", [m.team_id, m.name]);
+      } catch {}
+    }
+  }
   async check() {
+    await this.cleanupStaleWorktrees();
     if (this.ttlMs === 0)
       return;
     const cutoff = Date.now() - this.ttlMs;
@@ -16521,8 +16621,6 @@ class Watchdog {
   start() {
     if (this.timer)
       return;
-    if (this.ttlMs === 0)
-      return;
     this.timer = setInterval(() => this.check(), this.checkIntervalMs);
   }
   stop() {
@@ -16548,6 +16646,7 @@ var plugin = async (input) => {
   const db = createDb(dbPath);
   const registry2 = new MemberRegistry;
   const tracker = new DescendantTracker;
+  const nudgedMembers = new Set;
   const pluginTransport = input.client._client;
   const rawClient = new OpencodeClient({ client: pluginTransport });
   initLog(rawClient);
@@ -16601,6 +16700,15 @@ 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 nudgeKey = `${transition.teamId}:${transition.memberName}`;
+            if (!nudgedMembers.has(nudgeKey) && shouldNudgeIdleMember(db, transition.teamId, transition.memberName)) {
+              nudgedMembers.add(nudgeKey);
+              log(`nudge:idle-without-report name=${transition.memberName}`);
+              client3.session.promptAsync({
+                sessionID,
+                parts: [{ type: "text", text: "[System]: You completed your work but did not report results. Send your findings to the lead via team_message now." }]
+              }).catch(() => {});
+            }
           } else if (transition.to === "error") {
             notifyTeamEvent(client3, "error", { memberName: transition.memberName });
           } else if (transition.to === "retry") {
@@ -16811,18 +16919,21 @@ var plugin = async (input) => {
         },
         async execute(args, ctx) {
           const result = await executeTeamShutdown(deps, args, ctx.sessionID);
-          ctx.metadata({ title: `Shutdown \u2192 ${args.member}` });
+          const hasWarning = result.includes("uncommitted");
+          ctx.metadata({ title: hasWarning ? `${args.member} shut down \u2014 uncommitted changes` : `${args.member} shut down` });
           return result;
         }
       }),
       team_cleanup: tool({
         description: "Clean up the team. All teammates must be shut down first. Removes team data and frees resources.",
         args: {
-          force: tool.schema.boolean().default(false).describe("Force cleanup even if members are active (will abort them)")
+          force: tool.schema.boolean().default(false).describe("Force cleanup even if members are active (will abort them)"),
+          acknowledge_uncommitted: tool.schema.boolean().default(false)
         },
         async execute(args, ctx) {
           const result = await executeTeamCleanup(deps, args, ctx.sessionID);
-          ctx.metadata({ title: "Team cleaned up" });
+          const blocked = result.includes("uncommitted");
+          ctx.metadata({ title: blocked ? "Cleanup blocked \u2014 uncommitted changes" : "Team cleaned up" });
           return result;
         }
       }),

package/package.json

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

@@ -98,3 +98,17 @@ export function checkToolIsolation(
     throw new Error("Team tools are not available to sub-agents. Report findings to your parent teammate via your normal output.")
   }
 }
+
+/**
+ * Check if a member went idle without ever sending a message to the lead.
+ * Returns true if the member is idle/ready and has no outbound messages.
+ */
+export function shouldNudgeIdleMember(db: Database, teamId: string, memberName: string): boolean {
+  const member = db.query("SELECT status FROM team_member WHERE team_id = ? AND name = ?")
+    .get(teamId, memberName) as { status: string } | null
+  if (!member || member.status !== "ready") return false
+
+  const msg = db.query("SELECT id FROM team_message WHERE team_id = ? AND from_name = ? AND (to_name = 'lead' OR to_name IS NULL) LIMIT 1")
+    .get(teamId, memberName) as { id: string } | null
+  return !msg
+}

package/src/index.ts

@@ -8,7 +8,7 @@ import { wrapThrowingClient } from "./client"
 import { recoverStaleMembers, recoverUndeliveredMessages, recoverOrphanedWorktrees } from "./recovery"
 import { MemberRegistry, DescendantTracker } from "./state"
 import { isWorktreeInstance } from "./util"
-import { handleSessionStatusEvent, handleSessionCreatedEvent, checkToolIsolation } from "./hooks"
+import { handleSessionStatusEvent, handleSessionCreatedEvent, checkToolIsolation, shouldNudgeIdleMember } from "./hooks"
 import { notifyTeamEvent, notifyWorkingProgress } from "./notify"
 import { buildLeadSystemPrompt, buildTeammateSystemPrompt, buildTeamCompactionContext } from "./system-prompt"
 import { log, initLog } from "./log"
@@ -50,6 +50,7 @@ const plugin: Plugin = async (input) => {
   // Initialize in-memory state
   const registry = new MemberRegistry()
   const tracker = new DescendantTracker()
+  const nudgedMembers = new Set<string>()
 
   // Extract the working HeyAPI transport from the plugin-provided v1 client and pass it
   // to the v2 OpencodeClient. The plugin framework provides a v1 client which stores its
@@ -123,6 +124,16 @@ 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 })
+            // 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)) {
+              nudgedMembers.add(nudgeKey)
+              log(`nudge:idle-without-report name=${transition.memberName}`)
+              client.session.promptAsync({
+                sessionID,
+                parts: [{ type: "text", text: "[System]: You completed your work but did not report results. Send your findings to the lead via team_message now." }],
+              }).catch(() => { /* best effort */ })
+            }
           } else if (transition.to === "error") {
             notifyTeamEvent(client, "error", { memberName: transition.memberName })
           } else if (transition.to === "retry") {
@@ -361,7 +372,8 @@ const plugin: Plugin = async (input) => {
         },
         async execute(args, ctx) {
           const result = await executeTeamShutdown(deps, args, ctx.sessionID)
-          ctx.metadata({ title: `Shutdown → ${args.member}` })
+          const hasWarning = result.includes("uncommitted")
+          ctx.metadata({ title: hasWarning ? `${args.member} shut down — uncommitted changes` : `${args.member} shut down` })
           return result
         },
       }),
@@ -370,10 +382,12 @@ const plugin: Plugin = async (input) => {
         description: "Clean up the team. All teammates must be shut down first. Removes team data and frees resources.",
         args: {
           force: tool.schema.boolean().default(false).describe("Force cleanup even if members are active (will abort them)"),
+          acknowledge_uncommitted: tool.schema.boolean().default(false),
         },
         async execute(args, ctx) {
           const result = await executeTeamCleanup(deps, args, ctx.sessionID)
-          ctx.metadata({ title: "Team cleaned up" })
+          const blocked = result.includes("uncommitted")
+          ctx.metadata({ title: blocked ? "Cleanup blocked — uncommitted changes" : "Team cleaned up" })
           return result
         },
       }),

package/src/system-prompt.ts

@@ -75,6 +75,10 @@ export function buildLeadSystemPrompt(db: Database, teamId: string): string {
     "Do NOT poll team_status or team_tasks_list repeatedly — 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.",
+    "",
+    "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 — merge or commit first.",
   )
 
   return lines.join("\n")
@@ -88,7 +92,7 @@ export function buildTeammateSystemPrompt(db: Database, teamId: string, memberNa
   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.`
+  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.`
 }
 
 /**
@@ -131,9 +135,15 @@ export function buildTeamCompactionContext(
     ? `Members: ${memberList}`
     : "Members: none"
 
-  return [
+  const lines = [
     roleLine,
     membersLine,
     `Tasks: ${completed} completed, ${inProgress} in progress, ${pending} pending`,
-  ].join("\n")
+  ]
+
+  if (role === "member") {
+    lines.push("IMPORTANT: You MUST send your results to the lead via team_message before stopping.")
+  }
+
+  return lines.join("\n")
 }

package/src/tools/shared.ts

@@ -0,0 +1,39 @@
+import type { ToolDeps } from "../types"
+import { findTeamBySession } from "../types"
+
+/** Function type for dirty worktree check — injectable for testing. */
+export type IsDirtyFn = (dir: string) => Promise<boolean>
+
+/** Check if a worktree directory has uncommitted changes via git status. */
+export async function checkWorktreeDirty(dir: string): Promise<boolean> {
+  try {
+    const proc = Bun.spawn(["git", "-C", dir, "status", "--porcelain"], { stdout: "pipe", stderr: "pipe" })
+    const output = await new Response(proc.stdout).text()
+    const exitCode = await proc.exited
+    if (exitCode !== 0) return false // git failed — assume clean
+    return output.trim().length > 0
+  } catch {
+    return false // can't check — assume clean
+  }
+}
+
+/** Validate that the session belongs to the team lead. Throws if not. */
+export function requireLead(
+  deps: Pick<ToolDeps, "db" | "registry">,
+  sessionId: string,
+): { teamId: string; teamName: string } {
+  const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId)
+  if (!teamInfo) throw new Error("This session is not in a team. Use team_create first.")
+  if (teamInfo.role !== "lead") throw new Error("Only the team lead can use this tool.")
+  return { teamId: teamInfo.teamId, teamName: teamInfo.teamName }
+}
+
+/** Validate that the session belongs to any team member (lead or teammate). Throws if not. */
+export function requireTeamMember(
+  deps: Pick<ToolDeps, "db" | "registry">,
+  sessionId: string,
+): { teamId: string; teamName: string; role: "lead" | "member"; memberName?: string } {
+  const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId)
+  if (!teamInfo) throw new Error("This session is not in a team.")
+  return teamInfo
+}

package/src/tools/team-broadcast.ts

@@ -1,5 +1,5 @@
 import type { ToolDeps } from "../types"
-import { findTeamBySession } from "../types"
+import { requireTeamMember } from "./shared"
 import { broadcastMessage, markDelivered } from "../messaging"
 import { log } from "../log"
 
@@ -11,8 +11,7 @@ export async function executeTeamBroadcast(
   args: { text: string },
   sessionId: string,
 ): Promise<string> {
-  const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId)
-  if (!teamInfo) throw new Error("This session is not in a team. Use team_create first.")
+  const teamInfo = requireTeamMember(deps, sessionId)
 
   const senderName = teamInfo.role === "lead" ? "lead" : (teamInfo.memberName ?? "unknown")
 

package/src/tools/team-claim.ts

@@ -1,5 +1,5 @@
 import type { ToolDeps } from "../types"
-import { findTeamBySession } from "../types"
+import { requireTeamMember } from "./shared"
 
 /**
  * Execute the team_claim tool. Atomically claims a pending task.
@@ -10,8 +10,7 @@ export async function executeTeamClaim(
   args: { task_id: string },
   sessionId: string,
 ): Promise<string> {
-  const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId)
-  if (!teamInfo) throw new Error("This session is not in a team.")
+  const teamInfo = requireTeamMember(deps, sessionId)
 
   const claimerName = teamInfo.role === "lead" ? "lead" : (teamInfo.memberName ?? "unknown")
 

package/src/tools/team-cleanup.ts

@@ -1,19 +1,21 @@
 import type { ToolDeps } from "../types"
-import { findTeamBySession } from "../types"
+import { requireLead, checkWorktreeDirty } from "./shared"
+import type { IsDirtyFn } from "./shared"
+import { log } from "../log"
 
 /**
  * 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.
+ * Checks for uncommitted changes BEFORE aborting sessions or removing worktrees.
+ * If force=true, aborts active sessions but still blocks on dirty worktrees.
+ * Pass acknowledge_uncommitted=true to remove dirty worktrees.
  */
 export async function executeTeamCleanup(
   deps: ToolDeps,
-  args: { force: boolean },
+  args: { force: boolean; acknowledge_uncommitted?: boolean },
   sessionId: string,
+  isDirty: IsDirtyFn = checkWorktreeDirty,
 ): Promise<string> {
-  const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId)
-  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 teamInfo = requireLead(deps, sessionId)
 
   const members = deps.db.query("SELECT name, session_id, status, worktree_dir, worktree_branch, workspace_id 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; workspace_id: string | null }>
@@ -25,7 +27,28 @@ export async function executeTeamCleanup(
     throw new Error(`Cannot clean up team "${teamInfo.teamName}": ${active.length} member(s) still active: ${names}. Use team_shutdown on each member first, or call team_cleanup with force: true to abort them immediately.`)
   }
 
-  // Force-abort active members
+  // Check for uncommitted changes BEFORE aborting sessions — agents can still commit if warned
+  if (!args.acknowledge_uncommitted) {
+    const dirty: Array<{ name: string; branch: string }> = []
+    for (const member of members) {
+      if (member.worktree_dir) {
+        try {
+          if (await isDirty(member.worktree_dir)) {
+            dirty.push({ name: member.name, branch: member.worktree_branch ?? "unknown" })
+          }
+        } catch {
+          log(`cleanup:dirty-check:failed name=${member.name}`)
+        }
+      }
+    }
+
+    if (dirty.length > 0) {
+      const warnings = dirty.map(d => `  - ${d.name} (branch: ${d.branch})`).join("\n")
+      return `Warning: ${dirty.length} teammate(s) have uncommitted changes in their worktrees:\n${warnings}\n\nCommit or merge their work first, then call team_cleanup with acknowledge_uncommitted: true to proceed.`
+    }
+  }
+
+  // Force-abort active members (only reached if worktrees are clean or acknowledged)
   if (args.force) {
     for (const member of active) {
       try {

package/src/tools/team-message.ts

@@ -1,5 +1,6 @@
 import type { ToolDeps } from "../types"
-import { findTeamBySession, resolveRecipientSession } from "../types"
+import { resolveRecipientSession } from "../types"
+import { requireTeamMember } from "./shared"
 import { sendMessage, markDelivered } from "../messaging"
 import { log } from "../log"
 
@@ -12,8 +13,7 @@ export async function executeTeamMessage(
   args: { to: string; text: string; approve?: boolean; reject?: string },
   sessionId: string,
 ): Promise<string> {
-  const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId)
-  if (!teamInfo) throw new Error("This session is not in a team. Use team_create first.")
+  const teamInfo = requireTeamMember(deps, sessionId)
 
   const senderName = teamInfo.role === "lead" ? "lead" : (teamInfo.memberName ?? "unknown")
 

package/src/tools/team-results.ts

@@ -1,5 +1,5 @@
 import type { ToolDeps } from "../types"
-import { findTeamBySession } from "../types"
+import { requireTeamMember } from "./shared"
 
 /** Row shape for unread messages query. */
 interface UnreadMessageRow {
@@ -18,8 +18,7 @@ export async function executeTeamResults(
   args: { from?: string },
   sessionId: string,
 ): Promise<string> {
-  const team = findTeamBySession(deps.db, deps.registry, sessionId)
-  if (!team) throw new Error("not in a team")
+  const team = requireTeamMember(deps, sessionId)
 
   const rows = args.from
     ? (deps.db

package/src/tools/team-shutdown.ts

@@ -1,5 +1,6 @@
 import type { ToolDeps } from "../types"
-import { findTeamBySession } from "../types"
+import { requireLead, checkWorktreeDirty } from "./shared"
+import type { IsDirtyFn } from "./shared"
 
 /**
  * Execute the team_shutdown tool. Requests a teammate to shut down.
@@ -9,18 +10,19 @@ import { findTeamBySession } from "../types"
  * - If member is idle or force=true, abort immediately and set status='shutdown'.
  * - If member is busy and force=false, send a shutdown message via promptAsync
  *   and set status='shutdown_requested'. The member finishes work and reports back.
+ *
+ * Warns if the member's worktree has uncommitted changes.
  */
 export async function executeTeamShutdown(
   deps: ToolDeps,
   args: { member: string; force?: boolean },
   sessionId: string,
+  isDirty: IsDirtyFn = checkWorktreeDirty,
 ): Promise<string> {
-  const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId)
-  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 teamInfo = requireLead(deps, sessionId)
 
-  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
+  const member = deps.db.query("SELECT session_id, status, worktree_branch, worktree_dir FROM team_member WHERE team_id = ? AND name = ?")
+    .get(teamInfo.teamId, args.member) as { session_id: string; status: string; worktree_branch: string | null; worktree_dir: 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`)
 
@@ -30,7 +32,8 @@ export async function executeTeamShutdown(
   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}`
+    const dirtyWarning = await getDirtyWarning(member.worktree_dir, args.member, isDirty)
+    return `Force shut down "${args.member}".${branchInfo}${dirtyWarning}`
   }
 
   // Determine if member is idle or busy
@@ -46,7 +49,8 @@ export async function executeTeamShutdown(
   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}`
+    const dirtyWarning = await getDirtyWarning(member.worktree_dir, args.member, isDirty)
+    return `Teammate "${args.member}" has been shut down.${branchInfo}${dirtyWarning}`
   }
 
   // Busy + not force → graceful: send shutdown message, set shutdown_requested
@@ -91,3 +95,14 @@ async function abortAndShutdown(
     [Date.now(), teamId, memberName],
   )
 }
+
+/** Build a warning suffix if the member's worktree has uncommitted changes. */
+async function getDirtyWarning(worktreeDir: string | null, memberName: string, isDirty: IsDirtyFn): Promise<string> {
+  if (!worktreeDir) return ""
+  try {
+    if (await isDirty(worktreeDir)) {
+      return `\n\nWarning: ${memberName} has uncommitted changes in their worktree. Commit or merge before calling team_cleanup.`
+    }
+  } catch { /* best effort */ }
+  return ""
+}

package/src/tools/team-spawn.ts

@@ -1,6 +1,6 @@
 import type { ToolDeps, PermissionRule } from "../types"
 import { validateMemberName } from "../util"
-import { findTeamBySession } from "../types"
+import { requireLead } from "./shared"
 import { sendMessage } from "../messaging"
 import { log } from "../log"
 
@@ -9,6 +9,11 @@ function getSpawnTimeout(): number {
   return Number(process.env.SPAWN_TIMEOUT_MS) || 120_000
 }
 
+/** Returns true if the directory is already inside an OpenCode worktree. */
+function isWorktreeDirectory(dir: string): boolean {
+  return dir.includes("/opencode/worktree/")
+}
+
 /** Race a promise against a timeout. Throws if the timeout fires first. Cleans up timer on resolution. */
 function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T> {
   let timer: ReturnType<typeof setTimeout>
@@ -34,16 +39,14 @@ export async function executeTeamSpawn(
   const nameError = validateMemberName(args.name)
   if (nameError) throw new Error(nameError)
 
-  const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId)
-  if (!teamInfo) throw new Error("This session is not in a team. Use team_create first.")
-  if (teamInfo.role !== "lead") throw new Error("Only the team lead can spawn teammates.")
+  const teamInfo = requireLead(deps, sessionId)
 
   // Check duplicate name
   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 useWorktree = args.worktree !== false
+  const useWorktree = args.worktree !== false && !isWorktreeDirectory(deps.directory)
   const usePlanApproval = args.plan_approval === true
 
   log(`spawn:start name=${args.name} agent=${args.agent} worktree=${useWorktree}`)
@@ -99,17 +102,31 @@ export async function executeTeamSpawn(
   }
 
   // Permission rules on session.create are the hard gate (server-enforced).
-  // For read-only agents, deny write tools and explicitly allow team tools
-  // so the agent's built-in restrictive permissions don't block them.
+  // For read-only agents, deny write tools and explicitly allow team tools.
+  // For all agents with worktrees, allowlist the worktree path for edit/bash.
   const isReadOnly = args.agent === "plan" || args.agent === "explore"
   const TEAM_TOOLS = ["team_message", "team_broadcast", "team_tasks_list", "team_tasks_add", "team_tasks_complete", "team_claim"] as const
-  const permission: PermissionRule[] | undefined = isReadOnly
-    ? [
-        { permission: "edit", pattern: "*", action: "deny" },
-        { permission: "bash", pattern: "*", action: "deny" },
-        ...TEAM_TOOLS.map(t => ({ permission: t, pattern: "*", action: "allow" as const })),
-      ]
-    : undefined
+  const permission: PermissionRule[] = []
+
+  if (worktreeDir) {
+    permission.push(
+      { permission: "edit", pattern: `${worktreeDir}/**`, action: "allow" },
+    )
+    if (!isReadOnly) {
+      permission.push({ permission: "bash", pattern: "*", action: "allow" })
+    }
+  }
+
+  if (isReadOnly) {
+    permission.push(
+      { permission: "edit", pattern: "*", action: "deny" },
+      { permission: "bash", pattern: "*", action: "deny" },
+    )
+  }
+
+  permission.push(
+    ...TEAM_TOOLS.map(t => ({ permission: t, pattern: "*", action: "allow" as const })),
+  )
 
   // Create child session — bind to workspace if available (server-enforced CWD isolation).
   // Falls back to no workspace binding if workspace.create failed.
@@ -120,7 +137,7 @@ export async function executeTeamSpawn(
       deps.client.session.create({
         parentID: sessionId,
         title: `${args.name} (@${args.agent} teammate)`,
-        ...(permission ? { permission } : {}),
+        permission,
         ...(workspaceId ? { workspaceID: workspaceId } : {}),
       }),
       getSpawnTimeout(), `session.create for "${args.name}"`
@@ -196,20 +213,55 @@ export async function executeTeamSpawn(
     )
   }
 
+  if (isReadOnly) {
+    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",
+    )
+  } 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",
+    )
+  }
+
+  context.push("", "When you finish your task:")
+  if (!isReadOnly && worktreeBranch) {
+    context.push(`1. Commit your changes: git add -A && git commit -m "your summary"`)
+    context.push("2. If you claimed a task, mark it complete using team_tasks_complete.")
+    context.push(
+      "3. Send ONE message to the lead using team_message with this format:",
+    )
+  } else if (!isReadOnly) {
+    context.push("1. If you claimed a task, mark it complete using team_tasks_complete.")
+    context.push(
+      "2. Send ONE message to the lead using team_message with this format:",
+    )
+  } else {
+    context.push(
+      "1. Send ONE message to the lead using team_message with this format:",
+    )
+  }
   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.",
+    "<task-result>",
+    "<status>completed or failed</status>",
+    "<summary>One-line summary of what you did</summary>",
+    "<details>Full findings or changes made</details>",
+  )
+  if (worktreeBranch) {
+    context.push(`<branch>${worktreeBranch}</branch>`)
+  }
+  context.push("</task-result>")
+  const lastStep = !isReadOnly && worktreeBranch ? "4" : !isReadOnly ? "3" : "2"
+  context.push(
+    `${lastStep}. 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.",
     "",

package/src/tools/team-status.ts

@@ -1,5 +1,5 @@
 import type { ToolDeps } from "../types"
-import { findTeamBySession } from "../types"
+import { requireTeamMember } from "./shared"
 
 /** Tracks the last time team_status was called per team ID (epoch ms). */
 export const lastCallTime = new Map<string, number>()
@@ -13,8 +13,7 @@ export async function executeTeamStatus(
   deps: ToolDeps,
   sessionId: string,
 ): Promise<string> {
-  const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId)
-  if (!teamInfo) throw new Error("This session is not in a team.")
+  const teamInfo = requireTeamMember(deps, sessionId)
 
   const now = Date.now()
   const last = lastCallTime.get(teamInfo.teamId)
@@ -24,9 +23,9 @@ export async function executeTeamStatus(
   lastCallTime.set(teamInfo.teamId, now)
 
   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"
+    "SELECT name, session_id, agent, status, execution_status, worktree_branch, worktree_dir, plan_approval 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; worktree_branch: string | null; plan_approval: string
+    name: string; session_id: string; agent: string; status: string; execution_status: string; worktree_branch: string | null; worktree_dir: string | null; plan_approval: string
   }>
 
   const tasks = deps.db.query(
@@ -46,6 +45,9 @@ export async function executeTeamStatus(
       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 (m.worktree_dir) {
+        lines.push(`    worktree: ${m.worktree_dir}`)
+      }
     }
   }
 

package/src/tools/team-tasks-add.ts

@@ -1,5 +1,5 @@
 import type { ToolDeps } from "../types"
-import { findTeamBySession } from "../types"
+import { requireTeamMember } from "./shared"
 import { generateId } from "../util"
 
 interface TaskInput {
@@ -17,8 +17,7 @@ export async function executeTeamTasksAdd(
   args: { tasks: TaskInput[] },
   sessionId: string,
 ): Promise<string> {
-  const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId)
-  if (!teamInfo) throw new Error("This session is not in a team.")
+  const teamInfo = requireTeamMember(deps, sessionId)
 
   const ids: string[] = []
   const now = Date.now()

package/src/tools/team-tasks-complete.ts

@@ -1,5 +1,5 @@
 import type { ToolDeps } from "../types"
-import { findTeamBySession } from "../types"
+import { requireTeamMember } from "./shared"
 
 /**
  * Execute the team_tasks_complete tool. Marks a task as completed
@@ -10,8 +10,7 @@ export async function executeTeamTasksComplete(
   args: { task_id: string },
   sessionId: string,
 ): Promise<string> {
-  const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId)
-  if (!teamInfo) throw new Error("This session is not in a team.")
+  const teamInfo = requireTeamMember(deps, sessionId)
 
   const task = deps.db.query("SELECT * FROM team_task WHERE id = ? AND team_id = ?")
     .get(args.task_id, teamInfo.teamId) as Record<string, unknown> | null

package/src/tools/team-tasks-list.ts

@@ -1,5 +1,5 @@
 import type { ToolDeps } from "../types"
-import { findTeamBySession } from "../types"
+import { requireTeamMember } from "./shared"
 
 /**
  * Execute the team_tasks_list tool. Shows all tasks on the shared board.
@@ -8,8 +8,7 @@ export async function executeTeamTasksList(
   deps: ToolDeps,
   sessionId: string,
 ): Promise<string> {
-  const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId)
-  if (!teamInfo) throw new Error("This session is not in a team.")
+  const teamInfo = requireTeamMember(deps, sessionId)
 
   const tasks = deps.db.query(
     "SELECT * FROM team_task WHERE team_id = ? ORDER BY time_created ASC"

package/src/tools/team-view.ts

@@ -1,5 +1,5 @@
 import type { ToolDeps } from "../types"
-import { findTeamBySession } from "../types"
+import { requireTeamMember } from "./shared"
 
 /**
  * Execute the team_view tool. Navigates the TUI to a teammate's session
@@ -10,8 +10,7 @@ export async function executeTeamView(
   args: { member: string },
   sessionId: string,
 ): Promise<string> {
-  const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId)
-  if (!teamInfo) throw new Error("This session is not in a team.")
+  const teamInfo = requireTeamMember(deps, sessionId)
 
   const member = deps.db.query("SELECT session_id, status, agent FROM team_member WHERE team_id = ? AND name = ?")
     .get(teamInfo.teamId, args.member) as { session_id: string; status: string; agent: string } | null

package/src/watchdog.ts

@@ -32,8 +32,38 @@ export class Watchdog {
     this.checkIntervalMs = opts.checkIntervalMs ?? 60_000
   }
 
+  private static STALE_THRESHOLD_MS = Number(process.env.STALE_WORKTREE_THRESHOLD_MS) || 300_000
+
+  /** Clean up worktrees and workspaces for shutdown/error members past the stale threshold. */
+  async cleanupStaleWorktrees(): Promise<void> {
+    const cutoff = Date.now() - Watchdog.STALE_THRESHOLD_MS
+    const stale = this.db.query(
+      `SELECT tm.team_id, tm.name, tm.worktree_dir, tm.workspace_id
+       FROM team_member tm
+       JOIN team t ON tm.team_id = t.id
+       WHERE t.status = 'active'
+         AND tm.status IN ('shutdown', 'error')
+         AND tm.worktree_dir IS NOT NULL
+         AND tm.time_updated < ?`
+    ).all(cutoff) as Array<{ team_id: string; name: string; worktree_dir: string; workspace_id: string | null }>
+
+    for (const m of stale) {
+      try {
+        if (m.workspace_id) {
+          await this.client.workspace.remove({ id: m.workspace_id })
+        }
+        await this.client.worktree.remove({ worktreeRemoveInput: { directory: m.worktree_dir } })
+        this.db.run(
+          "UPDATE team_member SET worktree_dir = NULL, worktree_branch = NULL, workspace_id = NULL WHERE team_id = ? AND name = ?",
+          [m.team_id, m.name]
+        )
+      } catch { /* best effort */ }
+    }
+  }
+
   /** Run a single check for stale busy members. */
   async check(): Promise<void> {
+    await this.cleanupStaleWorktrees()
     if (this.ttlMs === 0) return
 
     const cutoff = Date.now() - this.ttlMs
@@ -70,10 +100,9 @@ export class Watchdog {
     }
   }
 
-  /** Start the periodic check. */
+  /** Start the periodic check. Runs stale worktree GC regardless of TTL setting. */
   start(): void {
     if (this.timer) return
-    if (this.ttlMs === 0) return
     this.timer = setInterval(() => this.check(), this.checkIntervalMs)
   }