pi-teams 0.5.2 → 0.7.2

package/README.md

@@ -23,6 +23,9 @@ pi install npm:pi-teams
 - **Spawn Specialists**: Create agents like "Security Expert" or "Frontend Pro" to handle sub-tasks in parallel.
 - **Shared Task Board**: Keep everyone on the same page with a persistent list of tasks and their status.
 - **Agent Messaging**: Agents can send direct messages to each other and to you (the Team Lead) to report progress.
+- **Broadcast Messaging**: Send a message to the entire team at once for global coordination.
+- **Plan Approval Mode**: Require teammates to submit their implementation plans for lead approval before they touch any code.
+- **Quality Gate Hooks**: Automated shell scripts can run when tasks are completed (e.g., to run tests or linting).
 - **Autonomous Work**: Teammates automatically "wake up," read their instructions, and poll their inboxes for new work while idle.
 - **Beautiful UI**: Optimized vertical splits in `tmux` with clear labels so you always know who is doing what.
 
@@ -44,14 +47,44 @@ You don't need to learn complex code commands. Just talk to Pi in plain English!
 **Pro Tip:** You can specify a different model for a specific teammate!
 > **You:** "Spawn a teammate named 'speed-bot' using 'haiku' to quickly run some benchmarks."
 
+**New: Plan Approval Mode**
+> **You:** "Spawn a teammate named 'refactor-bot' and require plan approval before they make any changes."
+
+**Customize Teammate Model & Thinking**
+> **You:** "Spawn a teammate named 'architect-bot' using 'gpt-4o' with 'high' thinking level for deep reasoning."
+> **You:** "Spawn a teammate named 'frontend-dev' using 'haiku' with 'low' thinking level for quick iterations."
+> **You:** "Spawn a teammate named 'code-reviewer' using 'gpt-4o' with 'medium' thinking level."
+
+You can customize **both** the model and thinking level for each teammate independently:
+- **Model**: Override team's default model for a specific teammate (e.g., `gpt-4o`, `haiku`, `glm-4.7`)
+- **Thinking Level**: Balance speed vs. depth per teammate:
+  - `off`: No thinking blocks (fastest)
+  - `minimal`: Minimal reasoning overhead
+  - `low`: Light reasoning for quick decisions
+  - `medium`: Balanced reasoning (default for most work)
+  - `high`: Extended reasoning for complex problems
+
+This lets you build teams with varied capabilities—fast, lightweight teammates for simple tasks, and powerful, thoughtful teammates for complex work.
+
 ### 3. Assign a Task
 > **You:** "Create a task for security-bot: 'Check the .env.example file for sensitive defaults' and set it to in_progress."
 
-### 4. Send a Message
-> **You:** "Tell security-bot to focus on the 'config/' directory first."
-> *The lead agent uses `send_message` to put an instruction in the teammate's inbox.*
+### 4. Submit and Evaluate a Plan
+Teammates in `planning` mode will use `task_submit_plan`. As the lead, you can then:
+> **You:** "Review refactor-bot's plan for task 5. If it looks good, approve it. If not, reject it with feedback on the test coverage."
+
+### 5. Broadcast a Message
+> **You:** "Broadcast to the entire team: 'The API endpoint has changed to /v2. Please update your work accordingly.'"
 
-### 5. Inter-Agent Communication
+### 6. Automated Hooks
+Add a script at `.pi/team-hooks/task_completed.sh` to run automated checks when any task is finished.
+```bash
+#!/bin/bash
+# Example: Run tests when a task is completed
+npm test
+```
+
+### 7. Inter-Agent Communication
 > Teammates can also talk to each other! For example, a `frontend-bot` can message a `backend-bot` to coordinate on an API schema without your intervention.
 
 ### 6. Check on Progress
@@ -72,7 +105,10 @@ Pi automatically uses these tools when you give instructions like the examples a
 - `read_config`: Get details about the team and its members.
 
 ### Teammates
