@hueyexe/opencode-ensemble 0.4.0 → 0.5.1

package/README.md

@@ -1,21 +1,21 @@
 # OpenCode Ensemble
 
-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.
+Run 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.
+Plugin built on the public OpenCode SDK. No internal dependencies.
 
 ## What actually happens
 
-You ask the agent to do something complex. The agent decides it needs help, creates a team, and spawns teammates. Each teammate gets its own OpenCode session with a fresh context window and a specific task.
+You ask the agent to do something complex. It creates a team, spawns teammates, and they work in parallel. Each teammate runs in its own OpenCode session with a fresh context window.
 
-Here's a real interaction:
+A real interaction:
 
 ```
 You: "Add input validation to all API endpoints and write tests for each one."
 
 The lead agent:
 1. Creates a team called "validation"
-2. Adds tasks to the shared board: one per endpoint
+2. Adds tasks to the shared board, one per endpoint
 3. Spawns 3 teammates:
    - alice: validate user endpoints (POST /users, PUT /users/:id)
    - bob: validate order endpoints (POST /orders, PUT /orders/:id)
@@ -23,7 +23,7 @@ The lead agent:
 4. carol's tasks depend on alice and bob finishing first
 ```
 
-From here, things happen in parallel. Alice and bob work simultaneously in their own sessions. You see toast notifications as they make progress:
+Alice and bob work simultaneously. You see toast notifications as they progress:
 
 ```
 [toast] Teammate alice spawned (build)
@@ -31,18 +31,18 @@ From here, things happen in parallel. Alice and bob work simultaneously in their
 [toast] Teammate carol spawned (build)
 ```
 
-The teammates talk to each other and to the lead:
+Teammates talk to each other and to the lead:
 
 ```
 alice -> lead: "User validation done. Added zod schemas to POST /users and PUT /users/:id."
-bob -> lead: "Order validation done. Found an edge case in PUT /orders/:id — negative quantities were allowed."
+bob -> lead: "Order validation done. Found an edge case in PUT /orders/:id, negative quantities were allowed."
 bob -> alice: "Did you handle email format validation? I want to match the pattern for order contact emails."
-alice -> bob: "Yes, using z.string().email() — see src/validators/user.ts line 12."
+alice -> bob: "Yes, using z.string().email(). See src/validators/user.ts line 12."
 ```
 
-When alice and bob finish, carol's blocked tasks unblock automatically. Carol starts writing tests using the actual validation schemas alice and bob created.
+When alice and bob finish, carol's blocked tasks unblock automatically. Carol starts writing tests using the validation schemas they created.
 
-The lead keeps you updated throughout. You can check on things at any time:
+Check on things at any time:
 
 ```
 You: "How's the team doing?"
@@ -56,7 +56,7 @@ Lead calls team_status:
   Tasks: 5 total (3 completed, 1 in_progress, 1 pending)
 ```
 
-Want to see what carol is actually doing? The lead can switch your view to her session:
+Want to see what carol is doing? The lead can switch your view to her session:
 
 ```
 You: "Show me what carol is working on."
@@ -79,9 +79,9 @@ Lead: "All validation and tests are complete. 5 endpoints validated,
 
 ## Install
 
-Add the plugin to your OpenCode config. This can be project-level or global.
+Add the plugin to your OpenCode config. Project-level or global.
 
-**Project-level** — `opencode.json` in your project root:
+**Project-level** (`opencode.json` in your project root):
 
 ```json
 {
@@ -89,7 +89,7 @@ Add the plugin to your OpenCode config. This can be project-level or global.
 }
 ```
 
-**Global** — `~/.config/opencode/opencode.json`:
+**Global** (`~/.config/opencode/opencode.json`):
 
 ```json
 {
@@ -97,7 +97,7 @@ Add the plugin to your OpenCode config. This can be project-level or global.
 }
 ```
 
-That's it. OpenCode auto-installs npm plugins at startup (cached in `~/.cache/opencode/node_modules/`). No `npm install` or `bun add` needed.
+OpenCode auto-installs npm plugins at startup (cached in `~/.cache/opencode/node_modules/`). No `npm install` needed.
 
 ### Local development
 
@@ -115,15 +115,15 @@ export { default } from "/path/to/opencode-ensemble/src/index.ts"
 
 ## Tools
 
-13 tools total. The lead has all of them. Teammates get 6 (messaging + tasks).
+13 tools. The lead has all of them. Teammates get 6 (messaging + tasks).
 
 **Team lifecycle** (lead only)
 
 | Tool | What it does |
 |------|-------------|
 | `team_create` | Create a team. Caller becomes the lead. |
-| `team_spawn` | Start a new teammate with a task. |
-| `team_shutdown` | Ask a teammate to stop. |
+| `team_spawn` | Start a new teammate with a task. Supports `plan_approval` mode. |
+| `team_shutdown` | Ask a teammate to stop. Supports `force` flag for immediate abort. |
 | `team_cleanup` | Remove the team when done. |
 | `team_status` | See all members, their status, and a task summary. |
 | `team_view` | Switch the TUI to a teammate's session. |
@@ -132,7 +132,7 @@ export { default } from "/path/to/opencode-ensemble/src/index.ts"
 
 | Tool | What it does |
 |------|-------------|
-| `team_message` | Send a direct message to a teammate or the lead. |
+| `team_message` | Send a direct message to a teammate or the lead. Also handles plan approval/rejection. |
 | `team_broadcast` | Message everyone on the team. |
 | `team_results` | Retrieve full message content (messages to lead are truncated on delivery). |
 
@@ -147,28 +147,31 @@ export { default } from "/path/to/opencode-ensemble/src/index.ts"
 
 ## What you see in the TUI
 
-The plugin works within OpenCode's existing TUI. There's no custom team panel (that requires core TUI changes, which are [in progress upstream](https://github.com/sst/opencode)).
+The plugin works within OpenCode's existing TUI. No custom team panel (that requires core TUI changes, which are [in progress upstream](https://github.com/sst/opencode)).
 
-What you do get:
+What you get:
 
 - **Toast notifications** when teammates spawn, finish, error, shut down, or get rate-limited
 - **Working progress toasts** showing who's still active after every status change (e.g. "Working: alice, bob (2/3)")
 - **Rich tool titles** in the sidebar (e.g. "Spawned alice (build)", "Message -> bob", "Task board (3 tasks)")
 - **Session switching** via `team_view` to see any teammate's full chat log
-- **Status checks** via `team_status` for a snapshot of the whole team (also fires a toast)
+- **Status checks** via `team_status` for a snapshot of the whole team
 
-Teammate messages arrive in the lead's session as `[Team message from alice]: ...` blocks. They look like user messages in the TUI because that's how `promptAsync` delivery works. The content is clearly labeled with the sender's name.
+Teammate messages arrive in the lead's session as `[Team message from alice]: ...` blocks. They look like user messages because that's how `promptAsync` delivery works. Content is clearly labeled with the sender's name.
 
 ## Architecture
 
 - **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.
+- **Git worktree isolation**: each teammate gets their own worktree by default, so multiple agents can edit files without conflicts. Opt out with `worktree: false` for read-only agents.
+- **System prompt injection**: the lead's system prompt includes team state (member statuses, task counts) on every LLM call. Teammates get a short role reminder.
+- **Compaction safety**: team context is preserved when OpenCode compacts long conversations
+- **Shell environment**: teammate shells get `ENSEMBLE_TEAM`, `ENSEMBLE_MEMBER`, `ENSEMBLE_ROLE`, and `ENSEMBLE_BRANCH` variables
 - **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, 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
+- **Graceful shutdown**: busy teammates receive a shutdown message and finish their current work. Use `force: true` to abort immediately.
 - **Rate limiting**: token bucket (configurable via `OPENCODE_ENSEMBLE_RATE_LIMIT`, default 10 tokens/sec)
 
 ## Configuration
@@ -187,12 +190,34 @@ OPENCODE_ENSEMBLE_TIMEOUT=3600000
 OPENCODE_ENSEMBLE_TIMEOUT=0
 ```
 
