shariq-pi-extensions 0.5.1 → 0.7.0

package/README.md

@@ -23,7 +23,7 @@ Run `/reload` in an existing Pi session after installation; new sessions load th
 - structured user questions (`ask_user`)
 - persistent goals with evidence checklists and budgets
 - a task list for multi-deliverable work, with a live progress dock
-- Pi subagents with profiles, worktree isolation, and a takeover dashboard
+- Pi subagents with profiles, worktree isolation, a takeover dashboard, and an optional Fusion mode (lead plus persistent sidekick across light, medium, and heavy model tiers)
 - Smart Compaction: structured checkpoints with file and worktree state
 - managed background terminals
 - Firecrawl web search, scraping, and developer search
@@ -33,7 +33,7 @@ Run `/reload` in an existing Pi session after installation; new sessions load th
 - configurable steer, interrupt, or follow-up Enter behavior
 - `/exit` as an alias for `/quit`
 
-The package also ships the `ember-warm-dark` theme and the `background-terminals` and `subagents` skills. Pi loads the skills from the installed package; copying them into `<agent-dir>/skills` would leave stale duplicates after removal.
+The package also ships the `ember-warm-dark` theme and the `background-terminals`, `fusion`, and `subagents` skills. Pi loads the skills from the installed package; copying them into `<agent-dir>/skills` would leave stale duplicates after removal.
 
 The suite is developed and tested against Pi 1.0. See [`docs/EXTENSIONS.md`](docs/EXTENSIONS.md) for commands, tools, configuration, and external dependencies.
 

package/docs/EXTENSIONS.md

@@ -18,7 +18,7 @@ Persistent, branch-safe objectives with an evidence checklist, token budgets, pa
 
 ### [Subagents](../extensions/subagents/README.md)
 
-Flat Pi child agents with profiles, capability policies, context forks, resumable sessions, optional git worktree isolation, peer messaging, and a takeover dashboard. Children cannot start agents. The model delegates only when the user asks. Results are delivered as custom messages that start a parent turn when the parent is idle. Configuration lives in `<agent-dir>/subagents.json`, with trusted-project overrides in `.pi/subagents.json`.
+Flat Pi child agents with profiles, capability policies, an optional per-profile process runtime that gives children Pi's built-in extensions (codemode, MCP, tool search), review options that drop skills or `AGENTS.md` files, context forks, resumable sessions, optional git worktree isolation, peer messaging, and a takeover dashboard. Children cannot start agents. The model delegates only when the user asks, unless optional Fusion mode is on: then the main session leads, a persistent `sidekick` implements decided work, and light `worker` and `verifier` profiles take routine edits and checks, each on a user-configured model tier. Results are delivered as custom messages that start a parent turn when the parent is idle. Configuration lives in `<agent-dir>/subagents.json`, with trusted-project overrides in `.pi/subagents.json`.
 
 ### [Smart Compaction](../extensions/smart-compaction/README.md)
 

package/extensions/shared/child-session.ts

@@ -38,6 +38,10 @@ export interface ChildResourceOptions {
   agentDir?: string;
   /** Child-only extensions, such as a capability guard, loaded beside the normal ones. */
   extensionFactories?: InlineExtension[];
+  /** Start without discovered skills, AGENTS.md files, or extensions (inline factories still load). */
+  noSkills?: boolean;
+  noContextFiles?: boolean;
+  noExtensions?: boolean;
 }
 
 /** Load normal global/package resources and trust-gated project resources. */
@@ -54,6 +58,9 @@ export async function createChildResources(options: ChildResourceOptions) {
       ? { appendSystemPrompt: options.appendSystemPrompt }
       : {}),
     ...(options.extensionFactories ? { extensionFactories: options.extensionFactories } : {}),
+    noSkills: options.noSkills,
+    noContextFiles: options.noContextFiles,
+    noExtensions: options.noExtensions,
   });
   await loader.reload();
   return { loader, settingsManager };

package/extensions/subagents/README.md

@@ -46,9 +46,20 @@ Capability modes:
 
 Restrictive modes fail closed: an extension tool is unavailable until it is classified in `src/backends/pi.ts`, and a child-only `tool_call` check refuses unclassified tools at call time, including tools registered later. The session-only `task_list` tool is allowed in every mode.
 
