@leo-alvarenga/pi-mini-subagents 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leonardo A. Alvarenga
+
+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,83 @@
+# @leo-alvarenga/pi-mini-subagents
+
+Transient subagents for the [Pi coding agent](https://github.com/earendil-works/pi-mono).
+Delegate a task to a separate headless `pi` process (its own context window),
+get its findings back, and watch running/completed subagents live in a panel
+above the input editor.
+
+## Features
+
+- **`mini_subagent` tool**: single mode (`task`) or parallel mode (`tasks[]`,
+  max 8, 4 concurrent). Each subagent is a transient `pi --mode json -p --no-session`
+  process, so it has an isolated context window and nothing is persisted.
+- **Read-only by default**: subagents get `read/grep/find/ls`. Set
+  `allowWrite: true` to grant `replace/insert/edit/write` (hash-anchored ops
+  preferred).
+- **No recursion**: children inherit `PI_SUBAGENT=1` and the extension no-ops
+  on it, so a subagent can never spawn its own subagents.
+- **Dynamic minimal prompt**: read-only restriction always; a write clause is
+  appended only when `allowWrite` is set.
+- **Question protocol**: a subagent that cannot proceed emits a `NEEDS_INPUT:`
+  block in its final message. The tool reports the questions and instructs the
+  caller to re-call with `answers` (a fresh subagent is spawned with them).
+- **Live TUI panel** (`Alt+S`): header with running/done counts, Nerd Font
+  status glyphs (⏳ running, ✓ done, ✗ failed, ? needs input), an 8-row budget
+  with `… +N more`, and hidden entirely while empty.
+- **`/subagents` command**: prints the full list grouped by status.
+- **Session-isolated state**: survives `/reload` and compaction via replay
+  from the session branch; no files written by the extension. Running records
+  are dropped on replay (their processes do not survive a reload).
+
+## Install
+
+```bash
+pi install npm:@leo-alvarenga/pi-mini-subagents
+```
+
+or add the local path / npm spec to your project `.pi/settings.json`, then run
+`/reload`.
+
+## Usage
+
+```
+"Use a subagent to find every place we do auth"
+"Run 3 subagents in parallel: one for models, one for providers, one for routes"
+```
+
+Tool parameters:
+
+- `task` (single mode) or `tasks` (parallel mode, array of `{ task, allowWrite?, answers?, cwd? }`)
+- `allowWrite` (single mode, default false)
+- `answers` (single mode re-spawn)
+- `cwd` (single mode working directory)
+
+## The NEEDS_INPUT loop
+
+1. A subagent ends with:
+
+   ```
+   NEEDS_INPUT:
+   - which auth provider should this use?
+   ```
+
+2. `mini_subagent` returns `needs_input` with the questions listed.
+3. Answer them (ask the user if you don't know), then call `mini_subagent`
+   again with the same `task` and your answers in `answers`. A new subagent is
+   spawned with the answers embedded.
+
+## Keybinding
+
+`Alt+S` toggles the panel. If your terminal intercepts that chord, pick a free
+one and change `PANEL_TOGGLE_CHORD` in `src/constants.ts`.
+
+## Skill
+
+The package ships a sample `subagent` skill (`skills/subagent/SKILL.md`),
+auto-loaded by pi. It teaches the agent when to delegate to `mini_subagent`,
+how to write self-contained tasks, and when to keep work in the main context.
+To install it manually (e.g. without the extension), copy that `SKILL.md` into
+`~/.pi/agent/skills/subagent/`.
+
+## License
+
+MIT — see [LICENSE](LICENSE). Copyright (c) 2026 Leonardo A. Alvarenga.

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@leo-alvarenga/pi-mini-subagents",
+  "version": "0.1.0",
+  "description": "Transient subagents for Pi: mini_subagent tool (single + parallel), /subagents command, and a live TUI panel",
+  "license": "MIT",
+  "repository": "github.com/leo-alvarenga/pi-mono",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "pi-extension",
+    "pi-package",
+    "pi",
+    "subagent"
+  ],
+  "files": [
+    "src",
+    "skills",
+    "README.md",
+    "LICENSE",
+    "!src/*.test.ts"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^7.0.2"
+  },
+  "scripts": {
+    "build": "tsc --noEmit",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/skills/subagent/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: subagent
+description: Delegate independent or high-output work to transient subagents via the mini_subagent tool. Use when a task can be parallelized or would flood the main context with raw output (repo-wide scans, large files, multi-part research); subagents report back only their findings.
+---
+
+# Using Subagents
+
+The `mini_subagent` tool runs a transient headless `pi` process with its own
+isolated context window and returns only its findings. Use it to protect your
+main context and to parallelize independent work.
+
+## When to delegate
+
+- The task produces a lot of output you only need a summary of (large logs,
+  repo-wide greps, multi-file analysis).
+- Several independent questions that can run in parallel — one subagent per
+  module, provider, route, or issue.
+- Reading or analyzing big files whose raw bytes should not enter the main
+  context.
+
+## When NOT to delegate
+
+- A one-line answer you can get from a single `read`/`grep` yourself.
+- Work that depends on the main session's in-flight edits or reasoning — a
+  subagent starts fresh with no session memory.
+- Edits you must review carefully yourself: keep the subagent read-only and
+  make the changes in the main context.
+
+## Writing a good task
+
+- Make it self-contained: state the goal, the files or directories, and the
+  exact shape of the answer you want back.
+- Use absolute or unambiguous paths — the subagent shares only a `cwd`, not
+  your current reasoning.
+- Ask for a summary, not a raw dump. That is the whole point.
+
+## Read-only by default
+
+Subagents can only `read`/`grep`/`find`/`ls` unless you set `allowWrite: true`.
+Prefer read-only: have the subagent report findings, then edit in the main
+context yourself.
+
+## Parallel mode
+
+Use `tasks` (array, max 8) when the work is independent. Run sequentially when
+tasks share state or depend on each other's results.
+
+## NEEDS_INPUT loop
+
+If a subagent returns `needs_input`, it cannot proceed. Answer its questions
+(ask the user if you don't know), then re-call with the same `task` and your
+answers in `answers`. Never guess.

package/src/command.ts

@@ -0,0 +1,71 @@
+import type { ExtensionAPI, Theme } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+
+import { REPORT_ENTRY } from "./constants";
+import type { SubagentStore } from "./state";
+import type { SubagentRecord } from "./types";
+import { getStyledSubagent } from "./utils";
+
+function renderReport(records: SubagentRecord[], theme: Theme): string {
+  if (records.length === 0) return `  ${theme.fg("dim", "No subagents.")}`;
+
+  const lines: string[] = [];
+  const section = (label: string, items: SubagentRecord[]): void => {
+    if (items.length === 0) return;
+
+    lines.push(`  ${theme.fg("muted", `${label} (${items.length})`)}`);
+
+    for (const r of items) {
+      lines.push(getStyledSubagent(r, theme));
+    }
+
+    lines.push("");
+  };
+
+  section(
+    "Running",
+    records.filter((r) => r.status === "running"),
+  );
+
+  section(
+    "Needs input",
+    records.filter((r) => r.status === "needs_input"),
+  );
+
+  section(
+    "Completed",
+    records.filter((r) => r.status === "completed"),
+  );
+
+  section(
+    "Failed",
+    records.filter((r) => r.status === "failed"),
+  );
+
+  return lines.join("\n");
+}
+
+export function registerSubagentsCommand(
+  pi: ExtensionAPI,
+  store: SubagentStore,
+): void {
+  pi.registerCommand("subagents", {
+    description: "Show all subagents grouped by status",
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) {
+        ctx.ui.notify("/subagents requires interactive mode", "error");
+        return;
+      }
+
+      pi.appendEntry(REPORT_ENTRY, {
+        records: [...store.getState(ctx).records],
+      });
+    },
+  });
+
+  pi.registerEntryRenderer<{ records: SubagentRecord[] }>(
+    REPORT_ENTRY,
+    (entry, _options, theme) =>
+      new Text(renderReport(entry.data?.records ?? [], theme), 0, 0),
+  );
+}

package/src/constants.ts

@@ -0,0 +1,71 @@
+import type { KeyId } from "@earendil-works/pi-tui";
+import type { ThemeColor } from "@earendil-works/pi-coding-agent";
+
+import type { SubagentStatus } from "./types";
+
+export type SubagentStatusUi = {
+  icon: string;
+  fg: ThemeColor;
+  bold?: boolean;
+};
+
+export const STATUSES = [
+  "running",
+  "completed",
+  "failed",
+  "needs_input",
+] as const;
+
+export const STATUS_STYLES: Record<SubagentStatus, SubagentStatusUi> = {
+  running: { icon: "⏳ ", fg: "accent", bold: true },
+  completed: { icon: "✓ ", fg: "success" },
+  failed: { icon: "✗ ", fg: "error", bold: true },
+  needs_input: { icon: "? ", fg: "warning", bold: true },
+};
+
+/** Tool allowlist for a read-only subagent. */
+export const READ_ONLY_TOOLS = ["read", "grep", "find", "ls"];
+
+/** Tool allowlist for a write-capable subagent (hash-anchored ops first). */
+export const WRITE_TOOLS = [
+  "read",
+  "grep",
+  "find",
+  "ls",
+  "replace",
+  "insert",
+  "edit",
+  "write",
+];
+
+/** Marker the subagent emits when it cannot proceed without outside input. */
+export const NEEDS_INPUT_MARKER = "NEEDS_INPUT:";
+
+/** Max parallel tasks per call. */
+export const MAX_PARALLEL_TASKS = 8;
+/** Max concurrent subagent processes. */
+export const MAX_CONCURRENCY = 4;
+/** Per-task output byte cap for parallel results. */
+export const PER_TASK_OUTPUT_CAP = 50 * 1024;
+/** Max chars of final output kept in the stored record (TUI summary). */
+export const MAX_STORED_OUTPUT = 2000;
+
+/** Max task rows rendered in the expanded TUI widget. */
+export const MAX_PANEL_ROWS = 8;
+
+/** Widget key for the panel above the editor. */
+export const WIDGET_KEY = "subagents";
+
+/** Custom entry type carrying the durable state snapshot. */
+export const STATE_ENTRY = "subagents.state";
+
+/** Custom entry type rendered by the /subagents command. */
+export const REPORT_ENTRY = "subagents.report";
+
+/** Chord that toggles the panel. */
+export const PANEL_TOGGLE_CHORD: KeyId = "alt+s";
+
+export const PANEL_STATE_ICON = {
+  collapsed: "󰅂",
+  expanded: "󰅀",
+};

package/src/core.ts

@@ -0,0 +1,104 @@
+import {
+  MAX_STORED_OUTPUT,
+  NEEDS_INPUT_MARKER,
+  READ_ONLY_TOOLS,
+  WRITE_TOOLS,
+} from "./constants";
+import type { SubagentStatus } from "./types";
+
+const ALWAYS = "You are a transient subagent. Complete the task, then stop";
+const READ_ONLY = `You may only READ and EXPLORE. Do not modify files or run mutating commands.`;
+const WRITE_OK = `You may edit files ONLY if strictly necessary, preferring hash-anchored operations (replace/insert) over rewriting.`;
+
+const QUESTIONS_SUFFIX = `If the task cannot be completed without information you cannot obtain yourself, end your final message with the exact block below and stop — do not guess:
+
+${NEEDS_INPUT_MARKER}
+- <question>
+
+Report your findings clearly and concisely.`;
+
+/** Dynamic minimal prompt: read-only always; write permission added only when allowed. */
+export function buildSystemPrompt(allowWrite: boolean): string {
+  let prompt = ALWAYS;
+
+  if (!allowWrite) prompt += `\n\n${READ_ONLY}`;
+  else prompt += `\n\n${WRITE_OK}`;
+
+  return `${prompt}\n\n${QUESTIONS_SUFFIX}`;
+}
+
+/** Tool allowlist for the spawned child process. */
+export function buildAllowlist(allowWrite: boolean): string[] {
+  return allowWrite ? WRITE_TOOLS : READ_ONLY_TOOLS;
+}
+
+/**
+ * Extract the questions the subagent needs answered, if it emitted the
+ * NEEDS_INPUT block. Returns `[]` when the marker is present but no bullet
+ * lines follow, and `undefined` when the marker is absent.
+ */
+export function parseNeedsInput(text: string): string[] | undefined {
+  const lines = text.split("\n");
+  const idx = lines.findIndex((l) => l.trim() === NEEDS_INPUT_MARKER);
+  if (idx === -1) return undefined;
+
+  const questions: string[] = [];
+
+  for (const line of lines.slice(idx + 1)) {
+    const trimmed = line.trim();
+
+    if (trimmed.startsWith("- ")) {
+      const q = trimmed.slice(2).trim();
+      if (q) questions.push(q);
+    } else if (trimmed === "") {
+      continue;
+    } else {
+      break;
+    }
+  }
+
+  return questions;
+}
+
+/** Classify a finished subagent run into a record status. */
+export function classifyResult(opts: {
+  exitCode: number;
+  stopReason?: string;
+  needsInput: boolean;
+}): SubagentStatus {
+  if (opts.needsInput) return "needs_input";
+
+  if (
+    opts.exitCode !== 0 ||
+    opts.stopReason === "error" ||
+    opts.stopReason === "aborted"
+  ) {
+    return "failed";
+  }
+
+  return "completed";
+}
+
+/** Truncate a string to a char budget, appending an ellipsis marker. */
+export function truncateChars(text: string, max: number): string {
+  if (text.length <= max) return text;
+
+  return `${text.slice(0, max)}…`;
+}
+
+/** Truncate to a UTF-8 byte budget (for parallel per-task caps). */
+export function truncateBytes(text: string, maxBytes: number): string {
+  if (Buffer.byteLength(text, "utf8") <= maxBytes) return text;
+
+  let out = text.slice(0, maxBytes);
+  while (Buffer.byteLength(out, "utf8") > maxBytes) {
+    out = out.slice(0, -1);
+  }
+
+  return `${out}\n\n[Output truncated: ${Buffer.byteLength(text, "utf8") - Buffer.byteLength(out, "utf8")} bytes omitted.]`;
+}
+
+/** Final output kept in the stored record (TUI summary only). */
+export function summarizeOutput(text: string): string {
+  return truncateChars(text, MAX_STORED_OUTPUT);
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { registerSubagentsCommand } from "./command";
+import { STATE_ENTRY, WIDGET_KEY } from "./constants";
+import { killAllRunning } from "./spawn";
+import { SubagentStore } from "./state";
+import { registerMiniSubagentTool } from "./tool";
+import { registerSubagentWidget, refreshWidget } from "./widget";
+
+export default function (pi: ExtensionAPI): void {
+  // Child subagent processes inherit PI_SUBAGENT=1; they must not be able to
+  // spawn sub-subagents, so the tool/widget/command never register there.
+  if (process.env.PI_SUBAGENT) return;
+
+  const store = new SubagentStore(
+    (snapshot) => pi.appendEntry(STATE_ENTRY, snapshot),
+    (ctx) => refreshWidget(ctx, store),
+  );
+
+  registerMiniSubagentTool(pi, store);
+  registerSubagentsCommand(pi, store);
+  registerSubagentWidget(pi, store);
+
+  pi.on("session_start", (_event, ctx) => store.replay(ctx));
+  pi.on("session_tree", (_event, ctx) => store.replay(ctx));
+  pi.on("session_before_compact", (_event, ctx) => store.persistSnapshot(ctx));
+  pi.on("session_shutdown", (_event, ctx) => {
+    killAllRunning();
+    if (ctx.hasUI) ctx.ui.setWidget(WIDGET_KEY, undefined);
+  });
+}

package/src/spawn.ts

@@ -0,0 +1,202 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { buildAllowlist, buildSystemPrompt } from "./core";
+
+export interface SubagentUsage {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  cost: number;
+  contextTokens: number;
+  turns: number;
+}
+
+export interface SubagentRunResult {
+  /** Final assistant text from the subagent. */
+  output: string;
+  usage: SubagentUsage;
+  model?: string;
+  stopReason?: string;
+  errorMessage?: string;
+  exitCode: number;
+  stderr: string;
+  aborted: boolean;
+}
+
+const activeProcesses = new Set<ChildProcess>();
+
+/** Signal every still-running subagent process (session shutdown cleanup). */
+export function killAllRunning(): void {
+  for (const proc of activeProcesses) {
+    try {
+      proc.kill("SIGTERM");
+    } catch {
+      /* already gone */
+    }
+  }
+}
+
+/** Resolve the command that re-invokes pi (handles bun virtual scripts). */
+function getPiInvocation(args: string[]): { command: string; args: string[] } {
+  const currentScript = process.argv[1];
+  const isBunVirtualScript = currentScript?.startsWith("/$bunfs/root/");
+  if (currentScript && !isBunVirtualScript && fs.existsSync(currentScript)) {
+    return { command: process.execPath, args: [currentScript, ...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 };
+}
+
+async function writePromptTempFile(prompt: string): Promise<{ dir: string; filePath: string }> {
+  const dir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "pi-mini-subagent-"));
+  const filePath = path.join(dir, "prompt.md");
+  await fs.promises.writeFile(filePath, prompt, { encoding: "utf-8", mode: 0o600 });
+  return { dir, filePath };
+}
+
+/** Extract the last text part of an assistant message. */
+function extractText(msg: any): string {
+  const content = Array.isArray(msg?.content) ? msg.content : [];
+  for (let i = content.length - 1; i >= 0; i--) {
+    const part = content[i];
+    if (part?.type === "text" && typeof part.text === "string") return part.text;
+  }
+  return "";
+}
+
+export interface RunSubagentOptions {
+  cwd: string;
+  task: string;
+  allowWrite: boolean;
+  answers?: string;
+  signal?: AbortSignal;
+}
+
+/**
+ * Spawn a transient headless pi subprocess, stream its JSON events, and
+ * resolve with the final output once it exits.
+ */
+export async function runSubagent(opts: RunSubagentOptions): Promise<SubagentRunResult> {
+  const prompt = buildSystemPrompt(opts.allowWrite);
+  const { dir: tmpDir, filePath: tmpPath } = await writePromptTempFile(prompt);
+
+  const taskText = opts.answers
+    ? `Task: ${opts.task}\n\nAnswers from the user:\n${opts.answers}`
+    : `Task: ${opts.task}`;
+
+  const args = [
+    "--mode", "json",
+    "-p",
+    "--no-session",
+    "--tools", buildAllowlist(opts.allowWrite).join(","),
+    "--append-system-prompt", tmpPath,
+    taskText,
+  ];
+
+  const result: SubagentRunResult = {
+    output: "",
+    usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+    exitCode: 0,
+    stderr: "",
+    aborted: false,
+  };
+
+  try {
+    const exitCode = await new Promise<number>((resolve) => {
+      const invocation = getPiInvocation(args);
+      const proc = spawn(invocation.command, invocation.args, {
+        cwd: opts.cwd,
+        shell: false,
+        stdio: ["ignore", "pipe", "pipe"],
+        env: { ...process.env, PI_SUBAGENT: "1" },
+      });
+      activeProcesses.add(proc);
+
+      let buffer = "";
+      const processLine = (line: string) => {
+        if (!line.trim()) return;
+        let event: any;
+        try {
+          event = JSON.parse(line);
+        } catch {
+          return;
+        }
+
+        if (event.type === "message_end" && event.message) {
+          const msg = event.message;
+          if (msg.role === "assistant") {
+            result.usage.turns++;
+            const usage = msg.usage;
+            if (usage) {
+              result.usage.input += usage.input || 0;
+              result.usage.output += usage.output || 0;
+              result.usage.cacheRead += usage.cacheRead || 0;
+              result.usage.cacheWrite += usage.cacheWrite || 0;
+              result.usage.cost += usage.cost?.total || 0;
+              result.usage.contextTokens = usage.totalTokens || 0;
+            }
+            if (!result.model && msg.model) result.model = msg.model;
+            if (msg.stopReason) result.stopReason = msg.stopReason;
+            if (msg.errorMessage) result.errorMessage = msg.errorMessage;
+            result.output = extractText(msg);
+          }
+        }
+      };
+
+      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) => {
+        result.stderr += data.toString();
+      });
+
+      proc.on("close", (code) => {
+        activeProcesses.delete(proc);
+        if (buffer.trim()) processLine(buffer);
+        resolve(code ?? 0);
+      });
+
+      proc.on("error", () => {
+        activeProcesses.delete(proc);
+        resolve(1);
+      });
+
+      if (opts.signal) {
+        const kill = () => {
+          result.aborted = true;
+          proc.kill("SIGTERM");
+          setTimeout(() => {
+            try {
+              proc.kill("SIGKILL");
+            } catch {
+              /* already dead */
+            }
+          }, 5000);
+        };
+        if (opts.signal.aborted) kill();
+        else opts.signal.addEventListener("abort", kill, { once: true });
+      }
+    });
+
+    result.exitCode = exitCode;
+    if (result.aborted) result.stopReason = "aborted";
+    return result;
+  } finally {
+    try {
+      fs.unlinkSync(tmpPath);
+      fs.rmdirSync(tmpDir);
+    } catch {
+      /* ignore */
+    }
+  }
+}

