@jerryan/pi-subagent-tools 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# @jerryan/pi-subagent-tools
+
+A minimal pi extension for delegating work to isolated subagent processes. Three tools, one job each. The agent is a **project manager** — delegate by default, dive in only when necessary.
+
+## What makes this different?
+
+Every subagent is a fresh `pi` process with an isolated context window. No agent definitions to write, no configuration files to maintain, no mode-switching parameters to misconfigure. Each tool's name *is* the contract:
+
+- **`review`** — always read-only, always in the current project. You can't forget to lock it down.
+- **`explore`** — always read-only, requires a target directory. Picks up the target project's settings, skills, and context.
+- **`delegate`** — general-purpose worker. Inherits the parent's tools and system prompt for optimal cache reuse. Optional CWD and skills.
+
+## Installation
+
+```bash
+pi install npm:@jerryan/pi-subagent-tools
+```
+
+The extension is available the next time you start a pi session.
+
+## Tools
+
+### `review`
+
+Review code, diffs, or files in the current project. The reviewer is always read-only — it cannot modify files or execute commands.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `task` | string | Yes | What to review |
+| `skills` | string[] | No | Skills to load via `--skill` |
+
+### `explore`
+
+Map a project directory. The explorer runs in the target directory, picking up its `.pi/settings.json`, skills, AGENTS.md, and other context files. Always read-only.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `task` | string | Yes | What to explore |
+| `cwd` | string | Yes | Target project directory |
+| `skills` | string[] | No | Skills to load via `--skill` |
+
+### `delegate`
+
+General-purpose worker. No tool filtering, no system prompt override — the subagent inherits the parent's full environment, enabling cache hits when used with context inheritance (future).
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `task` | string | Yes | Task to delegate |
+| `cwd` | string | No | Working directory (defaults to parent's CWD) |
+| `skills` | string[] | No | Skills to load via `--skill` |
+| `context` | `"fresh"` \| `"inherit"` | No | Context mode (not yet implemented) |
+
+## Recursion guard
+
+Subagents cannot spawn further subagents beyond one level:
+
+| Parent role | `review` | `explore` | `delegate` |
+|-------------|:--:|:--:|:--:|
+| Parent (normal) | ✓ | ✓ | ✓ |
+| Delegate child | ✓ | ✓ | Rejects at runtime |
+| Review / explore child | — | — | — |
+
+## Related
+
+- **[pi-subagents](https://github.com/nicobailon/pi-subagents)** — Feature-rich implementation with agent definitions, background runs, session forking, inter-process communication, and a full management UI. The definitive reference for what's possible, though possibly more than most workflows need.
+- **[pi-subagent-lite](https://github.com/JerryAZR/pi-subagent-lite)** — Ultra-minimal (~250 lines). A single `task` tool with minimal context overhead.
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,428 @@
+/**
+ * pi-subagent-tools — Specialized subagent delegation for pi
+ *
+ * Registers three tools for the "agent as project manager" workflow:
+ *   review   — Read-only code review in the current project
+ *   explore  — Read-only exploration of external projects (requires cwd)
+ *   delegate — General-purpose worker with optional readonly and context inheritance
+ *
+ * Recursion guard via PI_SUBAGENT_TOOLS_ROLE env var:
+ *   - Parent (unset): all three tools active
+ *   - Delegate child: review/explore active, delegate registered but rejects at runtime
+ *   - Review/explore child: no subagent tools registered
+ */
+
+import * as fs from "node:fs";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import * as path from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
+import { Container, Spacer, Text, Markdown } from "@earendil-works/pi-tui";
+import { Type } from "@sinclair/typebox";
+import {
+  runSubagent,
+  READONLY_TOOLS,
+} from "./spawn.ts";
+import { shortenPath, formatUsage, createSpinner } from "./tui.ts";
+
+const subagentSpinners = new Map<string, () => string>();
+
+const EXTENSION_DIR = path.dirname(fileURLToPath(import.meta.url));
+
+// ---------------------------------------------------------------------------
+// Compact preview component — delegates to Text.render(width) for wrapping
+// ---------------------------------------------------------------------------
+
+export class CompactPreview {
+  private textComp: Text;
+  private maxLines: number;
+
+  constructor(text: string, maxLines: number = 5) {
+    this.maxLines = maxLines;
+    this.textComp = new Text(text, 0, 0);
+  }
+
+  render(width: number): string[] {
+    const lines = this.textComp.render(width);
+    if (lines.length === 0) return [];
+
+    if (lines.length <= this.maxLines) return lines;
+
+    return ["...", ...lines.slice(-this.maxLines)];
+  }
+
+  invalidate() {
+    this.textComp.invalidate();
+  }
+}
+
+const PROMPTS_DIR = path.resolve(EXTENSION_DIR, "prompts");
+const REVIEW_PROMPT_FILE = path.join(PROMPTS_DIR, "review.md");
+const EXPLORE_PROMPT_FILE = path.join(PROMPTS_DIR, "explore.md");
+const EXTENSION_FILE = path.join(EXTENSION_DIR, "index.ts");
+
+// Role guard
+// ---------------------------------------------------------------------------
+
+export const ROLE_ENV = "PI_SUBAGENT_TOOLS_ROLE";
+
+export type SubagentRole = "delegate" | "review" | "explore";
+
+export function getCurrentRole(): SubagentRole | undefined {
+  const value = process.env[ROLE_ENV];
+  if (value === "delegate" || value === "review" || value === "explore") {
+    return value;
+  }
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Shared parameter types
+// ---------------------------------------------------------------------------
+
+export const TaskParam = Type.String({
+  description: "Task to delegate to the subagent",
+});
+
+export const SkillsParam = Type.Optional(
+  Type.Array(Type.String(), {
+    description: "Optional startup skills to load via --skill",
+  }),
+);
+
+export const CwdParam = Type.Optional(
+  Type.String({
+    description:
+      "Working directory for the subagent. Defaults to the parent's cwd.",
+  }),
+);
+
+export const ContextParam = Type.Optional(
+  Type.String({
+    enum: ["fresh", "inherit"],
+    description:
+      'Context mode. "fresh" (default): isolated process with no parent history. "inherit": forks parent session so child sees conversation history.',
+  }),
+);
+
+// Tool-specific parameter schemas
+export const ReviewParams = Type.Object({
+  task: TaskParam,
+  skills: SkillsParam,
+});
+
+export const ExploreParams = Type.Object({
+  task: TaskParam,
+  cwd: Type.String({
+    description:
+      "Working directory for the explorer. Required — the explorer runs in the target project to pick up its settings, skills, and context files.",
+  }),
+  skills: SkillsParam,
+});
+
+export const DelegateParams = Type.Object({
+  task: TaskParam,
+  cwd: CwdParam,
+  skills: SkillsParam,
+  context: ContextParam,
+});
+
+// ---------------------------------------------------------------------------
+// Shared execute helper
+// ---------------------------------------------------------------------------
+
+async function subagentExecute(
+  cwd: string,
+  task: string,
+  skills: string[] | undefined,
+  allowedTools: string[] | undefined,
+  extensionFile: string | undefined,
+  systemPromptFile: string | undefined,
+  childRole: "review" | "explore" | "delegate" | undefined,
+  signal: AbortSignal | undefined,
+  onUpdate: ((result: any) => void) | undefined,
+) {
+  // Validate cwd exists before spawning
+  if (!cwd) {
+    return {
+      content: [{ type: "text" as const, text: "Cannot spawn subagent: cwd is required." }],
+      isError: true,
+      details: { final: true },
+    };
+  }
+  try {
+    const stat = fs.statSync(cwd);
+    if (!stat.isDirectory()) {
+      return {
+        content: [{
+          type: "text" as const,
+          text: `Cannot spawn subagent: "${cwd}" is not a directory.`,
+        }],
+        isError: true,
+        details: { final: true },
+      };
+    }
+  } catch (err: any) {
+    return {
+      content: [{
+        type: "text" as const,
+        text: `Cannot spawn subagent: cwd "${cwd}" does not exist or is not accessible (${err.message}).`,
+      }],
+      isError: true,
+      details: { final: true },
+    };
+  }
+
+  try {
+    const result = await runSubagent({
+      cwd,
+      task,
+      skills,
+      allowedTools,
+      extensionFile,
+      systemPromptFile,
+      childRole,
+      signal,
+      onUpdate,
+    });
+    return {
+      content: [{ type: "text" as const, text: result.output }],
+      isError: result.isError,
+      details: {
+        usage: {
+          turns: result.turns,
+          total: result.tokens?.total,
+          input: result.tokens?.input,
+          output: result.tokens?.output,
+          durationMs: result.durationMs,
+        },
+        final: true,
+        stderr: result.stderr,
+      },
+      toolCalls: result.toolCalls,
+    };
+  } catch (err: any) {
+    return {
+      content: [{
+        type: "text" as const,
+        text: `Subagent failed: ${err.message || String(err)}`,
+      }],
+      isError: true,
+      details: { final: true },
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Shared render helpers
+// ---------------------------------------------------------------------------
+
+function renderSubagentCall(
+  label: string,
+  args: { task: string; cwd?: string },
+  theme: any,
+) {
+  const firstLine = args.task.split("\n")[0];
+  const combined = args.cwd ? `${shortenPath(args.cwd)} | ${firstLine}` : firstLine;
+  const preview = combined.length > 80 ? combined.slice(0, 77) + "..." : combined;
+  return new Text(
+    `${theme.fg("toolTitle", theme.bold(label))}${theme.fg("dim", preview)}`,
+    0, 0,
+  );
+}
+
+function renderSubagentResult(
+  result: { content: Array<{ type: string; text?: string }>; isError?: boolean; details?: any },
+  options: { expanded: boolean },
+  theme: any,
+  context: { toolCallId: string },
+) {
+  if (!subagentSpinners.has(context.toolCallId)) {
+    subagentSpinners.set(context.toolCallId, createSpinner());
+  }
+  const spin = subagentSpinners.get(context.toolCallId)!;
+  const raw = result.content.filter((c: any) => c.type === "text").map((c: any) => c.text).join("");
+  const output = raw.split("\n").map(l => l.startsWith("▸") ? theme.fg("muted", l) : l).join("\n");
+  const container = new Container();
+
+  if (result.details?.final) subagentSpinners.delete(context.toolCallId);
+
+  if (!options.expanded) {
+    const text = output || theme.fg("dim", "(no output)");
+    const usage = result.details?.usage;
+    const hint = ` · ${theme.fg("dim", "Ctrl+O to expand")}`;
+    const status = usage ? formatUsage(usage, spin) + hint : "";
+    container.addChild(new CompactPreview(text));
+    if (status) container.addChild(new Text(theme.fg("dim", status), 0, 0));
+    return container;
+  }
+
+  const isFinal = !!result.details?.final;
+  if (isFinal) {
+    const mdTheme = getMarkdownTheme();
+    container.addChild(new Markdown(raw, 0, 0, mdTheme));
+  } else {
+    container.addChild(new CompactPreview(output, 15));
+  }
+  if (result.details?.usage) {
+    container.addChild(new Spacer(1));
+    container.addChild(new Text(theme.fg("dim", formatUsage(result.details.usage, spin)), 0, 0));
+  }
+
+  return container;
+}
+
+// ---------------------------------------------------------------------------
+// Extension entry point
+// ---------------------------------------------------------------------------
+
+export default function (pi: ExtensionAPI) {
+  const role = getCurrentRole();
+
+  // Review/explore children: register git tool only, then return
+  if (role === "review" || role === "explore") {
+    pi.registerTool({
+      name: "git",
+      label: "Git",
+      description: "Run read-only git commands (log, diff, status, show, branch, blame).",
+      promptSnippet: "Run a read-only git command",
+      parameters: Type.Object({
+        command: Type.String({
+          description: "Git command with arguments (e.g. 'log --oneline -10', 'diff HEAD~1', 'status').",
+        }),
+      }),
+      async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+        try {
+          const args = params.command.trim().split(/\s+/);
+          if (args.length === 0) {
+            return { content: [{ type: "text" as const, text: "No git command provided." }], isError: true };
+          }
+          const subcommand = args[0];
+          const READONLY_GIT = new Set(["log","diff","show","status","branch","blame",
+            "rev-parse","rev-list","ls-tree","ls-files","grep","describe","shortlog","whatchanged"]);
+          if (!READONLY_GIT.has(subcommand)) {
+            return {
+              content: [{ type: "text" as const, text: `git ${subcommand} is not allowed (read-only commands only).` }],
+              isError: true,
+            };
+          }
+          const output = execFileSync("git", args, {
+            cwd: ctx.cwd,
+            encoding: "utf-8",
+            maxBuffer: 10 * 1024 * 1024,
+            timeout: 30_000,
+          });
+          return { content: [{ type: "text" as const, text: output }] };
+        } catch (err: any) {
+          return {
+            content: [{ type: "text" as const, text: `git ${params.command}\n\n${err.stderr || err.message}` }],
+            isError: true,
+          };
+        }
+      },
+    });
+    return;
+  }
+
+
+  // Delegate tool: always registered (cache compatibility), rejects in delegate children
+  pi.registerTool({
+    name: "delegate",
+    label: "Delegate",
+    description:
+      "Delegate a task to an isolated subagent process. " +
+      "For general-purpose work that doesn't fit the review or explore tools.",
+    promptSnippet: "Delegate a task to a worker subagent",
+    promptGuidelines: [
+      "Use the delegate tool for non-trivial, self-contained implementation tasks — it has full tool access unlike the read-only review and explore tools.",
+    ],
+    parameters: DelegateParams,
+    async execute(_toolCallId, params, signal, onUpdate, ctx) {
+      if (role === "delegate") {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: "Delegation not available in delegate subagents. Use review or explore instead.",
+            },
+          ],
+          isError: true,
+        };
+      }
+      return subagentExecute(
+        params.cwd ?? ctx.cwd,
+        params.task,
+        params.skills,
+        undefined, // no tool filtering — cache-compatible
+        EXTENSION_FILE, // same extensions → same system prompt → cache hit
+        undefined, // no system prompt — cache-compatible
+        "delegate", // delegate children can spawn review/explore but not delegate further
+        signal,
+        onUpdate,
+      );
+    },
+    renderCall: (args, theme) => renderSubagentCall("delegate ", args, theme),
+    renderResult: (result, options, theme, context) => renderSubagentResult(result as any, options, theme, context),
+  });
+
+  // Review tool
+  pi.registerTool({
+    name: "review",
+    label: "Review",
+    description:
+      "Review code changes or files in the current project. " +
+      "The reviewer is always read-only and runs in the parent's working directory. " +
+      "Use for code review, diff inspection, issue analysis, and quality checks.",
+    promptSnippet: "Review code or files with a read-only subagent",
+    promptGuidelines: [
+      "Use the review tool for code review, diff inspection, and quality checks — it is read-only and cannot modify files.",
+    ],
+    parameters: ReviewParams,
+    async execute(_toolCallId, params, signal, onUpdate, ctx) {
+      return subagentExecute(
+        ctx.cwd,
+        params.task,
+        params.skills,
+        READONLY_TOOLS,
+        EXTENSION_FILE,
+        REVIEW_PROMPT_FILE,
+        "review",
+        signal,
+        onUpdate,
+      );
+    },
+    renderCall: (args, theme) => renderSubagentCall("review ", args, theme),
+    renderResult: (result, options, theme, context) => renderSubagentResult(result as any, options, theme, context),
+  });
+
+  // Explore tool
+  pi.registerTool({
+    name: "explore",
+    label: "Explore",
+    description:
+      "Explore a project directory to understand its structure, patterns, and key files. " +
+      "The explorer is always read-only and runs in the specified working directory. " +
+      "Use for mapping codebases, scouting dependencies, or understanding unfamiliar projects.",
+    promptSnippet: "Explore a project directory with a read-only subagent",
+    promptGuidelines: [
+      "Use the explore tool to map unfamiliar codebases or scout dependencies — it runs read-only in the specified directory.",
+    ],
+    parameters: ExploreParams,
+    async execute(_toolCallId, params, signal, onUpdate, ctx) {
+      return subagentExecute(
+        params.cwd,
+        params.task,
+        params.skills,
+        READONLY_TOOLS,
+        EXTENSION_FILE,
+        EXPLORE_PROMPT_FILE,
+        "explore",
+        signal,
+        onUpdate,
+      );
+    },
+    renderCall: (args, theme) => renderSubagentCall("explore ", args, theme),
+    renderResult: (result, options, theme, context) => renderSubagentResult(result as any, options, theme, context),
+  });
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@jerryan/pi-subagent-tools",
+  "version": "0.1.0",
+  "description": "Minimal pi extension: delegate, review, and explore via isolated subagent processes",
+  "type": "module",
+  "main": "index.ts",
+  "files": [
+    "index.ts",
+    "spawn.ts",
+    "tui.ts",
+    "prompts/*.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "pi",
+    "pi-extension",
+    "pi-package",
+    "subagent",
+    "delegate",
+    "review",
+    "explore"
+  ],
+  "license": "MIT",
+  "author": "Zerui An",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JerryAZR/pi-subagent-tools"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "pretest": "node -e \"const{cp}=require('fs');cp('test/mocks/@earendil-works','node_modules/@earendil-works',{recursive:true},()=>{})\"",
+    "test": "node --experimental-strip-types --test test/*.test.ts"
+  },
+  "pi": {
+    "extensions": ["./index.ts"]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.74.0",
+    "@earendil-works/pi-coding-agent": "^0.74.0",
+    "@earendil-works/pi-tui": "^0.74.0",
+    "@sinclair/typebox": "^0.34.0",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0"
+  }
+}

package/prompts/explore.md

@@ -0,0 +1,4 @@
+You are a codebase explorer. Map the structure, identify key files, and report patterns.
+You are in read-only mode — use the git tool for repository inspection. Do not modify files or run destructive commands.
+Focus on entry points, architecture, dependencies, and areas of interest.
+End with a clear summary of the codebase structure and notable findings.

package/prompts/review.md

@@ -0,0 +1,4 @@
+You are a code reviewer. Inspect code, find issues, and report findings clearly.
+You are in read-only mode — use the git tool for repository inspection. Do not modify files or run destructive commands.
+Focus on correctness, edge cases, readability, and adherence to the task requirements.
+End with a clear summary of findings organized by severity.

package/spawn.ts

@@ -0,0 +1,262 @@
+/**
+ * Shared subagent spawn logic.
+ */
+
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { Message } from "@earendil-works/pi-ai";
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { UsageStats } from "./tui.ts";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface SpawnOptions {
+  cwd: string;
+  task: string;
+  skills?: string[];
+  allowedTools?: string[];
+  extensionFile?: string;
+  systemPromptFile?: string;
+  childRole?: "review" | "explore" | "delegate";
+  signal?: AbortSignal;
+  onUpdate?: (result: AgentToolResult) => void;
+}
+
+export interface SpawnResult {
+  output: string;
+  isError: boolean;
+  exitCode: number;
+  tokens?: { input: number; output: number; total: number };
+  turns: number;
+  toolCalls: string[];
+  durationMs: number;
+  stderr?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+export const READONLY_TOOLS = ["read", "grep", "find", "ls", "git"];
+
+// ---------------------------------------------------------------------------
+// Pi process detection
+// ---------------------------------------------------------------------------
+
+export function getPiInvocation(args: string[]): {
+  command: string;
+  args: string[];
+} {
+  const currentScript = process.argv[1];
+  if (currentScript && fs.existsSync(currentScript)) {
+    return { command: process.execPath, args: [currentScript, ...args] };
+  }
+  const npmGlobalRoot = process.env.APPDATA
+    ? path.join(process.env.APPDATA, "npm", "node_modules")
+    : process.env.HOME
+      ? path.join(process.env.HOME, ".npm-global", "node_modules")
+      : null;
+  if (npmGlobalRoot) {
+    const cliPath = path.join(npmGlobalRoot, "@earendil-works", "pi-coding-agent", "dist", "cli.js");
+    if (fs.existsSync(cliPath)) {
+      return { command: process.execPath, args: [cliPath, ...args] };
+    }
+  }
+  const execName = path.basename(process.execPath).toLowerCase();
+  const isGenericRuntime = /^(node|bun)(\.exe)?$/.test(execName);
+  if (!isGenericRuntime) return { command: process.execPath, args };
+  return { command: "pi", args };
+}
+
+// ---------------------------------------------------------------------------
+// Argument construction
+// ---------------------------------------------------------------------------
+
+export function buildSpawnArgs(opts: SpawnOptions): string[] {
+  const args: string[] = ["--mode", "json", "-p"];
+
+  args.push("--no-session");
+
+  if (opts.allowedTools && opts.allowedTools.length > 0) {
+    args.push("--tools", opts.allowedTools.join(","));
+  }
+
+  for (const skill of opts.skills ?? []) {
+    args.push("--skill", skill);
+  }
+
+  if (opts.extensionFile) {
+    args.push("--extension", opts.extensionFile);
+  }
+
+  if (opts.systemPromptFile) {
+    args.push("--append-system-prompt", opts.systemPromptFile);
+  }
+
+  args.push(opts.task);
+  return args;
+}
+
+// ---------------------------------------------------------------------------
+// JSONL parsing
+// ---------------------------------------------------------------------------
+
+function getFinalOutput(messages: Message[]): string {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if (msg.role === "assistant") {
+      for (const part of msg.content) {
+        if (part.type === "text") return part.text ?? "";
+      }
+    }
+  }
+  return "";
+}
+
+// ---------------------------------------------------------------------------
+// Main spawn function
+// ---------------------------------------------------------------------------
+
+export async function runSubagent(opts: SpawnOptions): Promise<SpawnResult> {
+  const args = buildSpawnArgs(opts);
+  const invocation = getPiInvocation(args);
+
+  let buffer = "";
+  let stderr = "";
+  let spawnError: string | null = null;
+  const messages: Message[] = [];
+  let turnCount = 0;
+  let tokens = { input: 0, output: 0, total: 0 };
+  const toolCallNames: string[] = [];
+  const env: Record<string, string | undefined> = { ...process.env };
+  if (opts.childRole) env.PI_SUBAGENT_TOOLS_ROLE = opts.childRole;
+
+  const startTime = Date.now();
+
+  let previousTurnsText = "";
+  let streamText = "";
+
+  const displayText = () => previousTurnsText + (previousTurnsText && streamText ? "\n" : "") + streamText;
+  const proc = spawn(invocation.command, invocation.args, {
+    cwd: opts.cwd,
+    shell: false,
+    stdio: ["ignore", "pipe", "pipe"],
+    env,
+  });
+
+  const MAX_MSG_COUNT = 5;
+  const MAX_PREV_LINES = 20;
+
+  const trimPrev = () => {
+    const lines = previousTurnsText.split("\n");
+    if (lines.length > MAX_PREV_LINES) previousTurnsText = lines.slice(-MAX_PREV_LINES).join("\n");
+  };
+
+  let lastUpdate = 0;
+  let pendingTimer: ReturnType<typeof setTimeout> | null = null;
+  const UPDATE_INTERVAL = 200;
+
+  const doUpdate = () => {
+    if (!opts.onUpdate) return;
+    const bottom = displayText();
+    opts.onUpdate({
+      content: [{ type: "text", text: bottom }],
+      details: { usage: { turns: turnCount, input: tokens.input, output: tokens.output, total: tokens.total, durationMs: Date.now() - startTime } satisfies UsageStats, toolCalls: [...toolCallNames] },
+    });
+  };
+
+  const fireUpdate = () => {
+    if (!opts.onUpdate) return;
+    const now = Date.now();
+    if (now - lastUpdate >= UPDATE_INTERVAL) {
+      lastUpdate = now;
+      doUpdate();
+    } else if (!pendingTimer) {
+      pendingTimer = setTimeout(() => {
+        pendingTimer = null;
+        lastUpdate = Date.now();
+        doUpdate();
+      }, UPDATE_INTERVAL - (now - lastUpdate));
+    }
+  };
+
+  const processLine = (line: string) => {
+    if (!line.trim()) return;
+    let event: any;
+    try { event = JSON.parse(line); } catch { return; }
+
+    // Per-token streaming: show text on every message_update
+    if (event.type === "message_update" && event.message) {
+      const text = (event.message.content ?? [])
+        .filter((c: any) => c.type === "text" || c.type === "thinking")
+        .map((c: any) => c[c.type]).join("");
+      streamText = text;
+      fireUpdate();
+    }
+
+    if (event.type === "message_end" && event.message) {
+      const msg = event.message as Message & { content: any[] };
+      messages.push(msg);
+      if (messages.length > MAX_MSG_COUNT) messages.splice(0, messages.length - MAX_MSG_COUNT);
+      if (msg.role === "assistant") {
+        turnCount++;
+        if (msg.usage) {
+          tokens.input += msg.usage.input || 0;
+          tokens.output += msg.usage.output || 0;
+          tokens.total += msg.usage.totalTokens || 0;
+        }
+        if (streamText) {
+          previousTurnsText = previousTurnsText ? previousTurnsText + "\n" + streamText : streamText;
+          streamText = "";
+          trimPrev();
+        } else {
+          const text = (msg.content ?? []).filter((c: any) => c.type === "text" || c.type === "thinking").map((c: any) => c[c.type]).join("");
+          if (text) {
+            previousTurnsText = previousTurnsText ? previousTurnsText + "\n" + text : text;
+            trimPrev();
+          }
+        }
+        for (const tc of (msg.content ?? []).filter((c: any) => c.type === "toolCall")) {
+          toolCallNames.push(tc.name);
+          const parts = [`▸ ${tc.name}`];
+          if (tc.arguments && typeof tc.arguments === "object" && !Array.isArray(tc.arguments)) {
+            const entries = Object.entries(tc.arguments);
+            const capPerParam = entries.length > 1;
+            for (const [k, v] of entries) {
+              const val = typeof v === "string" ? v : JSON.stringify(v);
+              const short = capPerParam && val.length > 40 ? val.slice(0, 37) + "..." : val;
+              parts.push(`${k}=${short}`);
+            }
+          }
+          let line = parts.join(" ");
+          if (line.length > 80) line = line.slice(0, 77) + "...";
+          previousTurnsText = previousTurnsText ? `${previousTurnsText}\n${line}` : line;
+          trimPrev();
+        }
+        fireUpdate();
+      }
+    }
+  };
+
+  const exitCode = await new Promise<number>((resolve) => {
+    const killProc = () => { proc.kill("SIGTERM"); setTimeout(() => { if (!proc.killed) try { proc.kill("SIGKILL"); } catch { /* not supported on all platforms */ } }, 5000); };
+    if (opts.signal) {
+      if (opts.signal.aborted) killProc();
+      else opts.signal.addEventListener("abort", killProc, { once: true });
+    }
+    proc.stdout.on("data", (data) => { buffer += data.toString(); const lines = buffer.split("\n"); buffer = lines.pop() || ""; for (const line of lines) processLine(line); });
+    proc.stderr.on("data", (data) => { stderr += data.toString(); });
+    proc.on("close", (code) => { if (opts.signal) opts.signal.removeEventListener("abort", killProc); if (buffer.trim()) processLine(buffer); resolve(code ?? 1); });
+    proc.on("error", (err) => { if (opts.signal) opts.signal.removeEventListener("abort", killProc); spawnError = err.message; resolve(1); });
+  });
+
+  if (opts.signal?.aborted) return { output: "Subagent was aborted", isError: true, exitCode: 1, tokens, turns: turnCount, toolCalls: toolCallNames, durationMs: Date.now() - startTime };
+  if (spawnError) return { output: `Failed to start subagent: ${spawnError}`, isError: true, exitCode: 1, tokens, turns: turnCount, toolCalls: toolCallNames, durationMs: Date.now() - startTime };
+  if (exitCode !== 0) return { output: stderr || `Subagent exited with code ${exitCode}`, isError: true, exitCode, tokens, turns: turnCount, toolCalls: toolCallNames, durationMs: Date.now() - startTime };
+
+  const output = getFinalOutput(messages);
+  return { output: output || "(no output)", isError: false, exitCode: 0, tokens, turns: turnCount, toolCalls: toolCallNames, durationMs: Date.now() - startTime, stderr: stderr.trim() || undefined };
+}

package/tui.ts

@@ -0,0 +1,66 @@
+/**
+ * TUI rendering helpers for pi-subagent-tools.
+ *
+ * Tool call cards, result display, progress indicators.
+ */
+
+import * as os from "node:os";
+
+/**
+ * Shorten a path by replacing the home directory with ~
+ */
+export function shortenPath(p: string): string {
+  const normalized = p.toLowerCase();
+  for (const home of [process.env.HOME, process.env.USERPROFILE, os.homedir()]) {
+    if (home && normalized.startsWith(home.toLowerCase())) {
+      return `~${p.slice(home.length)}`;
+    }
+  }
+  return p;
+}
+
+/**
+ * Format duration in human-readable form
+ */
+export function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+  return `${Math.floor(ms / 60000)}m${String(Math.floor((ms % 60000) / 1000)).padStart(2, "0")}s`;
+}
+
+/**
+ * Format token count with k suffix for large numbers
+ */
+export function formatTokens(n: number): string {
+  let s: string;
+  if (n < 1000) s = String(n) + "   ";  // trailing spaces give same visual weight as k/M suffix; padStart right-aligns
+  else if (n < 1_000_000) s = (Math.trunc(n / 100) / 10).toFixed(1) + "k";
+  else s = (Math.trunc(n / 100_000) / 10).toFixed(1) + "M";
+  return s.padStart(6);
+}
+
+const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+export function createSpinner(): () => string {
+  let idx = 0;
+  return () => {
+    const frame = SPINNER[idx];
+    idx = (idx + 1) % SPINNER.length;
+    return frame;
+  };
+}
+
+export interface UsageStats {
+  turns: number;
+  input: number;
+  output: number;
+  total: number;
+  durationMs: number;
+}
+
+export function formatUsage(u: UsageStats, spin: () => string): string {
+  const parts: string[] = [`${spin()} · Turn ${u.turns}`];
+  parts.push(`Tokens: input ${formatTokens(u.input)} | output ${formatTokens(u.output)}`);
+  if (u.durationMs != null) parts.push(formatDuration(u.durationMs));
+  return parts.join(" · ");
+}