@leo-alvarenga/pi-mini-subagents 0.2.8 → 0.2.11

package/README.md

@@ -70,14 +70,6 @@ Tool parameters:
 `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

@@ -1,6 +1,6 @@
 {
   "name": "@leo-alvarenga/pi-mini-subagents",
-  "version": "0.2.8",
+  "version": "0.2.11",
   "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",
@@ -27,7 +27,7 @@
     "typebox": "*"
   },
   "dependencies": {
-    "@leo-alvarenga/pi-ext-core": "^0.4.1"
+    "@leo-alvarenga/pi-ext-core": "^0.4.3"
   },
   "pi": {
     "extensions": [

package/src/config.ts

@@ -0,0 +1,129 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import {
+  capitalize,
+  formatTokens,
+  type SubagentRecord,
+  type SubagentSpec,
+} from "@leo-alvarenga/pi-ext-core";
+
+import {
+  MAX_CONCURRENCY,
+  MAX_PANEL_ROWS,
+  MAX_PARALLEL_TASKS,
+  MAX_STORED_OUTPUT,
+  MAX_WRITES_PER_SUBAGENT,
+  NEEDS_INPUT_MARKER,
+  NEEDS_INPUT_SUFFIX,
+  PANEL_TOGGLE_CHORD,
+  PER_TASK_OUTPUT_CAP,
+  REPORT_ENTRY,
+  STATE_ENTRY,
+  STATUS_STYLES,
+  WIDGET_KEY,
+} from "./constants";
+
+function getStyledSubagent(r: SubagentRecord, th: Theme): string {
+  const task = r.task.replace(/\s*[\r\n]+\s*/g, " ");
+
+  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, 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 const SUBAGENTS_SPEC: SubagentSpec = {
+  tool: {
+    name: "mini_subagents",
+    label: "Mini Subagents",
+    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`.",
+  },
+
+  spawn: {
+    flagEnv: "PI_SUBAGENT",
+  },
+
+  prompt: {
+    snippet:
+      "Delegate a task to a transient headless subagent (single or parallel) and get its results back",
+    guidelines: [
+      "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.",
+    ],
+    instructions: {
+      always: "You are a transient subagent. Complete the task, then stop",
+      readOnly:
+        "You may only READ and EXPLORE. Do not modify files or run mutating commands.",
+      writeAllowed:
+        "You may edit files ONLY if strictly necessary, preferring hash-anchored operations (replace/insert) over rewriting.",
+    },
+    needsInput: {
+      marker: NEEDS_INPUT_MARKER,
+      suffix: NEEDS_INPUT_SUFFIX,
+    },
+  },
+
+  endorsement: {
+    enabled: true,
+  },
+
+  orchestratorMode: {
+    enabled: true,
+  },
+
+  limits: {
+    maxPanelRows: MAX_PANEL_ROWS,
+    maxConcurrency: MAX_CONCURRENCY,
+    maxStoredOutput: MAX_STORED_OUTPUT,
+    maxParallelTasks: MAX_PARALLEL_TASKS,
+    perTaskOutputCap: PER_TASK_OUTPUT_CAP,
+    maxWritesPerSubagent: MAX_WRITES_PER_SUBAGENT,
+  },
+
+  entries: {
+    state: STATE_ENTRY,
+    report: REPORT_ENTRY,
+  },
+
+  panel: {
+    title: "  Subagents",
+    widgetKey: WIDGET_KEY,
+    toggleChord: PANEL_TOGGLE_CHORD,
+    emptyText: "No subagents yet. Ask the agent to delegate a task!",
+  },
+
+  rowLine: (r, theme) => getStyledSubagent(r, theme),
+
+  reportSections: (s) => {
+    const byStatus = s.records.reduce<Record<string, SubagentRecord[]>>(
+      (acc, curr) => {
+        const label = capitalize(curr.status.toLowerCase()).replaceAll(
+          "_",
+          " ",
+        );
+
+        if (!acc[label]?.length) acc[label] = [];
+
+        acc[label].push(curr);
+
+        return acc;
+      },
+      {},
+    );
+
+    return Object.entries(byStatus).map(([label, records]) => ({
+      label,
+      records,
+    }));
+  },
+};

package/src/constants.ts