package/src/state.ts

@@ -0,0 +1,88 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { STATE_ENTRY } from "./constants";
+import type { SubagentRecord, SubagentState } from "./types";
+
+/**
+ * Session-scoped subagent state.
+ *
+ * Keyed by session id so forked/parallel sessions never overwrite each other,
+ * and replayed from the session branch on session events so it survives
+ * /reload and compaction without the extension writing its own files.
+ * Running records are dropped on replay — their processes do not survive a reload.
+ */
+export class SubagentStore {
+  private readonly stateBySession = new Map<string, SubagentState>();
+
+  constructor(
+    private readonly persist: (snapshot: SubagentState) => void,
+    private readonly emitChange: (ctx: ExtensionContext) => void,
+  ) {}
+
+  private sid(ctx: ExtensionContext): string {
+    return ctx.sessionManager.getSessionId();
+  }
+
+  getState(ctx: ExtensionContext): SubagentState {
+    const sid = this.sid(ctx);
+    let s = this.stateBySession.get(sid);
+    if (!s) this.stateBySession.set(sid, (s = { records: [], nextId: 1 }));
+    return s;
+  }
+
+  /** Commit a snapshot: update memory, persist, refresh the panel. */
+  commit(ctx: ExtensionContext, next: SubagentState): void {
+    this.stateBySession.set(this.sid(ctx), next);
+    this.persist(next);
+    this.emitChange(ctx);
+  }
+
+  /** Create a `running` record and commit it. */
+  start(ctx: ExtensionContext, task: string, allowWrite: boolean, cwd?: string): SubagentRecord {
+    const s = this.getState(ctx);
+    const record: SubagentRecord = {
+      id: s.nextId,
+      task,
+      status: "running",
+      allowWrite,
+      cwd,
+      startedAt: Date.now(),
+    };
+    this.commit(ctx, { records: [...s.records, record], nextId: s.nextId + 1 });
+    return record;
+  }
+
+  /** Patch an existing record in place and commit. */
+  finish(ctx: ExtensionContext, id: number, patch: Partial<SubagentRecord>): void {
+    const s = this.getState(ctx);
+    this.commit(ctx, {
+      records: s.records.map((r) => (r.id === id ? { ...r, ...patch } : r)),
+      nextId: s.nextId,
+    });
+  }
+
+  /** Rebuild the current session's state from the branch (no disk writes). */
+  replay(ctx: ExtensionContext): void {
+    const s = this.getState(ctx);
+    s.records = [];
+    s.nextId = 1;
+
+    for (const entry of ctx.sessionManager.getBranch()) {
+      if (entry.type === "custom" && entry.customType === STATE_ENTRY) {
+        const d = entry.data as SubagentState | undefined;
+        if (d) {
+          s.records = d.records.filter((r) => r.status !== "running");
+          s.nextId = d.nextId;
+        }
+      }
+    }
+
+    this.emitChange(ctx);
+  }
+
+  /** Persist the latest snapshot right before compaction so it lands after the cut point. */
+  persistSnapshot(ctx: ExtensionContext): void {
+    const s = this.getState(ctx);
+    if (s.records.length > 0) this.persist(s);
+  }
+}

