@hueyexe/opencode-ensemble 0.3.1 → 0.5.0

package/src/tools/team-spawn.ts

@@ -1,13 +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 },
+  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)
@@ -22,28 +26,95 @@ export async function executeTeamSpawn(
     .get(teamInfo.teamId, args.name)
   if (existing) throw new Error(`Teammate "${args.name}" already exists in team "${teamInfo.teamName}"`)
 
-  // Create child session via SDK
-  const createResult = await deps.client.session.create({
+  const useWorktree = args.worktree !== false
+  const usePlanApproval = args.plan_approval === true
+
+  // Create worktree if enabled
+  let worktreeDir: string | null = null
+  let worktreeBranch: string | null = null
+
+  if (useWorktree) {
+    const worktreeName = `ensemble-${teamInfo.teamName}-${args.name}`
+    try {
+      const result = await deps.client.worktree.create({ name: worktreeName })
+      if (result.data) {
+        worktreeDir = result.data.directory
+        worktreeBranch = result.data.branch
+      }
+    } catch {
+      // Worktree creation failed — fall back to shared directory with a warning
+      try {
+        await deps.client.tui.showToast({
+          title: "Team",
+          message: `Worktree creation failed for ${args.name}, using shared directory`,
+          variant: "warning",
+          duration: 4000,
+        })
+      } catch { /* TUI may not be available */ }
+    }
+  }
+
+  // Create child session — use worktree directory if available
+  const createOpts: Record<string, unknown> = {
     body: { parentID: sessionId, title: `${args.name} (@${args.agent} teammate)` },
-  })
-  const childSessionId = createResult.data?.id
-  if (!childSessionId) throw new Error("Failed to create teammate session")
+  }
+  if (worktreeDir) {
+    createOpts.directory = worktreeDir
+  }
+
+  let childSessionId: string | undefined
+  try {
+    const createResult = await deps.client.session.create(createOpts as Parameters<typeof deps.client.session.create>[0])
+    childSessionId = createResult.data?.id
+  } catch (err) {
+    // Rollback worktree if session creation failed
+    if (worktreeDir) {
+      try { await deps.client.worktree.remove({ worktreeRemoveInput: { directory: worktreeDir } }) } catch { /* best effort */ }
+    }
+    throw new Error(`Failed to create session for teammate "${args.name}": ${err instanceof Error ? err.message : String(err)}`)
+  }
+
+  if (!childSessionId) {
+    if (worktreeDir) {
+      try { await deps.client.worktree.remove({ worktreeRemoveInput: { directory: worktreeDir } }) } catch { /* best effort */ }
+    }
+    throw new Error("Failed to create teammate session")
+  }
 
   // Register in DB
+  const planApproval = usePlanApproval ? "pending" : "none"
   const now = Date.now()
   deps.db.run(
-    `INSERT INTO team_member (team_id, name, session_id, agent, status, execution_status, model, prompt, time_created, time_updated)
-     VALUES (?, ?, ?, ?, 'busy', 'starting', ?, ?, ?, ?)`,
-    [teamInfo.teamId, args.name, childSessionId, args.agent, args.model ?? null, args.prompt, now, now]
+    `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
   deps.registry.register(teamInfo.teamId, args.name, childSessionId)
 
-  // Build teammate context message per AGENTS.md Teammate Context Message Design
+  // Build teammate context message
   const context = [
     `You are "${args.name}", a teammate in team "${teamInfo.teamName}".`,
     `Your agent type is "${args.agent}".`,
+  ]
+
+  if (worktreeBranch) {
+    context.push(`You are working on branch "${worktreeBranch}" in your own worktree. Your changes are isolated from other teammates.`)
+  }
+
+  // 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:",
     "- team_message: send a message to the lead or another teammate",
@@ -61,10 +132,24 @@ 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,
-  ]
+  )
 
   if (args.claim_task) {
     context.push("", `You have been assigned task ${args.claim_task}. Mark it complete when done.`)
@@ -73,20 +158,23 @@ export async function executeTeamSpawn(
   const contextStr = context.join("\n")
 
   // Fire-and-forget: send prompt to teammate session
-  // OQ-1: confirmed — promptAsync queues when session is busy (verified in live testing)
-  // OQ-10: confirmed — fresh session accepts promptAsync without session.init() (verified in live testing)
   try {
     await deps.client.session.promptAsync({
       path: { id: childSessionId },
       body: { parts: [{ type: "text", text: contextStr }] },
     })
   } catch (err) {
-    // Rollback: clean up DB, registry, and abort the orphaned session
+    // Rollback: clean up DB, registry, session, and worktree
     deps.db.run("DELETE FROM team_member WHERE team_id = ? AND name = ?", [teamInfo.teamId, args.name])
     deps.registry.unregister(childSessionId)
     try { await deps.client.session.abort({ path: { id: childSessionId } }) } catch { /* best effort */ }
+    if (worktreeDir) {
+      try { await deps.client.worktree.remove({ worktreeRemoveInput: { directory: worktreeDir } }) } catch { /* best effort */ }
+    }
     throw new Error(`Failed to send initial prompt to teammate "${args.name}": ${err instanceof Error ? err.message : String(err)}`)
   }
 
-  return `Teammate "${args.name}" spawned (agent: ${args.agent}). They are working on: ${args.prompt.slice(0, 120)}${args.prompt.length > 120 ? "..." : ""}`
+  const branchInfo = worktreeBranch ? ` (branch: ${worktreeBranch})` : ""
+  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 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
+    name: string; session_id: string; agent: string; status: string; execution_status: string; worktree_branch: string | null; plan_approval: string
   }>
 
   const tasks = deps.db.query(
@@ -43,7 +43,9 @@ export async function executeTeamStatus(
     lines.push("Members:")
     for (const m of members) {
       const statusIcon = m.status === "busy" ? "working" : m.status === "ready" ? "idle" : m.status
-      lines.push(`  ${m.name}  [${statusIcon}]  agent: ${m.agent}  session: ${m.session_id}`)
+      const branch = m.worktree_branch ? `  branch: ${m.worktree_branch}` : ""
+      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
 }
 
 /**
@@ -37,6 +39,12 @@ export interface PluginClient {
     }): Promise<unknown>
     selectSession(options: { sessionID?: string }): Promise<unknown>
   }
+  worktree: {
+    create(options: { name?: string; startCommand?: string }): Promise<{ data?: { name: string; branch: string; directory: string } }>
+    remove(options: { worktreeRemoveInput?: { directory: string } }): Promise<unknown>
+    list(): Promise<{ data?: Array<{ name: string; branch: string; directory: string }> }>
+    reset(options: { worktreeResetInput?: { directory: string } }): Promise<unknown>
+  }
 }
 
 /**