@@ -15,21 +15,6 @@ export const STATUS_STYLES: Record<SubagentStatus, StatusUi> = {
   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:";
 
@@ -41,26 +26,31 @@ ${NEEDS_INPUT_MARKER}
 
 Report your findings clearly and concisely.`;
 
-/** 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). */
+/** Max parallel tasks per call */
+export const MAX_PARALLEL_TASKS = 12;
+
+/** Max concurrent subagent processes */
+export const MAX_CONCURRENCY = 8;
+
+/** Per-task output byte cap for parallel results */
+export const PER_TASK_OUTPUT_CAP = 80 * 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_WRITES_PER_SUBAGENT = 4;
+
+/** Max task rows rendered in the expanded TUI widget */
 export const MAX_PANEL_ROWS = 8;
 
-/** Widget key for the panel above the editor. */
+/** Widget key for the panel above the editor */
 export const WIDGET_KEY = "subagents";
 
-/** Custom entry type carrying the durable state snapshot. */
+/** Custom entry type carrying the durable state snapshot */
 export const STATE_ENTRY = "subagents.state";
 
-/** Custom entry type rendered by the /subagents command. */
+/** Custom entry type rendered by the /subagents command */
 export const REPORT_ENTRY = "subagents.report";
 
-/** Chord that toggles the panel. */
+/** Chord that toggles the panel */
 export const PANEL_TOGGLE_CHORD: KeyId = "alt+s";

package/src/index.ts

@@ -1,120 +1,12 @@
-import type { ExtensionAPI, Theme } from "@earendil-works/pi-coding-agent";
-import {
-  capitalize,
-  createSubagentRuntime,
-  formatTokens,
-  type SubagentRecord,
-} from "@leo-alvarenga/pi-ext-core";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createSubagentRuntime } from "@leo-alvarenga/pi-ext-core";
 
-import {
-  MAX_CONCURRENCY,
-  MAX_PANEL_ROWS,
-  MAX_PARALLEL_TASKS,
-  MAX_STORED_OUTPUT,
-  NEEDS_INPUT_MARKER,
-  NEEDS_INPUT_SUFFIX,
-  PANEL_TOGGLE_CHORD,
-  PER_TASK_OUTPUT_CAP,
-  READ_ONLY_TOOLS,
-  REPORT_ENTRY,
-  STATE_ENTRY,
-  STATUS_STYLES,
-  WIDGET_KEY,
-  WRITE_TOOLS,
-} from "./constants";
-
-function getStyledSubagent(r: SubagentRecord, th: Theme): string {
-  const task = r.task.replace(/\s*[\r\n]+\s*/g, " ");
-
-  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, 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;
-}
+import { SUBAGENTS_SPEC } from "./config";
 
 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;
 
-  createSubagentRuntime(pi, {
-    toolName: "mini_subagent",
-    toolLabel: "Mini Subagent",
-    spawnFlagEnv: "PI_SUBAGENT",
-    toolDescription:
-      "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.",
-    ],
-    promptInstructions: {
-      always: "You are a transient subagent. Complete the task, then stop",
-      readOnly:
-        "You may only READ and EXPLORE. Do not modify files or run mutating commands.",
-      writeAllowed:
-        "You may edit files ONLY if strictly necessary, preferring hash-anchored operations (replace/insert) over rewriting.",
-    },
-    needsInput: {
-      marker: NEEDS_INPUT_MARKER,
-      suffix: NEEDS_INPUT_SUFFIX,
-    },
-    allowlists: {
-      readOnly: READ_ONLY_TOOLS,
-      writeable: WRITE_TOOLS,
-    },
-
-    limits: {
-      maxPanelRows: MAX_PANEL_ROWS,
-      maxConcurrency: MAX_CONCURRENCY,
-      maxStoredOutput: MAX_STORED_OUTPUT,
-      maxParallelTasks: MAX_PARALLEL_TASKS,
-      perTaskOutputCap: PER_TASK_OUTPUT_CAP,
-    },
-
-    state: { entryType: STATE_ENTRY },
-    report: { entryType: REPORT_ENTRY },
-
-    panel: {
-      title: "  Subagents",
-      widgetKey: WIDGET_KEY,
-      toggleChord: PANEL_TOGGLE_CHORD,
-      emptyText: "No subagents yet. Ask the agent to delegate a task!",
-    },
-
-    rowLine: (r, theme) => getStyledSubagent(r, theme),
-    reportSections: (s) => {
-      const byStatus = s.records.reduce<Record<string, SubagentRecord[]>>(
-        (acc, curr) => {
-          const label = capitalize(curr.status.toLowerCase()).replaceAll(
-            "_",
-            " ",
-          );
-
-          if (!acc[label]?.length) acc[label] = [];
-
-          acc[label].push(curr);
-
-          return acc;
-        },
-        {},
-      );
-
-      return Object.entries(byStatus).map(([label, records]) => ({
-        label,
-        records,
-      }));
-    },
-  });
+  createSubagentRuntime(pi, SUBAGENTS_SPEC);
 }

package/skills/subagent/SKILL.md

@@ -1,52 +0,0 @@
----
-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.