-Children load the same packages and extensions as the parent but not Pi's built-in extensions (`codemode`, MCP, and tool search), because Pi does not export them to extensions.
+## Runtimes and review options
 
-Each tool call inside a child times out after three minutes.
+Children run in-process by default: fast to start and light on memory. In-process children load the same packages and extensions as the parent but not Pi's built-in extensions (`codemode`, MCP, and tool search), because Pi does not export them to extensions. Each tool call inside an in-process child times out after three minutes.
+
+A profile with `"runtime": "process"` runs each child as its own `pi --mode rpc` process instead. The child gets the full Pi setup, including the built-in extensions, and a crash or memory blowup stays in the child. The cost is a second or two of startup and a separate process per child. A child-only extension loaded with `-e` enforces the capability inside the process and carries `message_parent`, `ask_parent`, `list_peers`, and `message_peer` over Pi's RPC dialog protocol. Closing the parent closes the child's input, and the child shuts down.
+
+`codemode` and `tool_search` are allowed in every capability mode; each tool a codemode script calls passes the same check, so a script cannot widen a child's capability.
+
+Profiles can also shape what the child starts with. None of these settings reach the model:
+
+- `"tools": ["read", "grep"]`: an exact allowlist on top of the capability;
+- `"skills": false`: start without skills;
+- `"contextFiles": false`: start without `AGENTS.md` and `CLAUDE.md` files, for an unbiased review;
+- `"extensions": false`: start without discovered extensions.
 
 User profiles and personas live in `<agent-dir>/subagents.json`. Trusted projects can override them in `.pi/subagents.json`:
 
@@ -60,6 +71,12 @@ User profiles and personas live in `<agent-dir>/subagents.json`. Trusted project
       "description": "Review changes without editing",
       "instructions": "Find correctness and regression risks. Cite files and lines.",
       "capability": "execute"
