pi-subagents-lite 1.1.0 → 1.3.0

package/README.md

@@ -18,13 +18,14 @@ Every tool the LLM sees costs tokens — in the system prompt, and in every turn
 | `promptGuidelines` with rules | _(none)_ |
 | Parameters with `.description()` | Bare `Type.String()` |
 
-Tool names like `Agent` and `StopAgent`, and parameter names like `prompt`, `description`, `run_in_background` are self-documenting. The LLM infers usage from the schema — no verbose descriptions needed. Tool results reinforce correct usage with clear success/error messages.
+Tool names like `Agent`, `StopAgent`, and `AgentStatus`, and parameter names like `prompt`, `description`, `run_in_background` are self-documenting. The LLM infers usage from the schema — no verbose descriptions needed. Tool results reinforce correct usage with clear success/error messages.
 
-**Result:** foreground and background agents, custom agent types, per-model concurrency, cost tracking, steering, model overrides — all with minimal token overhead.
+**Result:** foreground and background agents, custom agent types, per-model concurrency, cost tracking, steering, model overrides, agent status — all with minimal token overhead.
 
 ## Features
 
-- **Two tools** — `Agent` (spawn) and `StopAgent` (stop)
+- **Three tools** — `Agent` (spawn), `StopAgent` (stop), and `AgentStatus` (list agents)
+- **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
 
@@ -96,9 +98,10 @@ Stop a running agent at any time via /agents command
 | Parameter | Required | Description |
 |---|---|---|
 | `prompt` | ✅ | The task for the sub-agent |
-| `description` | ✅ | Brief description for the LLM caller |
+| `description` | | Brief description for the LLM caller (optional — if omitted, derived from prompt) |
 | `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
@@ -384,6 +389,16 @@ Agent IDs can be discovered from:
 - The `StopAgent` error message, which lists all running agent IDs
 - The `/agents` menu's **Running agents** section
 
+## AgentStatus Tool
+
+List all agents with their type, short ID, and status. Returns a formatted list of all agents (running, queued, completed, stopped, error) and a nudge message reminding the LLM not to poll.
+
+**Usage:** The LLM calls `AgentStatus` to check on agents, but the extension nudges it to wait for automatic notifications instead of polling. This prevents wasteful repeated calls while still allowing the LLM to discover agents when needed.
+
+**Output format:** `type·short_id·status, type·short_id·status, ...`
+
+Example: `general-purpose·a1b2c3·running, Explore·d4e5f6·completed`
+
 ## Output Logs
 
 `/tmp/pi-agent-outputs/<agentId>.log` — append-only, human-readable, `tail -f` friendly. Every line is prefixed with an ISO 8601 timestamp:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents-lite",
-  "version": "1.1.0",
+  "version": "1.3.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-status.ts

@@ -0,0 +1,50 @@
+/**
+ * agent-status.ts — AgentStatus tool implementation.
+ *
+ * A lightweight informational tool that lists all agents (running, queued,
+ * completed, stopped, error) from the manager and returns a clear message
+ * about not polling for status.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AgentRecord } from "./types.js";
+import { SHORT_ID_LENGTH } from "./types.js";
+import { getManager } from "./state.js";
+
+/**
+ * Format a single agent record as "type·short_id·status".
+ */
+function formatAgent(record: AgentRecord): string {
+  const shortId = record.id.slice(0, SHORT_ID_LENGTH);
+  return `${record.display.type}·${shortId}·${record.lifecycle.status}`;
+}
+
+/**
+ * Execute the AgentStatus tool.
+ *
+ * Returns a formatted list of all agents with their type, short ID, and status,
+ * followed by a nudge message telling the model not to poll.
+ */
+export async function executeAgentStatusTool(
+  _toolCallId: string,
+  _params: Record<string, unknown>,
+  _signal: AbortSignal | undefined,
+  _onUpdate: ((update: any) => void) | undefined,
+  _ctx: ExtensionContext,
+): Promise<any> {
+  const manager = getManager();
+  const agents = manager.listAgents();
+
+  const nudge = "Don't poll — you'll receive notifications when agents complete.";
+
+  if (agents.length === 0) {
+    return {
+      content: [{ type: "text", text: `No agents running or completed.\n\n${nudge}` }],
+    };
+  }
+
+  const formatted = agents.map(formatAgent).join(", ");
+  return {
+    content: [{ type: "text", text: `${formatted}\n\n${nudge}` }],
+  };
+}

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

@@ -38,6 +38,7 @@ import { AgentWidget, type UICtx } from "./ui/agent-widget.js";
 import { showAgentsMainMenu } from "./menus.js";
 import { loadConfig } from "./config-io.js";
 import { executeAgentTool, executeStopAgentTool, toolCallListener, backgroundAgentIds, scheduleNudge } from "./tool-execution.js";
+import { executeAgentStatusTool } from "./agent-status.js";
 import { renderAgentToolCall, renderAgentToolResult, renderSubagentResult } from "./renderer.js";
 import {
   __config,
@@ -49,6 +50,7 @@ import {
   clearManager,
   setWidget,
   setPiInstance,
+  setSessionCtx,
   resetSessionOverrides,
   resetLastToolsExpanded,
   syncWidgetSettings,
@@ -167,10 +169,10 @@ function registerAgentTool(pi: ExtensionAPI): void {
     label: "Agent",
     parameters: Type.Object({
       prompt: Type.String(),
-      description: Type.String(),
+      description: Type.Optional(Type.String()),
       agent: agentParam,
       run_in_background: Type.Optional(Type.Boolean()),
-
+      worktree_path: Type.Optional(Type.String()),
     }),
     execute: executeAgentTool,
 
@@ -210,6 +212,15 @@ export default function (pi: ExtensionAPI) {
     execute: executeStopAgentTool,
   });
 
+  // AgentStatus tool — stealth schema, list all agents and their statuses
+  // @ts-expect-error — description removed to save prompt tokens
+  pi.registerTool({
+    name: "AgentStatus",
+    label: "AgentStatus",
+    parameters: Type.Object({}),
+    execute: executeAgentStatusTool,
+  });
+
   // Message renderer — subagent-result (background agent completion)
   pi.registerMessageRenderer("subagent-result", (message, options, theme) =>
     renderSubagentResult(
@@ -248,6 +259,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) {
@@ -225,9 +253,10 @@ export async function executeAgentTool(
   }
 
   const prompt = params.prompt as string;
-  const description = params.description as string;
+  const description = (params.description as string | undefined) || prompt.split("\n")[0].slice(0, 80) || prompt.slice(0, 80);
   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}`;
+}