shariq-pi-extensions 0.5.0 → 0.6.0

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. 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)
 
@@ -58,4 +58,4 @@ Adds `/exit` as an alias for `/quit`.
 
 ## Tool exposure
 
-Pi 1.0 lets each tool choose how the model reaches it. Tools that ask the user, manage lifecycles, or change session state (questions, goals, task list, terminals, subagents) use `model-only` exposure: they stay declared to the model even with `codemode.mode: "only"`, and codemode scripts cannot call them. The read-only web tools keep the default `direct` exposure so scripts can call them in parallel. Read-only tools also declare `readOnlyHint` annotations for permission extensions.
+Pi 1.0 lets each tool choose how the model reaches it. Tools that ask the user, manage lifecycles, or change session state (questions, goals, task list, starting, writing to, or stopping terminals, subagents) use `model-only` exposure: they stay declared to the model even with `codemode.mode: "only"`, and codemode scripts cannot call them. The read-only web tools and `read_terminal` and `list_terminals` keep the default `direct` exposure so scripts can call them in parallel and filter their output. Read-only tools also declare `readOnlyHint` annotations for permission extensions.

package/extensions/background-terminals/README.md

@@ -10,7 +10,7 @@ Session-scoped background pseudo-terminals for Pi. The extension combines Codex-
 - `list_terminals` — list running and settled terminals.
 - `stop_terminal` — stop complete process groups with TERM-to-KILL escalation.
 
-Each output response carries a byte cursor; pass it to the next read or write to get only new output. The tools render as compact cards with expandable output, use `model-only` exposure, and running terminals appear in the shared **Active work** dock with elapsed time and the latest output line.
+`read_terminal` and `list_terminals` are read-only and callable from codemode scripts, so a script can filter a long log down to what matters; the tools that start, write to, or stop processes use `model-only` exposure. Each output response carries a byte cursor; pass it to the next read or write to get only new output. The tools render as compact cards with expandable output, and running terminals appear in the shared **Active work** dock with elapsed time and the latest output line.
 
 When a model-started terminal exits, its status and a bounded output tail are delivered as a custom message. An idle parent starts a new turn for it; a busy parent receives it, together with any other pending results, when its run settles. The message never appears as user-authored or follow-up input, and reading the terminal does not suppress it.
 

package/extensions/background-terminals/index.ts