+    },
+    "fresh-eyes": {
+      "description": "Independent review that ignores repository instructions",
+      "capability": "execute",
+      "runtime": "process",
+      "contextFiles": false
     }
   },
   "personas": {
@@ -72,11 +89,42 @@ User profiles and personas live in `<agent-dir>/subagents.json`. Trusted project
 
 Project configuration is ignored for untrusted projects. `maxConcurrent` is bounded to 1–50 and defaults to 50. `/subagents profiles` lists profiles, and `/subagents config` opens a validated editor for the global or trusted-project file.
 
+## Fusion mode
+
+Fusion mode is optional and off by default. When it is on, the main session acts as the lead and delegates without being asked: one persistent `sidekick` per workstream implements decided work, and light profiles take routine edits and checks. The lead keeps intent, planning, architecture, security, and final review. Turn it on with `/subagents fusion on`, or set `"fusion": true` in either configuration file; a trusted project's setting wins over the global one.
+
+Fusion adds these profiles and tiers:
+
+| Profile | Tier | Capability | Use |
+|---|---|---|---|
+| `sidekick` | medium | all | decided implementation and debugging from a concrete failure |
+| `explore` | medium | execute | substantive read-only tracing |
+| `reviewer` | medium | execute | one fresh review of a final diff |
+| `worker` | light | all | fully specified mechanical edits, docs, narrow tests |
+| `verifier` | light | execute | builds, tests, and reproductions; reports failures only |
+| `general-purpose` | heavy | all | hard decided work after the sidekick is blocked |
+
+Each tier maps to a model and thinking level for children; the lead keeps the model you selected in Pi. An unset tier, or an unset field, inherits the parent session's, so with no `tiers` block every child runs on the parent's model:
+
+```json
+{
+  "fusion": true,
+  "tiers": {
+    "light": { "model": "provider/fast-model", "thinking": "medium" },
+    "medium": { "model": "provider/coding-model", "thinking": "xhigh" }
+  }
+}
+```
+
+Any profile can set `"tier"`, with or without Fusion mode. A profile's own `model` and `thinking` win over its tier, and a call's overrides win over both. Profiles you define with the same names are merged over the Fusion defaults, so you can change one field without restating the rest. `list_agent_profiles` and `/subagents profiles` show the mode, the tiers, and each profile's tier. A child started from a Fusion profile can still be resumed after the mode is turned off.
+
+Only the lead sees the Fusion guideline and the `fusion` skill; children keep the default rules and cannot start agents.
+
 ## Context and continuation
 
 New children start without parent context. `fork_turns` can be `all` or a positive number of recent user turns; the fork keeps user messages and final assistant text and drops thinking, tool calls, and tool results.
 
-Every child has a persistent Pi session file. `resume_from` continues a finished or cancelled child with its transcript, tool state, and id, including after a parent reload or restart. An archived child resumes with its stored profile, persona, capability, and worktree unless the call overrides them. A child still loaded in this session keeps its settings, so a resume call that passes different ones is rejected. A run interrupted by cancellation or reload is recorded as `cancelled`, not as a failure.
+Every child has a persistent Pi session file. `resume_from` continues a finished or cancelled child with its transcript, tool state, and id, including after a parent reload or restart. An archived child resumes with its stored profile, persona, capability, and worktree unless the call overrides them, and takes its model and thinking level from that profile, its tier, or the call. A child still loaded in this session keeps its settings, so a resume call that passes different ones is rejected. A run interrupted by cancellation or reload is recorded as `cancelled`, not as a failure.
 
 A child running in another Pi process cannot be resumed, and its worktree cannot be changed, until that process finishes or exits; a crashed owner is detected and its child becomes resumable.
 
@@ -100,7 +148,9 @@ Lifecycle tools render as compact cards with expandable detail. Running children
 ## Layout
 
 - `src/manager.ts`: Effect service, lifecycle, snapshots, cancellation, and retention
-- `src/backends/pi.ts`: in-process Pi child sessions, capability filtering, context seeding, resume, and the parent bridge
+- `src/backends/pi.ts`: in-process Pi child sessions, capability filtering, shared event translation, context seeding, resume, and the parent bridge
+- `src/backends/pi-process.ts`: process-runtime children over Pi's RPC protocol
+- `src/child-bridge.ts`: the extension loaded into process-runtime children for capability enforcement and the parent bridge
 - `src/config.ts`: profiles, personas, validation, and limits
 - `src/catalog.ts`: global resumable-agent catalog
 - `src/context.ts`: context forks and profile prompt assembly

package/extensions/subagents/index.ts

@@ -68,6 +68,7 @@ import {
   type IsolationMode,
 } from "./src/config.ts";
 import { buildTaskPrompt, forkConversation, parseForkTurns } from "./src/context.ts";
+import { FUSION_LEAD_GUIDELINE, isFusionSkill } from "./src/fusion.ts";
 import {
   applyAgentWorktree,
   applyAgentWorktreeTo,
@@ -102,6 +103,7 @@ import {
   upsertSubagentCatalog,
   type ArchivedSubagent,
 } from "./src/catalog.ts";
+import { CHILD_ENV } from "./src/child-bridge.ts";
 
 const SUBAGENT_OUTPUT_MAX_BYTES = 24 * 1024;
 const WAIT_OUTPUT_MAX_BYTES = 48 * 1024;
@@ -175,6 +177,8 @@ function truncatedOutput(
 }
 
 export default function (pi: ExtensionAPI) {
+  // A process-runtime child is managed by its parent; it must not manage children itself.
+  if (process.env[CHILD_ENV] === "1") return;
   const deliverSettlement = settlementDelivery(pi);
   let runtime: SubagentRuntime | undefined;
   let managerPromise: Promise<SubagentManagerShape> | undefined;
@@ -372,7 +376,7 @@ export default function (pi: ExtensionAPI) {
     ctx: ExtensionContext,
     options: SpawnOptions,
   ): Promise<PreparedSpawn> => {
-    const config = loadSubagentConfig(ctx.cwd, ctx.isProjectTrusted());
+    const config = loadSubagentConfig(ctx.cwd, ctx.isProjectTrusted(), { resumable: Boolean(options.resumeFrom) });
     const liveSource = options.resumeFrom ? manager.view.get(options.resumeFrom) : undefined;
     if (liveSource?.status === "running") {
       throw new Error(`Cannot resume running subagent "${options.resumeFrom}"; use send_message instead.`);
@@ -478,9 +482,10 @@ export default function (pi: ExtensionAPI) {
         title,
         origin: options.origin ?? "model",
         cwd,
-        model: resumeSessionFile ? options.model : profile.model,
-        reasoningEffort: resumeSessionFile ? options.thinking : profile.thinking,
+        model: profile.model,
+        reasoningEffort: profile.thinking,
         capability: profile.capability,
+        childOptions: profile.childOptions,
         agentType: profile.agentType,
         persona: profile.persona,
         isolation: profile.isolation,
@@ -692,6 +697,20 @@ export default function (pi: ExtensionAPI) {
     await closing?.dispose();
   });
 
+  // Fusion mode swaps the lead's activation rule and reveals the fusion skill.
+  // Children never have spawn_agent; they also hide the skill through hideFusionSkill.
+  pi.on("before_agent_start", (event, ctx) => {
+    const options = event.systemPromptOptions;
+    const lead = options.selectedTools.includes("spawn_agent");
+    const fusion = lead && loadSubagentConfig(ctx.cwd, ctx.isProjectTrusted()).fusion;
+    if (fusion && options.toolGuidelines.spawn_agent) {
+      options.toolGuidelines.spawn_agent = options.toolGuidelines.spawn_agent.map((guideline) =>
+        guideline === SUBAGENT_SPAWN_PROMPT_GUIDELINES[0] ? FUSION_LEAD_GUIDELINE : guideline,
+      );
+    }
+    if (!fusion) options.skills = options.skills.filter((skill) => !isFusionSkill(skill.baseDir));
+  });
+
   // --- Tools -------------------------------------------------------------
 
   pi.registerTool({
@@ -1025,7 +1044,10 @@ export default function (pi: ExtensionAPI) {
       const config = loadSubagentConfig(ctx.cwd, ctx.isProjectTrusted());
       const profileLines = Object.entries(config.profiles).map(
         ([name, profile]) =>
-          `profile ${name}: ${profile.description ?? "no description"}; capability=${profile.capability ?? "all"}; isolation=${profile.isolation ?? "none"}`,
+          `profile ${name}: ${profile.description ?? "no description"}; capability=${profile.capability ?? "all"}; isolation=${profile.isolation ?? "none"}${profile.tier ? `; tier=${profile.tier}` : ""}`,
+      );
+      const tierLines = Object.entries(config.tiers).map(
+        ([tier, setting]) => `tier ${tier}: model=${setting?.model ?? "parent"}; thinking=${setting?.thinking ?? "parent"}`,
       );
       const personaLines = Object.entries(config.personas).map(
         ([name, persona]) => `persona ${name}: ${persona.description ?? "no description"}`,
@@ -1033,9 +1055,9 @@ export default function (pi: ExtensionAPI) {
       return {
         content: [{
           type: "text",
-          text: [`maxConcurrent=${config.maxConcurrent}`, ...profileLines, ...personaLines].join("\n"),
+          text: [`maxConcurrent=${config.maxConcurrent}`, `fusion=${config.fusion ? "on" : "off"}`, ...tierLines, ...profileLines, ...personaLines].join("\n"),
         }],
-        details: { maxConcurrent: config.maxConcurrent, profiles: config.profiles, personas: config.personas },
+        details: { maxConcurrent: config.maxConcurrent, fusion: config.fusion, tiers: config.tiers, profiles: config.profiles, personas: config.personas },
       };
     },
     renderCall(_args, theme) {
@@ -1427,9 +1449,9 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.registerCommand("subagents", {
-    description: "Inspect agents, peer messages, profiles, or configuration",
+    description: "Inspect agents, peer messages, profiles, or configuration, or switch Fusion mode",
     getArgumentCompletions: (prefix) =>
-      ["agents", "peers", "profiles", "config"]
+      ["agents", "peers", "profiles", "config", "fusion", "fusion on", "fusion off"]
         .filter((value) => value.startsWith(prefix.trim()))
         .map((value) => ({ value, label: value })),
     handler: async (args, ctx) => {
@@ -1458,6 +1480,33 @@ export default function (pi: ExtensionAPI) {
         }
         return;
       }
+      if (action === "fusion" || action.startsWith("fusion ")) {
+        const value = action.slice("fusion".length).trim();
+        const enabled = () => loadSubagentConfig(ctx.cwd, ctx.isProjectTrusted()).fusion;
+        if (!value) {
+          ctx.ui.notify(`Fusion mode is ${enabled() ? "on" : "off"}. Use /subagents fusion on or off.`, "info");
+          return;
+        }
+        if (value !== "on" && value !== "off") {
+          ctx.ui.notify("Use /subagents fusion on or off", "error");
+          return;
+        }
+        try {
+          const document = JSON.parse(loadConfigDocument("global", ctx.cwd)) as Record<string, unknown>;
+          document.fusion = value === "on";
+          saveConfigDocument("global", ctx.cwd, JSON.stringify(document));
+          const overridden = enabled() !== (value === "on");
+          ctx.ui.notify(
+            overridden
+              ? `Saved fusion ${value} globally, but this project's .pi/subagents.json overrides it`
+              : `Fusion mode ${value}; it applies from your next message`,
+            overridden ? "warning" : "info",
+          );
+        } catch (error) {
+          ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+        }
+        return;
+      }
       const manager = await getManager();
       if (action === "peers") {
         await openPeerMessageViewer(ctx, manager.view);
@@ -1466,6 +1515,7 @@ export default function (pi: ExtensionAPI) {
       if (action === "profiles") {
         const config = loadSubagentConfig(ctx.cwd, ctx.isProjectTrusted());
         const entries = [
+          { label: `fusion: ${config.fusion ? "on" : "off"} · tiers`, text: JSON.stringify({ fusion: config.fusion, tiers: config.tiers }, null, 2) },
           ...Object.entries(config.profiles).map(([name, value]) => ({
             label: `profile: ${name}`,
             text: JSON.stringify(value, null, 2),
@@ -1481,7 +1531,7 @@ export default function (pi: ExtensionAPI) {
         return;
       }
       if (action !== "agents") {
-        ctx.ui.notify('Use /subagents agents, peers, profiles, or config', "error");
+        ctx.ui.notify('Use /subagents agents, peers, profiles, config, or fusion', "error");
         return;
       }
       if (manager.view.size() === 0) {

package/extensions/subagents/src/backends/pi-process.ts

@@ -0,0 +1,364 @@
+/**
+ * Process runtime for Pi subagents: each child is a separate `pi --mode rpc`
+ * process driven over Pi's documented JSONL RPC protocol. Children get the
+ * full CLI setup, including Pi's built-in extensions (codemode, MCP, tool
+ * search), and a crash stays in the child. The child-bridge extension enforces
+ * capability inside the child and carries parent questions over RPC dialogs.
+ */
+
+import { type ChildProcess, spawn } from "node:child_process";
+import * as fs from "node:fs";
+import { StringDecoder } from "node:string_decoder";
+import { fileURLToPath } from "node:url";
+import type { AssistantMessage, Model } from "@earendil-works/pi-ai";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+import type { Cause, Scope } from "effect";
+import { Effect, Queue, Stream } from "effect";
+import type { SubagentSession } from "../backend.ts";
+import type { SpawnTask, SubagentEvent, SubagentMeta } from "../domain.ts";
+import { SendError, SpawnError } from "../domain.ts";
+import {
+  BRIDGE_MARK,
+  CHILD_BRIDGE_ENV,
+  CHILD_CAPABILITY_ENV,
+  CHILD_ENV,
+  CHILD_TOOLS_ENV,
+  type BridgeRequest,
+} from "../child-bridge.ts";
+import { boundedError, resolvePiModel, settledOutcome, translateSessionEvent } from "./pi.ts";
+
+const STARTUP_TIMEOUT_MS = 60_000;
+const SHUTDOWN_TIMEOUT_MS = 5_000;
+const STDERR_TAIL_CHARS = 4_000;
+const CHILD_BRIDGE_PATH = fileURLToPath(new URL("../child-bridge.ts", import.meta.url));
+
+/**
+ * The command that starts this same Pi build. Under Node or Bun the entry
+ * script (often a `pi` symlink to cli.js) follows the runtime; a compiled
+ * binary is its own executable.
+ */
+export function piCommand(argv = process.argv, execPath = process.execPath): { file: string; args: string[] } {
+  const script = argv[1];
+  try {
+    if (script) {
+      const resolved = fs.realpathSync(script);
+      if (resolved !== fs.realpathSync(execPath) && fs.statSync(resolved).isFile()) {
+        return { file: execPath, args: [resolved] };
+      }
+    }
+  } catch {
+    // Fall through to the executable itself.
+  }
+  return { file: execPath, args: [] };
+}
+
+/** CLI arguments for one child; exported for tests. */
+export function childArgs(task: SpawnTask, model: Model<any> | undefined, sessionFile: string | undefined): string[] {
+  const args = ["--mode", "rpc"];
+  if (sessionFile) args.push("--session", sessionFile);
+  if (model) args.push("--provider", model.provider, "--model", model.id);
+  const thinking = task.reasoningEffort ?? task.parent.inheritedThinkingLevel;
+  if (thinking) args.push("--thinking", thinking);
+  args.push(task.parent.projectTrusted ? "--approve" : "--no-approve");
+  if (task.childOptions?.skills === false) args.push("--no-skills");
+  if (task.childOptions?.contextFiles === false) args.push("--no-context-files");
+  if (task.childOptions?.extensions === false) args.push("--no-extensions");
+  args.push("-e", CHILD_BRIDGE_PATH);
+  return args;
+}
+
+/** Seed a new child session with the forked parent context, as the in-process runtime does. */
+function prepareSessionFile(task: SpawnTask): string | undefined {
+  if (task.resumeSessionFile) return task.resumeSessionFile;
+  const inherited = task.parent.inheritedMessages ?? [];
+  if (inherited.length === 0) return undefined;
+  const manager = SessionManager.create(task.cwd, undefined, { parentSession: task.parent.parentSessionFile });
+  for (const message of inherited) manager.appendMessage(message);
+  const file = manager.getSessionFile();
+  return file && fs.existsSync(file) ? file : undefined;
+}
+
+type RpcRecord = { type?: string; id?: string; [key: string]: any };
+
+export const makeProcessSession = (
+  task: SpawnTask,
+): Effect.Effect<SubagentSession, SpawnError, Scope.Scope> =>
+  Effect.gen(function* () {
+    const registry = task.parent.modelRegistry;
+    const model = yield* Effect.try({
+      try: () => (registry ? resolvePiModel(registry, task.model, task.parent.inheritedModel) : task.parent.inheritedModel),
+      catch: (error) => new SpawnError({ message: boundedError(error) }),
+    });
+    const sessionFile = yield* Effect.try({
+      try: () => prepareSessionFile(task),
+      catch: (error) => new SpawnError({ message: boundedError(error) }),
+    });
+
+    const events = yield* Queue.make<SubagentEvent, Cause.Done>();
+    const emit = (event: SubagentEvent) => {
+      Queue.offerUnsafe(events, event);
+    };
+
+    const state = {
+      closed: false,
+      exited: false,
+      streaming: false,
+      settled: false,
+      runError: undefined as string | undefined,
+      runStartIndex: 0,
+      messages: [] as unknown[],
+      sessionFile,
+      sessionId: undefined as string | undefined,
+      stderr: "",
+      nextId: 0,
+    };
+    const pending = new Map<string, { resolve: (data: unknown) => void; reject: (error: Error) => void }>();
+
+    const command = piCommand();
+    const child: ChildProcess = spawn(command.file, [...command.args, ...childArgs(task, model, sessionFile)], {
+      cwd: task.cwd,
+      env: {
+        ...process.env,
+        [CHILD_ENV]: "1",
+        [CHILD_CAPABILITY_ENV]: task.capability,
+        ...(task.childOptions?.tools ? { [CHILD_TOOLS_ENV]: JSON.stringify(task.childOptions.tools) } : {}),
+        ...(task.parent.bridge ? { [CHILD_BRIDGE_ENV]: "1" } : {}),
+      },
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    const failAll = (error: Error) => {
+      for (const entry of pending.values()) entry.reject(error);
+      pending.clear();
+    };
+    const exitError = () => new Error(`The subagent process exited.${state.stderr.trim() ? ` ${state.stderr.trim().slice(-STDERR_TAIL_CHARS)}` : ""}`);
+
+    const write = (record: RpcRecord) => {
+      if (state.exited || !child.stdin?.writable) throw exitError();
+      child.stdin.write(`${JSON.stringify(record)}\n`);
+    };
+    const request = (record: RpcRecord) => new Promise<unknown>((resolve, reject) => {
+      const id = `req-${++state.nextId}`;
+      pending.set(id, { resolve, reject });
+      try {
+        write({ ...record, id });
+      } catch (error) {
+        pending.delete(id);
+        reject(error as Error);
+      }
+    });
+
+    const settle = () => {
+      if (state.settled) return;
+      state.settled = true;
+      emit({ _tag: "RunSettled", outcome: settledOutcome(state.messages, state.runStartIndex, state.runError) });
+    };
+
+    const currentMeta = (): SubagentMeta => {
+      const last = [...state.messages].reverse().find((message) => (message as { role?: string })?.role === "assistant") as AssistantMessage | undefined;
+      const label = last ? `${last.provider}/${last.model}` : model ? `${model.provider}/${model.id}` : undefined;
+      return {
+        backend: "pi",
+        origin: task.origin,
+        modelLabel: label,
+        contextWindow: model?.contextWindow,
+        sessionFilePath: state.sessionFile,
+        nativeSessionId: state.sessionId,
+        agentType: task.agentType,
+        persona: task.persona,
+        capability: task.capability,
+        isolation: task.isolation,
+        worktree: task.worktree,
+        concurrencyGroup: task.concurrencyGroup,
+        resumedFrom: task.resumeSessionFile,
+      };
+    };
+
+    // Answer bridge dialogs; dismiss every other dialog, since no person is watching the child.
+    const answerUi = async (record: RpcRecord) => {
+      const reply = (body: Record<string, unknown>) => {
+        try {
+          write({ type: "extension_ui_response", id: record.id, ...body });
+        } catch {
+          // The child exited; nothing is waiting for the answer.
+        }
+      };
+      const marked = (text: unknown) => typeof text === "string" && text.startsWith(BRIDGE_MARK)
+        ? JSON.parse(text.slice(BRIDGE_MARK.length)) as BridgeRequest
+        : undefined;
+      if (record.method === "notify") {
+        const body = marked(record.message);
+        if (body?.kind === "notify") task.parent.bridge?.notify(body.message);
+        return;
+      }
+      if (!["select", "confirm", "input", "editor"].includes(record.method)) return;
+      const body = record.method === "input" ? marked(record.title) : undefined;
+      const bridge = task.parent.bridge;
+      if (!body || !bridge) return reply({ cancelled: true });
+      try {
+        if (body.kind === "ask") reply({ value: await bridge.ask(body.question) });
+        else if (body.kind === "peers") reply({ value: JSON.stringify(bridge.listPeers()) });
+        else if (body.kind === "peer") {
+          await bridge.messagePeer(body.id, body.message);
+          reply({ value: "ok" });
+        } else reply({ cancelled: true });
+      } catch (error) {
+        reply({ value: `error: ${boundedError(error)}` });
+      }
+    };
+
+    const handleRecord = (record: RpcRecord) => {
+      if (record.type === "response") {
+        const entry = record.id ? pending.get(record.id) : undefined;
+        if (!entry) return;
+        pending.delete(record.id!);
+        if (record.success === false) entry.reject(new Error(String(record.error ?? "RPC command failed")));
+        else entry.resolve(record.data);
+        return;
+      }
+      if (record.type === "extension_ui_request") {
+        void answerUi(record);
+        return;
+      }
+      if (state.closed) return;
+      switch (record.type) {
+        case "agent_start":
+          state.streaming = true;
+          state.settled = false;
+          emit({ _tag: "RunStarted" });
+          break;
+        case "message_end":
+          state.messages.push(record.message);
+          translateSessionEvent(record as { type: string }, emit);
+          if ((record.message as { role?: string })?.role === "assistant") {
+            const usage = (record.message as AssistantMessage).usage;
+            emit({ _tag: "UsageChanged", tokens: usage?.totalTokens, contextWindow: model?.contextWindow });
+            emit({ _tag: "MetaChanged", meta: currentMeta() });
+          }
+          break;
+        case "agent_settled":
+          state.streaming = false;
+          settle();
+          break;
+        default:
+          translateSessionEvent(record as { type: string }, emit);
+      }
+    };
+
+    // Strict JSONL: split only on LF, never on Unicode line separators.
+    const decoder = new StringDecoder("utf8");
+    let buffer = "";
+    child.stdout!.on("data", (chunk: Buffer) => {
+      buffer += decoder.write(chunk);
+      let newline = buffer.indexOf("\n");
+      while (newline >= 0) {
+        const line = buffer.slice(0, newline).replace(/\r$/, "");
+        buffer = buffer.slice(newline + 1);
+        if (line.trim()) {
+          try {
+            handleRecord(JSON.parse(line) as RpcRecord);
+          } catch {
+            // Ignore a malformed record rather than losing the session.
+          }
+        }
+        newline = buffer.indexOf("\n");
+      }
+    });
+    child.stderr!.on("data", (chunk: Buffer) => {
+      state.stderr = (state.stderr + chunk.toString("utf8")).slice(-STDERR_TAIL_CHARS);
+    });
+    const exited = new Promise<void>((resolve) => {
+      const onExit = () => {
+        if (state.exited) return;
+        state.exited = true;
+        failAll(exitError());
+        if (!state.closed && !state.settled) {
+          state.runError ??= exitError().message;
+          state.streaming = false;
+          settle();
+        }
+        resolve();
+      };
+      child.once("exit", onExit);
+      child.once("error", (error) => {
+        state.stderr += `\n${error.message}`;
+        onExit();
+      });
+    });
+
+    yield* Effect.addFinalizer(() =>
+      Effect.promise(async () => {
+        state.closed = true;
+        // Closing stdin asks Pi for an orderly shutdown; escalate if it lingers.
+        child.stdin?.end();
+        const timeout = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms).unref?.());
+        await Promise.race([exited, timeout(SHUTDOWN_TIMEOUT_MS)]);
+        if (!state.exited) {
+          child.kill("SIGTERM");
+          await Promise.race([exited, timeout(1_000)]);
+          if (!state.exited) child.kill("SIGKILL");
+        }
+        failAll(new Error("Subagent session is closed."));
+        Queue.endUnsafe(events);
+      }),
+    );
+
+    // Wait until the child answers before handing the session to the manager.
+    const ready = yield* Effect.tryPromise({
+      try: () => Promise.race([
+        request({ type: "get_state" }),
+        new Promise((_resolve, reject) => setTimeout(() => reject(new Error("The subagent process did not start in time.")), STARTUP_TIMEOUT_MS).unref?.()),
+      ]) as Promise<{ sessionFile?: string; sessionId?: string }>,
+      catch: (error) => new SpawnError({ message: boundedError(error) }),
+    });
+    state.sessionFile = ready.sessionFile ?? state.sessionFile;
+    state.sessionId = ready.sessionId;
+
+    const startRun = (text: string) => {
+      state.runError = undefined;
+      state.settled = false;
+      state.runStartIndex = state.messages.length;
+      emit({ _tag: "RunStarted" });
+      request({ type: "prompt", message: text }).then(
+        (data) => {
+          // A handled prompt (for example an extension command) starts no run.
+          if ((data as { disposition?: string } | undefined)?.disposition === "handled" && !state.streaming) settle();
+        },
+        (error) => {
+          state.runError = boundedError(error);
+          if (!state.streaming) settle();
+        },
+      );
+    };
+
+    emit({ _tag: "MetaChanged", meta: currentMeta() });
+    startRun(task.prompt);
+
+    return {
+      meta: Effect.sync(currentMeta),
+      events: Stream.fromQueue(events),
+      send: (text) =>
+        Effect.suspend((): Effect.Effect<void, SendError> => {
+          if (state.closed || state.exited) return new SendError({ message: "Subagent session is closed." });
+          if (state.streaming) {
+            return Effect.tryPromise({
+              try: () => request({ type: "steer", message: text }),
+              catch: (error) => new SendError({ message: boundedError(error) }),
+            }).pipe(Effect.asVoid);
+          }
+          return Effect.sync(() => startRun(text));
+        }),
+      interrupt: Effect.promise(async () => {
+        if (state.closed || state.exited) return;
+        await request({ type: "clear_queue" }).catch(() => undefined);
+        await request({ type: "abort" }).catch(() => undefined);
+        while (!state.closed && !state.exited && state.streaming) {
+          await new Promise((resolve) => setTimeout(resolve, 50));
+        }
+        if (!state.closed && !state.settled) {
+          state.settled = true;
+          emit({ _tag: "RunSettled", outcome: { _tag: "Interrupted" } });
+        }
+      }),
+    } satisfies SubagentSession;
+  });