+## Best practices
+
+- Start with 2-3 teammates. More agents means more coordination overhead.
+- Give each teammate specific, self-contained tasks. Vague prompts produce vague results.
+- Spawn an explore agent first to understand the codebase, then spawn build agents with that context.
+- Use `worktree: false` for read-only agents (research, review, code analysis).
+- Use `plan_approval: true` for risky changes. The teammate sends a plan first, you review and approve before they write any code.
+- Don't micromanage. Teammates message you when done or when they're blocked.
+- Don't poll `team_status` in a loop. Wait for messages.
+
+## How this differs from Claude Code agent teams
+
+Same coordination model (shared tasks, peer messaging, lead coordination) with some additions:
+
+- **Git worktree isolation by default**: each teammate gets their own branch, no merge conflicts between parallel agents
+- **System prompt injection**: the lead's system prompt is updated with team state so it stays aware across turns
+- **Compaction safety**: team context is preserved when sessions get long
+- **Team-aware shell environment**: `ENSEMBLE_TEAM`, `ENSEMBLE_MEMBER`, `ENSEMBLE_ROLE`, `ENSEMBLE_BRANCH`
+- **Graceful shutdown**: teammates finish current work before stopping, with a force flag for emergencies
+- **Plan approval mode**: review teammate plans before they write code
+- **Works today as a plugin**: install and go, no upstream changes needed
+
 ## Development
 
 ```bash
 bun install
 bun run typecheck
-bun test             # 144 tests
+bun test             # 286 tests
 bun run build
 ```
 

package/dist/index.js

@@ -1,12 +1,16 @@
 // @bun
 var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, {
       get: all[name],
       enumerable: true,
       configurable: true,
-      set: (newValue) => all[name] = () => newValue
+      set: __exportSetter.bind(all, name)
     });
 };
 
@@ -12331,7 +12335,7 @@ function tool(input) {
 }
 tool.schema = exports_external;
 // src/index.ts
-import path2 from "path";
+import path3 from "path";
 import { mkdirSync } from "fs";
 
 // src/db.ts
