pi-subagents-lite 1.1.0 → 1.2.0

package/README.md

@@ -25,6 +25,7 @@ Tool names like `Agent` and `StopAgent`, and parameter names like `prompt`, `des
 ## Features
 
 - **Two tools** — `Agent` (spawn) and `StopAgent` (stop)
+- **Manual spawn** — spawn agents from the `/agents` menu without asking the LLM. Full control over model, thinking, turns, and background mode.
 - **Foreground & background** — block or fire-and-forget with auto-delivered results
 - **Custom agent types** — define via `.md` files with YAML frontmatter (tools, model, thinking, turn limits)
 - **Smart model resolution** — 6-level precedence: session → config → frontmatter → parent. Set once, forget
@@ -38,6 +39,7 @@ Tool names like `Agent` and `StopAgent`, and parameter names like `prompt`, `des
 - **Output logs** — human-readable, `tail -f` friendly
 - **Grace turns** — configurable grace turns after `max_turns` before hard abort
 - **Reload safety** — warns when active agents are killed by session reload
+- **Worktree support** — `worktree_path` parameter runs agents in a git worktree with validated path, worktree agent discovery, and UI label
 
 ## Install
 
@@ -99,6 +101,7 @@ Stop a running agent at any time via /agents command
 | `description` | ✅ | Brief description for the LLM caller |
 | `agent` | | Type name — `general-purpose`, `Explore`, or any custom type you define (see [Custom Agent Types](#custom-agent-types)). The available values are **auto-populated** from `.md` files in your agent directories — drop a file, it appears in the enum. Set `hidden: true` in frontmatter to hide a type from this list (still callable by name). |
 | `run_in_background` | | Fire-and-forget; result delivered automatically when done |
+| `worktree_path` | | Absolute path to a git worktree. Agent runs in that worktree's context, discovers agents from its `.pi/agents/` directory, and displays a worktree label in the widget and menus. Path is validated against the parent repo's git common dir. |
 
 > `model`, `max_turns`, and `thinking` are **not visible to the LLM** through tool introspection — the extension injects them at call time from agent config and frontmatter. `model` is resolved via the [Model Resolution](#model-resolution) chain; `max_turns`/`thinking` come from the agent's config. See [Custom Agent Types](#custom-agent-types) to set them.
 
@@ -282,12 +285,14 @@ The LLM never passes `model` — it's injected at call time via the `tool_call`
 
 ### `/agents`
 
-Management menu with five sections:
+Management menu with four sections:
 
-- **Model settings** — global default, per-type overrides, force background mode, cost display toggle, grace turns
-- **Concurrency** — default limit, per-provider and per-model slots, reset to defaults
 - **Running agents** — list with status and description; per-agent actions: view snapshot, view result, view error, steer, stop; bulk stop all running
-- **Widget settings** — force compact mode, max lines (full/compact), ctrl+o shortcut
+- **Spawn agent** — manually spawn an agent without asking the LLM. Pick a type, enter a prompt, configure options (model, thinking, max turns, grace turns, background), and spawn. Options are pre-filled from agent config and current settings. Spawn immediately or customize first.
+- **Settings** — model, concurrency, and widget settings grouped together
+  - **Model settings** — global default, per-type overrides, force background mode, cost display toggle, grace turns
+  - **Concurrency** — default limit, per-provider and per-model slots, reset to defaults
+  - **Widget settings** — force compact mode, max lines (full/compact), ctrl+o shortcut
 - **Debug** — agent types, agent briefing (sends capabilities to the LLM)
 
 ## Interface

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents-lite",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Lightweight sub-agents for pi — spawn specialized agents with isolated sessions, tools, and models.",
   "keywords": [
     "pi-package",

package/src/agent-manager.ts

@@ -94,6 +94,10 @@ export interface SpawnOptions {
   maxTurns?: number;
   thinkingLevel?: ThinkingLevel;
   isBackground?: boolean;
+  /** Resolved worktree path — forwarded as cwd to runAgent. */
+  worktreePath?: string;
+  /** Short display label for the worktree (set on record display after spawn). */
+  worktreeLabel?: string;
   /**
    * Model key for concurrency pool lookup (e.g. "llamacpp/4b_small").
    * When set, the agent is counted against that model's concurrency limit.
@@ -260,6 +264,8 @@ export class AgentManager {
         type,
         description: options.description,
         invocation: options.invocation,
+        worktreePath: options.worktreePath,
+        worktreeLabel: options.worktreeLabel,
       },
       execution: {
         abortController,
@@ -318,6 +324,7 @@ export class AgentManager {
       model: options.model,
       maxTurns: options.maxTurns,
       thinkingLevel: options.thinkingLevel,
+      cwd: options.worktreePath,
       graceTurns: options.graceTurns,
       signal: record.execution.abortController!.signal,
       ...this.createRecordCallbacks(record, options),

package/src/agent-types.ts

@@ -60,8 +60,13 @@ export function setAgentScanDirs(userDir: string, projectDir: string): void {
 /**
  * Scan the known agent directories and register any newly discovered agents
  * that aren't already in the registry. Returns the number of new agents added.
+ *
+ * @param worktreeDir - Optional absolute path to a worktree's `.pi/agents/` directory.
+ *   When set, agents from this directory are also scanned and added to the registry.
+ *   Worktree-local types use "project" source attribution and follow the same
+ *   parsing and name-uniqueness rules as the parent's project scan.
  */
-export async function discoverNewAgents(): Promise<number> {
+export async function discoverNewAgents(worktreeDir?: string): Promise<number> {
   const [userAgents, projectAgents] = await Promise.all([
     scanAgentFilesInDir(userAgentDir, "user"),
     scanAgentFilesInDir(projectAgentDir, "project"),
@@ -76,6 +81,21 @@ export async function discoverNewAgents(): Promise<number> {
       count++;
     }
   }
+
+  // Scan worktree-local agents (only when worktreeDir is provided)
+  if (worktreeDir) {
+    const worktreeAgents = await scanAgentFilesInDir(worktreeDir, "project");
+    // Use mergeAgents to convert AgentConfigFromMd to AgentConfig (applies fromMd
+    // and BASE_DEFAULTS), then add only names not already in the registry.
+    const wtMerged = mergeAgents(new Map(), [], worktreeAgents);
+    for (const [name, config] of wtMerged) {
+      if (!agents.has(name)) {
+        agents.set(name, config);
+        count++;
+      }
+    }
+  }
+
   return count;
 }
 

package/src/index.ts

@@ -49,6 +49,7 @@ import {
   clearManager,
   setWidget,
   setPiInstance,
+  setSessionCtx,
   resetSessionOverrides,
   resetLastToolsExpanded,
   syncWidgetSettings,
@@ -170,7 +171,7 @@ function registerAgentTool(pi: ExtensionAPI): void {
       description: Type.String(),
       agent: agentParam,
       run_in_background: Type.Optional(Type.Boolean()),
-
+      worktree_path: Type.Optional(Type.String()),
     }),
     execute: executeAgentTool,
 
@@ -248,6 +249,7 @@ export default function (pi: ExtensionAPI) {
   let unregisterTerminalInput: (() => void) | undefined;
 
   pi.on("session_start", async (_event: unknown, ctx: ExtensionContext) => {
+    setSessionCtx(ctx);
     resetSessionOverrides();
     agentActivity.clear();
     resetLastToolsExpanded();

package/src/menus.ts

@@ -6,22 +6,27 @@
  */
 
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import { getAgentConfig, getAvailableTypes, getAllTypes } from "./agent-types.js";
-import type { AgentRecord } from "./types.js";
+import { getAgentConfig, getAvailableTypes, getAllTypes, resolveType, discoverNewAgents } from "./agent-types.js";
+import type { AgentRecord, ThinkingLevel } from "./types.js";
 import { SHORT_ID_LENGTH, CONFIG_AGENT_NON_MODEL_KEYS } from "./types.js";
+import type { SpawnOptions } from "./agent-manager.js";
 import { ModelSelectorDialog, type ModelOption } from "./model-selector.js";
 import { ResultViewer, type ResultViewerStats } from "./result-viewer.js";
 import { getDisplayName } from "./format.js";
 import { buildSnapshotMarkdown } from "./context.js";
 
-import { parseModelKey } from "./utils.js";
+import { parseModelKey, findModelInRegistry } from "./utils.js";
 import {
   __config,
   sessionOverrides,
   piInstance,
+  sessionCtx,
+  agentActivity,
   getManager,
+  getWidget,
 } from "./state.js";
 import { resolveModel } from "./model-precedence.js";
+import { createActivityTracker, backgroundAgentIds } from "./tool-execution.js";
 import {
   setModelOverride,
   setDefaultModel,
@@ -242,6 +247,96 @@ async function runMenuLoop(
   }
 }
 
+// ============================================================================
+// Worktree picker helpers
+// ============================================================================
+
+/** Timeout for git worktree list command (ms). */
+const WORKTREE_LIST_TIMEOUT_MS = 5000;
+
+/** Max display length for a worktree path before truncation. */
+const WORKTREE_PATH_TRUNCATE_LEN = 60;
+
+interface WorktreeEntry {
+  path: string;
+  branch: string | null;
+  isDetached: boolean;
+}
+
+/**
+ * Parse `git worktree list --porcelain` output into structured entries.
+ *
+ * Format (one block per worktree, separated by blank lines):
+ *   worktree /path/to/worktree
+ *   HEAD <sha>
+ *   branch refs/heads/<name>   (or: (detached))
+ */
+function parseWorktreeList(output: string): WorktreeEntry[] {
+  const entries: WorktreeEntry[] = [];
+  const blocks = output.split(/\n\n+/);
+  for (const block of blocks) {
+    if (!block.trim()) continue;
+    const lines = block.split("\n");
+    let path = "";
+    let branch: string | null = null;
+    let isDetached = false;
+    for (const line of lines) {
+      if (line.startsWith("worktree ")) {
+        path = line.slice("worktree ".length);
+      } else if (line.startsWith("branch refs/heads/")) {
+        branch = line.slice("branch refs/heads/".length);
+      } else if (line === "detached") {
+        isDetached = true;
+      }
+    }
+    if (path) {
+      entries.push({ path, branch, isDetached });
+    }
+  }
+  return entries;
+}
+
+/** Truncate a path for display, keeping the tail. */
+function truncatePath(p: string): string {
+  if (p.length <= WORKTREE_PATH_TRUNCATE_LEN) return p;
+  return "..." + p.slice(p.length - WORKTREE_PATH_TRUNCATE_LEN + 3);
+}
+
+/**
+ * Fetch worktrees via `git worktree list --porcelain`.
+ * Returns null if git is unavailable or the command fails.
+ */
+async function listWorktrees(cwd: string): Promise<WorktreeEntry[] | null> {
+  try {
+    const result = await piInstance.exec(
+      "git",
+      ["worktree", "list", "--porcelain"],
+      { cwd, timeout: WORKTREE_LIST_TIMEOUT_MS },
+    );
+    if (result.code !== 0) return null;
+    return parseWorktreeList(result.stdout);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check whether a directory is inside a git repository.
+ * Uses `git rev-parse --git-common-dir` — the same strategy as the worktree validator.
+ */
+async function isInGitRepo(cwd: string): Promise<boolean> {
+  try {
+    const result = await piInstance.exec(
+      "git",
+      ["rev-parse", "--git-common-dir"],
+      { cwd, timeout: WORKTREE_LIST_TIMEOUT_MS },
+    );
+    return result.code === 0 && result.stdout.trim() !== "";
+  } catch {
+    return false;
+  }
+}
+
 // ============================================================================
 // /agents command handler
 // ============================================================================
@@ -439,26 +534,318 @@ function matchMenuChoice(
   return handlers[key];
 }
 
+// ============================================================================
+// Spawn agent menu
+// ============================================================================
+
+const THINKING_LEVELS: ThinkingLevel[] = ["off", "minimal", "low", "medium", "high", "xhigh"];
+
+/**
+ * Show the spawn agent flow: type selection → prompt → options sub-menu → spawn.
+ * Escape at any step aborts the flow and returns to the main menu.
+ */
+export async function showSpawnAgentMenu(
+  ctx: ExtensionCommandContext,
+  modelOptions: string[],
+): Promise<void> {
+  // Step 1: Type selection loop (unknown type → error → retry)
+  let selectedType: string;
+  while (true) {
+    const types = getAvailableTypes();
+    if (types.length === 0) {
+      ctx.ui.notify("No agent types available", "error");
+      return;
+    }
+    const type = await ctx.ui.select("Select agent type", types);
+    if (type === undefined) return; // Escape → main menu
+
+    const config = getAgentConfig(type);
+    if (!config) {
+      ctx.ui.notify(`Unknown agent type: ${type}`, "error");
+      continue; // Loop back to type selection
+    }
+    selectedType = type;
+    break;
+  }
+
+  const agentConfig = getAgentConfig(selectedType)!;
+
+  // Step 2: Prompt entry loop (empty prompt → error → retry)
+  let prompt: string;
+  while (true) {
+    const input = await ctx.ui.input("Agent prompt");
+    if (input === undefined) return; // Escape → main menu
+
+    if (!input.trim()) {
+      ctx.ui.notify("Prompt cannot be empty", "error");
+      continue; // Loop back to prompt input
+    }
+    prompt = input.trim();
+    break;
+  }
+
+  // Step 3: Options sub-menu with spawn action
+  const autoDescription = prompt.length > 50 ? prompt.slice(0, 50) : prompt;
+  let description = autoDescription;
+
+  // Check if parent's cwd is inside a git repo (for worktree picker visibility)
+  const parentCwd = sessionCtx?.cwd ?? "";
+  const inGitRepo = parentCwd ? await isInGitRepo(parentCwd) : false;
+
+  // Worktree picker state
+  let currentWorktreePath: string | undefined;
+  let currentWorktreeLabel = "Inherits parent cwd";
+
+  // Pre-fill model from precedence chain
+  const parentModelId = sessionCtx?.model
+    ? `${sessionCtx.model.provider}/${sessionCtx.model.id}`
+    : "";
+  const effectiveModelStr = resolveModel({
+    subagentType: selectedType,
+    agentConfig,
+    config: __config,
+    parentModelId,
+    sessionOverrides,
+  });
+  let currentModelStr = effectiveModelStr || ""; // "" means inherit parent
+  let currentThinking: ThinkingLevel | undefined = agentConfig.thinking;
+  let currentMaxTurns: number | undefined = agentConfig.maxTurns;
+  let currentGraceTurns: number | undefined = __config.agent.graceTurns ?? 6;
+  let currentBackground: boolean = __config.agent.forceBackground ?? false;
+
+  while (true) {
+    const displayModel = currentModelStr || "(inherits parent)";
+    const displayThinking = currentThinking ?? "inherit";
+    const displayMaxTurns = currentMaxTurns != null ? String(currentMaxTurns) : "unlimited";
+    const displayGraceTurns = String(currentGraceTurns ?? 6);
+    const displayBackground = currentBackground ? "ON" : "OFF";
+
+    const items = [
+      "Spawn",
+      "",
+      `Model · ${displayModel}`,
+      `Background · ${displayBackground}`,
+      `Thinking · ${displayThinking}`,
+      `Max turns · ${displayMaxTurns}`,
+      `Grace turns · ${displayGraceTurns}`,
+      `Description · ${description}`,
+    ];
+
+    if (inGitRepo) {
+      items.push(`Worktree · ${currentWorktreeLabel}`);
+    };
+
+    const choice = await ctx.ui.select("Spawn Options", items);
+    if (choice === undefined) return; // Escape → main menu
+
+    if (choice === "Spawn") {
+      // Resolve model string to Model object
+      let model: ReturnType<typeof findModelInRegistry> = undefined;
+      let modelKey: string | undefined;
+
+      if (currentModelStr) {
+        const registry = sessionCtx?.modelRegistry ?? ctx.modelRegistry;
+        model = findModelInRegistry(currentModelStr, registry, undefined);
+        if (!model) {
+          ctx.ui.notify(`Model not found: ${currentModelStr}`, "error");
+          continue; // Return to options sub-menu
+        }
+        modelKey = `${model.provider}/${model.id}`;
+      }
+
+      // Discover worktree-local agent types before spawn
+      if (currentWorktreePath) {
+        await discoverNewAgents(`${currentWorktreePath}/.pi/agents`);
+      }
+      // Resolve type (may have been discovered from worktree)
+      const resolvedType = resolveType(selectedType) ?? selectedType;
+
+      const spawnOptions: SpawnOptions = {
+        description,
+        model,
+        maxTurns: currentMaxTurns,
+        thinkingLevel: currentThinking,
+        isBackground: currentBackground,
+        modelKey,
+        invocation: {
+          modelName: model?.id,
+          thinking: currentThinking,
+          maxTurns: currentMaxTurns,
+          runInBackground: currentBackground,
+        },
+        graceTurns: currentGraceTurns,
+        worktreePath: currentWorktreePath,
+        worktreeLabel: currentWorktreePath ? currentWorktreeLabel : undefined,
+      };
+
+      const { state: activityState, callbacks } = createActivityTracker(currentMaxTurns);
+
+      let agentId: string;
+      try {
+        agentId = getManager().spawn(piInstance, sessionCtx, resolvedType, prompt, {
+          ...spawnOptions,
+          ...callbacks,
+        });
+      } catch (err) {
+        ctx.ui.notify(
+          `Spawn failed: ${err instanceof Error ? err.message : String(err)}`,
+          "error",
+        );
+        return; // Return to main menu
+      }
+
+      // Wire activity tracking for widget
+      agentActivity.set(agentId, activityState);
+      // Set UI context so widget can render (same as tool_execution_start handler)
+      const widget = getWidget();
+      if (widget) {
+        widget.setUICtx(ctx.ui as unknown as import("./ui/agent-widget.js").UICtx);
+        widget.ensureTimer();
+        widget.update();
+      }
+
+      if (currentBackground) {
+        backgroundAgentIds.add(agentId);
+        return; // Background: return to main menu immediately
+      }
+
+      // Foreground: block until completion
+      const fgRecord = getManager().getRecord(agentId);
+      if (fgRecord?.execution?.promise) {
+        await fgRecord.execution.promise;
+      }
+
+      agentActivity.delete(agentId);
+      getWidget()?.markFinished(agentId);
+      getWidget()?.update();
+
+      return; // Return to main menu
+    }
+
+    // Handle option changes
+    if (choice.startsWith("Description")) {
+      const input = await ctx.ui.input("Description", description);
+      if (input !== undefined && input.trim()) {
+        description = input.trim();
+      }
+    } else if (choice.startsWith("Model")) {
+      const chosen = await promptModelSelection(
+        ctx, modelOptions, currentModelStr || "(inherits parent)",
+      );
+      if (chosen !== null) {
+        currentModelStr = chosen === "(inherits parent)" ? "" : chosen;
+      }
+    } else if (choice.startsWith("Thinking")) {
+      const allLevels = [...THINKING_LEVELS, "inherit"];
+      const chosen = await ctx.ui.select("Thinking level", allLevels);
+      if (chosen !== undefined) {
+        currentThinking = chosen === "inherit" ? undefined : (chosen as ThinkingLevel);
+      }
+    } else if (choice.startsWith("Max turns")) {
+      const initial = currentMaxTurns != null ? String(currentMaxTurns) : "unlimited";
+      const input = await ctx.ui.input("Max turns (number or 'unlimited')", initial);
+      if (input !== undefined) {
+        const trimmed = input.trim().toLowerCase();
+        if (trimmed === "unlimited" || trimmed === "") {
+          currentMaxTurns = undefined;
+        } else {
+          const parsed = parseInt(trimmed, 10);
+          if (isNaN(parsed) || parsed < 1) {
+            ctx.ui.notify("Invalid value — must be a number ≥ 1 or 'unlimited'", "error");
+          } else {
+            currentMaxTurns = parsed;
+          }
+        }
+      }
+    } else if (choice.startsWith("Grace turns")) {
+      const parsed = await parseNumericInput(ctx, "Grace turns (≥ 0)", String(currentGraceTurns ?? 6), 0, "≥ 0");
+      if (parsed !== undefined) currentGraceTurns = parsed;
+    } else if (choice.startsWith("Background")) {
+      currentBackground = !currentBackground;
+    } else if (choice.startsWith("Worktree") && inGitRepo) {
+      // Open worktree picker
+      const worktrees = await listWorktrees(parentCwd);
+      if (!worktrees || worktrees.length === 0) {
+        ctx.ui.notify(
+          "No worktrees found or git worktree list unavailable",
+          "error",
+        );
+        continue; // Return to options sub-menu
+      }
+
+      const pickerItems = [
+        "Inherits parent cwd",
+        ...worktrees.map(wt => {
+          const branchLabel = wt.isDetached ? "detached" : (wt.branch ?? "detached");
+          const truncPath = truncatePath(wt.path);
+          return `${branchLabel}  ·  ${truncPath}`;
+        }),
+      ];
+
+      const picked = await ctx.ui.select("Select worktree", pickerItems);
+      if (picked === undefined) continue; // Escape → return to options sub-menu
+
+      if (picked === "Inherits parent cwd") {
+        currentWorktreePath = undefined;
+        currentWorktreeLabel = "Inherits parent cwd";
+      } else {
+        // Find the matching worktree by index (offset by "Inherits parent cwd")
+        const idx = pickerItems.indexOf(picked) - 1;
+        if (idx >= 0 && idx < worktrees.length) {
+          const wt = worktrees[idx];
+          currentWorktreePath = wt.path;
+          currentWorktreeLabel = wt.branch ?? "detached";
+        }
+      }
+    }
+  }
+}
+
+export async function showSettingsMenu(
+  ctx: ExtensionCommandContext,
+  modelOptions: string[],
+): Promise<void> {
+  const menuItems = [
+    "1. Model settings — Set global default and per-type model overrides",
+    "2. Concurrency settings — Set per-model slot limits",
+    "3. Widget settings — Configure widget display options",
+    "",
+    "Back",
+  ];
+
+  const handlers: Record<string, () => Promise<void>> = {
+    "1": () => showModelSettingsMenu(ctx, modelOptions),
+    "2": () => showConcurrencySettingsMenu(ctx, modelOptions),
+    "3": () => showWidgetSettingsMenu(ctx),
+  };
+
+  while (true) {
+    const choice = await ctx.ui.select("Settings", menuItems);
+    if (choice === undefined || choice === "Back") return;
+
+    const action = matchMenuChoice(choice, handlers);
+    if (action) await action();
+  }
+}
+
 export async function showAgentsMainMenu(
   ctx: ExtensionCommandContext,
   modelOptions: string[],
 ): Promise<void> {
   const menuItems = [
     "1. Running agents — List running/queued agents",
-    "2. Model settings — Set global default and per-type model overrides",
-    "3. Concurrency settings — Set per-model slot limits",
-    "4. Widget settings — Configure widget display options",
-    "5. Debug — Agent types, briefing, diagnostics",
+    "2. Spawn agent — Manually spawn a new agent",
+    "3. Settings — Model, concurrency, and widget settings",
+    "4. Debug — Agent types, briefing, diagnostics",
     "",
     "Press Escape to close",
   ];
 
   const handlers: Record<string, () => Promise<void>> = {
     "1": () => showRunningAgentsMenu(ctx),
-    "2": () => showModelSettingsMenu(ctx, modelOptions),
-    "3": () => showConcurrencySettingsMenu(ctx, modelOptions),
-    "4": () => showWidgetSettingsMenu(ctx),
-    "5": () => showDebugMenu(ctx),
+    "2": () => showSpawnAgentMenu(ctx, modelOptions),
+    "3": () => showSettingsMenu(ctx, modelOptions),
+    "4": () => showDebugMenu(ctx),
   };
 
   // Loop so sub-menus navigate back to root; only Escape at root closes
@@ -572,6 +959,7 @@ async function handleAgentBriefing(ctx: ExtensionCommandContext): Promise<void>
   lines.push("| `agent` | Which agent type to use (default: general-purpose) |");
   lines.push("| `thinking` | Optional thinking mode override (e.g., `off`, `minimal`, `low`, `medium`, `high`, `xhigh`) |");
   lines.push("| `run_in_background` | When `true`, result is auto-delivered — do NOT poll. Continue working while waiting. |");
+  lines.push("| `worktree_path` | Optional path to a git worktree of the parent's repo. See below for details. |");
   lines.push("");
 
   // Usage guidelines
@@ -579,6 +967,15 @@ async function handleAgentBriefing(ctx: ExtensionCommandContext): Promise<void>
   lines.push("- Agents start fresh with their config — they do NOT inherit the parent conversation");
   lines.push("- For parallel tasks, spawn multiple `run_in_background: true` agents in one turn");
   lines.push("  → Results are auto-delivered — do NOT poll, the result will arrive when ready");
+  lines.push("");
+  lines.push("## `worktree_path` Parameter\n");
+  lines.push("Use `worktree_path` to run a subagent in a different git worktree of the parent's repository.");
+  lines.push("");
+  lines.push("- **Optional.** Omit to run the subagent in the parent's working directory (default behavior).");
+  lines.push("- **Must be a path** inside a git worktree of the parent's repo, including the main checkout. Not a different repo, not a non-git directory.");
+  lines.push("- **Relative paths** are resolved against the parent's working directory.");
+  lines.push("- **On failure** the validator returns a specific reason (e.g., 'not a worktree of the parent's repository', 'path does not exist') — use this to self-correct.");
+  lines.push("- **Agent type discovery:** The worktree's `.pi/agents/` directory is scanned for agent types when this param is set, so worktree-local types become available to that spawn.");
   piInstance.sendUserMessage(lines.join("\n"));
   ctx.ui.notify("Agent briefing sent to LLM", "info");
 }

package/src/renderer.ts

@@ -117,6 +117,9 @@ export function renderSubagentResult(
     if (d.outputFile as string) {
       headerLine += `\n  ${theme.fg("dim", `tail -f ${d.outputFile}`)}`;
     }
+    if (d.worktreePath as string) {
+      headerLine += `\n  ${theme.fg("dim", `worktree: ${d.worktreePath}`)}`;
+    }
     inner.addChild(new Text(headerLine, 0, 0));
 
     if (expanded && text) {
@@ -153,5 +156,8 @@ function buildFallbackResultLine(
   if (d?.outputFile) {
     line += `\n  ${theme.fg("dim", `tail -f ${d.outputFile}`)}`;
   }
+  if (d?.worktreePath) {
+    line += `\n  ${theme.fg("dim", `worktree: ${d.worktreePath}`)}`;
+  }
   return line;
 }

package/src/state.ts

@@ -5,7 +5,7 @@
  * PI runtime doesn't propagate ESM live binding reassignments.
  */
 
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionContext, ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { SessionModelOverrides, SubagentsConfig } from "./model-precedence.js";
 import { DEFAULT_CONFIG } from "./config-io.js";
 import { AgentManager } from "./agent-manager.js";
@@ -15,6 +15,8 @@ export let sessionOverrides: SessionModelOverrides = { default: null };
 export let __config: SubagentsConfig = { ...DEFAULT_CONFIG, agent: { ...DEFAULT_CONFIG.agent }, concurrency: { ...DEFAULT_CONFIG.concurrency } };
 export const agentActivity = new Map<string, AgentActivity>();
 export let piInstance: ExtensionAPI;
+/** Stored ExtensionContext from session_start — used by menu spawn flow. */
+export let sessionCtx: ExtensionContext;
 
 // Holder objects — PI runtime doesn't propagate ESM live binding reassignments
 const managerHolder: { current?: AgentManager } = {};
@@ -26,6 +28,7 @@ export function setManager(m: AgentManager): void { managerHolder.current = m; }
 export function clearManager(): void { managerHolder.current = undefined; }
 export function setWidget(w: AgentWidget | undefined): void { widgetHolder.current = w; }
 export function setPiInstance(pi: ExtensionAPI): void { piInstance = pi; }
+export function setSessionCtx(ctx: ExtensionContext): void { sessionCtx = ctx; }
 export function getManager(): AgentManager { return managerHolder.current!; }
 export function getWidget(): AgentWidget | undefined { return widgetHolder.current; }
 

package/src/tool-execution.ts

@@ -14,6 +14,7 @@ import type { AgentActivity } from "./ui/agent-widget.js";
 import { resolveType, getAgentConfig, discoverNewAgents } from "./agent-types.js";
 import { resolveModel } from "./model-precedence.js";
 import { addUsage, getLifetimeTotal, getSessionContextPercent, type LifetimeUsage } from "./usage.js";
+import { validateWorktreePath } from "./worktree-validator.js";
 
 // Shared state imported from state.ts
 import { parseModelKey, findModelInRegistry, parseThinkingLevel } from "./utils.js";
@@ -24,6 +25,7 @@ import {
   agentActivity,
   getManager,
   getWidget,
+  sessionCtx,
 } from "./state.js";
 
 // ============================================================================
@@ -60,8 +62,9 @@ export function errorResult(text: string, details?: Record<string, unknown>) {
 /**
  * Create an AgentActivity state and spawn callbacks for tracking tool usage.
  * Used by both foreground and background paths to avoid duplication.
+ * Exported for use by the menu spawn flow.
  */
-function createActivityTracker(maxTurns?: number, onStreamUpdate?: () => void) {
+export function createActivityTracker(maxTurns?: number, onStreamUpdate?: () => void) {
   const state: AgentActivity = {
     activeTools: new Map(),
     toolUses: 0,
@@ -136,6 +139,10 @@ export function buildAgentDetails(
     description: record.display.description,
   };
 
+  if (record.display.worktreePath) {
+    details.worktreePath = record.display.worktreePath;
+  }
+
   if (options?.includeStatus) {
     details.status = record.lifecycle.status;
     details.outputFile = record.display.outputFile;
@@ -191,7 +198,7 @@ function emitIndividualNudge(agentId: string, record?: AgentRecord): void {
   piInstance.sendMessage(
     {
       customType: "subagent-result",
-      content: `[Subagent "${record.display.type}" completed]\n\n${record.result ?? ""}`,
+      content: `[Subagent "${record.display.type}" ${record.lifecycle.status}]\n\n${record.result ?? ""}`,
       details,
       display: true,
     },
@@ -213,11 +220,32 @@ export async function executeAgentTool(
   _onUpdate: ((update: any) => void) | undefined,
   ctx: ExtensionContext,
 ): Promise<any> {
+  // Validate worktree_path early — needed for on-demand agent discovery
+  const rawWorktreePath = params.worktree_path as string | undefined;
+  let validatedWorktreePath: string | undefined;
+  let worktreeLabel: string | undefined;
+  if (rawWorktreePath && rawWorktreePath.trim() !== "") {
+    try {
+      const parentCwd = sessionCtx?.cwd ?? ctx.cwd;
+      const validation = await validateWorktreePath(piInstance, rawWorktreePath, parentCwd);
+      if (!validation.ok) {
+        return errorResult(validation.error);
+      }
+      validatedWorktreePath = validation.resolvedPath;
+      worktreeLabel = validation.label;
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return errorResult(`worktree_path validation failed: ${msg}`);
+    }
+  }
+
   const type = (params.agent as string) || "general-purpose";
   let resolvedType = resolveType(type);
   if (!resolvedType) {
-    // Not found in registry — try scanning filesystem for agents added during the session
-    await discoverNewAgents();
+    // Not found in registry — try scanning filesystem for agents added during the session.
+    // When worktree_path is set, also scan the worktree's .pi/agents/ directory.
+    const worktreeDir = validatedWorktreePath ? `${validatedWorktreePath}/.pi/agents` : undefined;
+    await discoverNewAgents(worktreeDir);
     resolvedType = resolveType(type);
   }
   if (!resolvedType) {
@@ -228,6 +256,7 @@ export async function executeAgentTool(
   const description = params.description as string;
   const runInBackground = params.run_in_background as boolean | undefined;
   const maxTurns = params.max_turns as number | undefined ?? getAgentConfig(resolvedType)?.maxTurns;
+
   const modelStr = params.model as string | undefined;
   const model = findModelInRegistry(modelStr, ctx.modelRegistry, ctx.model);
   const modelKey = model ? `${model.provider}/${model.id}` : undefined;
@@ -247,6 +276,8 @@ export async function executeAgentTool(
     modelKey,
     invocation: { modelName },
     graceTurns: __config.agent.graceTurns,
+    worktreePath: validatedWorktreePath,
+    worktreeLabel,
   };
 
   if (runInBackground || __config.agent.forceBackground) {

package/src/types.ts

@@ -142,6 +142,10 @@ export interface AgentDisplayInfo {
   invocation?: AgentInvocation;
   /** The tool_use_id from the original Agent tool call. */
   toolCallId?: string;
+  /** Resolved absolute path of the worktree this agent is running in. */
+  worktreePath?: string;
+  /** Short display label for the worktree (e.g., "feature" or "feature/packages/web"). */
+  worktreeLabel?: string;
 }
 
 /**

package/src/ui/agent-widget.ts

@@ -362,11 +362,18 @@ export class AgentWidget {
     const truncate = (line: string) => truncateToWidth(line, w);
     const blocks: RenderBlock[] = [];
     for (const a of finished) {
+      const continuations: string[] = [];
+      if (!this.isCompact()) {
+        if (a.display.outputFile || a.display.worktreeLabel) {
+          const parts: string[] = [];
+          if (a.display.worktreeLabel) parts.push(`@${a.display.worktreeLabel}`);
+          if (a.display.outputFile) parts.push(`tail -f ${a.display.outputFile}`);
+          continuations.push(truncate(theme.fg("dim", `${VLINE}    ${parts.join("  ")}`)));
+        }
+      }
       blocks.push({
         header: truncate(`${theme.fg("dim", BRANCH)} ${this.renderFinishedLine(a, theme)}`),
-        continuations: a.display.outputFile
-          ? [truncate(theme.fg("dim", `${VLINE}    tail -f ${a.display.outputFile}`))]
-          : [],
+        continuations,
       });
     }
     return blocks;
@@ -398,14 +405,17 @@ export class AgentWidget {
       } else {
         // Full: header + continuation lines
         const headerLine = `${BRANCH} ${theme.fg("accent", frame)} ${theme.bold(name)}  ${a.display.description}  ${statsLine}`;
+        const continuations: string[] = [];
+        if (a.display.outputFile || a.display.worktreeLabel) {
+          const parts: string[] = [];
+          if (a.display.worktreeLabel) parts.push(`@${a.display.worktreeLabel}`);
+          if (a.display.outputFile) parts.push(`tail -f ${a.display.outputFile}`);
+          continuations.push(truncate(`${VLINE}  ` + theme.fg("dim", `${VLINE} ${parts.join("  ")}`)));
+        }
+        continuations.push(truncate(`${VLINE}  ` + theme.fg("dim", `└ ${activity}`)));
         blocks.push({
           header: truncate(headerLine),
-          continuations: [
-            ...(a.display.outputFile
-              ? [truncate(`${VLINE}  ` + theme.fg("dim", `${VLINE} tail -f ${a.display.outputFile}`))]
-              : []),
-            truncate(`${VLINE}  ` + theme.fg("dim", `└ ${activity}`)),
-          ],
+          continuations,
         });
       }
     }

package/src/worktree-validator.ts

@@ -0,0 +1,199 @@
+/**
+ * worktree-validator.ts — Validate, resolve, and label a worktree path.
+ *
+ * Pure async functions that validate a `worktree_path` value against the parent's
+ * git repository. Depends on `pi.exec` for git commands.
+ *
+ * Validation strategy: compare `git-common-dir` of the parent and target paths.
+ * If they share the same common dir, the target is a worktree of the parent's repo.
+ */
+
+import * as path from "node:path";
+import { existsSync, statSync, realpathSync } from "node:fs";
+
+/** Timeout for git commands (ms). */
+const GIT_EXEC_TIMEOUT_MS = 5000;
+
+/** Specific error messages returned to the LLM for self-correction. */
+export const WORKTREE_VALIDATION_ERRORS = {
+  PATH_DOES_NOT_EXIST: "worktree_path does not exist: the specified path was not found on disk",
+  NOT_A_DIRECTORY: "worktree_path is not a directory: the specified path exists but is not a directory",
+  PARENT_NOT_IN_GIT_REPO: "worktree_path validation failed: the parent session is not inside a git repository",
+  NOT_IN_GIT_REPO: "worktree_path is not inside a git repository",
+  DIFFERENT_REPO: "worktree_path is not a worktree of the parent's repository",
+  GIT_NOT_FOUND: "worktree_path validation failed: git executable not found on this host",
+  GIT_TIMEOUT: "worktree_path validation failed: git command timed out",
+} as const;
+
+/** Successful validation result. */
+export interface WorktreeValidationSuccess {
+  ok: true;
+  /** Resolved absolute path (symlinks followed, relative resolved). Undefined when path is empty/omitted. */
+  resolvedPath?: string;
+  /** Worktree root directory. */
+  worktreeRoot?: string;
+  /** Short display label for the widget. */
+  label?: string;
+}
+
+/** Failed validation result. */
+export interface WorktreeValidationFailure {
+  ok: false;
+  /** Human-readable error describing the specific failure reason. */
+  error: string;
+}
+
+export type WorktreeValidationResult = WorktreeValidationSuccess | WorktreeValidationFailure;
+
+/**
+ * Minimal interface for the pi exec function — only what the validator needs.
+ */
+interface PiExec {
+  exec(cmd: string, args: string[], opts?: { cwd?: string; timeout?: number }): Promise<{ code: number; stdout: string; stderr: string }>;
+}
+
+/**
+ * Run `git rev-parse --git-common-dir` and return the trimmed result.
+ * Returns a failure result if the command fails or git is unavailable.
+ */
+async function getGitCommonDir(
+  pi: PiExec,
+  cwd: string,
+  notInRepoError: string,
+): Promise<{ ok: true; commonDir: string } | { ok: false; error: string }> {
+  try {
+    const result = await pi.exec("git", ["rev-parse", "--git-common-dir"], { cwd, timeout: GIT_EXEC_TIMEOUT_MS });
+    if (result.code !== 0) return { ok: false, error: notInRepoError };
+    const commonDir = result.stdout.trim();
+    if (!commonDir) return { ok: false, error: notInRepoError };
+    return { ok: true, commonDir };
+  } catch (err: unknown) {
+    const msg = String(err instanceof Error ? err.message : err);
+    if (msg.includes("ENOENT") || msg.includes("not found")) {
+      return { ok: false, error: WORKTREE_VALIDATION_ERRORS.GIT_NOT_FOUND };
+    }
+    return { ok: false, error: WORKTREE_VALIDATION_ERRORS.GIT_TIMEOUT };
+  }
+}
+
+/**
+ * Validate a worktree path against the parent's git repository.
+ *
+ * Resolution order:
+ * 1. Empty/whitespace → treated as omitted (return ok with no path)
+ * 2. Resolve relative against parent cwd
+ * 3. Resolve symlinks (realpath)
+ * 4. Check exists + is directory
+ * 5. Get and compare git-common-dir for parent and target
+ * 6. Get worktree root via --show-toplevel
+ * 7. Normalize and compute display label
+ *
+ * @param pi - Minimal exec interface (pi.exec)
+ * @param worktreePath - The raw worktree_path value from the LLM
+ * @param parentCwd - The parent session's working directory
+ * @returns Validation result with resolved path + label, or error
+ */
+export async function validateWorktreePath(
+  pi: PiExec,
+  worktreePath: string,
+  parentCwd: string,
+): Promise<WorktreeValidationResult> {
+  // Step 1: Empty / whitespace → treat as omitted
+  if (!worktreePath || worktreePath.trim() === "") {
+    return { ok: true };
+  }
+
+  // Step 2: Resolve relative paths against parent cwd
+  const resolved = path.isAbsolute(worktreePath)
+    ? worktreePath
+    : path.resolve(parentCwd, worktreePath);
+
+  // Step 3: Check existence
+  if (!existsSync(resolved)) {
+    return { ok: false, error: WORKTREE_VALIDATION_ERRORS.PATH_DOES_NOT_EXIST };
+  }
+
+  // Step 4: Check is directory (resolve symlinks first via stat)
+  let realPath: string;
+  try {
+    const stat = statSync(resolved);
+    if (!stat.isDirectory()) {
+      return { ok: false, error: WORKTREE_VALIDATION_ERRORS.NOT_A_DIRECTORY };
+    }
+    // Resolve symlinks — use realpathSync to get the canonical path
+    realPath = realpathSync(resolved);
+  } catch {
+    // stat failed — likely a broken symlink or permission issue
+    return { ok: false, error: WORKTREE_VALIDATION_ERRORS.PATH_DOES_NOT_EXIST };
+  }
+
+  // Step 5: Get and compare git-common-dir for parent and target
+  const parentResult = await getGitCommonDir(pi, parentCwd, WORKTREE_VALIDATION_ERRORS.PARENT_NOT_IN_GIT_REPO);
+  if (!parentResult.ok) return parentResult;
+
+  const targetResult = await getGitCommonDir(pi, realPath, WORKTREE_VALIDATION_ERRORS.NOT_IN_GIT_REPO);
+  if (!targetResult.ok) return targetResult;
+
+  // Compare common dirs — must share the same repo
+  const parentCommonAbs = path.isAbsolute(parentResult.commonDir)
+    ? parentResult.commonDir
+    : path.resolve(parentCwd, parentResult.commonDir);
+  const targetCommonAbs = path.isAbsolute(targetResult.commonDir)
+    ? targetResult.commonDir
+    : path.resolve(realPath, targetResult.commonDir);
+
+  if (parentCommonAbs !== targetCommonAbs) {
+    return { ok: false, error: WORKTREE_VALIDATION_ERRORS.DIFFERENT_REPO };
+  }
+
+  // Step 6: Get the worktree root via git rev-parse --show-toplevel
+  let worktreeRoot: string;
+  try {
+    const result = await pi.exec("git", ["rev-parse", "--show-toplevel"], { cwd: realPath, timeout: GIT_EXEC_TIMEOUT_MS });
+    if (result.code !== 0) {
+      worktreeRoot = realPath;
+    } else {
+      const raw = result.stdout.trim();
+      worktreeRoot = raw ? (path.isAbsolute(raw) ? raw : path.resolve(realPath, raw)) : realPath;
+    }
+  } catch {
+    worktreeRoot = realPath;
+  }
+
+  // Step 7: Normalize and compute display label
+  const normalizedRealPath = realPath.replace(/\\/g, "/");
+  const normalizedRoot = worktreeRoot.replace(/\\/g, "/");
+  const label = computeLabel(normalizedRealPath, normalizedRoot);
+
+  return {
+    ok: true,
+    resolvedPath: normalizedRealPath,
+    worktreeRoot: normalizedRoot,
+    label,
+  };
+}
+
+/**
+ * Compute a short display label for the worktree path.
+ *
+ * Rules:
+ * - Root of worktree → basename (e.g., "/wt/feature" → "feature")
+ * - Subdirectory → basename/relative (e.g., "/wt/feature/packages/web" → "feature/packages/web")
+ * - Always forward slashes regardless of host OS
+ */
+export function computeLabel(resolvedPath: string, worktreeRoot: string): string {
+  // Normalize both paths to forward slashes for cross-platform comparison
+  const normalizedResolved = resolvedPath.replace(/\\/g, "/");
+  const normalizedRoot = worktreeRoot.replace(/\\/g, "/");
+
+  const rootBasename = normalizedRoot.split("/").filter(Boolean).pop() ?? "";
+
+  if (normalizedResolved === normalizedRoot) {
+    return rootBasename;
+  }
+
+  // Compute relative path using posix separator
+  const relative = path.posix.relative(normalizedRoot, normalizedResolved);
+
+  return `${rootBasename}/${relative}`;
+}