package/src/tool.ts

@@ -0,0 +1,321 @@
+import { Type } from "typebox";
+import type {
+  AgentToolResult,
+  ExtensionAPI,
+} from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+
+import {
+  MAX_CONCURRENCY,
+  MAX_PARALLEL_TASKS,
+  PER_TASK_OUTPUT_CAP,
+} from "./constants";
+import {
+  classifyResult,
+  parseNeedsInput,
+  summarizeOutput,
+  truncateBytes,
+} from "./core";
+import { runSubagent } from "./spawn";
+import type { SubagentStore } from "./state";
+import type { SubagentDetails, SubagentRecord } from "./types";
+
+const TaskItem = Type.Object({
+  task: Type.String({ description: "Task to delegate to a subagent" }),
+  allowWrite: Type.Optional(
+    Type.Boolean({
+      description: "Allow the subagent to edit files. Default: false.",
+    }),
+  ),
+  answers: Type.Optional(
+    Type.String({
+      description: "Answers to a prior NEEDS_INPUT, for re-spawn of this task",
+    }),
+  ),
+  cwd: Type.Optional(
+    Type.String({ description: "Working directory for this subagent" }),
+  ),
+});
+
+const MiniSubagentParams = Type.Object({
+  task: Type.Optional(
+    Type.String({ description: "Task to delegate (single mode)" }),
+  ),
+  tasks: Type.Optional(
+    Type.Array(TaskItem, {
+      description: "Tasks to delegate in parallel (max 8)",
+    }),
+  ),
+  allowWrite: Type.Optional(
+    Type.Boolean({
+      description: "Allow write for single mode. Default: false.",
+    }),
+  ),
+  answers: Type.Optional(
+    Type.String({
+      description: "Answers to a prior NEEDS_INPUT (single mode re-spawn)",
+    }),
+  ),
+  cwd: Type.Optional(
+    Type.String({ description: "Working directory (single mode)" }),
+  ),
+});
+
+async function mapWithConcurrencyLimit<TIn, TOut>(
+  items: TIn[],
+  concurrency: number,
+  fn: (item: TIn, index: number) => Promise<TOut>,
+): Promise<TOut[]> {
+  if (items.length === 0) return [];
+
+  const limit = Math.max(1, Math.min(concurrency, items.length));
+  const results = new Array<TOut>(items.length);
+
+  let next = 0;
+  const workers = new Array(limit).fill(null).map(async () => {
+    while (true) {
+      const i = next++;
+      if (i >= items.length) return;
+      results[i] = await fn(items[i], i);
+    }
+  });
+
+  await Promise.all(workers);
+  return results;
+}
+
+function needsInputContent(r: SubagentRecord): string {
+  const qs = (r.questions ?? []).map((q) => `- ${q}`).join("\n");
+
+  return `The subagent needs input to complete this task.\n\nQuestions:\n${qs || "- (unparsed)"}\n\nAsk the user (or answer from context), then call mini_subagent again with the same \`task\` and your answers in \`answers\`.`;
+}
+
+function singleContent(r: SubagentRecord): string {
+  if (r.status === "needs_input") return needsInputContent(r);
+
+  if (r.status === "failed") {
+    return `Subagent failed: ${r.error ?? r.output ?? "(no output)"}`;
+  }
+
+  return r.output ?? "(no output)";
+}
+
+export function registerMiniSubagentTool(
+  pi: ExtensionAPI,
+  store: SubagentStore,
+): void {
+  pi.registerTool({
+    name: "mini_subagent",
+    label: "Mini Subagent",
+    parameters: MiniSubagentParams,
+    description:
+      "Delegate a task to a transient headless subagent (a separate pi process) and get its findings back. " +
+      "Modes: single (task) or parallel (tasks array, max 8). Subagents are read-only by default; set allowWrite to let one edit files. " +
+      "If a subagent reports it needs input (NEEDS_INPUT), answer the questions and call again with `answers`.",
+    promptSnippet:
+      "Delegate a task to a transient read-only subagent (single or parallel)",
+    promptGuidelines: [
+      "Subagents are read-only unless you set allowWrite: true.",
+      "If a result asks for input, answer the questions (ask the user if needed) and re-call with `answers` — do not guess.",
+    ],
+
+    async execute(_toolCallId, params, signal, onUpdate, ctx) {
+      const hasTasks = (params.tasks?.length ?? 0) > 0;
+      const hasSingle = Boolean(params.task);
+      const modeCount = Number(hasTasks) + Number(hasSingle);
+
+      const errorResult = (text: string): AgentToolResult<SubagentDetails> => ({
+        content: [{ type: "text", text }],
+        details: { mode: hasTasks ? "parallel" : "single", records: [] },
+      });
+
+      if (modeCount !== 1) {
+        return errorResult(
+          "Provide exactly one of `task` (single) or `tasks` (parallel).",
+        );
+      }
+
+      // --- single mode ---
+      if (hasSingle) {
+        const record = store.start(
+          ctx,
+          params.task!,
+          params.allowWrite ?? false,
+          params.cwd,
+        );
+
+        const run = await runSubagent({
+          cwd: params.cwd ?? ctx.cwd,
+          task: params.task!,
+          allowWrite: params.allowWrite ?? false,
+          answers: params.answers,
+          signal,
+        });
+
+        const needsInput = parseNeedsInput(run.output);
+
+        const status = classifyResult({
+          exitCode: run.exitCode,
+          stopReason: run.stopReason,
+          needsInput: needsInput !== undefined,
+        });
+
+        const patch: Partial<SubagentRecord> = {
+          status,
+          output: summarizeOutput(run.output),
+          tokens: run.usage.contextTokens,
+          questions: needsInput,
+          error:
+            status === "failed"
+              ? run.errorMessage || run.stderr.slice(0, 500) || undefined
+              : undefined,
+          finishedAt: Date.now(),
+        };
+
+        store.finish(ctx, record.id, patch);
+        const final = { ...record, ...patch };
+
+        return {
+          content: [{ type: "text", text: singleContent(final) }],
+          details: {
+            mode: "single",
+            records: [final],
+          } satisfies SubagentDetails,
+        };
+      }
+
+      // --- parallel mode ---
+      const tasks = params.tasks!;
+      if (tasks.length > MAX_PARALLEL_TASKS) {
+        return errorResult(
+          `Too many parallel tasks (${tasks.length}). Max is ${MAX_PARALLEL_TASKS}.`,
+        );
+      }
+
+      const results: SubagentRecord[] = tasks.map((t) =>
+        store.start(ctx, t.task, t.allowWrite ?? false, t.cwd),
+      );
+      const makeDetails = (): SubagentDetails => ({
+        mode: "parallel",
+        records: [...results],
+      });
+      const emit = () => {
+        const running = results.filter((r) => r.status === "running").length;
+        const done = results.length - running;
+        onUpdate?.({
+          content: [
+            {
+              type: "text",
+              text: `Parallel: ${done}/${results.length} done, ${running} running…`,
+            },
+          ],
+          details: makeDetails(),
+        });
+      };
+
+      await mapWithConcurrencyLimit(
+        tasks,
+        MAX_CONCURRENCY,
+        async (t, index) => {
+          const run = await runSubagent({
+            cwd: t.cwd ?? ctx.cwd,
+            task: t.task,
+            allowWrite: t.allowWrite ?? false,
+            answers: t.answers,
+            signal,
+          });
+          const needsInput = parseNeedsInput(run.output);
+          const status = classifyResult({
+            exitCode: run.exitCode,
+            stopReason: run.stopReason,
+            needsInput: needsInput !== undefined,
+          });
+          const patch: Partial<SubagentRecord> = {
+            status,
+            output: summarizeOutput(run.output),
+            tokens: run.usage.contextTokens,
+            questions: needsInput,
+            error:
+              status === "failed"
+                ? run.errorMessage || run.stderr.slice(0, 500) || undefined
+                : undefined,
+            finishedAt: Date.now(),
+          };
+          results[index] = { ...results[index], ...patch };
+          store.finish(ctx, results[index].id, patch);
+          emit();
+        },
+      );
+
+      const successCount = results.filter(
+        (r) => r.status === "completed",
+      ).length;
+      const sections = results.map((r) => {
+        let body: string;
+        if (r.status === "completed")
+          body = truncateBytes(r.output ?? "", PER_TASK_OUTPUT_CAP);
+        else if (r.status === "needs_input")
+          body = `Needs input:\n${(r.questions ?? []).map((q) => `- ${q}`).join("\n")}`;
+        else body = r.error ?? "(no output)";
+        return `### #${r.id} ${r.status}\n${body}`;
+      });
+
+      let content = `Parallel: ${successCount}/${results.length} succeeded\n\n${sections.join("\n\n---\n\n")}`;
+      const blocked = results.filter((r) => r.status === "needs_input");
+      if (blocked.length > 0) {
+        content += `\n\nSome subagents need input. Answer their questions, then call mini_subagent again with \`tasks\` for just those tasks (each with its own \`answers\`):\n`;
+        content += blocked
+          .map(
+            (r) =>
+              `- #${r.id}: ${(r.questions ?? []).join(" / ") || "(unparsed)"}`,
+          )
+          .join("\n");
+      }
+
+      return {
+        content: [{ type: "text", text: content }],
+        details: makeDetails(),
+      };
+    },
+
+    renderCall(args, theme) {
+      if (args.tasks && args.tasks.length > 0) {
+        let text =
+          theme.fg("toolTitle", theme.bold("mini_subagent ")) +
+          theme.fg("accent", `parallel (${args.tasks.length} tasks)`);
+        for (const t of args.tasks.slice(0, 3)) {
+          const preview =
+            t.task.length > 40 ? `${t.task.slice(0, 40)}…` : t.task;
+          text += `\n  ${theme.fg("dim", preview)}${t.allowWrite ? theme.fg("warning", " ✎") : ""}`;
+        }
+        if (args.tasks.length > 3)
+          text += `\n  ${theme.fg("muted", `… +${args.tasks.length - 3} more`)}`;
+        return new Text(text, 0, 0);
+      }
+
+      const preview = args.task
+        ? args.task.length > 60
+          ? `${args.task.slice(0, 60)}…`
+          : args.task
+        : "...";
+      let text =
+        theme.fg("toolTitle", theme.bold("mini_subagent ")) +
+        theme.fg("dim", preview);
+      if (args.allowWrite) text += theme.fg("warning", " ✎");
+      return new Text(text, 0, 0);
+    },
+
+    renderResult(result, _options, theme) {
+      const details = result.details as SubagentDetails | undefined;
+      const text =
+        result.content[0]?.type === "text" ? result.content[0].text : "";
+      const statuses = details?.records.map((r) => r.status) ?? [];
+      const color = statuses.includes("failed")
+        ? "error"
+        : statuses.includes("needs_input")
+          ? "warning"
+          : "muted";
+      return new Text(theme.fg(color, text), 0, 0);
+    },
+  });
+}