@@ -12407,7 +12411,9 @@ var MIGRATIONS = [
   `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;`,
   `ALTER TABLE team_member ADD COLUMN worktree_dir TEXT;
-   ALTER TABLE team_member ADD COLUMN worktree_branch TEXT;`
+   ALTER TABLE team_member ADD COLUMN worktree_branch TEXT;`,
+  `ALTER TABLE team_member ADD COLUMN plan_approval TEXT NOT NULL DEFAULT 'none'
+     CHECK(plan_approval IN ('none', 'pending', 'approved', 'rejected'));`
 ];
 function applyMigrations(db) {
   const { user_version: current } = db.query("PRAGMA user_version").get();
@@ -12727,6 +12733,71 @@ async function notifyWorkingProgress(client, db, teamId) {
   } catch {}
 }
 
+// src/system-prompt.ts
+var STATUS_DISPLAY = {
+  busy: "working",
+  ready: "idle",
+  shutdown_requested: "shutting down",
+  shutdown: "shut down",
+  error: "error"
+};
+function buildLeadSystemPrompt(db, teamId) {
+  const team = db.query("SELECT name FROM team WHERE id = ?").get(teamId);
+  if (!team)
+    return "";
+  const members = db.query("SELECT name, status FROM team_member WHERE team_id = ?").all(teamId);
+  const taskCounts = db.query("SELECT status, COUNT(*) as count FROM team_task WHERE team_id = ? GROUP BY status").all(teamId);
+  const countMap = {};
+  for (const row of taskCounts) {
+    countMap[row.status] = row.count;
+  }
+  const completed = countMap["completed"] ?? 0;
+  const inProgress = countMap["in_progress"] ?? 0;
+  const pending = countMap["pending"] ?? 0;
+  const memberList = members.map((m) => `${m.name} [${STATUS_DISPLAY[m.status] ?? m.status}]`).join(", ");
+  const teammateLine = members.length > 0 ? `Teammates: ${memberList}` : "Teammates: none";
+  return [
+    `You are leading team "${team.name}" with ${members.length} active teammates.`,
+    teammateLine,
+    `Tasks: ${completed} completed, ${inProgress} in progress, ${pending} pending`,
+    "",
+    "Teammates work asynchronously and message you when done.",
+    "Do NOT poll team_status or team_tasks_list repeatedly \u2014 wait for messages.",
+    "After spawning teammates, tell the user what you've set up and wait.",
+    "When all teammates finish, summarize results and suggest next steps."
+  ].join(`
+`);
+}
+function buildTeammateSystemPrompt(db, teamId, memberName) {
+  const team = db.query("SELECT name FROM team WHERE id = ?").get(teamId);
+  if (!team)
+    return "";
+  return `You are "${memberName}", a teammate in team "${team.name}". Use team_message to communicate.`;
+}
+function buildTeamCompactionContext(db, teamId, role, memberName) {
+  const team = db.query("SELECT name FROM team WHERE id = ?").get(teamId);
+  if (!team)
+    return "";
+  const members = db.query("SELECT name, status FROM team_member WHERE team_id = ?").all(teamId);
+  const taskCounts = db.query("SELECT status, COUNT(*) as count FROM team_task WHERE team_id = ? GROUP BY status").all(teamId);
+  const countMap = {};
+  for (const row of taskCounts) {
+    countMap[row.status] = row.count;
+  }
+  const completed = countMap["completed"] ?? 0;
+  const inProgress = countMap["in_progress"] ?? 0;
+  const pending = countMap["pending"] ?? 0;
+  const roleLine = role === "lead" ? `[Team Context] You are the lead of team "${team.name}".` : `[Team Context] You are a teammate named "${memberName}" in team "${team.name}".`;
+  const memberList = members.map((m) => `${m.name} (${STATUS_DISPLAY[m.status] ?? m.status})`).join(", ");
+  const membersLine = members.length > 0 ? `Members: ${memberList}` : "Members: none";
+  return [
+    roleLine,
+    membersLine,
+    `Tasks: ${completed} completed, ${inProgress} in progress, ${pending} pending`
+  ].join(`
+`);
+}
+
 // src/types.ts
 function findTeamBySession(db, registry2, sessionId) {
   const entry = registry2.getBySession(sessionId);
@@ -12767,6 +12838,7 @@ async function executeTeamCreate(deps, args, sessionId) {
 }
 
 // src/tools/team-spawn.ts
+import path2 from "path";
 async function executeTeamSpawn(deps, args, sessionId) {
   const nameError = validateMemberName(args.name);
   if (nameError)
@@ -12780,6 +12852,7 @@ async function executeTeamSpawn(deps, args, sessionId) {
   if (existing)
     throw new Error(`Teammate "${args.name}" already exists in team "${teamInfo.teamName}"`);
   const useWorktree = args.worktree !== false;
+  const usePlanApproval = args.plan_approval === true;
   let worktreeDir = null;
   let worktreeBranch = null;
   if (useWorktree) {
@@ -12827,9 +12900,10 @@ async function executeTeamSpawn(deps, args, sessionId) {
     }
     throw new Error("Failed to create teammate session");
   }
+  const planApproval = usePlanApproval ? "pending" : "none";
   const now = Date.now();
-  deps.db.run(`INSERT INTO team_member (team_id, name, session_id, agent, status, execution_status, model, prompt, 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.db.run(`INSERT INTO team_member (team_id, name, session_id, agent, status, execution_status, model, prompt, worktree_dir, worktree_branch, plan_approval, time_created, time_updated)
+     VALUES (?, ?, ?, ?, 'busy', 'starting', ?, ?, ?, ?, ?, ?, ?)`, [teamInfo.teamId, args.name, childSessionId, args.agent, args.model ?? null, args.prompt, worktreeDir, worktreeBranch, planApproval, now, now]);
   deps.registry.register(teamInfo.teamId, args.name, childSessionId);
   const context = [
     `You are "${args.name}", a teammate in team "${teamInfo.teamName}".`,
@@ -12838,7 +12912,21 @@ async function executeTeamSpawn(deps, args, sessionId) {
   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 (usePlanApproval) {
+    context.push("", "IMPORTANT: You are in PLAN MODE.", "Read and explore the codebase, then send your implementation plan to the lead via team_message.", "Do NOT write or modify any files until the lead approves your plan.", "Wait for the lead's approval message before proceeding with implementation.");
+  }
+  context.push("", "Tools available to you:", "- team_message: send a message to the lead or another teammate", "- team_broadcast: send a message to all team members", "- team_tasks_list: view the shared team task board", "- team_tasks_add: add tasks to the shared board", "- team_tasks_complete: mark a task complete on the shared board", "- team_claim: claim a pending task from the shared board", "", "When you finish your task:", "1. If you claimed a task, mark it complete using team_tasks_complete.", "2. Send ONE message to the lead with your findings using team_message.", "3. STOP. Do not send follow-up confirmations, status updates, or 'standing by' messages.", "", "If you are blocked, send ONE message to the lead describing the specific blocker.", "", "Your plain text output is NOT visible to the team. You MUST use team_message to communicate.");
+  try {
+    const agentsPath = path2.join(deps.directory, "AGENTS.md");
+    const file2 = Bun.file(agentsPath);
+    if (await file2.exists()) {
+      const content = await file2.text();
+      const truncated = content.length > 2000 ? content.slice(0, 2000) + `
+...(truncated)` : content;
+      context.push("", "Project guidelines (from AGENTS.md):", truncated);
+    }
+  } catch {}
+  context.push("", "Your task:", args.prompt);
   if (args.claim_task) {
     context.push("", `You have been assigned task ${args.claim_task}. Mark it complete when done.`);
   }
@@ -12863,7 +12951,8 @@ async function executeTeamSpawn(deps, args, sessionId) {
     throw new Error(`Failed to send initial prompt to teammate "${args.name}": ${err instanceof Error ? err.message : String(err)}`);
   }
   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 ? "..." : ""}`;
+  const planInfo = usePlanApproval ? " [plan mode \u2014 will send plan for approval]" : "";
+  return `Teammate "${args.name}" spawned (agent: ${args.agent})${branchInfo}${planInfo}. They are working on: ${args.prompt.slice(0, 120)}${args.prompt.length > 120 ? "..." : ""}`;
 }
 
 // src/tools/team-message.ts
@@ -12875,20 +12964,40 @@ async function executeTeamMessage(deps, args, sessionId) {
   const recipientSessionId = resolveRecipientSession(deps.db, deps.registry, teamInfo.teamId, args.to);
   if (!recipientSessionId)
     throw new Error(`Recipient "${args.to}" not found in team "${teamInfo.teamName}"`);
+  let messageText = args.text;
+  if (args.approve || args.reject) {
+    if (args.approve && args.reject) {
+      throw new Error("Cannot both approve and reject a plan.");
+    }
+    if (teamInfo.role !== "lead") {
+      throw new Error("Only the lead can approve or reject plans.");
+    }
+    const recipient = deps.db.query("SELECT plan_approval FROM team_member WHERE team_id = ? AND name = ?").get(teamInfo.teamId, args.to);
+    if (!recipient || recipient.plan_approval !== "pending") {
+      throw new Error(`Recipient "${args.to}" is not in plan approval mode (plan_approval is not pending).`);
+    }
+    if (args.approve) {
+      deps.db.run("UPDATE team_member SET plan_approval = 'approved', time_updated = ? WHERE team_id = ? AND name = ?", [Date.now(), teamInfo.teamId, args.to]);
+      messageText = `[Plan Approved] ${args.text}`;
+    } else {
+      deps.db.run("UPDATE team_member SET plan_approval = 'rejected', time_updated = ? WHERE team_id = ? AND name = ?", [Date.now(), teamInfo.teamId, args.to]);
+      messageText = `[Plan Rejected: ${args.reject}] ${args.text}`;
+    }
+  }
   const msgId = sendMessage(deps.db, {
     teamId: teamInfo.teamId,
     from: senderName,
     to: args.to,
-    content: args.text
+    content: messageText
   });
   const isToLead = args.to === "lead";
   const MAX_LEAD_MSG = 500;
   let deliveryText;
-  if (isToLead && args.text.length > MAX_LEAD_MSG) {
-    const truncated = args.text.slice(0, MAX_LEAD_MSG);
+  if (isToLead && messageText.length > MAX_LEAD_MSG) {
+    const truncated = messageText.slice(0, MAX_LEAD_MSG);
     deliveryText = `[Team message from ${senderName}]: ${truncated}... (use team_results to read full message)`;
   } else {
-    deliveryText = `[Team message from ${senderName}]: ${args.text}`;
+    deliveryText = `[Team message from ${senderName}]: ${messageText}`;
   }
   await deps.client.session.promptAsync({
     path: { id: recipientSessionId },
@@ -12949,29 +13058,42 @@ async function executeTeamShutdown(deps, args, sessionId) {
     throw new Error(`Teammate "${args.member}" not found in team "${teamInfo.teamName}"`);
   if (member.status === "shutdown")
     throw new Error(`Teammate "${args.member}" is already shut down`);
-  deps.db.run("UPDATE team_member SET status = 'shutdown_requested', time_updated = ? WHERE team_id = ? AND name = ?", [Date.now(), teamInfo.teamId, args.member]);
-  try {
-    await deps.client.session.abort({ path: { id: member.session_id } });
-  } catch {
-    try {
-      await deps.client.tui.showToast({
-        title: "Team",
-        message: `Failed to abort ${args.member} session \u2014 will rely on event hook`,
-        variant: "warning",
-        duration: 4000
-      });
-    } catch {}
+  const force = args.force ?? false;
+  if (member.status === "shutdown_requested") {
+    await abortAndShutdown(deps, teamInfo.teamId, args.member, member.session_id);
+    const branchInfo = member.worktree_branch ? ` Changes on branch: ${member.worktree_branch}` : "";
+    return `Force shut down "${args.member}".${branchInfo}`;
   }
+  let isIdle = false;
   try {
     const statuses = await deps.client.session.status();
     const sessionStatus = statuses.data?.[member.session_id];
-    if (!sessionStatus || sessionStatus.type === "idle") {
-      deps.db.run("UPDATE team_member SET status = 'shutdown', execution_status = 'idle', time_updated = ? WHERE team_id = ? AND name = ?", [Date.now(), teamInfo.teamId, args.member]);
-      const branchInfo = member.worktree_branch ? ` Changes on branch: ${member.worktree_branch}` : "";
-      return `Teammate "${args.member}" has been shut down.${branchInfo}`;
-    }
+    isIdle = !sessionStatus || sessionStatus.type === "idle";
+  } catch {}
+  if (isIdle || force) {
+    await abortAndShutdown(deps, teamInfo.teamId, args.member, member.session_id);
+    const branchInfo = member.worktree_branch ? ` Changes on branch: ${member.worktree_branch}` : "";
+    return `Teammate "${args.member}" has been shut down.${branchInfo}`;
+  }
+  try {
+    await deps.client.session.promptAsync({
+      path: { id: member.session_id },
+      body: {
+        parts: [{
+          type: "text",
+          text: `[Shutdown requested]: The lead has requested you shut down. Finish your current task, send your final findings to the lead via team_message, then stop.`
+        }]
+      }
+    });
   } catch {}
-  return `Shutdown requested for ${args.member}. Will complete when current work finishes.`;
+  deps.db.run("UPDATE team_member SET status = 'shutdown_requested', time_updated = ? WHERE team_id = ? AND name = ?", [Date.now(), teamInfo.teamId, args.member]);
+  return `Shutdown requested for ${args.member}. They will finish current work and shut down. Call team_shutdown with force: true to abort immediately.`;
+}
+async function abortAndShutdown(deps, teamId, memberName, sessionId) {
+  try {
+    await deps.client.session.abort({ path: { id: sessionId } });
+  } catch {}
+  deps.db.run("UPDATE team_member SET status = 'shutdown', execution_status = 'idle', time_updated = ? WHERE team_id = ? AND name = ?", [Date.now(), teamId, memberName]);
 }
 
 // src/tools/team-cleanup.ts
@@ -13140,7 +13262,7 @@ async function executeTeamStatus(deps, sessionId) {
     return "No changes since last check.";
   }
   lastCallTime.set(teamInfo.teamId, now);
-  const members = deps.db.query("SELECT name, session_id, agent, status, execution_status, worktree_branch FROM team_member WHERE team_id = ? ORDER BY time_created ASC").all(teamInfo.teamId);
+  const members = deps.db.query("SELECT name, session_id, agent, status, execution_status, worktree_branch, plan_approval FROM team_member WHERE team_id = ? ORDER BY time_created ASC").all(teamInfo.teamId);
   const tasks = deps.db.query("SELECT status FROM team_task WHERE team_id = ?").all(teamInfo.teamId);
   const lines = [];
   lines.push(`Team: ${teamInfo.teamName} (you are the ${teamInfo.role})`);
@@ -13152,7 +13274,8 @@ async function executeTeamStatus(deps, sessionId) {
     for (const m of members) {
       const statusIcon = m.status === "busy" ? "working" : m.status === "ready" ? "idle" : m.status;
       const branch = m.worktree_branch ? `  branch: ${m.worktree_branch}` : "";
-      lines.push(`  ${m.name}  [${statusIcon}]  agent: ${m.agent}${branch}  session: ${m.session_id}`);
+      const plan = m.plan_approval !== "none" ? `, plan: ${m.plan_approval}` : "";
+      lines.push(`  ${m.name}  [${statusIcon}${plan}]  agent: ${m.agent}${branch}  session: ${m.session_id}`);
     }
   }
   if (tasks.length > 0) {
@@ -13332,12 +13455,12 @@ var DEFAULT_WATCHDOG_TTL_MS = 30 * 60 * 1000;
 var DEFAULT_WATCHDOG_CHECK_MS = 60 * 1000;
 var plugin = async (input) => {
   const dbPath = getDbPath();
-  mkdirSync(path2.dirname(dbPath), { recursive: true });
+  mkdirSync(path3.dirname(dbPath), { recursive: true });
   const db = createDb(dbPath);
   const registry2 = new MemberRegistry;
   const tracker = new DescendantTracker;
   const client = input.client;
-  const deps = { db, registry: registry2, tracker, client };
+  const deps = { db, registry: registry2, tracker, client, directory: input.directory };
   const recovery = await recoverStaleMembers(db, client);
   if (recovery.interrupted > 0) {
     const members = db.query("SELECT tm.team_id, tm.name, tm.session_id FROM team_member tm JOIN team t ON tm.team_id = t.id WHERE t.status = 'active'").all();
@@ -13412,6 +13535,38 @@ var plugin = async (input) => {
         }
       }
     },
+    "experimental.chat.system.transform": async (input2, output) => {
+      if (!input2.sessionID)
+        return;
+      const teamInfo = findTeamBySession(db, registry2, input2.sessionID);
+      if (!teamInfo)
+        return;
+      const prompt = teamInfo.role === "lead" ? buildLeadSystemPrompt(db, teamInfo.teamId) : buildTeammateSystemPrompt(db, teamInfo.teamId, teamInfo.memberName);
+      output.system.push(prompt);
+    },
+    "experimental.session.compacting": async (input2, output) => {
+      const teamInfo = findTeamBySession(db, registry2, input2.sessionID);
+      if (!teamInfo)
+        return;
+      const context = buildTeamCompactionContext(db, teamInfo.teamId, teamInfo.role, teamInfo.memberName);
+      output.context.push(context);
+    },
+    "shell.env": async (input2, output) => {
+      if (!input2.sessionID)
+        return;
+      const teamInfo = findTeamBySession(db, registry2, input2.sessionID);
+      if (!teamInfo)
+        return;
+      output.env.ENSEMBLE_TEAM = teamInfo.teamName;
+      output.env.ENSEMBLE_ROLE = teamInfo.role;
+      if (teamInfo.memberName) {
+        output.env.ENSEMBLE_MEMBER = teamInfo.memberName;
+        const member = db.query("SELECT worktree_branch FROM team_member WHERE team_id = ? AND name = ?").get(teamInfo.teamId, teamInfo.memberName);
+        if (member?.worktree_branch) {
+          output.env.ENSEMBLE_BRANCH = member.worktree_branch;
+        }
+      }
+    },
     tool: {
       team_create: tool({
         description: "Create a new agent team. You become the team lead. Use this before spawning teammates.",
@@ -13432,7 +13587,8 @@ var 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)")
+          worktree: tool.schema.boolean().default(true).describe("Create a git worktree for file isolation (default: true, set false for read-only agents)"),
+          plan_approval: tool.schema.boolean().default(false).describe("Require teammate to send a plan for approval before writing files (default: false)")
         },
         async execute(args, ctx) {
           const result = await executeTeamSpawn(deps, args, ctx.sessionID);
@@ -13444,7 +13600,9 @@ var plugin = async (input) => {
         description: "Send a message to a specific teammate or to the lead. Use 'lead' to message the team lead.",
         args: {
           to: tool.schema.string().describe("Recipient name ('lead' or teammate name)"),
-          text: tool.schema.string().describe("Message content (max 10KB)")
+          text: tool.schema.string().describe("Message content (max 10KB)"),
+          approve: tool.schema.boolean().optional().describe("Approve a teammate's plan (only when recipient has plan_approval='pending')"),
+          reject: tool.schema.string().optional().describe("Reject a teammate's plan with reason (only when recipient has plan_approval='pending')")
         },
         async execute(args, ctx) {
           const result = await executeTeamMessage(deps, args, ctx.sessionID);
@@ -13523,9 +13681,10 @@ var plugin = async (input) => {
         }
       }),
       team_shutdown: tool({
-        description: "Request a teammate to shut down. The teammate finishes current work then stops.",
+        description: "Request a teammate to shut down. The teammate finishes current work then stops. " + "Pass force: true to abort immediately without waiting.",
         args: {
-          member: tool.schema.string().describe("Teammate name to shut down")
+          member: tool.schema.string().describe("Teammate name to shut down"),
+          force: tool.schema.boolean().default(false).describe("Force immediate abort without waiting for current work to finish")
         },
         async execute(args, ctx) {
           const result = await executeTeamShutdown(deps, args, ctx.sessionID);
@@ -13549,9 +13708,10 @@ var plugin = async (input) => {
         args: {},
         async execute(_args, ctx) {
           const result = await executeTeamStatus(deps, ctx.sessionID);
-          const members = deps.db.query("SELECT status FROM team_member WHERE team_id IN (SELECT id FROM team WHERE lead_session_id = ? OR id IN (SELECT team_id FROM team_member WHERE session_id = ?))").all(ctx.sessionID, ctx.sessionID);
-          const busy = members.filter((m) => m.status === "busy").length;
-          ctx.metadata({ title: `Team: ${members.length} members (${busy} working)` });
+          const statusMap = { busy: "working", ready: "idle", shutdown_requested: "stopping", shutdown: "done", error: "error" };
+          const members = deps.db.query("SELECT name, status FROM team_member WHERE team_id IN (SELECT id FROM team WHERE lead_session_id = ? OR id IN (SELECT team_id FROM team_member WHERE session_id = ?))").all(ctx.sessionID, ctx.sessionID);
+          const summary = members.map((m) => `${m.name}: ${statusMap[m.status] ?? m.status}`).join(", ");
+          ctx.metadata({ title: summary || "No teammates" });
           return result;
         }
       }),

package/package.json

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

package/src/index.ts

@@ -7,6 +7,8 @@ import { recoverStaleMembers, recoverUndeliveredMessages, recoverOrphanedWorktre
 import { MemberRegistry, DescendantTracker } from "./state"
 import { handleSessionStatusEvent, handleSessionCreatedEvent, checkToolIsolation } from "./hooks"
 import { notifyTeamEvent, notifyWorkingProgress } from "./notify"
+import { buildLeadSystemPrompt, buildTeammateSystemPrompt, buildTeamCompactionContext } from "./system-prompt"
+import { findTeamBySession } from "./types"
 import { executeTeamCreate } from "./tools/team-create"
 import { executeTeamSpawn } from "./tools/team-spawn"
 import { executeTeamMessage } from "./tools/team-message"
@@ -47,7 +49,7 @@ const plugin: Plugin = async (input) => {
 
   // Build shared tool dependencies
   const client = input.client as unknown as PluginClient
-  const deps: ToolDeps = { db, registry, tracker, client }
+  const deps: ToolDeps = { db, registry, tracker, client, directory: input.directory }
 
   // Run recovery on init — mark stale busy members as error + abort orphaned sessions
   const recovery = await recoverStaleMembers(db, client)
@@ -152,6 +154,42 @@ const plugin: Plugin = async (input) => {
       }
     },
 
+    // System prompt injection — keeps lead aware of team state, reminds teammates of role
+    "experimental.chat.system.transform": async (input, output) => {
+      if (!input.sessionID) return
+      const teamInfo = findTeamBySession(db, registry, input.sessionID)
+      if (!teamInfo) return
+      const prompt = teamInfo.role === "lead"
+        ? buildLeadSystemPrompt(db, teamInfo.teamId)
+        : buildTeammateSystemPrompt(db, teamInfo.teamId, teamInfo.memberName!)
+      output.system.push(prompt)
+    },
+
+    // Compaction safety — preserves team context when sessions get long
+    "experimental.session.compacting": async (input, output) => {
+      const teamInfo = findTeamBySession(db, registry, input.sessionID)
+      if (!teamInfo) return
+      const context = buildTeamCompactionContext(db, teamInfo.teamId, teamInfo.role, teamInfo.memberName)
+      output.context.push(context)
+    },
+
+    // Team-aware shell environment for scripts and hooks
+    "shell.env": async (input, output) => {
+      if (!input.sessionID) return
+      const teamInfo = findTeamBySession(db, registry, input.sessionID)
+      if (!teamInfo) return
+      output.env.ENSEMBLE_TEAM = teamInfo.teamName
+      output.env.ENSEMBLE_ROLE = teamInfo.role
+      if (teamInfo.memberName) {
+        output.env.ENSEMBLE_MEMBER = teamInfo.memberName
+        const member = db.query("SELECT worktree_branch FROM team_member WHERE team_id = ? AND name = ?")
+          .get(teamInfo.teamId, teamInfo.memberName) as { worktree_branch: string | null } | null
+        if (member?.worktree_branch) {
+          output.env.ENSEMBLE_BRANCH = member.worktree_branch
+        }
+      }
+    },
+
     // Register all team tools
     tool: {
       team_create: tool({
@@ -177,6 +215,7 @@ const plugin: Plugin = async (input) => {
           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)"),
+          plan_approval: tool.schema.boolean().default(false).describe("Require teammate to send a plan for approval before writing files (default: false)"),
         },
         async execute(args, ctx) {
           const result = await executeTeamSpawn(deps, args, ctx.sessionID)
@@ -190,6 +229,8 @@ const plugin: Plugin = async (input) => {
         args: {
           to: tool.schema.string().describe("Recipient name ('lead' or teammate name)"),
           text: tool.schema.string().describe("Message content (max 10KB)"),
+          approve: tool.schema.boolean().optional().describe("Approve a teammate's plan (only when recipient has plan_approval='pending')"),
+          reject: tool.schema.string().optional().describe("Reject a teammate's plan with reason (only when recipient has plan_approval='pending')"),
         },
         async execute(args, ctx) {
           const result = await executeTeamMessage(deps, args, ctx.sessionID)
@@ -274,9 +315,11 @@ const plugin: Plugin = async (input) => {
       }),
 
       team_shutdown: tool({
-        description: "Request a teammate to shut down. The teammate finishes current work then stops.",
+        description: "Request a teammate to shut down. The teammate finishes current work then stops. " +
+          "Pass force: true to abort immediately without waiting.",
         args: {
           member: tool.schema.string().describe("Teammate name to shut down"),
+          force: tool.schema.boolean().default(false).describe("Force immediate abort without waiting for current work to finish"),
         },
         async execute(args, ctx) {
           const result = await executeTeamShutdown(deps, args, ctx.sessionID)
@@ -303,9 +346,10 @@ const plugin: Plugin = async (input) => {
         args: {},
         async execute(_args, ctx) {
           const result = await executeTeamStatus(deps, ctx.sessionID)
-          const members = deps.db.query("SELECT status FROM team_member WHERE team_id IN (SELECT id FROM team WHERE lead_session_id = ? OR id IN (SELECT team_id FROM team_member WHERE session_id = ?))").all(ctx.sessionID, ctx.sessionID) as Array<{ status: string }>
-          const busy = members.filter(m => m.status === "busy").length
-          ctx.metadata({ title: `Team: ${members.length} members (${busy} working)` })
+          const statusMap: Record<string, string> = { busy: "working", ready: "idle", shutdown_requested: "stopping", shutdown: "done", error: "error" }
+          const members = deps.db.query("SELECT name, status FROM team_member WHERE team_id IN (SELECT id FROM team WHERE lead_session_id = ? OR id IN (SELECT team_id FROM team_member WHERE session_id = ?))").all(ctx.sessionID, ctx.sessionID) as Array<{ name: string; status: string }>
+          const summary = members.map(m => `${m.name}: ${statusMap[m.status] ?? m.status}`).join(", ")
+          ctx.metadata({ title: summary || "No teammates" })
           return result
         },
       }),

package/src/schema.ts

@@ -73,6 +73,9 @@ export const MIGRATIONS: string[] = [
   // 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;`,
+  // Migration 4: Add plan_approval column to team_member for plan-before-build workflow
+  `ALTER TABLE team_member ADD COLUMN plan_approval TEXT NOT NULL DEFAULT 'none'
+     CHECK(plan_approval IN ('none', 'pending', 'approved', 'rejected'));`,
 ]
 
 /**

package/src/system-prompt.ts

@@ -0,0 +1,111 @@
+import type { Database } from "bun:sqlite"
+
+/** Status display mapping from DB status to human-readable label. */
+const STATUS_DISPLAY: Record<string, string> = {
+  busy: "working",
+  ready: "idle",
+  shutdown_requested: "shutting down",
+  shutdown: "shut down",
+  error: "error",
+}
+
+/**
+ * Build the system prompt injected into the lead's session.
+ * Includes team name, member statuses, task counts, and anti-polling guidance.
+ */
+export function buildLeadSystemPrompt(db: Database, teamId: string): string {
+  const team = db.query("SELECT name FROM team WHERE id = ?").get(teamId) as { name: string } | null
+  if (!team) return ""
+
+  const members = db.query("SELECT name, status FROM team_member WHERE team_id = ?").all(teamId) as Array<{ name: string; status: string }>
+
+  const taskCounts = db.query(
+    "SELECT status, COUNT(*) as count FROM team_task WHERE team_id = ? GROUP BY status",
+  ).all(teamId) as Array<{ status: string; count: number }>
+
+  const countMap: Record<string, number> = {}
+  for (const row of taskCounts) {
+    countMap[row.status] = row.count
+  }
+
+  const completed = countMap["completed"] ?? 0
+  const inProgress = countMap["in_progress"] ?? 0
+  const pending = countMap["pending"] ?? 0
+
+  const memberList = members
+    .map((m) => `${m.name} [${STATUS_DISPLAY[m.status] ?? m.status}]`)
+    .join(", ")
+
+  const teammateLine = members.length > 0
+    ? `Teammates: ${memberList}`
+    : "Teammates: none"
+
+  return [
+    `You are leading team "${team.name}" with ${members.length} active teammates.`,
+    teammateLine,
+    `Tasks: ${completed} completed, ${inProgress} in progress, ${pending} pending`,
+    "",
+    "Teammates work asynchronously and message you when done.",
+    "Do NOT poll team_status or team_tasks_list repeatedly — wait for messages.",
+    "After spawning teammates, tell the user what you've set up and wait.",
+    "When all teammates finish, summarize results and suggest next steps.",
+  ].join("\n")
+}
+
+/**
+ * Build the system prompt injected into a teammate's session.
+ * Short role reminder with name, team name, and communication tool.
+ */
+export function buildTeammateSystemPrompt(db: Database, teamId: string, memberName: string): string {
+  const team = db.query("SELECT name FROM team WHERE id = ?").get(teamId) as { name: string } | null
+  if (!team) return ""
+
+  return `You are "${memberName}", a teammate in team "${team.name}". Use team_message to communicate.`
+}
+
+/**
+ * Build a concise context string for compaction.
+ * Includes team name, member statuses, task progress, and role statement.
+ */
+export function buildTeamCompactionContext(
+  db: Database,
+  teamId: string,
+  role: "lead" | "member",
+  memberName?: string,
+): string {
+  const team = db.query("SELECT name FROM team WHERE id = ?").get(teamId) as { name: string } | null
+  if (!team) return ""
+
+  const members = db.query("SELECT name, status FROM team_member WHERE team_id = ?").all(teamId) as Array<{ name: string; status: string }>
+
+  const taskCounts = db.query(
+    "SELECT status, COUNT(*) as count FROM team_task WHERE team_id = ? GROUP BY status",
+  ).all(teamId) as Array<{ status: string; count: number }>
+
+  const countMap: Record<string, number> = {}
+  for (const row of taskCounts) {
+    countMap[row.status] = row.count
+  }
+
+  const completed = countMap["completed"] ?? 0
+  const inProgress = countMap["in_progress"] ?? 0
+  const pending = countMap["pending"] ?? 0
+
+  const roleLine = role === "lead"
+    ? `[Team Context] You are the lead of team "${team.name}".`
+    : `[Team Context] You are a teammate named "${memberName}" in team "${team.name}".`
+
+  const memberList = members
+    .map((m) => `${m.name} (${STATUS_DISPLAY[m.status] ?? m.status})`)
+    .join(", ")
+
+  const membersLine = members.length > 0
+    ? `Members: ${memberList}`
+    : "Members: none"
+
+  return [
+    roleLine,
+    membersLine,
+    `Tasks: ${completed} completed, ${inProgress} in progress, ${pending} pending`,
+  ].join("\n")
+}

package/src/tools/team-message.ts

@@ -4,10 +4,11 @@ import { sendMessage, markDelivered } from "../messaging"
 
 /**
  * Execute the team_message tool. Sends a direct message to a teammate or lead.
+ * Optionally approves or rejects a teammate's plan (lead only).
  */
 export async function executeTeamMessage(
   deps: ToolDeps,
-  args: { to: string; text: string },
+  args: { to: string; text: string; approve?: boolean; reject?: string },
   sessionId: string,
 ): Promise<string> {
   const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId)
@@ -18,22 +19,52 @@ export async function executeTeamMessage(
   const recipientSessionId = resolveRecipientSession(deps.db, deps.registry, teamInfo.teamId, args.to)
   if (!recipientSessionId) throw new Error(`Recipient "${args.to}" not found in team "${teamInfo.teamName}"`)
 
+  // Handle plan approval/rejection
+  let messageText = args.text
+  if (args.approve || args.reject) {
+    if (args.approve && args.reject) {
+      throw new Error("Cannot both approve and reject a plan.")
+    }
+    if (teamInfo.role !== "lead") {
+      throw new Error("Only the lead can approve or reject plans.")
+    }
+    const recipient = deps.db.query(
+      "SELECT plan_approval FROM team_member WHERE team_id = ? AND name = ?"
+    ).get(teamInfo.teamId, args.to) as { plan_approval: string } | null
+    if (!recipient || recipient.plan_approval !== "pending") {
+      throw new Error(`Recipient "${args.to}" is not in plan approval mode (plan_approval is not pending).`)
+    }
+    if (args.approve) {
+      deps.db.run(
+        "UPDATE team_member SET plan_approval = 'approved', time_updated = ? WHERE team_id = ? AND name = ?",
+        [Date.now(), teamInfo.teamId, args.to]
+      )
+      messageText = `[Plan Approved] ${args.text}`
+    } else {
+      deps.db.run(
+        "UPDATE team_member SET plan_approval = 'rejected', time_updated = ? WHERE team_id = ? AND name = ?",
+        [Date.now(), teamInfo.teamId, args.to]
+      )
+      messageText = `[Plan Rejected: ${args.reject}] ${args.text}`
+    }
+  }
+
   const msgId = sendMessage(deps.db, {
     teamId: teamInfo.teamId,
     from: senderName,
     to: args.to,
-    content: args.text,
+    content: messageText,
   })
 
   // Deliver via promptAsync — truncate lead-bound messages over 500 chars
   const isToLead = args.to === "lead"
   const MAX_LEAD_MSG = 500
   let deliveryText: string
-  if (isToLead && args.text.length > MAX_LEAD_MSG) {
-    const truncated = args.text.slice(0, MAX_LEAD_MSG)
+  if (isToLead && messageText.length > MAX_LEAD_MSG) {
+    const truncated = messageText.slice(0, MAX_LEAD_MSG)
     deliveryText = `[Team message from ${senderName}]: ${truncated}... (use team_results to read full message)`
   } else {
-    deliveryText = `[Team message from ${senderName}]: ${args.text}`
+    deliveryText = `[Team message from ${senderName}]: ${messageText}`
   }
 
   await deps.client.session.promptAsync({

package/src/tools/team-shutdown.ts

@@ -3,13 +3,16 @@ import { findTeamBySession } from "../types"
 
 /**
  * Execute the team_shutdown tool. Requests a teammate to shut down.
- * Sets status to shutdown_requested, calls abort, then polls session status.
- * If the session is already idle after abort, transitions directly to shutdown.
- * Otherwise the event hook handles the transition when the session goes idle.
+ *
+ * Graceful negotiation flow:
+ * - If member is already shutdown_requested, treat as force (second call).
+ * - 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.
  */
 export async function executeTeamShutdown(
   deps: ToolDeps,
-  args: { member: string },
+  args: { member: string; force?: boolean },
   sessionId: string,
 ): Promise<string> {
   const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId)
@@ -21,44 +24,72 @@ export async function executeTeamShutdown(
   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`)
 
-  // Set to shutdown_requested
-  deps.db.run(
-    "UPDATE team_member SET status = 'shutdown_requested', time_updated = ? WHERE team_id = ? AND name = ?",
-    [Date.now(), teamInfo.teamId, args.member]
-  )
+  const force = args.force ?? false
 
-  // Call abort on the member's session (best effort)
-  try {
-    await deps.client.session.abort({ path: { id: member.session_id } })
-  } catch {
-    // Abort failed — session may already be gone. Fire a warning toast.
-    try {
-      await deps.client.tui.showToast({
-        title: "Team",
-        message: `Failed to abort ${args.member} session — will rely on event hook`,
-        variant: "warning",
-        duration: 4000,
-      })
-    } catch { /* TUI may not be available */ }
+  // Second call on an already-requested member → force abort
+  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}`
   }
 
-  // Fallback: poll session status after abort. If already idle, transition
-  // directly to shutdown. This handles the case where abort() on an
-  // already-idle session doesn't fire a session.status event.
+  // Determine if member is idle or busy
+  let isIdle = false
   try {
     const statuses = await deps.client.session.status()
     const sessionStatus = statuses.data?.[member.session_id]
-    if (!sessionStatus || sessionStatus.type === "idle") {
-      deps.db.run(
-        "UPDATE team_member SET status = 'shutdown', execution_status = 'idle', time_updated = ? WHERE team_id = ? AND name = ?",
-        [Date.now(), teamInfo.teamId, args.member]
-      )
-      const branchInfo = member.worktree_branch ? ` Changes on branch: ${member.worktree_branch}` : ""
-      return `Teammate "${args.member}" has been shut down.${branchInfo}`
-    }
+    isIdle = !sessionStatus || sessionStatus.type === "idle"
+  } catch {
+    // Status poll failed — assume busy, fall through to graceful path
+  }
+
+  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}`
+  }
+
+  // Busy + not force → graceful: send shutdown message, set shutdown_requested
+  try {
+    await deps.client.session.promptAsync({
+      path: { id: member.session_id },
+      body: {
+        parts: [{
+          type: "text",
+          text: `[Shutdown requested]: The lead has requested you shut down. Finish your current task, send your final findings to the lead via team_message, then stop.`,
+        }],
+      },
+    })
   } catch {
-    // Status poll failed — fall through to eventual consistency
+    // promptAsync failed — best effort
   }
 
-  return `Shutdown requested for ${args.member}. Will complete when current work finishes.`
+  deps.db.run(
+    "UPDATE team_member SET status = 'shutdown_requested', time_updated = ? WHERE team_id = ? AND name = ?",
+    [Date.now(), teamInfo.teamId, args.member],
+  )
+
+  return `Shutdown requested for ${args.member}. They will finish current work and shut down. Call team_shutdown with force: true to abort immediately.`
+}
+
+/**
+ * Abort a member's session and set their status to shutdown.
+ * Best-effort: if abort fails, we still mark them as shutdown.
+ */
+async function abortAndShutdown(
+  deps: ToolDeps,
+  teamId: string,
+  memberName: string,
+  sessionId: string,
+): Promise<void> {
+  try {
+    await deps.client.session.abort({ path: { id: sessionId } })
+  } catch {
+    // Abort failed — session may already be gone
+  }
+
+  deps.db.run(
+    "UPDATE team_member SET status = 'shutdown', execution_status = 'idle', time_updated = ? WHERE team_id = ? AND name = ?",
+    [Date.now(), teamId, memberName],
+  )
 }

package/src/tools/team-spawn.ts

@@ -1,15 +1,17 @@
 import type { ToolDeps } from "../types"
 import { generateId, validateMemberName } from "../util"
 import { findTeamBySession } from "../types"
+import path from "path"
 
 /**
  * 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.
+ * Pass plan_approval: true to require the teammate to send a plan before writing.
  */
 export async function executeTeamSpawn(
   deps: ToolDeps,
-  args: { name: string; agent: string; prompt: string; model?: string; claim_task?: string; worktree?: boolean },
+  args: { name: string; agent: string; prompt: string; model?: string; claim_task?: string; worktree?: boolean; plan_approval?: boolean },
   sessionId: string,
 ): Promise<string> {
   const nameError = validateMemberName(args.name)
@@ -25,6 +27,7 @@ export async function executeTeamSpawn(
   if (existing) throw new Error(`Teammate "${args.name}" already exists in team "${teamInfo.teamName}"`)
 
   const useWorktree = args.worktree !== false
+  const usePlanApproval = args.plan_approval === true
 
   // Create worktree if enabled
   let worktreeDir: string | null = null
@@ -79,11 +82,12 @@ export async function executeTeamSpawn(
   }
 
   // Register in DB
+  const planApproval = usePlanApproval ? "pending" : "none"
   const now = Date.now()
   deps.db.run(
-    `INSERT INTO team_member (team_id, name, session_id, agent, status, execution_status, model, prompt, 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]
+    `INSERT INTO team_member (team_id, name, session_id, agent, status, execution_status, model, prompt, worktree_dir, worktree_branch, plan_approval, time_created, time_updated)
+     VALUES (?, ?, ?, ?, 'busy', 'starting', ?, ?, ?, ?, ?, ?, ?)`,
+    [teamInfo.teamId, args.name, childSessionId, args.agent, args.model ?? null, args.prompt, worktreeDir, worktreeBranch, planApproval, now, now]
   )
 
   // Register in memory
@@ -99,6 +103,17 @@ export async function executeTeamSpawn(
     context.push(`You are working on branch "${worktreeBranch}" in your own worktree. Your changes are isolated from other teammates.`)
   }
 
+  // Plan approval mode — teammate must send plan before writing
+  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:",
@@ -117,6 +132,20 @@ export async function executeTeamSpawn(
     "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.",
+  )
+
+  // Load project AGENTS.md if it exists
+  try {
+    const agentsPath = path.join(deps.directory, "AGENTS.md")
+    const file = Bun.file(agentsPath)
+    if (await file.exists()) {
+      const content = await file.text()
+      const truncated = content.length > 2000 ? content.slice(0, 2000) + "\n...(truncated)" : content
+      context.push("", "Project guidelines (from AGENTS.md):", truncated)
+    }
+  } catch { /* file may not exist or be unreadable */ }
+
+  context.push(
     "",
     "Your task:",
     args.prompt,
@@ -146,5 +175,6 @@ export async function executeTeamSpawn(
   }
 
   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 ? "..." : ""}`
+  const planInfo = usePlanApproval ? " [plan mode — will send plan for approval]" : ""
+  return `Teammate "${args.name}" spawned (agent: ${args.agent})${branchInfo}${planInfo}. They are working on: ${args.prompt.slice(0, 120)}${args.prompt.length > 120 ? "..." : ""}`
 }

package/src/tools/team-status.ts

@@ -24,9 +24,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 FROM team_member WHERE team_id = ? ORDER BY time_created ASC"
+    "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) as Array<{
-    name: string; session_id: string; agent: string; status: string; execution_status: string; worktree_branch: string | null
+    name: string; session_id: string; agent: string; status: string; execution_status: string; worktree_branch: string | null; plan_approval: string
   }>
 
   const tasks = deps.db.query(
@@ -44,7 +44,8 @@ export async function executeTeamStatus(
     for (const m of members) {
       const statusIcon = m.status === "busy" ? "working" : m.status === "ready" ? "idle" : m.status
       const branch = m.worktree_branch ? `  branch: ${m.worktree_branch}` : ""
-      lines.push(`  ${m.name}  [${statusIcon}]  agent: ${m.agent}${branch}  session: ${m.session_id}`)
+      const plan = m.plan_approval !== "none" ? `, plan: ${m.plan_approval}` : ""
+      lines.push(`  ${m.name}  [${statusIcon}${plan}]  agent: ${m.agent}${branch}  session: ${m.session_id}`)
     }
   }
 

package/src/types.ts

@@ -11,6 +11,8 @@ export interface ToolDeps {
   tracker: DescendantTracker
   /** The OpenCode SDK client — used for session.create, promptAsync, abort, etc. */
   client: PluginClient
+  /** The project root directory — used for reading AGENTS.md and other project files. */
+  directory: string
 }
 
 /**