pi-teams 0.9.11 → 0.9.14

package/extensions/index.ts

@@ -18,39 +18,36 @@ import { spawnSync } from "node:child_process";
 /**
  * Build the command used to relaunch pi for teammate processes.
  *
- * Handles multiple installation scenarios:
- *
- * 1. Regular Node installs: argv[1] is the real pi launcher script on disk
- *    - execPath = /path/to/node (the interpreter)
- *    - argv[1] = /path/to/pi (the script)
- *    - We need to run the pi script directly (it has a shebang)
- *
- * 2. Bun-compiled binaries: argv[1] points to a virtual $bunfs path that
- *    doesn't exist on disk. execPath is the actual executable.
- *    - execPath = /path/to/pi-binary (the compiled executable)
- *    - argv[1] = /$bunfs/root/pi (virtual path, doesn't exist)
- *
- * 3. Fallback: If neither works, just use "pi" and hope it's on PATH.
+ * There are three common cases:
+ * - npm/node install: pi runs as `node .../dist/cli.js`
+ * - standalone compiled binary: process.execPath is the actual `pi` executable
+ * - shim-based installs (e.g. Volta): process.execPath is `node` and argv[1]
+ *   may be a shim path, so the safest relaunch command is plain `pi`
  */
 function getPiLaunchCommand(): string {
   const argv1 = process.argv[1];
+  const execPath = process.execPath;
 
-  // First, check if argv[1] is a real "pi" file on disk (regular Node install)
-  if (argv1 && path.basename(argv1) === "pi" && fs.existsSync(argv1)) {
-    return JSON.stringify(argv1);
-  }
+  // Regular Node install: relaunch the actual CLI script with node.
+  if (argv1) {
+    const ext = path.extname(argv1).toLowerCase();
+    const looksLikeScript = [".js", ".mjs", ".cjs", ".ts", ".mts", ".cts"].includes(ext)
+      || /(?:^|[/\\])dist[/\\]cli\.js$/i.test(argv1);
 
-  // For Bun-compiled binaries, execPath is the actual executable
-  if (process.execPath) {
-    return JSON.stringify(process.execPath);
+    if (looksLikeScript) {
+      return `node ${JSON.stringify(argv1)}`;
+    }
   }
 
-  // Fallback: try node with argv[1]
-  if (argv1) {
-    return `node ${JSON.stringify(argv1)}`;
+  // Standalone binary install: execPath is the pi executable itself.
+  if (execPath) {
+    const base = path.basename(execPath).toLowerCase();
+    if (base !== "node" && base !== "node.exe" && base !== "bun" && base !== "bun.exe") {
+      return JSON.stringify(execPath);
+    }
   }
 
-  // Last resort: just "pi"
+  // Shim-based installs (like Volta) are safest to relaunch through PATH.
   return "pi";
 }
 
@@ -349,12 +346,42 @@ export default function (pi: ExtensionAPI) {
 
   // For leads without PI_TEAM_NAME, check if we're registered as lead for a team
   const detectedTeamName = envTeamName || findLeadTeamForSession();
-  const teamName = detectedTeamName;
+  let teamName = detectedTeamName;
 
   const terminal = getTerminalAdapter();
 
+  // Track whether lead inbox polling has been started (to avoid duplicates)
+  let leadPollingStarted = false;
+  let sessionCtx: any = null;
+
+  /**
+   * Start inbox polling for the team lead.
+   * Called when a team is created or when the lead reconnects to an existing team.
+   * Requires sessionCtx to be set (from session_start).
+   */
+  function startLeadInboxPolling() {
+    if (leadPollingStarted || isTeammate || !sessionCtx) return;
+    leadPollingStarted = true;
+
+    setInterval(async () => {
+      if (!teamName) return;
+      if (sessionCtx.isIdle()) {
+        try {
+          const unread = await messaging.readInbox(teamName, agentName, true, false);
+          if (unread.length > 0) {
+            pi.sendUserMessage(`I have ${unread.length} new message(s) in my inbox. Reading them now...`);
+          }
+        } catch {
+          // Ignore errors for lead polling
+        }
+      }
+    }, 30000);
+  }
+
   pi.on("session_start", async (_event, ctx) => {
     paths.ensureDirs();
+    sessionCtx = ctx;
+
     if (isTeammate) {
       if (teamName) {
         const pidFile = path.join(paths.teamDir(teamName), `${agentName}.pid`);
@@ -385,34 +412,32 @@ export default function (pi: ExtensionAPI) {
       setTimeout(() => {
         pi.sendUserMessage(`I am starting my work as '${agentName}' on team '${teamName}'. Checking my inbox for instructions...`);
       }, 1000);
-    } else if (teamName) {
-      ctx.ui.setStatus("pi-teams", `Lead @ ${teamName}`);
-    }
 
-    // Inbox polling for BOTH teammates AND team-leads (anyone with teamName)
-    if (teamName) {
-      setInterval(async () => {
-        if (ctx.isIdle()) {
-          try {
-            const unread = await messaging.readInbox(teamName, agentName, true, false);
-            if (isTeammate) {
-              await runtime.writeRuntimeStatus(teamName, agentName, {
+      // Inbox polling for teammates
+      if (teamName) {
+        setInterval(async () => {
+          if (ctx.isIdle()) {
+            try {
+              const unread = await messaging.readInbox(teamName!, agentName, true, false);
+              await runtime.writeRuntimeStatus(teamName!, agentName, {
                 lastHeartbeatAt: Date.now(),
               });
-            }
-            if (unread.length > 0) {
-              pi.sendUserMessage(`I have ${unread.length} new message(s) in my inbox. Reading them now...`);
-            }
-          } catch (e) {
-            if (isTeammate) {
-              await runtime.writeRuntimeStatus(teamName, agentName, {
+              if (unread.length > 0) {
+                pi.sendUserMessage(`I have ${unread.length} new message(s) in my inbox. Reading them now...`);
+              }
+            } catch (e) {
+              await runtime.writeRuntimeStatus(teamName!, agentName, {
                 lastHeartbeatAt: Date.now(),
                 lastError: runtime.createRuntimeError(e),
               });
             }
           }
-        }
-      }, 30000);
+        }, 30000);
+      }
+    } else if (teamName) {
+      // Lead reconnecting to an existing team
+      ctx.ui.setStatus("pi-teams", `Lead @ ${teamName}`);
+      startLeadInboxPolling();
     }
   });
 
@@ -509,6 +534,9 @@ export default function (pi: ExtensionAPI) {
       const config = teams.createTeam(params.team_name, "local-session", "lead-agent", params.description, params.default_model, params.separate_windows);
       // Register this session as the lead so it can receive inbox messages
       registerLeadSession(params.team_name);
+      // Update teamName and start inbox polling for the lead
+      teamName = params.team_name;
+      startLeadInboxPolling();
       return {
         content: [{ type: "text", text: `Team ${params.team_name} created.` }],
         details: { config },
@@ -526,7 +554,7 @@ export default function (pi: ExtensionAPI) {
       prompt: Type.String(),
       cwd: Type.String(),
       model: Type.Optional(Type.String()),
-      thinking: Type.Optional(StringEnum(["off", "minimal", "low", "medium", "high"])),
+      thinking: Type.Optional(StringEnum(["off", "minimal", "low", "medium", "high", "xhigh"])),
       plan_mode_required: Type.Optional(Type.Boolean({ default: false })),
       separate_window: Type.Optional(Type.Boolean({ default: false })),
     }),
@@ -1093,6 +1121,9 @@ export default function (pi: ExtensionAPI) {
       // Create the team
       const config = teams.createTeam(params.team_name, "local-session", "lead-agent", `Predefined team: ${params.predefined_team}`, params.default_model, params.separate_windows);
       registerLeadSession(params.team_name);
+      // Update teamName and start inbox polling for the lead
+      teamName = params.team_name;
+      startLeadInboxPolling();
 
       const agentDefinitions = predefined.getAllAgentDefinitions(projectDir);
       const spawnResults: Array<{ name: string; status: string; error?: string }> = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-teams",
-  "version": "0.9.11",
+  "version": "0.9.14",
   "description": "Agent teams for pi, ported from claude-code-teams-mcp",
   "repository": {
     "type": "git",

package/src/adapters/cmux-adapter.test.ts

@@ -62,12 +62,16 @@ describe("CmuxAdapter", () => {
       process.env.CMUX_SOCKET_PATH = "/tmp/cmux.sock";
     });
 
-    it("should spawn a new pane and return the surface ID", () => {
-      mockExecCommand.mockReturnValue({ 
-        stdout: "OK surface-42", 
-        stderr: "", 
-        status: 0 
-      });
+    it("should spawn via new-split + poll + respawn-pane and return the new surface", () => {
+      mockExecCommand
+        // 1. listSurfaceRefs (before snapshot) — realistic cmux output
+        .mockReturnValueOnce({ stdout: "* surface:1  Terminal  [selected]\n  surface:2  Terminal\n", stderr: "", status: 0 })
+        // 2. new-split right
+        .mockReturnValueOnce({ stdout: "OK", stderr: "", status: 0 })
+        // 3. listSurfaceRefs (poll — finds new surface:42)
+        .mockReturnValueOnce({ stdout: "* surface:1  Terminal  [selected]\n  surface:2  Terminal\n  surface:42  Terminal\n", stderr: "", status: 0 })
+        // 4. respawn-pane
+        .mockReturnValueOnce({ stdout: "OK", stderr: "", status: 0 });
 
       const result = adapter.spawn({
         name: "test-agent",
@@ -76,19 +80,25 @@ describe("CmuxAdapter", () => {
         env: { PI_AGENT_ID: "test-123" },
       });
 
-      expect(result).toBe("surface-42");
-      expect(mockExecCommand).toHaveBeenCalledWith(
-        "cmux",
-        ["new-split", "right", "--command", "env PI_AGENT_ID=test-123 pi --agent test"]
-      );
+      expect(result).toBe("surface:42");
+
+      // Verify new-split was called without --command
+      expect(mockExecCommand).toHaveBeenCalledWith("cmux", ["new-split", "right"]);
+
+      // Verify respawn-pane was called with the new surface and full command
+      expect(mockExecCommand).toHaveBeenCalledWith("cmux", [
+        "respawn-pane",
+        "--surface", "surface:42",
+        "--command", "env PI_AGENT_ID=test-123 pi --agent test",
+      ]);
     });
 
     it("should spawn without env prefix when no PI_ vars", () => {
-      mockExecCommand.mockReturnValue({ 
-        stdout: "OK surface-99", 
-        stderr: "", 
-        status: 0 
-      });
+      mockExecCommand
+        .mockReturnValueOnce({ stdout: "  surface:1  Terminal\n", stderr: "", status: 0 })
+        .mockReturnValueOnce({ stdout: "OK", stderr: "", status: 0 })
+        .mockReturnValueOnce({ stdout: "  surface:1  Terminal\n  surface:99  Terminal\n", stderr: "", status: 0 })
+        .mockReturnValueOnce({ stdout: "OK", stderr: "", status: 0 });
 
       const result = adapter.spawn({
         name: "test-agent",
@@ -97,19 +107,20 @@ describe("CmuxAdapter", () => {
         env: { OTHER: "ignored" },
       });
 
-      expect(result).toBe("surface-99");
-      expect(mockExecCommand).toHaveBeenCalledWith(
-        "cmux",
-        ["new-split", "right", "--command", "pi"]
-      );
+      expect(result).toBe("surface:99");
+      expect(mockExecCommand).toHaveBeenCalledWith("cmux", [
+        "respawn-pane",
+        "--surface", "surface:99",
+        "--command", "pi",
+      ]);
     });
 
-    it("should throw on spawn failure", () => {
-      mockExecCommand.mockReturnValue({ 
-        stdout: "", 
-        stderr: "cmux not found", 
-        status: 1 
-      });
+    it("should throw on new-split failure", () => {
+      mockExecCommand
+        // listSurfaceRefs (before)
+        .mockReturnValueOnce({ stdout: "  surface:1  Terminal\n", stderr: "", status: 0 })
+        // new-split fails
+        .mockReturnValueOnce({ stdout: "", stderr: "cmux not found", status: 1 });
 
       expect(() => adapter.spawn({
         name: "test-agent",
@@ -119,19 +130,43 @@ describe("CmuxAdapter", () => {
       })).toThrow("cmux new-split failed with status 1");
     });
 
-    it("should throw on unexpected output format", () => {
-      mockExecCommand.mockReturnValue({ 
-        stdout: "ERROR something went wrong", 
-        stderr: "", 
-        status: 0 
-      });
+    it("should throw when new surface is not found after polling", () => {
+      mockExecCommand
+        // listSurfaceRefs (before)
+        .mockReturnValueOnce({ stdout: "  surface:1  Terminal\n", stderr: "", status: 0 })
+        // new-split OK
+        .mockReturnValueOnce({ stdout: "OK", stderr: "", status: 0 });
+
+      // All subsequent polls return the same surfaces (no new one appears)
+      // Each poll cycle = listSurfaceRefs + sleep
+      for (let i = 0; i < 20; i++) {
+        mockExecCommand
+          .mockReturnValueOnce({ stdout: "  surface:1  Terminal\n", stderr: "", status: 0 })  // listSurfaceRefs
+          .mockReturnValueOnce({ stdout: "", stderr: "", status: 0 });  // sleep
+      }
+
+      expect(() => adapter.spawn({
+        name: "test-agent",
+        cwd: "/home/user/project",
+        command: "pi",
+        env: {},
+      })).toThrow("new surface was not found");
+    });
+
+    it("should throw when respawn-pane fails", () => {
+      mockExecCommand
+        .mockReturnValueOnce({ stdout: "  surface:1  Terminal\n", stderr: "", status: 0 })
+        .mockReturnValueOnce({ stdout: "OK", stderr: "", status: 0 })
+        .mockReturnValueOnce({ stdout: "  surface:1  Terminal\n  surface:50  Terminal\n", stderr: "", status: 0 })
+        // respawn-pane fails
+        .mockReturnValueOnce({ stdout: "", stderr: "respawn error", status: 1 });
 
       expect(() => adapter.spawn({
         name: "test-agent",
         cwd: "/home/user/project",
         command: "pi",
         env: {},
-      })).toThrow("cmux new-split returned unexpected output");
+      })).toThrow("cmux respawn-pane failed with status 1");
     });
   });
 
@@ -306,4 +341,4 @@ describe("CmuxAdapter", () => {
       expect(adapter.isWindowAlive(undefined as unknown as string)).toBe(false);
     });
   });
-});
+});

package/src/adapters/cmux-adapter.ts

@@ -2,10 +2,20 @@
  * CMUX Terminal Adapter
  * 
  * Implements the TerminalAdapter interface for CMUX (cmux.dev).
+ *
+ * Spawn strategy: cmux's `new-split` does not support a `--command` flag.
+ * We follow the proven pattern from pi-cmux (npm:pi-cmux):
+ *   1. Snapshot existing surfaces
+ *   2. `cmux new-split <direction>`
+ *   3. Poll `cmux list-pane-surfaces` to find the newly created surface
+ *   4. `cmux respawn-pane --surface <id> --command <cmd>` to run the command
  */
 
 import { TerminalAdapter, SpawnOptions, execCommand } from "../utils/terminal-adapter";
 
+const SURFACE_POLL_ATTEMPTS = 20;
+const SURFACE_POLL_DELAY_MS = 150;
+
 export class CmuxAdapter implements TerminalAdapter {
   readonly name = "cmux";
 
@@ -18,34 +28,79 @@ export class CmuxAdapter implements TerminalAdapter {
     return !!process.env.CMUX_SOCKET_PATH || !!process.env.CMUX_WORKSPACE_ID;
   }
 
+  /**
+   * List all surface refs currently visible in the workspace.
+   */
+  private listSurfaceRefs(): Set<string> {
+    const refs = new Set<string>();
+    try {
+      const result = execCommand("cmux", ["list-pane-surfaces"]);
+      if (result.status === 0) {
+        for (const line of result.stdout.split("\n")) {
+          // Output lines look like: "* surface:5  ⠹ π · ziahmco  [selected]"
+          // Extract the surface:N ref from each line.
+          const match = line.match(/\b(surface:\d+)\b/);
+          if (match) refs.add(match[1]);
+        }
+      }
+    } catch {
+      // Ignore
+    }
+    return refs;
+  }
+
+  /**
+   * Block until a new surface appears that was not in `before`, or give up.
+   */
+  private waitForNewSurface(before: Set<string>): string | null {
+    for (let i = 0; i < SURFACE_POLL_ATTEMPTS; i++) {
+      const current = this.listSurfaceRefs();
+      for (const ref of current) {
+        if (!before.has(ref)) return ref;
+      }
+      // spawnSync-based sleep — keeps the adapter synchronous
+      execCommand("sleep", [String(SURFACE_POLL_DELAY_MS / 1000)]);
+    }
+    return null;
+  }
+
   spawn(options: SpawnOptions): string {
-    // We use new-split to create a new pane in CMUX.
-    // CMUX doesn't have a direct 'spawn' that returns a pane ID and runs a command 
-    // in one go while also returning the ID in a way we can easily capture for 'isAlive'.
-    // However, 'new-split' returns the new surface ID.
-    
-    // Construct the command with environment variables
+    // Construct the full command with PI_ environment variables
     const envPrefix = Object.entries(options.env)
       .filter(([k]) => k.startsWith("PI_"))
       .map(([k, v]) => `${k}=${v}`)
       .join(" ");
-    
+
     const fullCommand = envPrefix ? `env ${envPrefix} ${options.command}` : options.command;
 
-    // CMUX new-split returns "OK <UUID>"
-    const splitResult = execCommand("cmux", ["new-split", "right", "--command", fullCommand]);
-    
+    // 1. Snapshot existing surfaces before the split
+    const before = this.listSurfaceRefs();
+
+    // 2. Create the split (without --command, which is not supported)
+    const splitResult = execCommand("cmux", ["new-split", "right"]);
+
     if (splitResult.status !== 0) {
       throw new Error(`cmux new-split failed with status ${splitResult.status}: ${splitResult.stderr}`);
     }
 
-    const output = splitResult.stdout.trim();
-    if (output.startsWith("OK ")) {
-      const surfaceId = output.substring(3).trim();
-      return surfaceId;
+    // 3. Poll for the newly created surface
+    const newSurface = this.waitForNewSurface(before);
+    if (!newSurface) {
+      throw new Error("cmux new-split succeeded but new surface was not found");
+    }
+
+    // 4. Use respawn-pane to run the command in the new surface
+    const respawnResult = execCommand("cmux", [
+      "respawn-pane",
+      "--surface", newSurface,
+      "--command", fullCommand,
+    ]);
+
+    if (respawnResult.status !== 0) {
+      throw new Error(`cmux respawn-pane failed with status ${respawnResult.status}: ${respawnResult.stderr}`);
     }
 
-    throw new Error(`cmux new-split returned unexpected output: ${output}`);
+    return newSurface;
   }
 
   kill(paneId: string): void {

package/src/adapters/iterm2-adapter.ts

@@ -7,6 +7,8 @@
 
 import { TerminalAdapter, SpawnOptions, execCommand } from "../utils/terminal-adapter";
 import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as paths from "../utils/paths";
 
 /**
  * Context needed for iTerm2 spawning (tracks last pane for layout)
@@ -19,6 +21,8 @@ export interface Iterm2SpawnContext {
 export class Iterm2Adapter implements TerminalAdapter {
   readonly name = "iTerm2";
   private spawnContext: Iterm2SpawnContext = {};
+  /** Cached iTerm2 session ID for this process (looked up from team config) */
+  private cachedOwnSessionId: string | null | undefined = undefined;
 
   detect(): boolean {
     return process.env.TERM_PROGRAM === "iTerm.app" && !process.env.TMUX && !process.env.ZELLIJ;
@@ -146,6 +150,38 @@ end tell`;
 
   setTitle(title: string): void {
     const escapedTitle = title.replace(/"/g, '\\"');
+
+    // For teammate processes, find the specific session to avoid renaming
+    // unrelated iTerm2 tabs. The session ID is stored in the team config.
+    const sessionId = this.findOwnSessionId();
+    if (sessionId) {
+      const script = `tell application "iTerm2"
+  repeat with aWindow in windows
+    repeat with aTab in tabs of aWindow
+      repeat with aSession in sessions of aTab
+        if id of aSession is "${sessionId}" then
+          set name of aSession to "${escapedTitle}"
+          return "Found"
+        end if
+      end repeat
+    end repeat
+  end repeat
+end tell`;
+      try {
+        this.runAppleScript(script);
+      } catch {
+        // Ignore errors
+      }
+      return;
+    }
+
+    // If we're a teammate but haven't found our session ID yet (race condition
+    // during startup), skip the rename to avoid overwriting an unrelated tab.
+    if (process.env.PI_AGENT_NAME) {
+      return;
+    }
+
+    // Fallback for non-teammate processes (e.g., standalone pi sessions).
     const script = `tell application "iTerm2" to tell current session of current window
       set name to "${escapedTitle}"
     end tell`;
@@ -156,6 +192,40 @@ end tell`;
     }
   }
 
+  /**
+   * Look up this process's iTerm2 session ID from the team config.
+   * Teammates have PI_AGENT_NAME and PI_TEAM_NAME env vars, and the
+   * team config stores the iTerm2 session ID in the tmuxPaneId field.
+   * Caches the result once found to avoid repeated file reads.
+   */
+  private findOwnSessionId(): string | null {
+    // Return cached value if we've already found it
+    if (this.cachedOwnSessionId != null) return this.cachedOwnSessionId;
+
+    const agentName = process.env.PI_AGENT_NAME;
+    const teamName = process.env.PI_TEAM_NAME;
+    if (!agentName || !teamName) return null;
+
+    try {
+      const configFile = paths.configPath(teamName);
+      const config = JSON.parse(fs.readFileSync(configFile, "utf-8"));
+      const member = config.members?.find((m: any) => m.name === agentName);
+      if (
+        member?.tmuxPaneId &&
+        member.tmuxPaneId.startsWith("iterm_") &&
+        !member.tmuxPaneId.startsWith("iterm_win_")
+      ) {
+        this.cachedOwnSessionId = member.tmuxPaneId.replace("iterm_", "");
+        return this.cachedOwnSessionId;
+      }
+    } catch {
+      // Config not yet available — will retry on next call
+    }
+
+    // Don't cache null — the config might not be written yet (timing)
+    return null;
+  }
+
   /**
    * iTerm2 supports spawning separate OS windows via AppleScript
    */

package/src/utils/models.test.ts

@@ -0,0 +1,8 @@
+import { describe, it, expect } from "vitest";
+import { THINKING_LEVELS } from "./models";
+
+describe("thinking levels", () => {
+  it("includes xhigh for teammate configuration", () => {
+    expect(THINKING_LEVELS).toContain("xhigh");
+  });
+});

package/src/utils/models.ts

@@ -1,3 +1,7 @@
+export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
+
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+
 export interface Member {
   agentId: string;
   name: string;
@@ -10,7 +14,7 @@ export interface Member {
   subscriptions: any[];
   prompt?: string;
   color?: string;
-  thinking?: "off" | "minimal" | "low" | "medium" | "high";
+  thinking?: ThinkingLevel;
   planModeRequired?: boolean;
   backendType?: string;
   isActive?: boolean;

package/src/utils/predefined-teams.test.ts

@@ -11,6 +11,7 @@ import {
   getAllPredefinedTeams,
   getAgentDefinition,
   getPredefinedTeam,
+  saveTeamTemplate,
 } from "./predefined-teams";
 
 describe("parseAgentFrontmatter", () => {
@@ -256,7 +257,8 @@ full:
 
 describe("getAllAgentDefinitions and getAllPredefinedTeams", () => {
   const globalDir = path.join(os.homedir(), ".pi", "agent", "agents");
-  const globalTeamsDir = path.join(os.homedir(), ".pi", "agent");
+  const globalTeamsDir = path.join(os.homedir(), ".pi");
+  const legacyGlobalTeamsDir = path.join(os.homedir(), ".pi", "agent");
   const projectDir = path.join(os.tmpdir(), "pi-teams-test-project-" + Date.now());
   const projectAgentsDir = path.join(projectDir, ".pi", "agents");
   const projectTeamsDir = path.join(projectDir, ".pi");
@@ -264,6 +266,7 @@ describe("getAllAgentDefinitions and getAllPredefinedTeams", () => {
   // Store original files to restore later
   let originalGlobalAgents: string[] = [];
   let originalGlobalTeams: string | null = null;
+  let originalLegacyGlobalTeams: string | null = null;
 
   beforeEach(() => {
     // Create project directory
@@ -279,12 +282,31 @@ describe("getAllAgentDefinitions and getAllPredefinedTeams", () => {
     if (fs.existsSync(path.join(globalTeamsDir, "teams.yaml"))) {
       originalGlobalTeams = fs.readFileSync(path.join(globalTeamsDir, "teams.yaml"), "utf-8");
     }
+    if (fs.existsSync(path.join(legacyGlobalTeamsDir, "teams.yaml"))) {
+      originalLegacyGlobalTeams = fs.readFileSync(path.join(legacyGlobalTeamsDir, "teams.yaml"), "utf-8");
+    }
   });
 
   afterEach(() => {
     if (fs.existsSync(projectDir)) {
       fs.rmSync(projectDir, { recursive: true });
     }
+
+    const globalTeamsPath = path.join(globalTeamsDir, "teams.yaml");
+    if (originalGlobalTeams === null) {
+      if (fs.existsSync(globalTeamsPath)) fs.rmSync(globalTeamsPath);
+    } else {
+      fs.mkdirSync(globalTeamsDir, { recursive: true });
+      fs.writeFileSync(globalTeamsPath, originalGlobalTeams);
+    }
+
+    const legacyGlobalTeamsPath = path.join(legacyGlobalTeamsDir, "teams.yaml");
+    if (originalLegacyGlobalTeams === null) {
+      if (fs.existsSync(legacyGlobalTeamsPath)) fs.rmSync(legacyGlobalTeamsPath);
+    } else {
+      fs.mkdirSync(legacyGlobalTeamsDir, { recursive: true });
+      fs.writeFileSync(legacyGlobalTeamsPath, originalLegacyGlobalTeams);
+    }
   });
 
   it("combines global and project-local agents", () => {
@@ -330,6 +352,37 @@ custom:
     expect(result.find(t => t.name === "custom")).toBeDefined();
     expect(result.find(t => t.name === "custom")?.agents).toEqual(["agent1", "agent2"]);
   });
+
+  it("reads global predefined teams from ~/.pi/teams.yaml", () => {
+    fs.mkdirSync(globalTeamsDir, { recursive: true });
+    fs.writeFileSync(path.join(globalTeamsDir, "teams.yaml"), `
+root-global:
+  - scout
+`);
+
+    const result = getAllPredefinedTeams();
+
+    expect(result.find(t => t.name === "root-global")).toBeDefined();
+    expect(result.find(t => t.name === "root-global")?.agents).toEqual(["scout"]);
+  });
+
+  it("falls back to legacy ~/.pi/agent/teams.yaml when needed", () => {
+    const globalTeamsPath = path.join(globalTeamsDir, "teams.yaml");
+    if (fs.existsSync(globalTeamsPath)) {
+      fs.rmSync(globalTeamsPath);
+    }
+
+    fs.mkdirSync(legacyGlobalTeamsDir, { recursive: true });
+    fs.writeFileSync(path.join(legacyGlobalTeamsDir, "teams.yaml"), `
+legacy-global:
+  - scout
+`);
+
+    const result = getAllPredefinedTeams();
+
+    expect(result.find(t => t.name === "legacy-global")).toBeDefined();
+    expect(result.find(t => t.name === "legacy-global")?.agents).toEqual(["scout"]);
+  });
 });
 
 describe("getAgentDefinition and getPredefinedTeam", () => {
@@ -386,4 +439,73 @@ test-team:
     const result = getPredefinedTeam("non-existent", projectDir);
     expect(result).toBeUndefined();
   });
+});
+
+describe("saveTeamTemplate", () => {
+  const rootPiDir = path.join(os.homedir(), ".pi");
+  const globalAgentsDir = path.join(rootPiDir, "agent", "agents");
+  const globalTeamsPath = path.join(rootPiDir, "teams.yaml");
+  const projectDir = path.join(os.tmpdir(), "pi-teams-test-save-" + Date.now());
+
+  let originalGlobalTeams: string | null = null;
+  let originalAgentFiles = new Set<string>();
+
+  beforeEach(() => {
+    if (fs.existsSync(projectDir)) {
+      fs.rmSync(projectDir, { recursive: true });
+    }
+
+    if (fs.existsSync(globalTeamsPath)) {
+      originalGlobalTeams = fs.readFileSync(globalTeamsPath, "utf-8");
+    }
+    if (fs.existsSync(globalAgentsDir)) {
+      originalAgentFiles = new Set(fs.readdirSync(globalAgentsDir));
+    }
+  });
+
+  afterEach(() => {
+    if (fs.existsSync(projectDir)) {
+      fs.rmSync(projectDir, { recursive: true });
+    }
+
+    if (originalGlobalTeams === null) {
+      if (fs.existsSync(globalTeamsPath)) fs.rmSync(globalTeamsPath);
+    } else {
+      fs.mkdirSync(path.dirname(globalTeamsPath), { recursive: true });
+      fs.writeFileSync(globalTeamsPath, originalGlobalTeams);
+    }
+
+    if (fs.existsSync(globalAgentsDir)) {
+      for (const file of fs.readdirSync(globalAgentsDir)) {
+        if (!originalAgentFiles.has(file)) {
+          fs.rmSync(path.join(globalAgentsDir, file));
+        }
+      }
+    }
+  });
+
+  it("writes user-scoped teams to ~/.pi/teams.yaml and agents to ~/.pi/agent/agents", () => {
+    const result = saveTeamTemplate(
+      {
+        name: "audit-team",
+        members: [
+          {
+            name: "security-worker",
+            agentType: "teammate",
+            prompt: "Audit security issues",
+          },
+        ],
+      },
+      {
+        templateName: "audit-team",
+        scope: "user",
+      }
+    );
+
+    expect(result.teamsYamlPath).toBe(globalTeamsPath);
+    expect(result.agentsDir).toBe(globalAgentsDir);
+    expect(fs.existsSync(globalTeamsPath)).toBe(true);
+    expect(fs.readFileSync(globalTeamsPath, "utf-8")).toContain("audit-team:");
+    expect(fs.existsSync(path.join(globalAgentsDir, "security-worker.md"))).toBe(true);
+  });
 });

package/src/utils/predefined-teams.ts

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
+import { ThinkingLevel } from "./models";
 
 /**
  * Represents an agent definition from a .md file
@@ -10,7 +11,7 @@ export interface AgentDefinition {
   description: string;
   tools?: string[];
   model?: string;
-  thinking?: "off" | "minimal" | "low" | "medium" | "high";
+  thinking?: ThinkingLevel;
   prompt: string;
   filePath: string;
 }
@@ -215,12 +216,18 @@ export function getAllPredefinedTeams(projectDir?: string): PredefinedTeam[] {
   const teams: PredefinedTeam[] = [];
   const seenNames = new Set<string>();
 
-  // Global teams
-  const globalDir = path.join(os.homedir(), ".pi", "agent");
-  for (const team of discoverTeams(globalDir)) {
-    if (!seenNames.has(team.name)) {
-      seenNames.add(team.name);
-      teams.push(team);
+  // Global teams: prefer the documented ~/.pi/teams.yaml location,
+  // but still fall back to the legacy ~/.pi/agent/teams.yaml path.
+  const globalDirs = [
+    path.join(os.homedir(), ".pi"),
+    path.join(os.homedir(), ".pi", "agent"),
+  ];
+  for (const globalDir of globalDirs) {
+    for (const team of discoverTeams(globalDir)) {
+      if (!seenNames.has(team.name)) {
+        seenNames.add(team.name);
+        teams.push(team);
+      }
     }
   }
 
@@ -293,7 +300,7 @@ export function generateAgentMarkdown(agent: {
   description?: string;
   tools?: string[];
   model?: string;
-  thinking?: "off" | "minimal" | "low" | "medium" | "high";
+  thinking?: ThinkingLevel;
   prompt?: string;
 }): string {
   const lines: string[] = ["---"];
@@ -387,7 +394,7 @@ export function saveTeamTemplate(
       name: string;
       agentType: string;
       model?: string;
-      thinking?: "off" | "minimal" | "low" | "medium" | "high";
+      thinking?: ThinkingLevel;
       prompt?: string;
     }>;
     defaultModel?: string;
@@ -395,12 +402,13 @@ export function saveTeamTemplate(
   options: SaveTeamTemplateOptions
 ): SaveTeamTemplateResult {
   // Determine output paths based on scope
-  const baseDir = options.scope === "project"
-    ? path.join(options.projectDir || process.cwd(), ".pi")
-    : path.join(os.homedir(), ".pi", "agent");
+  const agentsDir = options.scope === "project"
+    ? path.join(options.projectDir || process.cwd(), ".pi", "agents")
+    : path.join(os.homedir(), ".pi", "agent", "agents");
 
-  const agentsDir = path.join(baseDir, "agents");
-  const teamsYamlPath = path.join(baseDir, "teams.yaml");
+  const teamsYamlPath = options.scope === "project"
+    ? path.join(options.projectDir || process.cwd(), ".pi", "teams.yaml")
+    : path.join(os.homedir(), ".pi", "teams.yaml");
 
   // Ensure agents directory exists
   if (!fs.existsSync(agentsDir)) {