@hueyexe/opencode-ensemble 0.4.0 → 0.5.0

package/README.md

@@ -187,6 +187,28 @@ OPENCODE_ENSEMBLE_TIMEOUT=3600000
 OPENCODE_ENSEMBLE_TIMEOUT=0
 ```
 
+### Best practices
+
+- Start with 2-4 teammates for most tasks. More agents means more coordination overhead.
+- Give each teammate 3-5 specific, self-contained tasks. Vague prompts produce vague results.
+- Start with research before implementation — spawn an explore agent first to understand the codebase, then spawn build agents with that context.
+- Use `worktree: false` for read-only agents (research, review, code analysis). They don't need file isolation.
+- Use `plan_approval: true` for risky changes — the teammate sends a plan first, you review and approve before they write any code.
+- Let the lead coordinate. Don't micromanage teammates — they message you when done or when they're blocked.
+- After spawning, tell the user what you've set up and wait for results. Don't poll `team_status` in a loop.
+
+### How this differs from Claude Code agent teams
+
+Claude Code has built-in agent teams. This plugin takes the same coordination model (shared tasks, peer messaging, lead coordination) and adds:
+
+- **Git worktree isolation by default** — each teammate gets their own branch, no merge conflicts between parallel agents
+- **System prompt injection** — the lead's system prompt is updated with team state (member statuses, task progress) so it stays aware across turns
+- **Compaction safety** — team context is preserved when sessions get long and OpenCode compacts the conversation
+- **Team-aware shell environment** — teammate shells get `ENSEMBLE_TEAM`, `ENSEMBLE_MEMBER`, `ENSEMBLE_ROLE`, and `ENSEMBLE_BRANCH` variables
+- **Graceful shutdown** — teammates finish their current work before stopping, with a force flag for emergencies
+- **Plan approval mode** — review teammate plans before they write code, useful for risky or unfamiliar changes
+- **Works today as a plugin** — no waiting for upstream features, install and go
+
 ## Development
 
 ```bash

package/dist/index.js

@@ -1,12 +1,16 @@
 // @bun
 var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, {
       get: all[name],
       enumerable: true,
       configurable: true,
-      set: (newValue) => all[name] = () => newValue
+      set: __exportSetter.bind(all, name)
     });
 };
 
@@ -12331,7 +12335,7 @@ function tool(input) {
 }
 tool.schema = exports_external;
 // src/index.ts
-import path2 from "path";
+import path3 from "path";
 import { mkdirSync } from "fs";
 
 // src/db.ts
@@ -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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hueyexe/opencode-ensemble",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Agent teams for OpenCode — parallel agents with peer-to-peer communication, shared tasks, and coordinated execution",
   "module": "src/index.ts",
   "main": "dist/index.js",
@@ -38,7 +38,7 @@
     "typescript": "^5"
   },
   "dependencies": {
-    "@opencode-ai/plugin": "^1.2.26",
-    "@opencode-ai/sdk": "^1.2.26"
+    "@opencode-ai/plugin": "^1.2.27",
+    "@opencode-ai/sdk": "^1.2.27"
   }
 }

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)

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
 }
 
 /**