@@ -230,7 +230,7 @@ export default function backgroundTerminals(pi: ExtensionAPI) {
     description:
       "Read a background terminal's output since a cursor; omit the cursor for the retained tail. " +
       "Use it when the user asks for progress or the process is waiting for input. Completion output arrives on its own.",
-    exposure: "model-only",
+    // Read-only, so codemode scripts may call it to filter large logs.
     annotations: { readOnlyHint: true, openWorldHint: false },
     parameters: Type.Object({
       id: Type.String({ description: 'Terminal id, such as "term-1".' }),
@@ -317,7 +317,6 @@ export default function backgroundTerminals(pi: ExtensionAPI) {
     name: "list_terminals",
     label: "List Background Terminals",
     description: "List background terminals with id, status, pid, elapsed time, and working directory.",
-    exposure: "model-only",
     annotations: { readOnlyHint: true, openWorldHint: false },
     parameters: Type.Object({}),
     async execute() {

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

@@ -44,9 +44,22 @@ Capability modes:
 - `execute`: the read-only set plus `bash` and background terminals, without direct edits;
 - `all`: every tool the child loads.
 
-Restrictive modes fail closed: an extension tool is unavailable until it is classified in `src/backends/pi.ts`. The session-only `task_list` tool is allowed in every mode.
+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.
 
-Each tool call inside a child times out after three minutes.
+## Runtimes and review options
+
+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`:
 
@@ -58,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": {
@@ -98,7 +117,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

@@ -102,6 +102,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 +176,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;
@@ -481,6 +484,7 @@ export default function (pi: ExtensionAPI) {
         model: resumeSessionFile ? options.model : profile.model,
         reasoningEffort: resumeSessionFile ? options.thinking : profile.thinking,
         capability: profile.capability,
+        childOptions: profile.childOptions,
         agentType: profile.agentType,
         persona: profile.persona,
         isolation: profile.isolation,

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;
+  });

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

@@ -37,6 +37,7 @@ import {
   shutdownAndDisposeChildSession,
 } from "../../../shared/child-session.ts";
 import { createToolCallTimeoutGuard } from "../../../shared/tool-call-timeout.ts";
+import { makeProcessSession } from "./pi-process.ts";
 
 const CHILD_SHUTDOWN_TIMEOUT_MS = 5_000;
 
@@ -70,6 +71,11 @@ const READ_CAPABILITY_TOOLS = new Set([
   "ask_parent",
   "list_peers",
   "message_peer",
+  // Pi built-ins that process-runtime children load. Each tool a codemode
+  // script calls passes the same tool_call check, and tool_search only finds
+  // tools, so neither can widen a child's capability.
+  "codemode",
+  "tool_search",
 ]);
 
 const WRITE_CAPABILITY_TOOLS = new Set(["write", "edit"]);
@@ -96,27 +102,40 @@ export function filterToolsForCapability(
   });
 }
 
+/** True when a child with this capability and optional exact allowlist may use the tool. */
+export function childToolAllowed(
+  name: string,
+  capability: SpawnTask["capability"],
+  allowlist?: ReadonlyArray<string>,
+): boolean {
+  if (allowlist && !allowlist.includes(name)) return false;
+  return filterToolsForCapability([name], capability).length > 0;
+}
+
 /**
- * Keep a restrictive child inside its capability for its whole life. A child-only
- * tool_call blocker refuses every unclassified tool, including tools registered
- * after startup and nested codemode calls; the loadout filter keeps them out of
- * the model's view. Tool definitions are never mutated because Pi shares them
- * by reference with the parent session.
+ * Keep a child inside its capability and allowlist for its whole life. A
+ * child-only tool_call blocker refuses every disallowed tool, including tools
+ * registered after startup and nested codemode calls; the loadout filter keeps
+ * them out of the model's view. Tool definitions are never mutated because Pi
+ * shares them by reference with the parent session.
  */
-export function capabilityGuardExtension(capability: SpawnTask["capability"]): ExtensionFactory {
+export function capabilityGuardExtension(
+  capability: SpawnTask["capability"],
+  allowlist?: ReadonlyArray<string>,
+): ExtensionFactory {
   return (pi) => {
-    if (capability === "all") return;
+    if (capability === "all" && !allowlist) return;
     pi.on("tool_call", (event) => {
-      if (filterToolsForCapability([event.toolName], capability).length) return undefined;
-      return { block: true, reason: `Tool "${event.toolName}" is not permitted for a ${capability} subagent.` };
+      if (childToolAllowed(event.toolName, capability, allowlist)) return undefined;
+      return { block: true, reason: `Tool "${event.toolName}" is not permitted for this subagent.` };
     });
   };
 }
 
-function restrictActiveTools(session: AgentSession, capability: SpawnTask["capability"]) {
-  if (capability === "all") return;
+function restrictActiveTools(session: AgentSession, capability: SpawnTask["capability"], allowlist?: ReadonlyArray<string>) {
+  if (capability === "all" && !allowlist) return;
   const active = session.getActiveToolNames();
-  const allowed = filterToolsForCapability(active, capability);
+  const allowed = active.filter((name) => childToolAllowed(name, capability, allowlist));
   if (allowed.length !== active.length) session.setActiveToolsByName(allowed);
 }
 
@@ -249,11 +268,10 @@ function messageRole(msg: unknown): Message["role"] | undefined {
   return undefined;
 }
 
-function lastAssistantMessage(
-  session: AgentSession,
+export function lastAssistantMessage(
+  messages: ReadonlyArray<unknown>,
   fromIndex = 0,
 ): AssistantMessage | undefined {
-  const messages = session.messages;
   for (let i = messages.length - 1; i >= fromIndex; i--) {
     const msg = messages[i];
     if (messageRole(msg) === "assistant") return msg as AssistantMessage;
@@ -262,8 +280,7 @@ function lastAssistantMessage(
 }
 
 /** Final assistant text output (last assistant message with text), v1 semantics. */
-function finalOutput(session: AgentSession, fromIndex = 0): string {
-  const messages = session.messages;
+export function finalOutput(messages: ReadonlyArray<unknown>, fromIndex = 0): string {
   for (let i = messages.length - 1; i >= fromIndex; i--) {
     const msg = messages[i];
     if (messageRole(msg) !== "assistant") continue;
@@ -347,7 +364,68 @@ function userText(msg: Message): string {
 
 // --- The session ------------------------------------------------------------------
 
-function boundedError(error: unknown) {
+/**
+ * Translate the Pi session events both runtimes share into subagent events.
+ * Run lifecycle, usage, and metadata stay with each runtime.
+ */
+export function translateSessionEvent(
+  event: { type: string; [key: string]: any },
+  emit: (event: SubagentEvent) => void,
+): void {
+  switch (event.type) {
+    case "message_update": {
+      const streamEvent = event.assistantMessageEvent;
+      if (streamEvent?.type === "text_delta") emit({ _tag: "AssistantDelta", kind: "text", delta: streamEvent.delta });
+      else if (streamEvent?.type === "thinking_delta") emit({ _tag: "AssistantDelta", kind: "thinking", delta: streamEvent.delta });
+      break;
+    }
+    case "message_end": {
+      const role = messageRole(event.message);
+      if (role === "user") {
+        const text = userText(event.message as Message);
+        if (text.trim()) emit({ _tag: "UserMessage", text });
+      } else if (role === "assistant") {
+        emit({ _tag: "AssistantMessage", parts: assistantParts(event.message as AssistantMessage) });
+      }
+      // toolResult messages are covered by tool_execution_end.
+      break;
+    }
+    case "tool_execution_start":
+      emit({ _tag: "ToolStart", toolId: event.toolCallId, name: event.toolName, argsPreview: safeJson(event.args) });
+      break;
+    case "tool_execution_update":
+      emit({ _tag: "ToolUpdate", toolId: event.toolCallId, outputPreview: toolPreview(event.partialResult) });
+      break;
+    case "tool_execution_end":
+      emit({ _tag: "ToolEnd", toolId: event.toolCallId, name: event.toolName, isError: event.isError, outputPreview: toolPreview(event.result) });
+      break;
+    case "queue_update":
+      emit({
+        _tag: "QueueChanged",
+        queued: [
+          ...(event.steering as string[]).map((text) => ({ text, kind: "steer" as const })),
+          ...(event.followUp as string[]).map((text) => ({ text, kind: "follow-up" as const })),
+        ],
+      });
+      break;
+  }
+}
+
+/** Settle one run from its own messages; an earlier run's answer never counts. */
+export function settledOutcome(
+  messages: ReadonlyArray<unknown>,
+  fromIndex: number,
+  runError: string | undefined,
+): Extract<SubagentEvent, { _tag: "RunSettled" }>["outcome"] {
+  const last = lastAssistantMessage(messages, fromIndex);
+  const partialText = finalOutput(messages, fromIndex) || undefined;
+  if (last?.stopReason === "aborted") return { _tag: "Interrupted", partialText };
+  const errorText = runError ?? (last?.stopReason === "error" ? (last.errorMessage ?? "Run failed") : undefined);
+  if (errorText !== undefined) return { _tag: "Failed", errorText: boundedError(errorText), partialText };
+  return { _tag: "Completed", finalText: finalOutput(messages, fromIndex) };
+}
+
+export function boundedError(error: unknown) {
   return (error instanceof Error ? error.message : String(error)).slice(
     0,
     4096,
@@ -379,7 +457,10 @@ const makePiSession = (
         const { loader, settingsManager } = await createChildResources({
           cwd: task.cwd,
           projectTrusted: task.parent.projectTrusted,
-          extensionFactories: [capabilityGuardExtension(task.capability)],
+          extensionFactories: [capabilityGuardExtension(task.capability, task.childOptions?.tools)],
+          noSkills: task.childOptions?.skills === false,
+          noContextFiles: task.childOptions?.contextFiles === false,
+          noExtensions: task.childOptions?.extensions === false,
         });
         const sessionManager = task.resumeSessionFile
           ? SessionManager.open(task.resumeSessionFile, undefined, task.cwd)
@@ -409,7 +490,7 @@ const makePiSession = (
         // the scope finalizer that owns cleanup is only registered later.
         try {
           await session.bindExtensions({ mode: "print" });
-          restrictActiveTools(session, task.capability);
+          restrictActiveTools(session, task.capability, task.childOptions?.tools);
         } catch (error) {
           await shutdownAndDisposeChildSession(session);
           throw error;
@@ -441,7 +522,7 @@ const makePiSession = (
 
     const activeModel = (): Model<any> | undefined => {
       const sessionModel = session.model;
-      const last = lastAssistantMessage(session);
+      const last = lastAssistantMessage(session.messages);
       if (!last) return sessionModel;
       if (
         sessionModel &&
@@ -488,37 +569,7 @@ const makePiSession = (
     const settle = () => {
       if (state.settled) return;
       state.settled = true;
-      // Only this run's messages count; an earlier answer must never become
-      // the output of a later run that failed before responding.
-      const last = lastAssistantMessage(session, state.runStartIndex);
-      const partialText = finalOutput(session, state.runStartIndex) || undefined;
-      if (last?.stopReason === "aborted") {
-        emit({
-          _tag: "RunSettled",
-          outcome: { _tag: "Interrupted", partialText },
-        });
-        return;
-      }
-      const errorText =
-        state.runError ??
-        (last?.stopReason === "error"
-          ? (last.errorMessage ?? "Run failed")
-          : undefined);
-      if (errorText !== undefined) {
-        emit({
-          _tag: "RunSettled",
-          outcome: {
-            _tag: "Failed",
-            errorText: boundedError(errorText),
-            partialText,
-          },
-        });
-        return;
-      }
-      emit({
-        _tag: "RunSettled",
-        outcome: { _tag: "Completed", finalText: finalOutput(session, state.runStartIndex) },
-      });
+      emit({ _tag: "RunSettled", outcome: settledOutcome(session.messages, state.runStartIndex, state.runError) });
     };
 
     const handleEvent = (event: AgentSessionEvent) => {
@@ -526,82 +577,24 @@ const makePiSession = (
       switch (event.type) {
         case "agent_start":
           // Extensions may register tools between runs; guard new ones too.
-          restrictActiveTools(session, task.capability);
+          restrictActiveTools(session, task.capability, task.childOptions?.tools);
           toolTimeout.apply(session);
           state.settled = false;
           emit({ _tag: "RunStarted" });
           break;
-        case "message_update": {
-          const streamEvent = event.assistantMessageEvent;
-          if (streamEvent.type === "text_delta") {
-            emit({
-              _tag: "AssistantDelta",
-              kind: "text",
-              delta: streamEvent.delta,
-            });
-          } else if (streamEvent.type === "thinking_delta") {
-            emit({
-              _tag: "AssistantDelta",
-              kind: "thinking",
-              delta: streamEvent.delta,
-            });
-          }
-          break;
-        }
-        case "message_end": {
-          const role = messageRole(event.message);
-          if (role === "user") {
-            const text = userText(event.message as Message);
-            if (text.trim()) emit({ _tag: "UserMessage", text });
-          } else if (role === "assistant") {
-            emit({
-              _tag: "AssistantMessage",
-              parts: assistantParts(event.message as AssistantMessage),
-            });
+        case "message_end":
+          translateSessionEvent(event, emit);
+          if (messageRole(event.message) === "assistant") {
             emitUsage();
             emit({ _tag: "MetaChanged", meta: currentMeta() });
           }
-          // toolResult messages are covered by tool_execution_end.
           break;
-        }
+        case "message_update":
         case "tool_execution_start":
-          emit({
-            _tag: "ToolStart",
-            toolId: event.toolCallId,
-            name: event.toolName,
-            argsPreview: safeJson(event.args),
-          });
-          break;
         case "tool_execution_update":
-          emit({
-            _tag: "ToolUpdate",
-            toolId: event.toolCallId,
-            outputPreview: toolPreview(event.partialResult),
-          });
-          break;
         case "tool_execution_end":
-          emit({
-            _tag: "ToolEnd",
-            toolId: event.toolCallId,
-            name: event.toolName,
-            isError: event.isError,
-            outputPreview: toolPreview(event.result),
-          });
-          break;
         case "queue_update":
-          emit({
-            _tag: "QueueChanged",
-            queued: [
-              ...event.steering.map((text) => ({
-                text,
-                kind: "steer" as const,
-              })),
-              ...event.followUp.map((text) => ({
-                text,
-                kind: "follow-up" as const,
-              })),
-            ],
-          });
+          translateSessionEvent(event, emit);
           break;
         case "agent_settled":
           settle();
@@ -696,5 +689,6 @@ export const piBackend: SubagentBackend = {
   capabilities: { steering: true, modelSelection: true, reasoningEffort: true },
   // In-process SDK: always available.
   available: Effect.succeed(true),
-  spawn: makePiSession,
+  // Profiles choose the runtime; "process" runs the child as its own Pi process.
+  spawn: (task) => (task.childOptions?.runtime === "process" ? makeProcessSession(task) : makePiSession(task)),
 };

package/extensions/subagents/src/child-bridge.ts

@@ -0,0 +1,105 @@
+/**
+ * Loaded with `-e` into a process-runtime subagent (`pi --mode rpc`). It keeps
+ * the child inside its capability and carries the parent bridge tools over
+ * Pi's RPC extension-UI subprotocol: notifications for one-way updates and
+ * input dialogs for questions that need an answer. It is not a suite
+ * extension and does nothing outside a child process.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { CHILD_EXCLUDED_TOOL_NAMES } from "../../shared/child-session.ts";
+import { childToolAllowed } from "./backends/pi.ts";
+import type { CapabilityMode } from "./config.ts";
+
+export const CHILD_ENV = "PI_SUBAGENT_CHILD";
+export const CHILD_CAPABILITY_ENV = "PI_SUBAGENT_CAPABILITY";
+export const CHILD_TOOLS_ENV = "PI_SUBAGENT_TOOLS";
+export const CHILD_BRIDGE_ENV = "PI_SUBAGENT_BRIDGE";
+/** Prefix that marks bridge traffic among ordinary extension UI requests. */
+export const BRIDGE_MARK = "pi-subagent-bridge:";
+
+export type BridgeRequest =
+  | { kind: "notify"; message: string }
+  | { kind: "ask"; question: string }
+  | { kind: "peers" }
+  | { kind: "peer"; id: string; message: string };
+
+const excluded = new Set<string>(CHILD_EXCLUDED_TOOL_NAMES);
+
+async function request(ctx: ExtensionContext, body: BridgeRequest, signal?: AbortSignal): Promise<string> {
+  const reply = await ctx.ui.input(`${BRIDGE_MARK}${JSON.stringify(body)}`, "", { signal });
+  if (reply === undefined) throw new Error("The parent session did not answer.");
+  if (reply.startsWith("error:")) throw new Error(reply.slice("error:".length).trim());
+  return reply;
+}
+
+export default function childBridge(pi: ExtensionAPI) {
+  if (process.env[CHILD_ENV] !== "1") return;
+  const capability = (process.env[CHILD_CAPABILITY_ENV] ?? "all") as CapabilityMode;
+  const allowlist = process.env[CHILD_TOOLS_ENV] ? (JSON.parse(process.env[CHILD_TOOLS_ENV]!) as string[]) : undefined;
+  const allowed = (name: string) => !excluded.has(name) && childToolAllowed(name, capability, allowlist);
+
+  pi.on("tool_call", (event) => (allowed(event.toolName)
+    ? undefined
+    : { block: true, reason: `Tool "${event.toolName}" is not permitted for this subagent.` }));
+  const restrict = () => {
+    const active = pi.getActiveTools();
+    const next = active.filter(allowed);
+    if (next.length !== active.length) pi.setActiveTools(next);
+  };
+  pi.on("session_start", restrict);
+  pi.on("agent_start", restrict);
+
+  if (process.env[CHILD_BRIDGE_ENV] !== "1") return;
+  pi.registerTool({
+    name: "message_parent",
+    label: "Message Parent",
+    description: "Send the parent a concise non-blocking update or warning.",
+    exposure: "model-only",
+    parameters: Type.Object({ message: Type.String({ description: "Parent update" }) }),
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      ctx.ui.notify(`${BRIDGE_MARK}${JSON.stringify({ kind: "notify", message: params.message } satisfies BridgeRequest)}`, "info");
+      return { content: [{ type: "text", text: "Update sent to parent." }], details: {} };
+    },
+  });
+  pi.registerTool({
+    name: "ask_parent",
+    label: "Ask Parent",
+    description: "Ask the parent a blocking question required to continue.",
+    exposure: "model-only",
+    parameters: Type.Object({ question: Type.String({ description: "Parent question" }) }),
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      const reply = await request(ctx, { kind: "ask", question: params.question }, signal);
+      return { content: [{ type: "text", text: `Parent reply:\n${reply}` }], details: {} };
+    },
+  });
+  pi.registerTool({
+    name: "list_peers",
+    label: "List Peer Agents",
+    description: "List sibling agents managed by the main thread. This cannot create agents.",
+    exposure: "model-only",
+    parameters: Type.Object({}),
+    async execute(_id, _params, signal, _onUpdate, ctx) {
+      const peers = JSON.parse(await request(ctx, { kind: "peers" }, signal)) as Array<{ id: string; status: string; title: string }>;
+      const text = peers.length
+        ? peers.map((peer) => `${peer.id}\t${peer.status}\t${peer.title}`).join("\n")
+        : "No peer agents are currently tracked.";
+      return { content: [{ type: "text", text }], details: { peers } };
+    },
+  });
+  pi.registerTool({
+    name: "message_peer",
+    label: "Message Peer Agent",
+    description: "Route a message to an existing sibling agent through the main-thread manager. This cannot create agents.",
+    exposure: "model-only",
+    parameters: Type.Object({
+      id: Type.String({ description: "Target peer id from list_peers" }),
+      message: Type.String({ description: "Message for the peer" }),
+    }),
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      await request(ctx, { kind: "peer", id: params.id, message: params.message }, signal);
+      return { content: [{ type: "text", text: `Message sent to ${params.id}.` }], details: { id: params.id } };
+    },
+  });
+}

package/extensions/subagents/src/config.ts

@@ -6,9 +6,11 @@ import type { ReasoningEffort } from "./domain.ts";
 export const AGENT_TYPES = ["general-purpose", "explore", "plan"] as const;
 export const CAPABILITY_MODES = ["read-only", "read-write", "execute", "all"] as const;
 export const ISOLATION_MODES = ["none", "worktree"] as const;
+export const RUNTIME_MODES = ["in-process", "process"] as const;
 
 export type CapabilityMode = (typeof CAPABILITY_MODES)[number];
 export type IsolationMode = (typeof ISOLATION_MODES)[number];
+export type RuntimeMode = (typeof RUNTIME_MODES)[number];
 
 export interface AgentProfile {
   description?: string;
@@ -17,6 +19,23 @@ export interface AgentProfile {
   model?: string;
   thinking?: ReasoningEffort;
   isolation?: IsolationMode;
+  /** "process" runs the child as a separate `pi --mode rpc` process with Pi's built-in extensions. */
+  runtime?: RuntimeMode;
+  /** Exact tool allowlist, applied on top of the capability. */
+  tools?: string[];
+  /** Set false to start the child without skills, AGENTS.md files, or extensions. */
+  skills?: boolean;
+  contextFiles?: boolean;
+  extensions?: boolean;
+}
+
+/** Child session options resolved from a profile; none of them reach the model. */
+export interface ChildSessionOptions {
+  runtime: RuntimeMode;
+  tools?: readonly string[];
+  skills: boolean;
+  contextFiles: boolean;
+  extensions: boolean;
 }
 
 export interface PersonaProfile {
@@ -93,13 +112,27 @@ function parseProfile(value: unknown): AgentProfile | undefined {
   if (thinking) profile.thinking = thinking;
   const isolation = enumValue(value.isolation, ISOLATION_MODES);
   if (isolation) profile.isolation = isolation;
+  const runtime = enumValue(value.runtime, RUNTIME_MODES);
+  if (runtime) profile.runtime = runtime;
+  if (Array.isArray(value.tools) && value.tools.every((name) => typeof name === "string" && name.trim())) {
+    profile.tools = value.tools.map((name) => (name as string).trim());
+  }
+  for (const key of ["skills", "contextFiles", "extensions"] as const) {
+    if (typeof value[key] === "boolean") profile[key] = value[key] as boolean;
+  }
   return profile;
 }
 
 function parsePersona(value: unknown): PersonaProfile | undefined {
   const profile = parseProfile(value);
   if (!profile?.instructions) return undefined;
-  return { ...profile, instructions: profile.instructions };
+  return {
+    description: profile.description,
+    instructions: profile.instructions,
+    model: profile.model,
+    thinking: profile.thinking,
+    isolation: profile.isolation,
+  };
 }
 
 function mergeConfig(base: SubagentConfig, raw: Record<string, unknown> | undefined): SubagentConfig {
@@ -168,6 +201,19 @@ function validateProfileDocument(name: string, value: unknown, persona: boolean)
   ) {
     throw new Error(`${name}.thinking is invalid.`);
   }
+  if (persona) return;
+  if (value.runtime !== undefined && !enumValue(value.runtime, RUNTIME_MODES)) {
+    throw new Error(`${name}.runtime must be one of ${RUNTIME_MODES.join(", ")}.`);
+  }
+  if (
+    value.tools !== undefined &&
+    (!Array.isArray(value.tools) || value.tools.length === 0 || !value.tools.every((tool) => typeof tool === "string" && tool.trim()))
+  ) {
+    throw new Error(`${name}.tools must be a non-empty array of tool names.`);
+  }
+  for (const key of ["skills", "contextFiles", "extensions"]) {
+    if (value[key] !== undefined && typeof value[key] !== "boolean") throw new Error(`${name}.${key} must be true or false.`);
+  }
 }
 
 export function saveConfigDocument(scope: ConfigScope, cwd: string, text: string) {
@@ -242,5 +288,12 @@ export function resolveProfile(
     model: options.model ?? profile.model ?? persona?.model,
     thinking: options.thinking ?? profile.thinking ?? persona?.thinking,
     isolation: options.isolation ?? profile.isolation ?? persona?.isolation ?? "none",
+    childOptions: {
+      runtime: profile.runtime ?? "in-process",
+      tools: profile.tools,
+      skills: profile.skills ?? true,
+      contextFiles: profile.contextFiles ?? true,
+      extensions: profile.extensions ?? true,
+    } satisfies ChildSessionOptions,
   } as const;
 }

package/extensions/subagents/src/domain.ts

@@ -9,7 +9,7 @@
 import type { Message, Model } from "@earendil-works/pi-ai";
 import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
 import { Data } from "effect";
-import type { CapabilityMode, IsolationMode } from "./config.ts";
+import type { CapabilityMode, ChildSessionOptions, IsolationMode } from "./config.ts";
 import type { WorktreeInfo } from "./worktree.ts";
 
 export type BackendName = "pi";
@@ -71,6 +71,8 @@ export interface SpawnTask {
   readonly reasoningEffort?: ReasoningEffort;
   /** Coarse tool capability policy, resolved from profile/persona/override. */
   readonly capability: CapabilityMode;
+  /** Runtime, tool allowlist, and resource switches from the profile. */
+  readonly childOptions?: ChildSessionOptions;
   readonly agentType: string;
   readonly persona?: string;
   readonly isolation: IsolationMode;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shariq-pi-extensions",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Cross-platform extension suite for the Pi coding agent.",
   "license": "MIT",
   "author": "Shariq Riaz",