-- `spawn_teammate`: Launch a new agent into a `tmux` pane with a role and instructions. (Optional: `model`)
+- `spawn_teammate`: Launch a new agent into a `tmux` pane with a role and instructions. (Optional: `model`, `thinking`, `plan_mode_required`)
+  - **`model`**: Specify which AI model this teammate should use (e.g., `gpt-4o`, `haiku`, `glm-4.7`, `glm-5`). If not specified, uses the team's default model. You can mix different models across teammates for cost/performance optimization.
+  - **`thinking`**: Set the agent's thinking level (`off`, `minimal`, `low`, `medium`, `high`). This controls how much time the agent spends reasoning before responding. If not specified, inherited from team/global settings. Different teammates can have different thinking levels.
+  - **`plan_mode_required`**: If true, teammate must submit plans for lead approval before making code changes
 - `check_teammate`: See if a teammate is still running or has unread messages.
 - `force_kill_teammate`: Stop a teammate and remove them from the team.
 - `process_shutdown_approved`: Orderly shutdown for a finished teammate.
@@ -81,18 +117,24 @@ Pi automatically uses these tools when you give instructions like the examples a
 - `task_create`: Create a new task.
 - `task_list`: List all tasks and their current status.
 - `task_get`: Get full details of a specific task.
-- `task_update`: Update a task's status or owner.
+- `task_update`: Update a task's status (pending, planning, in_progress, etc.) or owner.
 
 ### Messaging
 - `send_message`: Send a message to a teammate or lead.
+- `broadcast_message`: Send a message to the entire team.
 - `read_inbox`: Read incoming messages for an agent.
 
+### Task Planning & Approval
+- `task_submit_plan`: For teammates to submit their implementation plans.
+- `task_evaluate_plan`: For the lead to approve or reject a plan (with feedback).
+
 ---
 
 ## 🤖 Automated Behavior
 
 - **Initial Greeting**: When a teammate is spawned, they will automatically send a message saying they've started and are checking their inbox.
 - **Idle Polling**: Teammates check for new messages every 30 seconds if they are idle.
+- **Automated Hooks**: If `.pi/team-hooks/task_completed.sh` exists, it will automatically execute whenever a task status is changed to `completed`.
 - **Context Injection**: Each teammate is given a custom system prompt that defines their role and instructions for the team environment.
 
 ---

package/extensions/index.ts

@@ -60,8 +60,27 @@ export default function (pi: ExtensionAPI) {
   pi.on("before_agent_start", async (event, ctx) => {
     if (isTeammate && firstTurn) {
       firstTurn = false;
+
+      // Get the teammate's model and thinking level from team config for accurate reporting
+      let modelInfo = "";
+      if (teamName) {
+        try {
+          const teamConfig = await teams.readConfig(teamName);
+          const member = teamConfig.members.find(m => m.name === agentName);
+          if (member && member.model) {
+            modelInfo = `\nYou are currently using model: ${member.model}`;
+            if (member.thinking) {
+              modelInfo += ` with thinking level: ${member.thinking}`;
+            }
+            modelInfo += `. When reporting your model or thinking level, use these exact values.`;
+          }
+        } catch (e) {
+          // If config can't be read, that's okay - proceed without model info
+        }
+      }
+
       return {
-        systemPrompt: event.systemPrompt + `\n\nYou are teammate '${agentName}' on team '${teamName}'.\nYour lead is 'team-lead'.\nStart by calling read_inbox(team_name="${teamName}") to get your initial instructions.`,
+        systemPrompt: event.systemPrompt + `\n\nYou are teammate '${agentName}' on team '${teamName}'.\nYour lead is 'team-lead'.${modelInfo}\nStart by calling read_inbox(team_name="${teamName}") to get your initial instructions.`,
       };
     }
   });
@@ -119,7 +138,7 @@ end tell`;
       description: Type.Optional(Type.String()),
       default_model: Type.Optional(Type.String()),
     }),
-    async execute(toolCallId, params, signal, onUpdate, ctx) {
+    async execute(toolCallId, params: any, signal, onUpdate, ctx) {
       const config = teams.createTeam(params.team_name, "local-session", "lead-agent", params.description, params.default_model);
       return {
         content: [{ type: "text", text: `Team ${params.team_name} created.` }],
@@ -138,8 +157,10 @@ end tell`;
       prompt: Type.String(),
       cwd: Type.String(),
       model: Type.Optional(Type.String()),
+      thinking: Type.Optional(StringEnum(["off", "minimal", "low", "medium", "high"])),
+      plan_mode_required: Type.Optional(Type.Boolean({ default: false })),
     }),
