@d3ara1n/pi-subagent 1.1.0 → 1.2.0

package/README.md

@@ -34,8 +34,10 @@ This means:
 |------|-----------|---------|-------|-----------------|-------------|
 | `explorer` | fast | 900s | read, find, grep | — | Fast code search (read-only, no bash) |
 | `reviewer` | heavy | 3600s | read, bash, grep, find | — | Deep code review (read-only, bash for git/log) |
-| `worker` | default | 2400s | read, bash, edit, write, grep, find, delegate | explorer, researcher | Implementation — the only role that can modify files |
-| `researcher` | fast | 2400s | web_search, fetch_content, read, bash, delegate | explorer | Web research + GitHub repo analysis |
+| `worker` | default | 2400s | all (no whitelist) | explorer, researcher | Implementation — the only role that can modify files; full tool access (web, MCP, everything) |
+| `researcher` | fast | 2400s | web_search, fetch_content, source_check, get_search_content, read, bash, edit, write, delegate | explorer | Web research + GitHub repo analysis; writes artifacts only inside its temp dir |
+
+**Web tool naming**: `researcher`'s web tools use the community-standard names (`web_search`, `fetch_content`, `source_check`, `get_search_content`) shared by the most popular Pi web extensions — [pi-web-access](https://github.com/nicobailon/pi-web-access), `pi-web-tools`, `pi-browse`, and others. Install any of those and the researcher gets web access out of the box. If your web extension uses different tool names (e.g. `websearch`/`webfetch`) or you renamed the tools via a `toolNames` config, override `researcher.tools` in `agentOverrides` to match.
 
 **Nested delegation**: `worker` and `researcher` can spawn their own subagents. This keeps the main model's context clean — a worker can explore unfamiliar code via an `explorer` subagent without returning intermediate results to the main model.
 
