@esso0428/pi-subagents 0.17.5 → 0.17.7

package/dist/workflow/worker-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-source.js","sourceRoot":"","sources":["../../src/workflow/worker-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH;;;;;;GAMG;AACH,MAAM,mBAAmB,GACvB,6BAA6B;IAC7B,oCAAoC;IACpC,gCAAgC;IAChC,gFAAgF;IAChF,+EAA+E;IAC/E,KAAK;IACL,8DAA8D;IAC9D,gEAAgE;IAChE,+CAA+C;IAC/C,0FAA0F;IAC1F,KAAK;IACL,OAAO,CAAC;AAEV,MAAM,CAAC,MAAM,aAAa,GAAG;;;;;;;kBAOX,IAAI,CAAC,SAAS,CAAC,mBAAmB,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAisBpD,CAAC"}

package/dist/worktree.d.ts

@@ -4,7 +4,12 @@
  * Creates a temporary git worktree so the agent works on an isolated copy of the repo.
  * On completion, if no changes were made, the worktree is cleaned up.
  * If changes exist, a branch is created and returned in the result.
+ *
+ * Every git call goes through `pi.exec` (async) rather than `execFileSync`: a
+ * worktree copy can take seconds, and a session that spawns several isolated
+ * agents at once would otherwise serialize them all on the TUI's event loop.
  */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 export interface WorktreeInfo {
     /** Absolute path to the worktree directory (the copied repo's root). */
     path: string;
@@ -20,6 +25,8 @@ export interface WorktreeInfo {
      */
     workPath: string;
 }
+export declare function setWorktreeIsolationEnabled(enabled: boolean): void;
+export declare function isWorktreeIsolationEnabled(): boolean;
 export interface WorktreeCleanupResult {
     /** Whether changes were found in the worktree. */
     hasChanges: boolean;
@@ -32,15 +39,15 @@ export interface WorktreeCleanupResult {
  * Create a temporary git worktree for an agent.
  * Returns the worktree path, or undefined if not in a git repo.
  */
-export declare function createWorktree(cwd: string, agentId: string): WorktreeInfo | undefined;
+export declare function createWorktree(pi: ExtensionAPI, cwd: string, agentId: string): Promise<WorktreeInfo | undefined>;
 /**
  * Clean up a worktree after agent completion.
  * - If no changes: remove worktree entirely.
  * - If changes exist: create a branch, commit changes, return branch info.
  */
-export declare function cleanupWorktree(cwd: string, worktree: WorktreeInfo, agentDescription: string): WorktreeCleanupResult;
+export declare function cleanupWorktree(pi: ExtensionAPI, cwd: string, worktree: WorktreeInfo, agentDescription: string): Promise<WorktreeCleanupResult>;
 /**
  * Prune any orphaned worktrees (crash recovery).
  */
-export declare function pruneWorktrees(cwd: string): void;
+export declare function pruneWorktrees(pi: ExtensionAPI, cwd: string): Promise<void>;
 //# sourceMappingURL=worktree.d.ts.map

package/dist/worktree.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worktree.d.ts","sourceRoot":"","sources":["../src/worktree.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH,MAAM,WAAW,YAAY;IAC3B,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC,kDAAkD;IAClD,UAAU,EAAE,OAAO,CAAC;IACpB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAqCrF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,YAAY,EACtB,gBAAgB,EAAE,MAAM,GACvB,qBAAqB,CAwEvB;AAoBD;;GAEG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAIhD"}
+{"version":3,"file":"worktree.d.ts","sourceRoot":"","sources":["../src/worktree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAEpE,MAAM,WAAW,YAAY;IAC3B,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB;AAcD,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAElE;AAED,wBAAgB,0BAA0B,IAAI,OAAO,CAEpD;AAED,MAAM,WAAW,qBAAqB;IACpC,kDAAkD;IAClD,UAAU,EAAE,OAAO,CAAC;IACpB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAmBD;;;GAGG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,YAAY,EAChB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CA6BnC;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,EAAE,EAAE,YAAY,EAChB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,YAAY,EACtB,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAAC,qBAAqB,CAAC,CAoDhC;AAgBD;;GAEG;AACH,wBAAsB,cAAc,CAAC,EAAE,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAIjF"}

package/dist/worktree.js

@@ -4,32 +4,64 @@
  * Creates a temporary git worktree so the agent works on an isolated copy of the repo.
  * On completion, if no changes were made, the worktree is cleaned up.
  * If changes exist, a branch is created and returned in the result.
+ *
+ * Every git call goes through `pi.exec` (async) rather than `execFileSync`: a
+ * worktree copy can take seconds, and a session that spawns several isolated
+ * agents at once would otherwise serialize them all on the TUI's event loop.
  */
-import { execFileSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { existsSync, realpathSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, relative } from "node:path";
+/**
+ * Project-wide switch for worktree isolation (`worktreeIsolation` in
+ * subagents.json). Default `true` — unchanged behaviour.
+ *
+ * The `"off"` isolation value gives a model a legal way to decline a worktree,
+ * but it still depends on the model choosing it. This is the deterministic half
+ * of the same fix: on a large repo where every worktree costs real time and
+ * disk (#184), turning it off means no caller can create one, whatever it
+ * passes.
+ */
+let worktreeIsolationEnabled = true;
+export function setWorktreeIsolationEnabled(enabled) {
+    worktreeIsolationEnabled = enabled;
+}
+export function isWorktreeIsolationEnabled() {
+    return worktreeIsolationEnabled;
+}
+/**
+ * Run git and return its trimmed stdout, throwing on failure so callers keep
+ * the try/catch control flow `execFileSync` gave them.
+ *
+ * `pi.exec` never rejects — it reports failure in the result — and a command
+ * killed by its timeout comes back as `killed` with an exit code of 0, so both
+ * have to be checked to reproduce `execFileSync`'s "throws on anything but a
+ * clean exit".
+ */
+async function git(pi, cwd, args, timeout) {
+    const result = await pi.exec("git", args, { cwd, timeout });
+    if (result.killed || result.code !== 0) {
+        throw new Error(result.stderr.trim() || `git ${args.join(" ")} failed (exit ${result.code})`);
+    }
+    return result.stdout.trim();
+}
 /**
  * Create a temporary git worktree for an agent.
  * Returns the worktree path, or undefined if not in a git repo.
  */
-export function createWorktree(cwd, agentId) {
+export async function createWorktree(pi, cwd, agentId) {
     // Verify we're in a git repo with at least one commit (HEAD must exist)
     let baseSha;
     let subdir;
     try {
-        execFileSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd, stdio: "pipe", timeout: 5000 });
-        baseSha = execFileSync("git", ["rev-parse", "HEAD"], { cwd, stdio: "pipe", timeout: 5000 })
-            .toString()
-            .trim();
+        await git(pi, cwd, ["rev-parse", "--is-inside-work-tree"], 5000);
+        baseSha = await git(pi, cwd, ["rev-parse", "HEAD"], 5000);
         // Where cwd sits inside the repo ("" at the root): the agent must work at
         // the same subdirectory inside the copy, or a monorepo-package cwd would
         // silently widen to the whole repo. realpath both sides — git emits
         // resolved paths while cwd may arrive through a symlink (macOS /tmp).
-        const topLevel = execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd, stdio: "pipe", timeout: 5000 })
-            .toString()
-            .trim();
+        const topLevel = await git(pi, cwd, ["rev-parse", "--show-toplevel"], 5000);
         subdir = relative(realpathSync(topLevel), realpathSync(cwd));
     }
     catch {
@@ -40,11 +72,7 @@ export function createWorktree(cwd, agentId) {
     const worktreePath = join(tmpdir(), `pi-agent-${agentId}-${suffix}`);
     try {
         // Create detached worktree at HEAD
-        execFileSync("git", ["worktree", "add", "--detach", worktreePath, "HEAD"], {
-            cwd,
-            stdio: "pipe",
-            timeout: 30000,
-        });
+        await git(pi, cwd, ["worktree", "add", "--detach", worktreePath, "HEAD"], 30000);
         return { path: worktreePath, branch, baseSha, workPath: subdir ? join(worktreePath, subdir) : worktreePath };
     }
     catch {
@@ -57,38 +85,26 @@ export function createWorktree(cwd, agentId) {
  * - If no changes: remove worktree entirely.
  * - If changes exist: create a branch, commit changes, return branch info.
  */
-export function cleanupWorktree(cwd, worktree, agentDescription) {
+export async function cleanupWorktree(pi, cwd, worktree, agentDescription) {
     if (!existsSync(worktree.path)) {
         return { hasChanges: false };
     }
     try {
         // Check for uncommitted changes in the worktree
-        const status = execFileSync("git", ["status", "--porcelain"], {
-            cwd: worktree.path,
-            stdio: "pipe",
-            timeout: 10000,
-        }).toString().trim();
+        const status = await git(pi, worktree.path, ["status", "--porcelain"], 10000);
         if (status) {
             // Changes exist — stage, commit, and create a branch
-            execFileSync("git", ["add", "-A"], { cwd: worktree.path, stdio: "pipe", timeout: 10000 });
-            // Truncate description for commit message (no shell sanitization needed — execFileSync uses argv)
+            await git(pi, worktree.path, ["add", "-A"], 10000);
+            // Truncate description for commit message (no shell sanitization needed — pi.exec uses argv)
             const safeDesc = agentDescription.slice(0, 200);
             const commitMsg = `pi-agent: ${safeDesc}`;
-            execFileSync("git", ["commit", "--no-verify", "-m", commitMsg], {
-                cwd: worktree.path,
-                stdio: "pipe",
-                timeout: 10000,
-            });
+            await git(pi, worktree.path, ["commit", "--no-verify", "-m", commitMsg], 10000);
         }
         else {
-            const currentSha = execFileSync("git", ["rev-parse", "HEAD"], {
-                cwd: worktree.path,
-                stdio: "pipe",
-                timeout: 5000,
-            }).toString().trim();
+            const currentSha = await git(pi, worktree.path, ["rev-parse", "HEAD"], 5000);
             if (currentSha === worktree.baseSha) {
                 // No changes — remove worktree
-                removeWorktree(cwd, worktree.path);
+                await removeWorktree(pi, cwd, worktree.path);
                 return { hasChanges: false };
             }
         }
@@ -96,25 +112,17 @@ export function cleanupWorktree(cwd, worktree, agentDescription) {
         // If the branch already exists, append a suffix to avoid overwriting previous work.
         let branchName = worktree.branch;
         try {
-            execFileSync("git", ["branch", branchName], {
-                cwd: worktree.path,
-                stdio: "pipe",
-                timeout: 5000,
-            });
+            await git(pi, worktree.path, ["branch", branchName], 5000);
         }
         catch {
             // Branch already exists — use a unique suffix
             branchName = `${worktree.branch}-${Date.now()}`;
-            execFileSync("git", ["branch", branchName], {
-                cwd: worktree.path,
-                stdio: "pipe",
-                timeout: 5000,
-            });
+            await git(pi, worktree.path, ["branch", branchName], 5000);
         }
         // Update branch name in worktree info for the caller
         worktree.branch = branchName;
         // Remove the worktree (branch persists in main repo)
-        removeWorktree(cwd, worktree.path);
+        await removeWorktree(pi, cwd, worktree.path);
         return {
             hasChanges: true,
             branch: worktree.branch,
@@ -124,7 +132,7 @@ export function cleanupWorktree(cwd, worktree, agentDescription) {
     catch {
         // Best effort cleanup on error
         try {
-            removeWorktree(cwd, worktree.path);
+            await removeWorktree(pi, cwd, worktree.path);
         }
         catch { /* ignore */ }
         return { hasChanges: false };
@@ -133,18 +141,14 @@ export function cleanupWorktree(cwd, worktree, agentDescription) {
 /**
  * Force-remove a worktree.
  */
-function removeWorktree(cwd, worktreePath) {
+async function removeWorktree(pi, cwd, worktreePath) {
     try {
-        execFileSync("git", ["worktree", "remove", "--force", worktreePath], {
-            cwd,
-            stdio: "pipe",
-            timeout: 10000,
-        });
+        await git(pi, cwd, ["worktree", "remove", "--force", worktreePath], 10000);
     }
     catch {
         // If git worktree remove fails, try pruning
         try {
-            execFileSync("git", ["worktree", "prune"], { cwd, stdio: "pipe", timeout: 5000 });
+            await git(pi, cwd, ["worktree", "prune"], 5000);
         }
         catch { /* ignore */ }
     }
@@ -152,9 +156,9 @@ function removeWorktree(cwd, worktreePath) {
 /**
  * Prune any orphaned worktrees (crash recovery).
  */
-export function pruneWorktrees(cwd) {
+export async function pruneWorktrees(pi, cwd) {
     try {
-        execFileSync("git", ["worktree", "prune"], { cwd, stdio: "pipe", timeout: 5000 });
+        await git(pi, cwd, ["worktree", "prune"], 5000);
     }
     catch { /* ignore */ }
 }

package/dist/worktree.js.map

@@ -1 +1 @@
-{"version":3,"file":"worktree.js","sourceRoot":"","sources":["../src/worktree.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"worktree.js","sourceRoot":"","sources":["../src/worktree.ts"],"names":[],"mappings":"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"}

package/dist/xml.d.ts

@@ -0,0 +1,11 @@
+/**
+ * xml.ts — escaping for the `<task-notification>` payloads.
+ *
+ * A module of its own because both notification builders need it and they sit
+ * on opposite sides of a dependency edge: the agent one lives in `index.ts`,
+ * which imports `workflow/task.ts`, so the workflow one cannot reach back for
+ * it without a cycle.
+ */
+/** Escape XML special characters to prevent injection in structured notifications. */
+export declare function escapeXml(s: string): string;
+//# sourceMappingURL=xml.d.ts.map

package/dist/xml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xml.d.ts","sourceRoot":"","sources":["../src/xml.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,sFAAsF;AACtF,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3C"}

package/dist/xml.js

@@ -0,0 +1,13 @@
+/**
+ * xml.ts — escaping for the `<task-notification>` payloads.
+ *
+ * A module of its own because both notification builders need it and they sit
+ * on opposite sides of a dependency edge: the agent one lives in `index.ts`,
+ * which imports `workflow/task.ts`, so the workflow one cannot reach back for
+ * it without a cycle.
+ */
+/** Escape XML special characters to prevent injection in structured notifications. */
+export function escapeXml(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+//# sourceMappingURL=xml.js.map

package/dist/xml.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"xml.js","sourceRoot":"","sources":["../src/xml.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,sFAAsF;AACtF,MAAM,UAAU,SAAS,CAAC,CAAS;IACjC,OAAO,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAC9E,CAAC"}

package/docs/rpc.md

@@ -0,0 +1,183 @@
+# Driving subagents from another extension
+
+Another pi extension can spawn a subagent, listen for subagent completion, read the result and stop the run — all over the `pi.events` bus, without importing this package directly. Four request/reply channels (`subagents:rpc:ping`, `subagents:rpc:spawn`, `subagents:rpc:stop`, `subagents:rpc:consume`), eleven lifecycle events, and one in-process registry at `Symbol.for("pi-subagents:manager")`.
+
+The thing worth understanding up front is that **the bus is in-process.** Every "RPC" call here is a synchronous `pi.events.emit` into the same event loop, and every reply comes back the same way. That single fact explains most of what follows: why `signal` and the `on*` callbacks work on a spawn payload at all, why a `consume` fired inside a `subagents:completed` handler lands *before* the notification decision has been made, and why none of this survives a real process boundary.
+
+For the channel list, the reply envelope, the per-channel snippets and the event table, see [`README.md`](../README.md#cross-extension-rpc). This document is the reference README does not have room for: the complete spawn-option surface, every error string, the notification race, the registry, and what protocol version `2` does and does not promise.
+
+## Spawn options
+
+`subagents:rpc:spawn` forwards `options` to `AgentManager.spawn` — but not verbatim. The manager's `spawn` behind the RPC is `spawnTopLevel` (`src/index.ts:698-721`), which deletes internal-only fields first, and then `spawnResolved` (`src/index.ts:666-696`) overwrites the activity-tracker callbacks with its own. The full interface is `SpawnOptions` at `src/agent-manager.ts:169-303`; what a bus caller actually gets is three different things.
+
+**Honoured** — set these and they take effect:
+
+| Field | Type | Notes |
+|---|---|---|
+| `description` | string | What the agent is doing. Shown in the widget, FleetView and the completion notification |
+| `name` | string | A memorable second handle (`@auth-audit`). Slugged, never validated — anything unusable degrades rather than failing the spawn |
+| `model` | `Model` **or** `"provider/modelId"` | Strings are resolved at the RPC boundary against `ctx.modelRegistry`. `null` means inherit, not override. Resolution is fuzzy — see [Model Scope](../README.md#model-scope) |
+| `maxTurns` | number | Turn ceiling for the run |
+| `isolated` | boolean | Strips extensions, skills and nested tools. **Not** a git worktree — see the trap table below |
+| `inheritContext` | boolean | Fork the parent conversation into the child |
+| `thinkingLevel` | ThinkingLevel | Clamped to what the resolved model supports |
+| `isBackground` | boolean | Occupies a `maxConcurrent` slot and queues behind them. Every RPC spawn runs detached regardless; this is what decides whether it is *pooled* |
+| `bypassQueue` | boolean | Starts immediately even when the concurrency limit would queue it. The slot is still counted once running |
+| `structuredOutput` | CompiledSchema | Makes the child report through a `StructuredOutput` tool |
+| `isolation` | `"worktree"` | Temp git worktree, committed to a `pi-agent-*` branch on completion |
+| `cwd` | absolute path | The agent's tools operate here; `.pi` config still loads from the parent session's project |
+| `invocation` | AgentInvocation | Resolved snapshot used for UI display |
+| `signal` | AbortSignal | Aborting it stops the subagent |
+| `onSpawned` / `onQueued` / `onCompaction` / `onBeforeWorktreeCleanup` | functions | Fire as documented on `SpawnOptions` |
+
+**Silently stripped** — set these and nothing happens, with no error and no note. Each deletion is a deliberate guard, and the reasons are worth knowing because they say what the surface refuses to let a caller forge:
+
+| Field | Why it is taken away |
+|---|---|
+| `parentAgentId` | Ownership. A forged parent hides your agent under someone else's nested tools |
+| `workflowId` | A forged value would hide an RPC-spawned agent inside someone else's workflow — and take it out of the concurrency pool with it |
+| `depth`, `maxSubagentDepth` | The nesting cap is inherited, not declared |
+| `configCwd` | Config-discovery root; only nested launches may set it |
+| `rootSessionId` | Names a transcript directory, so a forged value is a path-traversal primitive |
+| `resumeSessionFile` | Worse: it names a file to **open and replay** as a conversation. Dispatcher only, and only from a path this extension itself recorded |
+| `reclaim` | Bypasses handle allocation, so a forged value would duplicate a live agent's name and make `@handle` ambiguous |
+| `blocking` | Every spawn through here is detached. A forged `blocking` would charge it to the foreground pool and defer it behind a queue whose gate nobody is holding |
+
+**Silently overwritten** — `onToolActivity`, `onTextDelta`, `onTurnEnd`, `onSessionCreated` and `onAssistantUsage` are replaced by the activity tracker's own (`src/index.ts:693`). Every programmatic spawn passes through one funnel so none can supply half-wired callbacks; a half-wired tracker renders worse than none, which is the bug behind a row that reads `thinking…` for an agent's whole life ([#181](https://github.com/tintinweb/pi-subagents/pull/181)).
+
+Four things that are not obvious from the tables:
+
+- **Nothing is required at runtime.** `description` is non-optional in TypeScript and never validated. A spawn with no `options` at all is legal and is what `test/cross-extension-rpc.test.ts:81-94` pins.
+- **`bypassQueue` is not stripped.** Its own doc comment scopes it to the scheduler and the `/agents` generator, but a bus caller can set it and skip the `maxConcurrent` check.
+- **`structuredOutput` is documented "set only by the workflow host"** (`src/agent-manager.ts:231-234`) and is also not stripped.
+- **`signal` and the `on*` callbacks are function values.** They work only because the bus is in-process. A caller that genuinely serializes its payload cannot use them, and they arrive as `undefined` rather than failing.
+
+### Names that look right and are not
+
+One of these already shipped as a bug in this project's own README example, so it is worth reading the table even if you are sure.
+
+| You might write | What it does | What you meant |
+|---|---|---|
+| `run_in_background` | Forwarded verbatim and ignored — it is the [`Agent`](../README.md#agent) *tool's* parameter name | `isBackground` |
+| `isolated: true` | Disables extensions, skills and nested tools | `isolation: "worktree"` for a git worktree |
+| `isolation: "worktree"` | Creates a git worktree | `isolated: true` to strip capabilities |
+| `configCwd` | Stripped | `cwd` |
+| `max_turns` / `thinking` / `inherit_context` | Ignored — tool and frontmatter spellings | `maxTurns` / `thinkingLevel` / `inheritContext` |
+| `memory` | Nothing. **There is no such option** | Memory scope comes only from the agent definition's frontmatter |
+
+**None of these produce an error.** Option keys are not validated on this path at all — unknown ones are accepted and dropped. (Contrast `agent()` inside a [workflow](workflows.md), which rejects unknown keys by name.)
+
+## Errors
+
+Every failure reaches the caller as `{ success: false, error }`, where `error` is `err?.message ?? String(err)` (`src/cross-extension-rpc.ts:87`) — so these strings are what you will actually see.
+
+| Error | Source |
+|---|---|
+| `No active session` | `src/cross-extension-rpc.ts:107` — called before the first bound `session_start`, or in a session that excludes pi-subagents |
+| `Model override "<label>" provided but ctx.modelRegistry is unavailable` | `src/cross-extension-rpc.ts:126` |
+| `Model not found: "<input>".` + available models | `src/model-resolver.ts:117` |
+| `Model not in scope: "<input>".` + allowed models | `src/model-scope.ts:62` — only with `scopeModels` on, and checked against the *resolved* model |
+| `Unknown or disabled agent type: "<raw>". Available: <list>.` | `src/agent-types.ts:187` — only under `fallbackSubagent: none` |
+| `No agent type given. Available: <list>.` | `src/agent-types.ts:187-194` — same condition |
+| `<reason> The configured fallbackSubagent "<x>" is itself unknown or disabled. Available: <list>.` | `src/agent-types.ts:205-207` |
+| `SpawnOptions.cwd must be an absolute path: "<value>"` | `src/agent-manager.ts:85` |
+| `SpawnOptions.cwd does not exist: "<cwd>"` | `src/agent-manager.ts:91` |
+| `SpawnOptions.cwd is not a directory: "<cwd>"` | `src/agent-manager.ts:94` |
+| `Cannot run with isolation: "worktree" — not a git repo, no commits yet, or 'git worktree add' failed.` | `src/agent-manager.ts:716-719`, surfaced through `awaitStartup` |
+| git plumbing failures | `src/worktree.ts:76` |
+| `Agent not found` | stop — `src/cross-extension-rpc.ts:170` |
+| `Agent is owned by another agent or workflow` | stop — `:178` |
+| `Agent is not running` | stop — `:182`. The record exists, so it has already settled |
+| `Agent not found or still running` | consume — `:193` |
+
+Three things the table cannot show:
+
+- **The failure that is not an error.** With `worktreeIsolation` off project-wide, `isolation: "worktree"` is dropped at `src/agent-manager.ts:712` with no error, no note on the record, and a success envelope on the wire. Your agent runs in the main tree. If you asked for isolation because two agents were going to write the same files, they now collide and nothing told you.
+- **`data` is omitted** when a handler returns nothing, so a successful stop or consume reply is a bare `{ success: true }` and `reply.data.anything` throws.
+- **`requestId` is not validated.** It is interpolated straight into the reply channel, so a caller that omits it gets its reply on the literal channel `subagents:rpc:spawn:reply:undefined` — where every other caller that omitted it is also listening. Send one, and send a unique one.
+
+## Ownership
+
+`isTopLevelAgent(record)` is `parentAgentId === undefined && workflowId === undefined` (`src/agent-manager.ts:122-126`). `subagents:rpc:stop` enforces it (`src/cross-extension-rpc.ts:178`): a nested child or a workflow's agent is owned by something that is *waiting on it*, and aborting it out from under that owner turns another extension's stop into a failed step. It is defence in depth rather than a live hole — no RPC hands out agent ids, so a caller has no ordinary way to name one it does not own.
+
+Two asymmetries to know about, stated as they are:
+
+- **Stop takes an id only** (`src/index.ts:806`). Consume takes an id *or* an `@handle`, through `resolveAgentRef` (`src/index.ts:816` → `:731-736`).
+- **Consume checks `parentAgentId` but not `workflowId`** (`src/index.ts:816`). A workflow-owned agent's result can be marked consumed over the bus even though the same agent cannot be stopped.
+
+The same predicate silently scopes the events. **Every lifecycle event is top-level only** — `subagents:started`, `:completed`, `:failed` and `:compacted` all return early for nested and workflow-owned agents (`src/index.ts:573`, `:615`, `:631`). A workflow's children are invisible on the bus: you will see the workflow's own agents come and go without a single event.
+
+## The notification race
+
+When a background agent finishes, pi-subagents sends the user a completion notification. If you have already shown the model that result yourself, that notification arrives on top of an answer that was already given, and it costs the parent a turn to dismiss. `subagents:rpc:consume` is how you say you have handled it — the bus-side half of what `get_subagent_result` does when it returns a result.
+
+**When you send it decides whether it works.** The timeline:
+
+1. The agent settles and `subagents:completed` is emitted — `src/index.ts:581`.
+2. Eleven lines later, at `src/index.ts:592`, the code checks `record.resultConsumed` and decides whether to notify at all.
+3. `pi.events` dispatch is synchronous and in-process, so a handler that emits `subagents:rpc:consume` **without awaiting anything** has already set that flag before step 2 evaluates.
+
+| When you consume | What happens |
+|---|---|
+| Synchronously, inside your `subagents:completed` handler | The notification is never scheduled. This is the clean path |
+| After an `await`, within 200 ms | Still suppressed. The nudge is held for `NUDGE_HOLD_MS` (`src/index.ts:451`), `consume` cancels the pending timer (`:819`), and there is a re-check at send time (`:474`) |
+| After 200 ms | Too late. The follow-up has fired with `triggerTurn: true` and cost the parent a turn |
+
+Fire-and-forget is the intended use: the reply carries nothing to act on, and the channel sits outside the `subagents:rpc:ping` version handshake on purpose (`src/cross-extension-rpc.ts:190`), so you can send it unconditionally and an older pi-subagents with no handler simply keeps notifying.
+
+Consumption is not terminal. An `@handle` steer un-consumes the record (`src/index.ts:920`) because the agent's reply to that message still needs relaying, and so does a background resume (`src/agent-manager.ts:1135`) because the record is starting a new run.
+
+One related thing that lives nowhere else: on every top-level settle, pi-subagents writes a session entry — not an event — via `pi.appendEntry("subagents:record", …)` (`src/index.ts:585`), carrying `id`, `type`, `description`, `status`, `result`, `error`, `startedAt` and `completedAt`. It exists for cross-extension history reconstruction. It is append-only history, not something to react to.
+
+## The manager registry
+
+`globalThis[Symbol.for("pi-subagents:manager")]` (`src/index.ts:649-659`) is a second integration surface — the standard Node cross-package singleton pattern, no bus involved:
+
+| Member | Signature | Notes |
+|---|---|---|
+| `waitForAll()` | `() => Promise<void>` | Resolves when nothing is running. **All** agents, including ones you did not spawn — a shutdown barrier, not a join |
+| `hasRunning()` | `() => boolean` | |
+| `spawn(pi, ctx, type, prompt, options)` | `=> string` | **Is** `spawnTopLevel`, so the strip list above applies identically |
+| `getRecord(id)` | `=> AgentRecord \| undefined` | Filtered through `isTopLevelAgent`, so someone else's child comes back `undefined` rather than leaking |
+
+The slot is claimed by the first activation only; subagent sessions re-activate this extension in the same process, and unconditionally overwriting would point the registry at a short-lived child manager whose shutdown would then delete the root session's entry ([#128](https://github.com/tintinweb/pi-subagents/pull/128)). Child activations leave it alone, and shutdown releases it only if this activation claimed it (`src/index.ts:747-750`, `:1105-1107`).
+
+Prefer the bus. The registry has no reply envelope, no version, and no availability event — `globalThis[Symbol.for("pi-subagents:manager")] === undefined` is the only probe you get, and it is also `undefined` in a session that filtered pi-subagents out. Reach for it for the two things the bus has no verb for — *is anything still running*, and *give me a settled record back* — or for a headless host that wants to block on `waitForAll()` before exiting.
+
+## Protocol versions
+
+`subagents:rpc:ping` replies `{ version: PROTOCOL_VERSION }`, currently `2` (`src/cross-extension-rpc.ts:33`). The constant was introduced already equal to `2` in 0.5.0; "v1" is a retroactive name for the pre-envelope contract, where spawn replied with a bare `{ id }` or `{ error }`, stop replied `{ success: boolean }` with no message, and each handler caught its own errors.
+
+Everything added since shipped **without a bump**, because all of it is additive: stop's ownership refusal, string-`model` resolution ([#59](https://github.com/tintinweb/pi-subagents/pull/59)/[#60](https://github.com/tintinweb/pi-subagents/issues/60)), `scopeModels` enforcement ([#240](https://github.com/tintinweb/pi-subagents/issues/240)), and the whole `consume` channel.
+
+> A `ping` that answers `2` does not tell you whether `consume` exists, whether model scope is enforced, or whether stop checks ownership.
+
+So: send `consume` unconditionally and ignore the outcome — an older build has no handler and simply keeps notifying, which is exactly why it was left outside the handshake. And treat every error envelope as authoritative rather than trying to predict which checks are in force.
+
+## Availability
+
+`subagents:ready` is the discovery signal, and both the RPC handlers and the event itself are wired on the first bound `session_start` (`src/index.ts:789`, `:799`, `:827`) — deliberately not at factory time. pi runs every extension factory *before* applying an agent's `extensions:` filter and only delivers lifecycle events to the survivors, so a factory-time broadcast made a filtered-out session advertise a spawn service it could never provide: `ping` succeeded and every `spawn` answered `No active session` ([#142](https://github.com/tintinweb/pi-subagents/issues/142)).
+
+The consequence is worth stating plainly: **a session that excludes pi-subagents is indistinguishable from pi-subagents not being installed.** It emits no `subagents:ready` and answers nothing. Give discovery a timeout and treat expiry as "not available here" rather than waiting indefinitely. The payload is `{}` — read nothing off it. Handlers are torn down and the flag reset on `session_shutdown` (`src/index.ts:1100-1103`), so a later `session_start` re-registers and re-emits.
+
+One more trap on the way in: an RPC-spawned agent emits **no `subagents:created`**. The only two emit sites are the `Agent` tool's background branch (`src/index.ts:2104`) and detached resume (`:1350`). Your first event for your own agent is `subagents:started` (`:625`), so key your bookkeeping off the id that `spawn` handed you, not off `subagents:created`.
+
+## What the tests pin
+
+This document has no test of its own, so it is worth knowing which claims are actually held in place:
+
+| Test | Level | Pins |
+|---|---|---|
+| `test/cross-extension-rpc.test.ts` | Mocked `SpawnCapable` | Envelope shape, per-channel error strings, model resolution and scope enforcement |
+| `test/rpc-lifecycle-gating.test.ts` | Real extension factory | Nothing wired at factory time, everything once at `session_start`, and live widget activity for RPC spawns ([#142](https://github.com/tintinweb/pi-subagents/issues/142)/[#181](https://github.com/tintinweb/pi-subagents/pull/181)) |
+| `test/rpc-result-consumption.test.ts` | Real delivery path | The notification firing, and not firing, around `consume` |
+
+Not pinned anywhere, so treat them as descriptions rather than contracts: the `SpawnOptions.cwd` error strings, `subagents:ready`'s `{}` payload, consume's handle resolution, and its missing `workflowId` check.
+
+## Reference implementation
+
+[**`tintinweb/pi-tasks`**](https://github.com/tintinweb/pi-tasks) is the working integration and the one this surface was shaped by. Its `TaskExecute` drives `subagents:rpc:spawn` — including the serialized `"provider/modelId"` string form that the boundary now resolves — and its `TaskOutput` drives `subagents:rpc:consume`, which exists because pi-tasks joins an agent on `subagents:completed` and reports the result itself ([pi-tasks#62](https://github.com/tintinweb/pi-tasks/issues/62)).
+
+Read it for the shape of the whole loop: waiting on `subagents:ready`, keeping an id-keyed map of outstanding spawns, resolving each from the `subagents:completed` / `subagents:failed` handler, and consuming the result in the same synchronous handler that reports it.
+
+If what you want is many coordinated agents rather than one, hand a script to [`SubagentWorkflow`](workflows.md) instead of fanning out over `subagents:rpc:spawn` — and note that a workflow's agents are not yours: they emit no lifecycle events, and `subagents:rpc:stop` refuses them.