-    async execute(toolCallId, params, signal, onUpdate, ctx) {
+    async execute(toolCallId, params: any, signal, onUpdate, ctx) {
       const safeName = paths.sanitizeName(params.name);
       const safeTeamName = paths.sanitizeName(params.team_name);
 
@@ -161,14 +182,48 @@ end tell`;
         subscriptions: [],
         prompt: params.prompt,
         color: "blue",
+        thinking: params.thinking,
+        planModeRequired: params.plan_mode_required,
       };
 
       await teams.addMember(safeTeamName, member);
       await messaging.sendPlainMessage(safeTeamName, "team-lead", safeName, params.prompt, "Initial prompt");
 
       const piBinary = process.argv[1] ? `node ${process.argv[1]}` : "pi"; // Assumed on path
-      const piCmd = piBinary;
-      
+      let piCmd = piBinary;
+
+      // Build model command with thinking level if specified
+      if (chosenModel) {
+        // If model doesn't include provider prefix (provider/model), use the team's defaultModel or fallback
+        let modelWithProvider = chosenModel;
+        if (!chosenModel.includes('/')) {
+          // Check if team has a defaultModel with a provider prefix
+          if (teamConfig.defaultModel && teamConfig.defaultModel.includes('/')) {
+            const [provider] = teamConfig.defaultModel.split('/');
+            modelWithProvider = `${provider}/${chosenModel}`;
+          } else {
+            // Use zai as default provider for glm models (matching user's pi settings)
+            if (chosenModel.startsWith('glm-')) {
+              modelWithProvider = `zai/${chosenModel}`;
+            }
+          }
+        }
+
+        if (params.thinking) {
+          piCmd = `${piBinary} --model ${modelWithProvider}:${params.thinking}`;
+        } else {
+          piCmd = `${piBinary} --model ${modelWithProvider}`;
+        }
+      } else if (params.thinking) {
+        piCmd = `${piBinary} --thinking ${params.thinking}`;
+      }
+
+      const env: Record<string, string> = {
+        ...process.env,
+        PI_TEAM_NAME: safeTeamName,
+        PI_AGENT_NAME: safeName,
+      };
+
       let paneId = "";
       try {
         if (process.env.ZELLIJ && !process.env.TMUX) {
@@ -178,13 +233,17 @@ end tell`;
             "--cwd", params.cwd, 
             "--close-on-exit",
             "--", 
-            "env", `PI_TEAM_NAME=${safeTeamName}`, `PI_AGENT_NAME=${safeName}`,
+            "env", ...Object.entries(env).filter(([k]) => k.startsWith("PI_")).map(([k, v]) => `${k}=${v}`),
             "sh", "-c", piCmd
           ];
           spawnSync("zellij", zellijArgs);
           paneId = `zellij_${safeName}`;
         } else if (process.env.TERM_PROGRAM === "iTerm.app" && !process.env.TMUX && !process.env.ZELLIJ) {
-          const itermCmd = `cd '${params.cwd}' && PI_TEAM_NAME=${safeTeamName} PI_AGENT_NAME=${safeName} ${piCmd}`;
+          const envStr = Object.entries(env)
+            .filter(([k]) => k.startsWith("PI_"))
+            .map(([k, v]) => `${k}=${v}`)
+            .join(" ");
+          const itermCmd = `cd '${params.cwd}' && ${envStr} ${piCmd}`;
           const teammates = teamConfig.members.filter(m => m.agentType === "teammate" && m.tmuxPaneId.startsWith("iterm_"));
           const lastTeammate = teammates.length > 0 ? teammates[teammates.length - 1] : null;
           
@@ -225,12 +284,15 @@ end tell`;
           if (result.status !== 0) throw new Error(`osascript failed with status ${result.status}: ${result.stderr.toString()}`);
           paneId = `iterm_${result.stdout.toString().trim()}`;
         } else {
+          const envArgs = Object.entries(env)
+            .filter(([k]) => k.startsWith("PI_"))
+            .map(([k, v]) => `${k}=${v}`);
           const tmuxArgs = [
             "split-window", 
             "-h", "-dP", 
             "-F", "#{pane_id}", 
             "-c", params.cwd, 
-            "env", `PI_TEAM_NAME=${safeTeamName}`, `PI_AGENT_NAME=${safeName}`,
+            "env", ...envArgs,
             "sh", "-c", piCmd
           ];
           const result = spawnSync("tmux", tmuxArgs);
@@ -264,10 +326,30 @@ end tell`;
       content: Type.String(),
       summary: Type.String(),
     }),