package/src/types.ts

@@ -0,0 +1,28 @@
+export type SubagentStatus = "running" | "completed" | "failed" | "needs_input";
+
+export interface SubagentRecord {
+  id: number;
+  task: string;
+  cwd?: string;
+  startedAt: number;
+  allowWrite: boolean;
+  finishedAt?: number;
+  status: SubagentStatus;
+
+  /** Final output summary (truncated for storage). */
+  output?: string;
+  tokens?: number;
+  error?: string;
+  questions?: string[];
+}
+
+export interface SubagentState {
+  records: SubagentRecord[];
+  nextId: number;
+}
+
+/** Shape stored in the tool result `details` for rendering. */
+export interface SubagentDetails {
+  mode: "single" | "parallel";
+  records: SubagentRecord[];
+}

package/src/utils.ts

@@ -0,0 +1,98 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth } from "@earendil-works/pi-tui";
+
+import { MAX_PANEL_ROWS, PANEL_STATE_ICON, STATUS_STYLES } from "./constants";
+import type { SubagentRecord } from "./types";
+
+function formatTokens(n: number): string {
+  if (n < 1000) return `${n} tokens`;
+  if (n < 10000) return `${(n / 1000).toFixed(1)}k tokens`;
+
+  return `${Math.round(n / 1000)}k tokens`;
+}
+
+export function getStyledSubagent(r: SubagentRecord, th: Theme): string {
+  const style = STATUS_STYLES[r.status] ?? STATUS_STYLES.completed;
+  let line = `${th.fg(style.fg, style.icon)} ${th.fg("accent", `#${r.id}`)} ${th.fg(style.fg, r.task)}`;
+
+  if (r.status === "completed" && r.tokens) {
+    line += th.fg("dim", ` · ${formatTokens(r.tokens)}`);
+  }
+
+  if (r.status === "failed") line += th.fg("dim", " · failed");
+  if (r.status === "needs_input") line += th.fg("dim", " · needs input");
+  if (r.allowWrite) line += th.fg("warning", " ✎");
+
+  return line;
+}
+
+export function getStyledSubagentHeader(
+  records: SubagentRecord[],
+  th: Theme,
+  isCollapsed?: boolean,
+): string {
+  const running = records.filter((r) => r.status === "running").length;
+
+  const done = records.length - running;
+  const collapseState = isCollapsed ? "collapsed" : "expanded";
+
+  return th.fg(
+    "accent",
+    `${PANEL_STATE_ICON[collapseState]} ⏳ Subagents — ${running} running / ${done} done`,
+  );
+}
+
+export function getStyledSubagentList(
+  records: SubagentRecord[],
+  th: Theme,
+  width: number,
+  isCollapsed?: boolean,
+): string[] {
+  const indent = (str: string, level = 1) => "  ".repeat(Math.abs(level)) + str;
+
+  const lines: string[] = [
+    truncateToWidth(
+      indent(getStyledSubagentHeader(records, th, isCollapsed)),
+      width,
+    ),
+  ];
+
+  if (!isCollapsed) {
+    lines.push("");
+
+    if (records.length === 0) {
+      lines.push(
+        truncateToWidth(
+          indent(
+            th.fg("dim", "No subagents yet. Ask the agent to delegate a task!"),
+            2,
+          ),
+          width,
+        ),
+      );
+    } else {
+      const running = records.filter((r) => r.status === "running");
+      const finished = records.filter((r) => r.status !== "running");
+      const visible = [...running, ...finished].slice(0, MAX_PANEL_ROWS);
+
+      for (const r of visible) {
+        lines.push(truncateToWidth(indent(getStyledSubagent(r, th), 2), width));
+      }
+
+      if (records.length > visible.length) {
+        lines.push(
+          truncateToWidth(
+            indent(
+              th.fg("dim", `… +${records.length - visible.length} more`),
+              3,
+            ),
+            width,
+          ),
+        );
+      }
+    }
+  }
+
+  lines.push("");
+  return lines;
+}

