@pify/subagent 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pifydev
+
+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,37 @@
+# @pify/subagent
+
+Spawn scoped subagents from within a [pi](https://github.com/earendil-works/pi) session. One tool call, one focused child agent — with its own tool allowlist, model, thinking level, and turn cap.
+
+Part of the [Pify suite](https://github.com/pifydev). Install with [`pify install subagent`](https://github.com/pifydev/cli) or `pi install npm:@pify/subagent`.
+
+## What it does
+
+- **`agent_run`** — delegate a task to a child pi session (in-process, isolated in-memory transcript). Foreground blocks and returns the child's report; `background: true` returns an id immediately (up to 4 concurrent) with a live widget showing spinners, token counts, and elapsed time.
+- **`agent_result`** — collect a background run's report; completed results survive `/reload`.
+- **Three builtin agent types**: `reviewer` (read-only, thinking high — findings with evidence), `scout` (read-only exploration — paths + excerpts), `worker` (full tools — scoped implementation, verifies before finishing).
+- **Custom agent types**, Claude Code-compatible: drop `.pi/agents/<name>.md` (project) or `<agentDir>/agents/<name>.md` (global) with frontmatter — `description`, `tools`, `model` (`provider/id`), `thinking`, `max_turns` — and a system-prompt body. Project overrides global overrides builtin; a def without `tools:` defaults to read-only.
+- **Guardrails**: tool allowlists are enforced at session creation; children are aborted at their turn cap; children cannot spawn children.
+- `/agents` lists types and this session's runs.
+
+## Where this sits in the suite
+
+`@pify/subagent` is deliberately the primitive: one child, one task, one report. Multi-agent coordination belongs to `@pify/swarm`; deterministic scripted orchestration to `@pify/workflow`.
+
+## Custom agent example
+
+```markdown
+---
+description: Security auditor for diffs
+tools: read, grep, find, ls
+model: anthropic/claude-haiku-4-5-20251001
+thinking: low
+max_turns: 15
+---
+
+You are a security auditor. Scan for hardcoded secrets, injection flaws,
+and overly broad permissions. Report file:line with remediation notes.
+```
+
+## License
+
+MIT © [Pify maintainers](https://github.com/pifydev)

package/extensions/subagent.ts

@@ -0,0 +1,317 @@
+/**
+ * @pify/subagent — spawn scoped subagents from within a pi session.
+ *
+ * The foundation layer of the Pify agent stack: one tool call spawns one
+ * child pi session (in-process, createAgentSession) with an agent type's
+ * tool allowlist, model/thinking overrides, and turn cap. Foreground runs
+ * block and return the child's report; background runs stream into a small
+ * widget and are collected with agent_result. Agent types are Claude
+ * Code-compatible markdown files (project > global > builtin); three
+ * builtins ship: reviewer, scout, worker.
+ *
+ * Coordination of many agents belongs to @pify/swarm; scripted orchestration
+ * to @pify/workflow — this package deliberately stays the primitive.
+ *
+ * Design synthesis: in-process runner + Claude Code tool shapes
+ * (tintinweb/pi-subagents), agent archetypes + md definitions
+ * (nicobailon/pi-subagents), sub-session mechanics proven in @pify/btw.
+ */
+import {
+  createAgentSession,
+  DefaultResourceLoader,
+  getAgentDir,
+  SessionManager,
+  type AgentSession,
+  type ExtensionAPI,
+  type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+
+import { loadAgentDefs } from "../src/defs.ts";
+import { CHILD_FRAMING, buildTaskPrompt, describeDefs, formatRunResult } from "../src/prompts.ts";
+import { buildWidgetLines } from "../src/widget.ts";
+import {
+  MAX_CONCURRENT_BACKGROUND,
+  isRecord,
+  type AgentDef,
+  type RunState,
+} from "../src/types.ts";
+
+const RESULT_ENTRY = "subagent-result";
+
+type UiContext = ExtensionContext;
+
+export default function subagent(pi: ExtensionAPI) {
+  let defs = new Map<string, AgentDef>();
+  const runs = new Map<string, RunState>();
+  const counters = new Map<string, number>();
+  let lastUiCtx: UiContext | null = null;
+
+  // ── UI ───────────────────────────────────────────────────────────────
+
+  function renderWidget(ctx: UiContext | null = lastUiCtx): void {
+    if (!ctx || !ctx.hasUI) return;
+    lastUiCtx = ctx;
+    const now = Date.now();
+    const anyVisible = [...runs.values()].some(
+      (r) => r.status === "running" || (r.finishedAt ?? 0) > now - 15_000,
+    );
+    if (!anyVisible) {
+      ctx.ui.setWidget("subagent", undefined);
+      return;
+    }
+    ctx.ui.setWidget(
+      "subagent",
+      (_tui: unknown, theme: { fg(c: string, s: string): string; bold(s: string): string }) =>
+        new Text(buildWidgetLines([...runs.values()], theme, Date.now()).join("\n"), 0, 0),
+      { placement: "aboveEditor" },
+    );
+  }
+
+  function notify(ctx: UiContext, message: string, level: "info" | "warning" | "error"): void {
+    if (ctx.hasUI) ctx.ui.notify(message, level);
+  }
+
+  // ── Child runner ─────────────────────────────────────────────────────
+
+  function nextId(agent: string): string {
+    const n = (counters.get(agent) ?? 0) + 1;
+    counters.set(agent, n);
+    return `${agent}-${n}`;
+  }
+
+  async function runChild(ctx: UiContext, def: AgentDef, run: RunState): Promise<void> {
+    let session: AgentSession | null = null;
+    let unsubscribe: (() => void) | null = null;
+    try {
+      let model = ctx.model ?? null;
+      if (def.model) {
+        const [provider, ...rest] = def.model.split("/");
+        const found =
+          provider && rest.length > 0 ? ctx.modelRegistry.find(provider, rest.join("/")) : undefined;
+        if (found) model = found;
+        else notify(ctx, `subagent ${run.id}: model ${def.model} not found — using session model`, "warning");
+      }
+      if (!model) throw new Error("No model available");
+
+      // getSystemPromptOptions lives on the command context; tool contexts may
+      // carry it at runtime — probe structurally, fall back to the defaults.
+      const promptHost = ctx as unknown as {
+        getSystemPromptOptions?: () => { customPrompt?: string; appendSystemPrompt?: string };
+      };
+      const promptOptions = promptHost.getSystemPromptOptions?.() ?? {};
+      const created = await createAgentSession({
+        sessionManager: SessionManager.inMemory(ctx.cwd),
+        model,
+        thinkingLevel: (def.thinking ?? pi.getThinkingLevel()) as never,
+        tools: def.tools,
+        resourceLoader: new DefaultResourceLoader({
+          cwd: ctx.cwd,
+          agentDir: getAgentDir(),
+          noExtensions: true,
+          noPromptTemplates: true,
+          noThemes: true,
+          systemPrompt: promptOptions.customPrompt,
+          appendSystemPrompt: [
+            ...(promptOptions.appendSystemPrompt ? [promptOptions.appendSystemPrompt] : []),
+            def.systemPrompt,
+            CHILD_FRAMING,
+          ],
+        }),
+      });
+      session = created.session;
+
+      unsubscribe = session.subscribe((event) => {
+        if (event.type === "message_end" && (event as { message?: { role?: string } }).message?.role === "assistant") {
+          run.turns++;
+          const usage = (event as { message?: { usage?: { totalTokens?: number } } }).message?.usage;
+          if (usage && typeof usage.totalTokens === "number") run.tokens += usage.totalTokens;
+          renderWidget();
+          if (run.turns >= def.maxTurns) {
+            void session?.abort().catch(() => {});
+          }
+        }
+      });
+
+      await session.prompt(buildTaskPrompt(run.task), { source: "extension" } as never);
+
+      const messages = session.messages as Array<{
+        role?: string;
+        stopReason?: unknown;
+        content?: Array<{ type?: string; text?: string }>;
+      }>;
+      const last = [...messages].reverse().find((m) => m.role === "assistant");
+      const text = (last?.content ?? [])
+        .filter((c) => c.type === "text" && typeof c.text === "string")
+        .map((c) => c.text)
+        .join("\n")
+        .trim();
+
+      run.result = text || null;
+      run.status =
+        last?.stopReason === "aborted" ? "aborted" : last?.stopReason === "error" ? "error" : "done";
+      if (run.status === "error") run.error = text || "child session error";
+    } catch (err) {
+      run.status = "error";
+      run.error = err instanceof Error ? err.message : String(err);
+    } finally {
+      run.finishedAt = Date.now();
+      if (unsubscribe) {
+        try {
+          unsubscribe();
+        } catch {
+          // gone
+        }
+      }
+      if (session) {
+        try {
+          session.dispose();
+        } catch {
+          // double-dispose fine
+        }
+      }
+      pi.appendEntry(RESULT_ENTRY, run);
+      renderWidget();
+    }
+  }
+
+  // ── Tools ────────────────────────────────────────────────────────────
+
+  pi.registerTool({
+    name: "agent_run",
+    label: "Run subagent",
+    description:
+      "Delegate one scoped task to a child agent. agent: reviewer (read-only review), scout " +
+      "(read-only exploration/research), worker (full tools, implements a task), or a custom type " +
+      "from .pi/agents/. background=false (default) blocks and returns the child's report; " +
+      "background=true returns an id immediately — collect it later with agent_result. " +
+      "Write the task as a complete, self-contained brief: the child sees none of this conversation.",
+    parameters: Type.Object({
+      agent: Type.String({ description: "Agent type name" }),
+      task: Type.String({ description: "Complete task brief for the child" }),
+      background: Type.Optional(Type.Boolean({ description: "Run without blocking (default false)" })),
+    }),
+    async execute(
+      _id,
+      params: { agent: string; task: string; background?: boolean },
+      _signal,
+      _onUpdate,
+      ctx,
+    ) {
+      const def = defs.get(params.agent.trim().toLowerCase());
+      if (!def) {
+        throw new Error(
+          `Unknown agent type "${params.agent}". Available: ${[...defs.keys()].sort().join(", ")}`,
+        );
+      }
+      if (!params.task.trim()) throw new Error("agent_run requires a non-empty task.");
+
+      const uiCtx = ctx as UiContext;
+      const background = params.background === true;
+      const active = [...runs.values()].filter((r) => r.status === "running").length;
+      if (background && active >= MAX_CONCURRENT_BACKGROUND) {
+        throw new Error(
+          `Too many background agents running (${active}/${MAX_CONCURRENT_BACKGROUND}). Collect results first or run foreground.`,
+        );
+      }
+
+      const run: RunState = {
+        id: nextId(def.name),
+        agent: def.name,
+        task: params.task.trim(),
+        background,
+        status: "running",
+        startedAt: Date.now(),
+        finishedAt: null,
+        tokens: 0,
+        turns: 0,
+        result: null,
+        error: null,
+      };
+      runs.set(run.id, run);
+      renderWidget(uiCtx);
+
+      if (background) {
+        void runChild(uiCtx, def, run).then(() => {
+          notify(uiCtx, `subagent ${run.id}: ${run.status}`, run.status === "done" ? "info" : "warning");
+        });
+        return {
+          content: [
+            { type: "text", text: `Started ${run.id} in the background. Collect with agent_result id="${run.id}".` },
+          ],
+          details: { id: run.id },
+        };
+      }
+
+      await runChild(uiCtx, def, run);
+      return {
+        content: [{ type: "text", text: formatRunResult(run) }],
+        details: { id: run.id, status: run.status, tokens: run.tokens },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "agent_result",
+    label: "Subagent result",
+    description: "Fetch the report of a background subagent by id (from agent_run).",
+    parameters: Type.Object({
+      id: Type.String({ description: "Run id, e.g. reviewer-1" }),
+    }),
+    async execute(_id, params: { id: string }) {
+      const run = runs.get(params.id.trim());
+      if (!run) {
+        const known = [...runs.keys()].sort().join(", ") || "(none this session)";
+        throw new Error(`No run "${params.id}". Known runs: ${known}`);
+      }
+      return {
+        content: [{ type: "text", text: formatRunResult(run) }],
+        details: { id: run.id, status: run.status },
+      };
+    },
+  });
+
+  // ── Lifecycle ────────────────────────────────────────────────────────
+
+  pi.on("session_start", async (_event, ctx) => {
+    defs = loadAgentDefs(ctx.cwd, getAgentDir());
+    // Completed runs from earlier in this session's branch are replayable so
+    // agent_result keeps working after /reload. Running ones did not survive.
+    runs.clear();
+    for (const entry of ctx.sessionManager.getBranch()) {
+      const e = entry as { type?: string; customType?: string; data?: unknown };
+      if (e.type !== "custom" || e.customType !== RESULT_ENTRY || !isRecord(e.data)) continue;
+      const data = e.data as unknown as RunState;
+      if (typeof data.id === "string" && data.status !== "running") runs.set(data.id, data);
+    }
+    renderWidget(ctx);
+  });
+
+  pi.on("session_shutdown", async (_event, ctx) => {
+    for (const run of runs.values()) {
+      if (run.status === "running") {
+        run.status = "aborted";
+        run.finishedAt = Date.now();
+      }
+    }
+    if (ctx.hasUI) ctx.ui.setWidget("subagent", undefined);
+  });
+
+  // ── Command ──────────────────────────────────────────────────────────
+
+  pi.registerCommand("agents", {
+    description: "List subagent types and this session's runs",
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) return;
+      const runLines =
+        [...runs.values()]
+          .map((r) => `${r.id}: ${r.status} (${r.turns} turns, ${r.tokens} tok)`)
+          .join("\n") || "(no runs yet)";
+      ctx.ui.notify(
+        `Agent types\n${describeDefs([...defs.values()])}\n\nRuns\n${runLines}\n\nCustom types: .pi/agents/<name>.md`,
+        "info",
+      );
+    },
+  });
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@pify/subagent",
+  "version": "0.1.0",
+  "description": "Spawn scoped subagents from within a pi session: agent_run/agent_result tools, Claude Code-compatible agent types, turn caps and tool allowlists",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "pify",
+    "subagent",
+    "agents"
+  ],
+  "homepage": "https://github.com/pifydev/subagent#readme",
+  "bugs": {
+    "url": "https://github.com/pifydev/subagent/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pifydev/subagent.git"
+  },
+  "license": "MIT",
+  "author": "Pify maintainers",
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "files": [
+    "extensions",
+    "src",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": ["./extensions/subagent.ts"],
+    "skills": ["./skills"]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "npm run typecheck && npm test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": { "optional": true },
+    "@earendil-works/pi-tui": { "optional": true },
+    "typebox": { "optional": true }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.4",
+    "@earendil-works/pi-tui": "^0.84.4",
+    "@types/node": "^22.10.2",
+    "typebox": "^1.1.38",
+    "typescript": "^5.7.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/subagent/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: subagent
+description: Use when a task benefits from delegation to a focused child agent - code review by fresh eyes, parallel read-only research, or a scoped implementation task - explains agent_run/agent_result and how to write good task briefs
+---
+
+# Subagents
+
+This project has the `@pify/subagent` extension installed: `agent_run` spawns
+one child pi session per call, `agent_result` collects background runs.
+
+## When to delegate
+
+- **reviewer** — a diff, plan, or module needs fresh eyes; read-only, reports
+  findings with evidence. Great right after you finish a change.
+- **scout** — you need facts from elsewhere in the codebase without spending
+  your own context reading files; read-only, returns paths + excerpts.
+- **worker** — a well-scoped implementation task can proceed independently;
+  full tools. Only delegate what you can specify completely.
+
+Do not delegate trivial lookups (read the file yourself) or tasks whose
+requirements you cannot state precisely.
+
+## Writing the task brief
+
+The child sees NONE of this conversation. The brief must be self-contained:
+- the goal and its boundaries (what NOT to touch),
+- relevant file paths you already know,
+- the expected deliverable shape ("report findings as file:line + why").
+
+## Foreground vs background
+
+- Default (foreground) blocks and returns the report — use when you need the
+  answer to continue.
+- `background: true` returns an id immediately — use for work that can run
+  while you continue; collect with `agent_result` before relying on it. At
+  most 4 background runs at once.
+
+Custom agent types: `.pi/agents/<name>.md` (description/tools/model/thinking/
+max_turns frontmatter + system-prompt body) — project overrides global
+overrides builtin.

package/src/builtin.ts

@@ -0,0 +1,48 @@
+/**
+ * Built-in agent types (adapted from nicobailon/pi-subagents' agent set,
+ * trimmed to three archetypes). Overridable: a project or global .md file
+ * with the same name wins.
+ */
+
+export const BUILTIN_AGENTS: Record<string, string> = {
+  reviewer: `---
+description: Read-only review specialist for diffs, plans, and code health
+tools: read, grep, find, ls
+thinking: high
+max_turns: 25
+---
+
+You are a disciplined review subagent. Inspect, evaluate, and report findings
+with evidence — never guess; verify from the code itself. You cannot modify
+anything: your deliverable is the report.
+
+For each finding give: file:line, what is wrong, why it matters, and a
+concrete suggestion. Rank findings by severity. If the code is fine, say so
+plainly — do not invent issues. End with a one-paragraph verdict.`,
+
+  scout: `---
+description: Fast read-only exploration and research across the codebase
+tools: read, grep, find, ls
+thinking: low
+max_turns: 25
+---
+
+You are a scout subagent: locate, map, and summarize — quickly. Answer the
+question with file paths and line references, quoting only the smallest
+relevant excerpts. Prefer breadth over depth unless asked otherwise. If
+something cannot be found, report exactly what you searched so the caller
+can redirect you. Your final message is the entire deliverable.`,
+
+  worker: `---
+description: Implementation agent with full tool access for a scoped task
+tools: read, bash, edit, write, grep, find, ls
+thinking: medium
+max_turns: 60
+---
+
+You are a worker subagent implementing one scoped task. Stay strictly within
+the task's boundaries: no drive-by refactors, no scope creep. Follow the
+project's existing conventions. Verify your work (build, tests, or a smoke
+check) before finishing. Your final message must state exactly what changed,
+what you verified, and anything you deliberately left undone.`,
+};

package/src/defs.ts

@@ -0,0 +1,43 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { basename, join } from "node:path";
+import { BUILTIN_AGENTS } from "./builtin.ts";
+import { parseAgentFile } from "./frontmatter.ts";
+import type { AgentDef } from "./types.ts";
+
+function loadDir(dir: string, source: "global" | "project"): AgentDef[] {
+  let files: string[];
+  try {
+    files = readdirSync(dir).filter((f) => f.endsWith(".md"));
+  } catch {
+    return [];
+  }
+  const defs: AgentDef[] = [];
+  for (const file of files) {
+    try {
+      const def = parseAgentFile(
+        basename(file, ".md"),
+        readFileSync(join(dir, file), "utf8"),
+        source,
+      );
+      if (def) defs.push(def);
+    } catch {
+      // unreadable file — skip
+    }
+  }
+  return defs;
+}
+
+/**
+ * Load all agent definitions. Precedence per name:
+ * project (.pi/agents/) > global (<agentDir>/agents/) > builtin.
+ */
+export function loadAgentDefs(cwd: string, agentDir: string): Map<string, AgentDef> {
+  const defs = new Map<string, AgentDef>();
+  for (const [name, content] of Object.entries(BUILTIN_AGENTS)) {
+    const def = parseAgentFile(name, content, "builtin");
+    if (def) defs.set(def.name, def);
+  }
+  for (const def of loadDir(join(agentDir, "agents"), "global")) defs.set(def.name, def);
+  for (const def of loadDir(join(cwd, ".pi", "agents"), "project")) defs.set(def.name, def);
+  return defs;
+}

package/src/frontmatter.ts

@@ -0,0 +1,71 @@
+import {
+  DEFAULT_MAX_TURNS,
+  THINKING_LEVELS,
+  VALID_TOOLS,
+  type AgentDef,
+  type ThinkingLevelName,
+  type ValidTool,
+} from "./types.ts";
+
+/**
+ * Parse a Claude Code-compatible agent definition file:
+ * `---` frontmatter with description / tools / model / thinking / max_turns,
+ * body = system prompt. Line-based parser — no YAML dependency; unknown keys
+ * are ignored, invalid values fall back to safe defaults.
+ */
+export function parseAgentFile(
+  name: string,
+  content: string,
+  source: AgentDef["source"],
+): AgentDef | null {
+  const normalized = content.replace(/\r\n/g, "\n");
+  const match = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(normalized);
+  if (!match) return null;
+
+  const fields = new Map<string, string>();
+  for (const line of match[1]!.split("\n")) {
+    const kv = /^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/.exec(line.trim());
+    if (kv) fields.set(kv[1]!.toLowerCase(), kv[2]!.trim());
+  }
+
+  const description = fields.get("description") ?? "";
+  if (!description) return null;
+
+  const tools = parseTools(fields.get("tools"));
+  const thinkingRaw = fields.get("thinking")?.toLowerCase();
+  const thinking = (THINKING_LEVELS as readonly string[]).includes(thinkingRaw ?? "")
+    ? (thinkingRaw as ThinkingLevelName)
+    : null;
+
+  const maxTurnsRaw = Number.parseInt(fields.get("max_turns") ?? "", 10);
+  const maxTurns =
+    Number.isFinite(maxTurnsRaw) && maxTurnsRaw > 0 && maxTurnsRaw <= 200
+      ? maxTurnsRaw
+      : DEFAULT_MAX_TURNS;
+
+  const model = fields.get("model") || null;
+
+  return {
+    name: name.toLowerCase(),
+    description,
+    tools,
+    model,
+    thinking,
+    maxTurns,
+    systemPrompt: match[2]!.trim(),
+    source,
+  };
+}
+
+/** Read-only default keeps a def missing `tools:` from mutating anything. */
+function parseTools(raw: string | undefined): ValidTool[] {
+  if (!raw) return ["read", "grep", "find", "ls"];
+  const requested = raw
+    .split(",")
+    .map((t) => t.trim().toLowerCase())
+    .filter(Boolean);
+  const valid = requested.filter((t): t is ValidTool =>
+    (VALID_TOOLS as readonly string[]).includes(t),
+  );
+  return valid.length > 0 ? valid : ["read", "grep", "find", "ls"];
+}

package/src/prompts.ts

@@ -0,0 +1,31 @@
+import type { AgentDef, RunState } from "./types.ts";
+
+/** Framing appended to every child's system prompt after the def body. */
+export const CHILD_FRAMING = [
+  "You are a subagent running a single delegated task inside another agent's session.",
+  "Your final assistant message IS the deliverable returned to the caller —",
+  "make it a complete, self-contained report; do not ask follow-up questions.",
+].join(" ");
+
+/** The task prompt sent to the child session. */
+export function buildTaskPrompt(task: string): string {
+  return task.trim();
+}
+
+/** Tool-result text returned to the parent model for a finished run. */
+export function formatRunResult(run: RunState): string {
+  const header = `[${run.agent} · ${run.id} · ${run.status} · ${run.turns} turns]`;
+  if (run.status === "done" && run.result) return `${header}\n${run.result}`;
+  if (run.status === "error") return `${header}\nError: ${run.error ?? "unknown failure"}`;
+  if (run.status === "aborted") {
+    return `${header}\nAborted (turn limit or user stop). Partial output:\n${run.result ?? "(none)"}`;
+  }
+  return `${header}\nStill running — call agent_result with id "${run.id}" later.`;
+}
+
+/** Summary for /agents. */
+export function describeDefs(defs: AgentDef[]): string {
+  return defs
+    .map((d) => `${d.name} (${d.source}) — ${d.description} [${d.tools.join(", ")}]`)
+    .join("\n");
+}

package/src/types.ts

@@ -0,0 +1,77 @@
+/**
+ * Local structural types for @pify/subagent.
+ * No imports from pi packages: src/ typechecks and runs standalone.
+ */
+
+export const VALID_TOOLS = [
+  "read",
+  "bash",
+  "powershell",
+  "edit",
+  "write",
+  "grep",
+  "find",
+  "ls",
+] as const;
+export type ValidTool = (typeof VALID_TOOLS)[number];
+
+export type ThinkingLevelName = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+export const THINKING_LEVELS: readonly ThinkingLevelName[] = [
+  "off",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+];
+
+/** A parsed agent definition (from builtin constants or *.md files). */
+export interface AgentDef {
+  name: string;
+  description: string;
+  tools: ValidTool[];
+  /** "provider/model-id" or null to inherit the session model. */
+  model: string | null;
+  thinking: ThinkingLevelName | null;
+  /** Assistant round-trips before the child is aborted. */
+  maxTurns: number;
+  /** Markdown body appended to the child's system prompt. */
+  systemPrompt: string;
+  source: "builtin" | "global" | "project";
+}
+
+export const DEFAULT_MAX_TURNS = 30;
+export const MAX_CONCURRENT_BACKGROUND = 4;
+
+export type RunStatus = "running" | "done" | "error" | "aborted";
+
+export interface RunState {
+  id: string;
+  agent: string;
+  task: string;
+  background: boolean;
+  status: RunStatus;
+  startedAt: number;
+  finishedAt: number | null;
+  tokens: number;
+  turns: number;
+  result: string | null;
+  error: string | null;
+}
+
+export interface ThemeLike {
+  fg(color: string, text: string): string;
+  bold(text: string): string;
+}
+
+export interface BranchEntryLike {
+  type?: string;
+  customType?: string;
+  data?: unknown;
+  [key: string]: unknown;
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/widget.ts

@@ -0,0 +1,60 @@
+import type { RunState, ThemeLike } from "./types.ts";
+
+const WIDTH = 54;
+
+function tokens(n: number): string {
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(1)}k`;
+  return String(n);
+}
+
+function elapsed(run: RunState, now: number): string {
+  const s = Math.max(0, Math.round(((run.finishedAt ?? now) - run.startedAt) / 1000));
+  if (s >= 60) return `${Math.floor(s / 60)}m ${s % 60}s`;
+  return `${s}s`;
+}
+
+function icon(status: RunState["status"]): string {
+  switch (status) {
+    case "running":
+      return "⟳";
+    case "done":
+      return "✓";
+    case "error":
+      return "✗";
+    case "aborted":
+      return "◼";
+  }
+}
+
+/**
+ * Widget above the editor listing active + recently finished runs.
+ * Empty when there is nothing to show.
+ */
+export function buildWidgetLines(runs: RunState[], theme: ThemeLike, now: number): string[] {
+  const visible = runs.filter((r) => r.status === "running" || (r.finishedAt ?? 0) > now - 15_000);
+  if (visible.length === 0) return [];
+
+  const dim = (s: string) => theme.fg("dim", s);
+  const lines: string[] = [];
+  const title = " 🤖 subagents ";
+  const hint = " /agents ";
+  const pad = Math.max(1, WIDTH - title.length - hint.length);
+  lines.push(dim(`╭${title}${"─".repeat(pad)}${hint}╮`));
+
+  for (const run of visible) {
+    const paint =
+      run.status === "running"
+        ? (s: string) => theme.fg("warning", s)
+        : run.status === "done"
+          ? (s: string) => theme.fg("success", s)
+          : (s: string) => theme.fg("error", s);
+    const head = paint(`${icon(run.status)} ${run.id}`);
+    const stats = dim(` · ${tokens(run.tokens)} tok · ${elapsed(run, now)}`);
+    const task = run.task.length > 30 ? `${run.task.slice(0, 30)}…` : run.task;
+    lines.push(`${dim("│ ")}${head}${stats} ${dim(task)}`);
+  }
+
+  lines.push(dim(`╰${"─".repeat(WIDTH)}╯`));
+  return lines;
+}