-    async execute(toolCallId, params, signal, onUpdate, ctx) {
+    async execute(toolCallId, params: any, signal, onUpdate, ctx) {
       await messaging.sendPlainMessage(params.team_name, agentName, params.recipient, params.content, params.summary);
       return {
         content: [{ type: "text", text: `Message sent to ${params.recipient}.` }],
+        details: {},
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "broadcast_message",
+    label: "Broadcast Message",
+    description: "Broadcast a message to all team members except the sender.",
+    parameters: Type.Object({
+      team_name: Type.String(),
+      content: Type.String(),
+      summary: Type.String(),
+      color: Type.Optional(Type.String()),
+    }),
+    async execute(toolCallId, params: any, signal, onUpdate, ctx) {
+      await messaging.broadcastMessage(params.team_name, agentName, params.content, params.summary, params.color);
+      return {
+        content: [{ type: "text", text: `Message broadcasted to all team members.` }],
+        details: {},
       };
     },
   });
@@ -309,6 +391,43 @@ end tell`;
     },
   });
 
+  pi.registerTool({
+    name: "task_submit_plan",
+    label: "Submit Plan",
+    description: "Submit a plan for a task, updating its status to 'planning'.",
+    parameters: Type.Object({
+      team_name: Type.String(),
+      task_id: Type.String(),
+      plan: Type.String(),
+    }),
+    async execute(toolCallId, params: any, signal, onUpdate, ctx) {
+      const updated = await tasks.submitPlan(params.team_name, params.task_id, params.plan);
+      return {
+        content: [{ type: "text", text: `Plan submitted for task ${params.task_id}.` }],
+        details: { task: updated },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "task_evaluate_plan",
+    label: "Evaluate Plan",
+    description: "Evaluate a submitted plan for a task.",
+    parameters: Type.Object({
+      team_name: Type.String(),
+      task_id: Type.String(),
+      action: StringEnum(["approve", "reject"]),
+      feedback: Type.Optional(Type.String({ description: "Required for rejection" })),
+    }),
+    async execute(toolCallId, params: any, signal, onUpdate, ctx) {
+      const updated = await tasks.evaluatePlan(params.team_name, params.task_id, params.action as any, params.feedback);
+      return {
+        content: [{ type: "text", text: `Plan for task ${params.task_id} has been ${params.action}d.` }],
+        details: { task: updated },
+      };
+    },
+  });
+
   pi.registerTool({
     name: "task_list",
     label: "List Tasks",
@@ -332,10 +451,10 @@ end tell`;
     parameters: Type.Object({
       team_name: Type.String(),
       task_id: Type.String(),
-      status: Type.Optional(StringEnum(["pending", "in_progress", "completed", "deleted"])),
+      status: Type.Optional(StringEnum(["pending", "planning", "in_progress", "completed", "deleted"])),
       owner: Type.Optional(Type.String()),
     }),
-    async execute(toolCallId, params, signal, onUpdate, ctx) {
+    async execute(toolCallId, params: any, signal, onUpdate, ctx) {
       const updated = await tasks.updateTask(params.team_name, params.task_id, {
         status: params.status as any,
         owner: params.owner,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-teams",
-  "version": "0.5.2",
+  "version": "0.7.2",
   "description": "Agent teams for pi, ported from claude-code-teams-mcp",
   "repository": "github:burggraf/pi-teams",
   "author": "Mark Burggraf",

package/src/utils/hooks.test.ts

@@ -0,0 +1,75 @@
+import fs from "node:fs";
+import path from "node:path";
+import { runHook } from "./hooks";
+import { describe, it, expect, beforeAll, afterAll, vi } from "vitest";
+
+describe("runHook", () => {
+  const hooksDir = path.join(process.cwd(), ".pi", "team-hooks");
+
+  beforeAll(() => {
+    if (!fs.existsSync(hooksDir)) {
+      fs.mkdirSync(hooksDir, { recursive: true });
+    }
+  });
+
+  afterAll(() => {
+    // Optional: Clean up created scripts
+    const files = ["success_hook.sh", "fail_hook.sh"];
+    files.forEach(f => {
+      const p = path.join(hooksDir, f);
+      if (fs.existsSync(p)) fs.unlinkSync(p);
+    });
+  });
+
+  it("should return true if hook script does not exist", async () => {
+    const result = await runHook("test_team", "non_existent_hook", { data: "test" });
+    expect(result).toBe(true);
+  });
+
+  it("should return true if hook script succeeds", async () => {
+    const hookName = "success_hook";
+    const scriptPath = path.join(hooksDir, `${hookName}.sh`);
+    
+    // Create a simple script that exits with 0
+    fs.writeFileSync(scriptPath, "#!/bin/bash\nexit 0", { mode: 0o755 });
+
+    const result = await runHook("test_team", hookName, { data: "test" });
+    expect(result).toBe(true);
+  });
+
+  it("should return false if hook script fails", async () => {
+    const hookName = "fail_hook";
+    const scriptPath = path.join(hooksDir, `${hookName}.sh`);
+    
+    // Create a simple script that exits with 1
+    fs.writeFileSync(scriptPath, "#!/bin/bash\nexit 1", { mode: 0o755 });
+
+    // Mock console.error to avoid noise in test output
+    const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    const result = await runHook("test_team", hookName, { data: "test" });
+    expect(result).toBe(false);
+
+    consoleSpy.mockRestore();
+  });
+
+  it("should pass the payload to the hook script", async () => {
+    const hookName = "payload_hook";
+    const scriptPath = path.join(hooksDir, `${hookName}.sh`);
+    const outputFile = path.join(hooksDir, "payload_output.txt");
+
+    // Create a script that writes its first argument to a file
+    fs.writeFileSync(scriptPath, `#!/bin/bash\necho "$1" > "${outputFile}"`, { mode: 0o755 });
+
+    const payload = { key: "value", "special'char": true };
+    const result = await runHook("test_team", hookName, payload);
+
+    expect(result).toBe(true);
+    const output = fs.readFileSync(outputFile, "utf-8").trim();
+    expect(JSON.parse(output)).toEqual(payload);
+
+    // Clean up
+    fs.unlinkSync(scriptPath);
+    if (fs.existsSync(outputFile)) fs.unlinkSync(outputFile);
+  });
+});

package/src/utils/hooks.ts

@@ -0,0 +1,35 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import fs from "node:fs";
+import path from "node:path";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Runs a hook script asynchronously if it exists.
+ * Hooks are located in .pi/team-hooks/{hookName}.sh relative to the CWD.
+ *
+ * @param teamName The name of the team.
+ * @param hookName The name of the hook to run (e.g., 'task_completed').
+ * @param payload The payload to pass to the hook script as the first argument.
+ * @returns true if the hook doesn't exist or executes successfully; false otherwise.
+ */
+export async function runHook(teamName: string, hookName: string, payload: any): Promise<boolean> {
+  const hookPath = path.join(process.cwd(), ".pi", "team-hooks", `${hookName}.sh`);
+
+  if (!fs.existsSync(hookPath)) {
+    return true;
+  }
+
+  try {
+    const payloadStr = JSON.stringify(payload);
+    // Use execFile: More secure (no shell interpolation) and asynchronous
+    await execFileAsync(hookPath, [payloadStr], {
+      env: { ...process.env, PI_TEAM: teamName },
+    });
+    return true;
+  } catch (error) {
+    console.error(`Hook ${hookName} failed:`, error);
+    return false;
+  }
+}

package/src/utils/lock.test.ts

@@ -1,3 +1,4 @@
+// Project: pi-teams
 import { describe, it, expect, vi, afterEach, beforeEach } from "vitest";
 import fs from "node:fs";
 import path from "node:path";

package/src/utils/lock.ts

@@ -1,10 +1,12 @@
+// Project: pi-teams
 import fs from "node:fs";
 import path from "node:path";
 
+const LOCK_TIMEOUT = 5000; // 5 seconds of retrying
+const STALE_LOCK_TIMEOUT = 30000; // 30 seconds for a lock to be considered stale
+
 export async function withLock<T>(lockPath: string, fn: () => Promise<T>, retries: number = 50): Promise<T> {
   const lockFile = `${lockPath}.lock`;
-  const LOCK_TIMEOUT = 5000; // 5 seconds of retrying
-  const STALE_LOCK_TIMEOUT = 30000; // 30 seconds for a lock to be considered stale
   
   while (retries > 0) {
     try {

package/src/utils/messaging.test.ts

@@ -2,7 +2,7 @@ import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
-import { appendMessage, readInbox, sendPlainMessage } from "./messaging";
+import { appendMessage, readInbox, sendPlainMessage, broadcastMessage } from "./messaging";
 import * as paths from "./paths";
 
 // Mock the paths to use a temporary directory
@@ -18,6 +18,9 @@ describe("Messaging Utilities", () => {
       return path.join(testDir, "inboxes", `${agentName}.json`);
     });
     vi.spyOn(paths, "teamDir").mockReturnValue(testDir);
+    vi.spyOn(paths, "configPath").mockImplementation((teamName) => {
+      return path.join(testDir, "config.json");
+    });
   });
 
   afterEach(() => {
@@ -66,4 +69,36 @@ describe("Messaging Utilities", () => {
     expect(all.length).toBe(2);
     expect(all.every(m => m.read)).toBe(true);
   });
+
+  it("should broadcast message to all members except the sender", async () => {
+    // Setup team config
+    const config = {
+      name: "test-team",
+      members: [
+        { name: "sender" },
+        { name: "member1" },
+        { name: "member2" }
+      ]
+    };
+    const configFilePath = path.join(testDir, "config.json");
+    fs.writeFileSync(configFilePath, JSON.stringify(config));
+    
+    await broadcastMessage("test-team", "sender", "broadcast text", "summary");
+
+    // Check member1's inbox
+    const inbox1 = await readInbox("test-team", "member1", false, false);
+    expect(inbox1.length).toBe(1);
+    expect(inbox1[0].text).toBe("broadcast text");
+    expect(inbox1[0].from).toBe("sender");
+
+    // Check member2's inbox
+    const inbox2 = await readInbox("test-team", "member2", false, false);
+    expect(inbox2.length).toBe(1);
+    expect(inbox2[0].text).toBe("broadcast text");
+    expect(inbox2[0].from).toBe("sender");
+
+    // Check sender's inbox (should be empty)
+    const inboxSender = await readInbox("test-team", "sender", false, false);
+    expect(inboxSender.length).toBe(0);
+  });
 });

package/src/utils/messaging.ts

@@ -3,6 +3,7 @@ import path from "node:path";
 import { InboxMessage } from "./models";
 import { withLock } from "./lock";
 import { inboxPath } from "./paths";
+import { readConfig } from "./teams";
 
 export function nowIso(): string {
   return new Date().toISOString();
@@ -71,3 +72,37 @@ export async function sendPlainMessage(
   };
   await appendMessage(teamName, toName, msg);
 }
+
+/**
+ * Broadcasts a message to all team members except the sender.
+ * @param teamName The name of the team
+ * @param fromName The name of the sender
+ * @param text The message text
+ * @param summary A short summary of the message
+ * @param color An optional color for the message
+ */
+export async function broadcastMessage(
+  teamName: string,
+  fromName: string,
+  text: string,
+  summary: string,
+  color?: string
+) {
+  const config = await readConfig(teamName);
+
+  // Create an array of delivery promises for all members except the sender
+  const deliveryPromises = config.members
+    .filter((member) => member.name !== fromName)
+    .map((member) => sendPlainMessage(teamName, fromName, member.name, text, summary, color));
+
+  // Execute deliveries in parallel and wait for all to settle
+  const results = await Promise.allSettled(deliveryPromises);
+
+  // Log failures for diagnostics
+  const failures = results.filter((r): r is PromiseRejectedResult => r.status === "rejected");
+  if (failures.length > 0) {
+    console.error(`Broadcast partially failed: ${failures.length} messages could not be delivered.`);
+    // Optionally log individual errors
+    failures.forEach((f) => console.error(`- Delivery error:`, f.reason));
+  }
+}

package/src/utils/models.ts

@@ -9,6 +9,7 @@ export interface Member {
   subscriptions: any[];
   prompt?: string;
   color?: string;
+  thinking?: "off" | "minimal" | "low" | "medium" | "high";
   planModeRequired?: boolean;
   backendType?: string;
   isActive?: boolean;
@@ -29,7 +30,9 @@ export interface TaskFile {
   subject: string;
   description: string;
   activeForm?: string;
-  status: "pending" | "in_progress" | "completed" | "deleted";
+  status: "pending" | "planning" | "in_progress" | "completed" | "deleted";
+  plan?: string;
+  planFeedback?: string;
   blocks: string[];
   blockedBy: string[];
   owner?: string;

package/src/utils/tasks.test.ts

@@ -1,8 +1,9 @@
+// Project: pi-teams
 import { describe, it, expect, vi, afterEach, beforeEach } from "vitest";
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
-import { createTask, updateTask, readTask, listTasks } from "./tasks";
+import { createTask, updateTask, readTask, listTasks, submitPlan, evaluatePlan } from "./tasks";
 import * as paths from "./paths";
 import * as teams from "./teams";
 
@@ -43,6 +44,24 @@ describe("Tasks Utilities", () => {
     expect(taskData.status).toBe("in_progress");
   });
 
+  it("should submit a plan successfully", async () => {
+    const task = await createTask("test-team", "Test Subject", "Test Description");
+    const plan = "Step 1: Do something\nStep 2: Profit";
+    const updated = await submitPlan("test-team", task.id, plan);
+    expect(updated.status).toBe("planning");
+    expect(updated.plan).toBe(plan);
+    
+    const taskData = JSON.parse(fs.readFileSync(path.join(testDir, `${task.id}.json`), "utf-8"));
+    expect(taskData.status).toBe("planning");
+    expect(taskData.plan).toBe(plan);
+  });
+
+  it("should fail to submit an empty plan", async () => {
+    const task = await createTask("test-team", "Empty Test", "Should fail");
+    await expect(submitPlan("test-team", task.id, "")).rejects.toThrow("Plan must not be empty");
+    await expect(submitPlan("test-team", task.id, "   ")).rejects.toThrow("Plan must not be empty");
+  });
+
   it("should list tasks", async () => {
     await createTask("test-team", "Task 1", "Desc 1");
     await createTask("test-team", "Task 2", "Desc 2");
@@ -74,4 +93,50 @@ describe("Tasks Utilities", () => {
     
     fs.unlinkSync(commonLockFile);
   });
+
+  it("should approve a plan successfully", async () => {
+    const task = await createTask("test-team", "Plan Test", "Should be approved");
+    await submitPlan("test-team", task.id, "Wait for it...");
+    
+    const approved = await evaluatePlan("test-team", task.id, "approve");
+    expect(approved.status).toBe("in_progress");
+    expect(approved.planFeedback).toBe("");
+  });
+
+  it("should reject a plan with feedback", async () => {
+    const task = await createTask("test-team", "Plan Test", "Should be rejected");
+    await submitPlan("test-team", task.id, "Wait for it...");
+    
+    const feedback = "Not good enough!";
+    const rejected = await evaluatePlan("test-team", task.id, "reject", feedback);
+    expect(rejected.status).toBe("planning");
+    expect(rejected.planFeedback).toBe(feedback);
+  });
+
+  it("should fail to evaluate a task not in 'planning' status", async () => {
+    const task = await createTask("test-team", "Status Test", "Invalid status for eval");
+    // status is "pending"
+    await expect(evaluatePlan("test-team", task.id, "approve")).rejects.toThrow("must be in 'planning' status");
+  });
+
+  it("should fail to evaluate a task without a plan", async () => {
+    const task = await createTask("test-team", "Plan Missing Test", "No plan submitted");
+    await updateTask("test-team", task.id, { status: "planning" }); // bypass submitPlan to have no plan
+    await expect(evaluatePlan("test-team", task.id, "approve")).rejects.toThrow("no plan has been submitted");
+  });
+
+  it("should fail to reject a plan without feedback", async () => {
+    const task = await createTask("test-team", "Feedback Test", "Should require feedback");
+    await submitPlan("test-team", task.id, "My plan");
+    await expect(evaluatePlan("test-team", task.id, "reject")).rejects.toThrow("Feedback is required when rejecting a plan");
+    await expect(evaluatePlan("test-team", task.id, "reject", "   ")).rejects.toThrow("Feedback is required when rejecting a plan");
+  });
+
+  it("should sanitize task IDs in all file operations", async () => {
+    const dirtyId = "../evil-id";
+    // sanitizeName should throw on this dirtyId
+    await expect(readTask("test-team", dirtyId)).rejects.toThrow(/Invalid name: "..\/evil-id"/);
+    await expect(updateTask("test-team", dirtyId, { status: "in_progress" })).rejects.toThrow(/Invalid name: "..\/evil-id"/);
+    await expect(evaluatePlan("test-team", dirtyId, "approve")).rejects.toThrow(/Invalid name: "..\/evil-id"/);
+  });
 });

package/src/utils/tasks.ts

@@ -1,9 +1,11 @@
+// Project: pi-teams
 import fs from "node:fs";
 import path from "node:path";
 import { TaskFile } from "./models";
 import { taskDir, sanitizeName } from "./paths";
 import { teamExists } from "./teams";
 import { withLock } from "./lock";
+import { runHook } from "./hooks";
 
 export function getTaskId(teamName: string): string {
   const dir = taskDir(teamName);
@@ -12,6 +14,12 @@ export function getTaskId(teamName: string): string {
   return ids.length > 0 ? (Math.max(...ids) + 1).toString() : "1";
 }
 
+function getTaskPath(teamName: string, taskId: string): string {
+  const dir = taskDir(teamName);
+  const safeTaskId = sanitizeName(taskId);
+  return path.join(dir, `${safeTaskId}.json`);
+}
+
 export async function createTask(
   teamName: string,
   subject: string,
@@ -48,9 +56,7 @@ export async function updateTask(
   updates: Partial<TaskFile>,
   retries?: number
 ): Promise<TaskFile> {
-  const dir = taskDir(teamName);
-  const safeTaskId = sanitizeName(taskId);
-  const p = path.join(dir, `${safeTaskId}.json`);
+  const p = getTaskPath(teamName, taskId);
 
   return await withLock(p, async () => {
     if (!fs.existsSync(p)) throw new Error(`Task ${taskId} not found`);
@@ -62,15 +68,81 @@ export async function updateTask(
       return updated;
     }
 
+    fs.writeFileSync(p, JSON.stringify(updated, null, 2));
+
+    if (updates.status === "completed") {
+      await runHook(teamName, "task_completed", updated);
+    }
+
+    return updated;
+  }, retries);
+}
+
+/**
+ * Submits a plan for a task, updating its status to "planning".
+ * @param teamName The name of the team
+ * @param taskId The ID of the task
+ * @param plan The content of the plan
+ * @returns The updated task
+ */
+export async function submitPlan(teamName: string, taskId: string, plan: string): Promise<TaskFile> {
+  if (!plan || !plan.trim()) throw new Error("Plan must not be empty");
+  return await updateTask(teamName, taskId, { status: "planning", plan });
+}
+
+/**
+ * Evaluates a submitted plan for a task.
+ * @param teamName The name of the team
+ * @param taskId The ID of the task
+ * @param action The evaluation action: "approve" or "reject"
+ * @param feedback Optional feedback for the evaluation (required for rejection)
+ * @param retries Number of times to retry acquiring the lock
+ * @returns The updated task
+ */
+export async function evaluatePlan(
+  teamName: string,
+  taskId: string,
+  action: "approve" | "reject",
+  feedback?: string,
+  retries?: number
+): Promise<TaskFile> {
+  const p = getTaskPath(teamName, taskId);
+
+  return await withLock(p, async () => {
+    if (!fs.existsSync(p)) throw new Error(`Task ${taskId} not found`);
+    const task: TaskFile = JSON.parse(fs.readFileSync(p, "utf-8"));
+
+    // 1. Validate state: Only "planning" tasks can be evaluated
+    if (task.status !== "planning") {
+      throw new Error(
+        `Cannot evaluate plan for task ${taskId} because its status is '${task.status}'. ` +
+        `Tasks must be in 'planning' status to be evaluated.`
+      );
+    }
+
+    // 2. Validate plan presence
+    if (!task.plan || !task.plan.trim()) {
+      throw new Error(`Cannot evaluate plan for task ${taskId} because no plan has been submitted.`);
+    }
+
+    // 3. Require feedback for rejections
+    if (action === "reject" && (!feedback || !feedback.trim())) {
+      throw new Error("Feedback is required when rejecting a plan.");
+    }
+
+    // 4. Perform update
+    const updates: Partial<TaskFile> = action === "approve" 
+      ? { status: "in_progress", planFeedback: "" }
+      : { status: "planning", planFeedback: feedback };
+
+    const updated = { ...task, ...updates };
     fs.writeFileSync(p, JSON.stringify(updated, null, 2));
     return updated;
   }, retries);
 }
 
 export async function readTask(teamName: string, taskId: string, retries?: number): Promise<TaskFile> {
-  const dir = taskDir(teamName);
-  const safeTaskId = sanitizeName(taskId);
-  const p = path.join(dir, `${safeTaskId}.json`);
+  const p = getTaskPath(teamName, taskId);
   if (!fs.existsSync(p)) throw new Error(`Task ${taskId} not found`);
   return await withLock(p, async () => {
     return JSON.parse(fs.readFileSync(p, "utf-8"));