@@ -138,7 +140,7 @@ Override, disable, or add subagent roles via `agentOverrides`. Built-in and cust
 }
 ```
 
-**Required fields for custom roles:** `role`, `description`, `examples`, `decisionTrigger`, `tools`, `systemPrompt`.
+**Required fields for custom roles:** `role`, `description`, `examples`, `decisionTrigger`, `systemPrompt`. `tools` is optional — absent means all tools, a list restricts to those exact tool names.
 
 **Optional fields:** `subagentRoles` (roles this role can spawn via delegate), `timeout` (per-role active-time timeout in seconds; unset or `0` is unlimited, negative values normalize to `0`), `maxTurns` / `maxCost` (per-role budget overrides; unset uses the top-level `maxTurns` / `maxCost` setting, `0` is unlimited, negative values normalize to `0`), `fallbackRole` (backup pi-model-roles role the whole run is retried on after a provider error; unset means no retry — see [Fallback observability](#fallback-observability)).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d3ara1n/pi-subagent",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
   "description": "Role-based subagent orchestration for pi — delegates tasks to specialized pi child processes with configurable model roles",
   "main": "src/index.ts",

package/src/index.ts

@@ -104,6 +104,16 @@ export default function subagentExtension(pi: ExtensionAPI) {
   const collectedRuns = new Map<string, CollectedRun>();
   let runCounter = 0;
 
+  // ── Live-run reaping ─────────────────────────────────────────
+  // Every in-flight run (foreground and background alike), removed once
+  // settled. session_shutdown aborts whatever is still here so no child
+  // process outlives the parent — quit, reload, or session replacement.
+  const liveRuns = new Set<RunHandle>();
+  function trackRun(run: RunHandle): void {
+    liveRuns.add(run);
+    void run.promise.then(() => liveRuns.delete(run));
+  }
+
   // Mutable guidelines array — rebuilt in session_start to reflect agentOverrides
   const guidelines: string[] = [];
 
@@ -178,12 +188,12 @@ export default function subagentExtension(pi: ExtensionAPI) {
     applyAgentOverrides(availableRoles, config.agentOverrides);
 
     // Validate custom roles (skip built-in roles — they already have all fields)
+    // `tools` is optional — absent means the role gets all tools.
     const REQUIRED_FIELDS = [
       "role",
       "description",
       "examples",
       "decisionTrigger",
-      "tools",
       "systemPrompt",
     ] as const;
     for (const [name, role] of Object.entries(availableRoles)) {
@@ -219,6 +229,15 @@ export default function subagentExtension(pi: ExtensionAPI) {
     }
   });
 
+  // Fires before the extension runtime is torn down (quit, reload, or
+  // session replacement). Aborting funnels through the standard abort path:
+  // children get SIGTERM → their own handlers kill grandchildren, aborted
+  // runs are audited to history, gates release. Without this, background
+  // children would burn tokens as unwaitable orphans after /reload or /new.
+  pi.on("session_shutdown", () => {
+    for (const run of liveRuns) run.abort("session shutdown");
+  });
+
   pi.registerTool({
     name: "subagent_delegate",
     label: "Delegate to subagent",
@@ -307,6 +326,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
         getRolesApi: getModelRolesAPI,
         getSessionId: () => ctx.sessionManager?.getSessionId(),
       });
+      trackRun(run);
 
       // ── Background: return the id immediately; the pipeline keeps running. ──
       if (params.background) {

package/src/roles.ts

@@ -2,7 +2,8 @@
  * Built-in subagent role definitions.
  *
  * Each maps to a pi-model-roles role and has a tailored system prompt
- * and tool set. Prompts are in English — concise, efficient, task-focused.
+ * and tool policy (an explicit allowlist, or all tools when unset).
+ * Prompts are in English — concise, efficient, task-focused.
  * Final output should be accurate and concise, stating conclusions directly.
  */
 
@@ -56,10 +57,9 @@ export const BUILTIN_ROLES: Record<string, SubagentRole> = {
     role: "default",
     timeout: 2400,
     description:
-      "the ONLY role that can MODIFY files — edit, write, refactor, fix, implement. Tools: read, bash, edit, write, grep, find, subagent_delegate. Can delegate to explorer/researcher.",
+      "Full tool access — the ONLY role that can MODIFY files (edit, write, refactor, fix, implement). Can delegate to explorer/researcher.",
     examples: ["Rename all snake_case fields to camelCase", "Add input validation to POST /login"],
     decisionTrigger: "Task modifies files?",
-    tools: ["read", "bash", "edit", "write", "grep", "find", "subagent_delegate"],
     subagentRoles: ["explorer", "researcher"],
     systemPrompt: [
       "Implementation worker. Work autonomously — all context is in the task description.",
@@ -67,10 +67,12 @@ export const BUILTIN_ROLES: Record<string, SubagentRole> = {
       "After each change, validate: run tests, check syntax, verify behavior.",
       "",
       "## Protecting your context",
-      "You have a `subagent_delegate` tool. Use it to offload exploration and research:",
+      "You have full tool access (web_search, fetch_content, MCP, ...) plus a `subagent_delegate` tool.",
+      "Use direct tools for quick lookups — e.g. check library docs/APIs with web_search or context7 before writing third-party code.",
+      "Delegate only when the work is substantial:",
       "- subagent_delegate(role=explorer) when you need to map unfamiliar code before editing",
-      "- subagent_delegate(role=researcher) when you need external docs or library references",
-      "Don't delegate tasks you can do with a single read or grep.",
+      "- subagent_delegate(role=researcher) when the research itself is a multi-step investigation",
+      "Don't delegate tasks you can do with a single read, grep, or web search.",
       "",
       "Output format (be brief — summarize, don't paste full diffs):",
       "## Changes: list each file touched and what changed",
@@ -82,23 +84,35 @@ export const BUILTIN_ROLES: Record<string, SubagentRole> = {
     fallbackRole: "default",
     timeout: 2400,
     description:
-      "the ONLY role with WEB ACCESS — search docs, fetch pages, analyze GitHub repos. Tools: web_search, fetch_content, read, bash, subagent_delegate. Can clone repos & delegate to explorer.",
+      "the ONLY role with WEB ACCESS — search docs, fetch pages, verify claims, analyze GitHub repos. Can clone repos & delegate to explorer.",
     examples: ["Find the React 19 migration guide", "Check GitHub issue #1234 for context"],
     decisionTrigger: "Task searches web or GitHub?",
-    tools: ["web_search", "fetch_content", "read", "bash", "subagent_delegate"],
+    tools: [
+      "web_search",
+      "fetch_content",
+      "source_check",
+      "get_search_content",
+      "read",
+      "bash",
+      "edit",
+      "write",
+      "subagent_delegate",
+    ],
     subagentRoles: ["explorer"],
     systemPrompt: [
       "Web researcher. Search with varied angles, prefer official docs over blogs.",
       "If first results are insufficient, refine queries and search again.",
       "",
+      "## Research artifacts",
+      "You may write files (downloaded docs, notes, intermediate results) — but ONLY under $PI_SUBAGENT_TMPDIR.",
+      "Never write anywhere else: project files and other directories are strictly off-limits.",
+      "",
       "## GitHub repo analysis",
       "When the task requires analyzing a GitHub repo:",
-      "1. git clone the repo into PI_SUBAGENT_TMPDIR (must exist)",
+      "1. Clone the repo into $PI_SUBAGENT_TMPDIR",
       "2. Use `subagent_delegate` with role=explorer to investigate the cloned codebase — pass the repo path and the research question",
       "3. Combine explorer findings with any web search results",
       "",
-      "bash is for git clone and read-only commands only. Never modify files.",
-      "",
       "Output format:",
       "## Answer: direct answer to the question (2-3 sentences)",
       "## Sources: list of URLs used",

package/src/run.test.ts

@@ -256,6 +256,63 @@ test("abort while queued fails the run and exposes thrown for the foreground pat
   gate.release();
 });
 
+test("handle.abort() reaps a queued background run (no caller signal)", async () => {
+  const gate = new AsyncSemaphore(1);
+  await gate.acquire();
+  const spawnImpl: SpawnImpl = async () => makeResult({ output: "never" });
+
+  const run = startSubagentRun(makeDeps({ gate, spawnImpl }));
+  run.abort("session shutdown");
+  const result = await run.promise;
+
+  assert.strictEqual(run.state, "failed");
+  assert.ok(run.thrown instanceof Error);
+  assert.match(result.errorMessage!, /cancelled while queued/);
+  assert.match(result.errorMessage!, /session shutdown/);
+  gate.release();
+});
+
+test("handle.abort(reason) fails a running run with the reason in the error message", async () => {
+  const signals: AbortSignal[] = [];
+  // Mirrors real spawn's abort handling: pre-aborted signals settle immediately
+  // (an "abort" listener alone would never fire — the event already happened).
+  const honoringSpawn: SpawnImpl = (_m, _t, options) =>
+    new Promise((_resolve, reject) => {
+      signals.push(options.signal!);
+      const die = () => reject(new Error("Subagent was aborted"));
+      if (options.signal?.aborted) die();
+      else options.signal?.addEventListener("abort", die, { once: true });
+    });
+
+  const run = startSubagentRun(makeDeps({ spawnImpl: honoringSpawn }));
+  run.abort("session shutdown");
+  const result = await run.promise;
+
+  assert.strictEqual(run.state, "failed");
+  assert.match(result.errorMessage!, /Subagent was aborted \(session shutdown\)/);
+  assert.ok(run.thrown instanceof Error);
+  // The internal controller the spawn honored is the same channel abort() used.
+  assert.ok(signals[0].aborted);
+});
+
+test("a pre-aborted caller signal chains into the run before spawn", async () => {
+  const controller = new AbortController();
+  controller.abort();
+  const spawnImpl: SpawnImpl = async (_m, _t, options) => {
+    if (options.signal?.aborted) throw new Error("Subagent was aborted");
+    return makeResult({ output: "done" });
+  };
+
+  const run = startSubagentRun(makeDeps({ signal: controller.signal, spawnImpl }));
+  const result = await run.promise;
+
+  assert.strictEqual(run.state, "failed");
+  assert.strictEqual(result.errorMessage, "Subagent was aborted");
+  // abort() after settle is a no-op — the terminal state never flips.
+  run.abort("session shutdown");
+  assert.strictEqual(run.state, "failed");
+});
+
 test("subscribers are notified on progress and terminal frames", async () => {
   let notifications = 0;
   const spawnImpl: SpawnImpl = async (_m, _t, options) => {

package/src/run.ts

@@ -9,6 +9,11 @@
  * exposed via `thrown`), and a subscriber list the `wait` tool uses to mirror
  * live progress into its own tool row.
  *
+ * Every run owns an AbortController. The foreground tool signal chains into
+ * it; runs started without a caller signal (background) are still abortable
+ * via handle.abort() — session_shutdown reaps every live run that way, so no
+ * child process outlives the parent.
+ *
  * All post-processing (fallback retry, output compression, summary
  * generation, history persistence) runs inside the pipeline, so background
  * runs finish exactly like foreground ones.
@@ -52,6 +57,8 @@ export interface RunHandle {
   readonly thrown: Error | undefined;
   /** Resolves with the terminal result once the run finishes (always succeeds). */
   readonly promise: Promise<SubagentResult>;
+  /** Abort the run — no-op after settle. Tool-cancellation and session-shutdown reaping both funnel here. */
+  abort(reason?: string): void;
   /** Get notified on every frame change. Returns an unsubscribe function. */
   subscribe(fn: () => void): () => void;
 }
@@ -69,7 +76,7 @@ export interface StartRunOptions {
   cwd: string;
   /** Nesting depth for the child (CURRENT_DEPTH + 1). */
   depth: number;
-  /** Foreground callers pass the tool's AbortSignal; background runs pass none and outlive the turn. */
+  /** Foreground callers chain the tool's AbortSignal in; background runs pass none and are aborted via handle.abort() instead. */
   signal?: AbortSignal;
   /** Per-call model override ('provider/model-id'), bypassing the role's configured model. */
   modelOverride?: string;
@@ -106,6 +113,14 @@ export function startSubagentRun(opts: StartRunOptions): RunHandle {
   let snapshot: SubagentResult = inputFrame(-1, true);
   let result: SubagentResult | undefined;
   let thrown: Error | undefined;
+  let settled = false;
+  let abortReason: string | undefined;
+  const controller = new AbortController();
+  const onCallerAbort = () => controller.abort();
+  if (opts.signal) {
+    if (opts.signal.aborted) controller.abort();
+    else opts.signal.addEventListener("abort", onCallerAbort, { once: true });
+  }
   let resolvePromise!: (r: SubagentResult) => void;
   const promise = new Promise<SubagentResult>((resolve) => {
     resolvePromise = resolve;
@@ -126,11 +141,14 @@ export function startSubagentRun(opts: StartRunOptions): RunHandle {
     notify();
   };
   const finish = (terminal: SubagentResult, error?: Error) => {
+    if (settled) return;
+    settled = true;
     result = terminal;
     snapshot = terminal;
     thrown = error;
     currentState = isFailedResult(terminal) ? "failed" : "finished";
     notify();
+    opts.signal?.removeEventListener("abort", onCallerAbort);
     resolvePromise(terminal);
   };
 
@@ -158,15 +176,22 @@ export function startSubagentRun(opts: StartRunOptions): RunHandle {
         listeners.delete(fn);
       };
     },
+    abort(reason?: string) {
+      if (settled) return;
+      if (reason) abortReason = reason;
+      controller.abort();
+    },
     promise,
   };
 
   (async () => {
     // ── Concurrency gate (abortable while queued) ──
     try {
-      await opts.gate.acquire(opts.signal);
+      await opts.gate.acquire(controller.signal);
     } catch {
-      const msg = "cancelled while queued for a concurrency slot";
+      const msg =
+        "cancelled while queued for a concurrency slot" +
+        (abortReason ? ` (${abortReason})` : "");
       finish({ ...inputFrame(1, false), errorMessage: msg }, new Error(msg));
       return;
     }
@@ -262,7 +287,7 @@ export function startSubagentRun(opts: StartRunOptions): RunHandle {
         maxTurns,
         maxCost,
         depth: opts.depth,
-        signal: opts.signal,
+        signal: controller.signal,
         onProgress: emitProgress,
       });
 
@@ -294,7 +319,7 @@ export function startSubagentRun(opts: StartRunOptions): RunHandle {
             maxTurns,
             maxCost,
             depth: opts.depth,
-            signal: opts.signal,
+            signal: controller.signal,
             onProgress: emitProgress,
           });
           runResult.fallbackFrom = fallbackFrom;
@@ -348,7 +373,9 @@ export function startSubagentRun(opts: StartRunOptions): RunHandle {
         activityLog: partial.activityLog,
         budgetMs: partial.budgetMs,
         elapsedMs: partial.startTime ? Date.now() - partial.startTime : undefined,
-        errorMessage: err?.message || String(err),
+        errorMessage: abortReason
+          ? `Subagent was aborted (${abortReason})`
+          : err?.message || String(err),
       };
       // The run spawned before throwing — audit it like any terminal state.
       // The partial output is raw (compression never ran on it).

package/src/spawn.ts

@@ -19,6 +19,29 @@ const INLINE_LIMIT = 8000;
 
 const PI_CODING_AGENT_PACKAGE = "@earendil-works/pi-coding-agent";
 
+// ── Parent-exit safety net ─────────────────────────────────────
+// process.on("exit") fires synchronously on every terminal path that goes
+// through process.exit — normal quit, signal-triggered graceful shutdown,
+// emergency terminal exit, uncaught crash. SIGTERM the live children so each
+// pi child runs its own cleanup (killing ITS tracked grandchildren) instead
+// of burning tokens as an orphan. This covers the paths where the graceful
+// session_shutdown reaping never fires; a SIGKILL'd parent is beyond help.
+const liveChildren = new Set<ChildProcess>();
+let exitHookInstalled = false;
+function reapChildrenOnExit(): void {
+  if (exitHookInstalled) return;
+  exitHookInstalled = true;
+  process.on("exit", () => {
+    for (const child of liveChildren) {
+      try {
+        child.kill("SIGTERM");
+      } catch {
+        /* already dead */
+      }
+    }
+  });
+}
+
 function isRunnableScript(filePath: string): boolean {
   try {
     if (!fs.existsSync(filePath)) return false;
@@ -508,6 +531,8 @@ export async function spawnSubagent(
         stdio: ["ignore", "pipe", "pipe"],
       });
       proc = p;
+      liveChildren.add(p);
+      reapChildrenOnExit();
 
       p.stdout.on("data", (data: Buffer) => {
         buffer += data.toString();
@@ -522,6 +547,7 @@ export async function spawnSubagent(
 
       p.on("exit", () => {
         processExited = true;
+        liveChildren.delete(p);
         clearEscalationTimer();
       });
 
@@ -548,6 +574,7 @@ export async function spawnSubagent(
 
       p.on("error", (err) => {
         processExited = true;
+        liveChildren.delete(p);
         if (timeoutHandle) clearTimeout(timeoutHandle);
         clearEscalationTimer();
         if (onAbort && options.signal) options.signal.removeEventListener("abort", onAbort);

package/src/types.ts

@@ -54,8 +54,11 @@ export interface SubagentRole {
   decisionTrigger: string;
   /** System prompt for the subagent */
   systemPrompt: string;
-  /** Tools available to this subagent */
-  tools: string[];
+  /**
+   * Tools available to this subagent. Empty or absent = all tools (no restriction).
+   * When set, only the listed tool names are exposed to the child (exact-name allowlist).
+   */
+  tools?: string[];
   /** If this role has `delegate`, restrict which roles it may spawn. undefined = no restriction. */
   subagentRoles?: string[];
   /** Per-role active-time timeout in seconds. `0` or unset means unlimited; negative values are normalized to `0`. */