package/src/widget.ts

@@ -0,0 +1,67 @@
+import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+
+import { PANEL_TOGGLE_CHORD, WIDGET_KEY } from "./constants";
+import type { SubagentStore } from "./state";
+import type { SubagentState } from "./types";
+import { getStyledSubagentList } from "./utils";
+
+let collapsed = true;
+
+class SubagentWidget {
+  private cachedWidth: number | undefined;
+  private cachedLines: string[] | undefined;
+
+  constructor(
+    private readonly theme: Theme,
+    private readonly snapshot: () => SubagentState,
+    private readonly isCollapsed: () => boolean,
+  ) {}
+
+  render(width: number): string[] {
+    if (this.snapshot().records.length === 0) return [];
+
+    if (this.cachedLines !== undefined && this.cachedWidth === width) {
+      return this.cachedLines;
+    }
+
+    const lines = getStyledSubagentList(
+      this.snapshot().records,
+      this.theme,
+      width,
+      this.isCollapsed(),
+    );
+
+    this.cachedWidth = width;
+    this.cachedLines = lines;
+    return lines;
+  }
+
+  invalidate(): void {
+    this.cachedWidth = undefined;
+    this.cachedLines = undefined;
+  }
+}
+
+export function refreshWidget(ctx: ExtensionContext, store: SubagentStore): void {
+  if (!ctx.hasUI) return;
+
+  ctx.ui.setWidget(
+    WIDGET_KEY,
+    (_tui, theme) =>
+      new SubagentWidget(
+        theme,
+        () => store.getState(ctx),
+        () => collapsed,
+      ),
+  );
+}
+
+export function registerSubagentWidget(pi: ExtensionAPI, store: SubagentStore): void {
+  pi.registerShortcut(PANEL_TOGGLE_CHORD, {
+    description: "Toggle subagents panel",
+    handler: (ctx) => {
+      collapsed = !collapsed;
+      refreshWidget(ctx, store);
+    },
+  });
+}