pi-famulus 0.1.9 → 0.2.0

package/src/index.ts

@@ -21,9 +21,9 @@ import { createAgentLoader, type AgentLoader } from "./agents/loader";
 import { createBashOverride } from "./bash-override";
 import { createComms, type CommsWithOrigin } from "./comms/comms";
 import { createRegistryCommsHost } from "./comms/registry-host";
-import { createAgentMessageTool, createContactSupervisorTool } from "./comms/tools";
+import { createAgentMessageTool } from "./comms/tools";
 import { registerReplyCommand } from "./comms/reply-command";
-import { describeManagerSearch, getFamulusHome, loadConfig, resolveManagerPath, resolveSubagentConfig } from "./config";
+import { describeManagerSearch, getFamulusHome, loadConfig, resolveManagerPath, resolveSubagentConfig, taskOutputPath } from "./config";
 import { ensureNativeManagerInstalled } from "./native-manager.js";
 import type { TaskExitInfo } from "./format";
 import { EXTENSION_VERSION, ManagerClient, type ManagerEvent, type TaskRecord } from "./manager-client";
@@ -31,7 +31,6 @@ import { createMonitorTool, exitEventFromRecord, MonitorRegistry } from "./monit
 import { admitAgentChild, reregisterAgentLeases } from "./subagent/admission";
 import { NotifyCenter } from "./notify";
 import { onWakeMessageEnd, registryStatusLookup } from "./wake-delivery";
-import { createChildBashTool } from "./subagent/child-bash";
 import { ChildShellTracker, createOverrunNotifier } from "./subagent/overrun";
 import {
   agentEndReason,
@@ -44,7 +43,11 @@ import {
 import { TranscriptWriter } from "./subagent/transcript";
 import { FleetWidget } from "./subagent/fleet-widget";
 import { WorkIndex, type WorkItem } from "./work-index";
-import { createPiSessionFn, isFamulusChildSession, modelCandidates } from "./subagent/pi-runtime";
+import { fileURLToPath } from "node:url";
+import { isFamulusChildSession, modelCandidates } from "./subagent/pi-runtime";
+import { createHostedSessionFn } from "./subagent/hosted-session";
+import { isHostedChildProcess, registerChildMode } from "./child-mode";
+import { openAttachView, registerAttachCommand } from "./tui/attach-command";
 import { SubagentRegistry } from "./subagent/registry";
 import { InProcessRunner } from "./subagent/runner";
 import { createSubagentTool } from "./subagent/tool";
@@ -56,6 +59,52 @@ import { registerTasksCommand } from "./tui/tasks-command";
 import { stderrPathFor } from "./tui/task-output-paths";
 import { shellWakeTitle } from "./wake";
 
+async function promptIfHostedSession(
+  c: ManagerClient,
+  live: () => ExtensionContext | null,
+  query: { sessionFile?: string | null; sessionId?: string },
+  where: "start" | "switch",
+): Promise<"takeover" | "stay" | "none"> {
+  if (!c.isAvailable() || c.protocolLevel() < 6) return "none";
+  const found = await c.hostedLookup({
+    ...(query.sessionId ? { sessionId: query.sessionId } : {}),
+    ...(query.sessionFile ? { sessionFile: query.sessionFile } : {}),
+  }).catch(() => null);
+  if (!found || found.residency !== "warm" || typeof found.child_id !== "string") return "none";
+  const uiCtx = live();
+  if (!uiCtx) return "none";
+  if (where === "start" && query.sessionId && uiCtx.sessionManager.getSessionId() !== query.sessionId) return "none";
+  if (!uiCtx.hasUI) {
+    uiCtx.ui.notify(
+      "This session file belongs to a warm hosted subagent. Use /attach from the parent, or open it in the TUI to take over.",
+      "warning",
+    );
+    return "stay";
+  }
+  const choice = await uiCtx.ui.select("This session is hosted by pi-famulus", [
+    "Attach to the hosted process",
+    "Take over",
+    "Cancel",
+  ]);
+  if (choice === "Take over") {
+    try {
+      await c.agentTakeover(found.child_id);
+      return "takeover";
+    } catch (err) {
+      uiCtx.ui.notify(err instanceof Error ? err.message : String(err), "error");
+      return "stay";
+    }
+  }
+  if (choice === "Attach to the hosted process") {
+    try {
+      await openAttachView(uiCtx, c, found.child_id);
+    } catch (err) {
+      uiCtx.ui.notify(err instanceof Error ? err.message : String(err), "error");
+    }
+  }
+  return "stay";
+}
+
 /** Read only the tail of a task output file for the notification preview (≤ maxChars). */
 export function readPreview(outputPath: string | undefined, maxChars: number): string {
   if (!outputPath) return "";
@@ -77,6 +126,10 @@ interface FamulusRuntime {
 }
 
 export default function (pi: ExtensionAPI): void {
+  if (isHostedChildProcess()) {
+    registerChildMode(pi);
+    return;
+  }
   if (isFamulusChildSession(pi)) return;
   // A /reload parked the previous instance's runtime: adopt it so its shells,
   // monitors and subagents keep running (see reload-handoff.ts). Another
@@ -414,6 +467,10 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
     clock,
     syncWithManager: deps.syncWithManager,
   });
+  registerAttachCommand(pi, {
+    getClient: () => client,
+    getRegistry: () => subagentRegistry,
+  });
   famulusInfo = {
     extensionVersion: EXTENSION_VERSION,
     managerPath,
@@ -447,9 +504,11 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
   // M4: comms host bridges the registry and the NotifyCenter. A single Comms
   // instance lives at extension scope (mailbox is per-run namespaced; pending
   // waiters are resolved via dispose() on session_shutdown).
+  let watchResume: (childId: string) => void = () => {};
   const commsHost = createRegistryCommsHost({
     getRegistry: () => subagentRegistry,
     getNotifyCenter: () => notifyCenter,
+    onResumeAccepted: (childId) => watchResume(childId),
   });
   const comms: CommsWithOrigin = createComms(commsHost, {
     decisionTimeoutMs: subagentConfig.decisionTimeoutMs,
@@ -466,6 +525,9 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
       defaultTimeoutMs: subagentConfig.timeoutMs,
       defaultConcurrency: subagentConfig.concurrency,
       clock,
+      registerResumeWatch: (watch) => {
+        watchResume = watch;
+      },
       resolveAgent: (name) => {
         const loader = agentLoader;
         if (!loader) return resolveAgentDef([], name); // builtins-only fallback
@@ -546,11 +608,48 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
       sessionId: startCtx.sessionManager.getSessionId(),
       managerPath,
       cwd: startCtx.cwd,
+      sessionFile: startCtx.sessionManager.getSessionFile?.(),
       clock,
       log: () => {}, // keep quiet; degradation is surfaced via tools
     });
 
+    // Hosted children run bash in their own process. The parent learns the
+    // foreground shell from task_started (origin child-bash) so overrun wakes
+    // still carry <shell>.
+    const childShells = new ChildShellTracker();
+    const parentSessionId = startCtx.sessionManager.getSessionId();
     client.onEvent((event) => {
+      const hosted = event as ManagerEvent & {
+        child_id?: string;
+        reason?: string;
+        request_id?: string;
+        message?: string;
+        name?: string;
+        residency?: string;
+        driver?: string;
+        last_text?: string;
+      };
+      if (hosted.event === "agent_comms" && hosted.child_id && hosted.request_id) {
+        const reason = hosted.reason === "need_decision" ? "need_decision" : "progress_update";
+        void comms.contactSupervisor(hosted.child_id, reason, hosted.message ?? "").then((reply) => {
+          if (reason === "need_decision") void client?.agentCommsReply(hosted.request_id!, hosted.child_id!, reply).catch(() => {});
+        }).catch(() => {});
+        return;
+      }
+      if (hosted.event === "agent_detach" && hosted.child_id) {
+        notifyCenter?.notify({
+          customType: "pi-famulus-wake",
+          content: `System wake — not a new user message.\n\nThe user talked to ${hosted.name ?? hosted.child_id} directly.\n${hosted.last_text ?? ""}`,
+          details: { kind: "supervisor-update", from: hosted.child_id, name: hosted.name ?? hosted.child_id, message: hosted.last_text ?? "" },
+        });
+        return;
+      }
+      if (hosted.event === "agent_state" && hosted.child_id) {
+        const handle = subagentRegistry?.handle(hosted.child_id) as { pauseStall?: () => void; resumeStall?: () => void } | undefined;
+        if (hosted.driver === "user") handle?.pauseStall?.();
+        else handle?.resumeStall?.();
+        return;
+      }
       if (event.event === "task_started" && event.task_id) {
         const prior = taskMeta.get(event.task_id);
         taskMeta.set(event.task_id, {
@@ -562,6 +661,14 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
               ? { startedAt: prior.startedAt }
               : {}),
         });
+        if (event.origin?.via === "child-bash" && event.origin.child_id) {
+          childShells.start(event.origin.child_id, {
+            taskId: event.task_id,
+            command: event.command ?? "",
+            startedAt: typeof event.ts === "number" ? event.ts : clock.now(),
+            outputPath: taskOutputPath(home, parentSessionId, event.task_id),
+          });
+        }
         if (notifyOnExit.has(event.task_id) && typeof event.ts === "number") {
           upsertBackgroundTask(event.task_id, event.ts);
         }
@@ -584,6 +691,7 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
         return;
       }
       if (event.event === "task_exited" && event.task_id) {
+        childShells.endByTask(event.task_id);
         // A known monitor closes (and patches the index via onExited); an
         // unknown id is buffered in case a monitor start is about to claim it.
         if (monitorRegistry?.handleExit(event.task_id, event)) return;
@@ -633,9 +741,7 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
         "warning",
       );
     }
-    // The foreground shell each child is blocked on, for its overrun wake.
-    const childShells = new ChildShellTracker();
-    const createSession = createPiSessionFn({
+    const createSession = createHostedSessionFn({
       getModelRegistry: () => ctx?.modelRegistry ?? null,
       getModelRuntime: () => {
         const registry = ctx?.modelRegistry as { runtime?: unknown } | null | undefined;
@@ -646,29 +752,10 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
       getScopedModels: () => ctx?.scopedModels ?? [],
       getCwd: () => ctx?.cwd ?? process.cwd(),
       getProjectTrusted: () => ctx?.isProjectTrusted() ?? false,
-      customTools: (req) => {
-        const tools: Array<ToolDefinition<any, any, any>> = [
-          // M4: every child can reach the supervisor and its siblings.
-          createContactSupervisorTool(comms, req.childId),
-          createAgentMessageTool(comms, { kind: "child", childId: req.childId, runId: req.runId }, commsHost, clock),
-        ];
-        // The no-background bash variant replaces the built-in bash inside
-        // child sessions (custom tools override builtins by name).
-        tools.push(
-          createChildBashTool({
-            getClient: () => client,
-            home,
-            sessionId: () => ctx?.sessionManager.getSessionId() ?? "",
-            sessionEnv: () => (ctx ? sessionEnv(ctx) : {}),
-            trackTask,
-            childId: req.childId,
-            runId: req.runId,
-            clock,
-            shells: childShells,
-          }),
-        );
-        return tools;
-      },
+      getClient: () => client,
+      getHome: () => home,
+      extensionEntry: fileURLToPath(import.meta.url),
+      piCommand: subagentConfig.piCommand,
     });
     // The registry outlives startCtx across a /reload, which leaves startCtx
     // stale; its closures keep plain values instead.
@@ -856,6 +943,9 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
         if (ok === null || client !== c || !c) return;
         if (ok) {
           if (c.protocolLevel() >= 4) void reconcileAgentLeases(c).catch(() => {});
+          const file = startCtx.sessionManager.getSessionFile?.();
+          const sid = startCtx.sessionManager.getSessionId();
+          void promptIfHostedSession(c, () => ctx, { sessionFile: file, sessionId: sid }, "start").catch(() => {});
           return;
         }
         // A /reload may have replaced startCtx by now; report to the live one.
@@ -900,6 +990,14 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
   };
   const runtime: FamulusRuntime = { attach: (host) => binding.attach(host) };
 
+  pi.on("session_before_switch", async (event, switchCtx) => {
+    const file = event.targetSessionFile;
+    if (!file || !client?.isAvailable()) return;
+    const outcome = await promptIfHostedSession(client, () => switchCtx, { sessionFile: file }, "switch");
+    if (outcome === "none" || outcome === "takeover") return;
+    return { cancel: true };
+  });
+
   pi.on("session_shutdown", async (event) => {
     if (event.reason === "reload" && ctx) {
       // Keep the session's shells, monitors and subagents running; the

package/src/manager-client.ts

@@ -18,10 +18,10 @@ import { famulusPaths } from "./config";
 import { realClock, type Clock, type ClockTimer } from "./clock";
 
 const MAX_FRAME_BYTES = 4 * 1024 * 1024; // 4 MiB (§3.3)
-const EXTENSION_VERSION = "0.1.9";
+const EXTENSION_VERSION = "0.2.0";
 export { EXTENSION_VERSION };
 // 5: speaks per-kind agent admission and queued acquire.
-const PROTOCOL = 5;
+const PROTOCOL = 6;
 const HELLO_TIMEOUT_MS = 5000;
 const RECONNECT_HELLO_TIMEOUT_MS = 25_000;
 const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
@@ -124,6 +124,8 @@ export interface ManagerEvent {
   output_size?: number;
   end_reason?: string;
   ts?: number;
+  /** Set on task_started when the daemon recorded who asked for the task. */
+  origin?: { via: string; child_id?: string; run_id?: string };
 }
 
 export class ManagerError extends Error {
@@ -142,6 +144,12 @@ export interface ManagerClientOptions {
   piPid?: number;
   /** Session working directory, sent on hello (optional; older managers ignore it). */
   cwd?: string;
+  /** `parent` for a pi session, `child` for pi-famulus inside a hosted subagent. */
+  role?: "parent" | "child";
+  childId?: string;
+  token?: string;
+  /** Pi session file this process has open. */
+  sessionFile?: string;
   log?: (message: string) => void;
   clock?: Clock;
 }
@@ -288,6 +296,10 @@ export class ManagerClient {
   private managerPath: string | null;
   private readonly piPid: number;
   private readonly cwd: string | undefined;
+  private readonly role: "parent" | "child";
+  private readonly childId: string | undefined;
+  private readonly token: string | undefined;
+  private readonly sessionFile: string | undefined;
   private readonly log: (message: string) => void;
   private readonly clock: Clock;
 
@@ -315,6 +327,10 @@ export class ManagerClient {
     this.managerPath = options.managerPath;
     this.piPid = options.piPid ?? process.pid;
     this.cwd = options.cwd;
+    this.role = options.role ?? "parent";
+    this.childId = options.childId;
+    this.token = options.token;
+    this.sessionFile = options.sessionFile;
     this.log = options.log ?? (() => {});
     this.clock = options.clock ?? realClock;
   }
@@ -458,20 +474,140 @@ export class ManagerClient {
     childId: string,
     workKind = "other",
     signal?: AbortSignal,
-  ): Promise<{ granted: boolean; rejection?: string }> {
+  ): Promise<{ granted: boolean; rejection?: string; queuedBehind?: number }> {
     if (signal?.aborted) throw new Error("subagent admission cancelled");
     const message: Record<string, unknown> = { type: "acquire_agent", child_id: childId };
     if (this.protocolLevel_ >= 5) message.work_kind = workKind;
     // Protocol 4 has no cancel frame. Keep its immediate acquire correlated so
     // admission can release a grant that arrives after the generation aborts.
     const res = await this.request(message, DEFAULT_REQUEST_TIMEOUT_MS, this.protocolLevel_ >= 5 ? signal : undefined, true);
-    return { granted: res.granted === true, ...(typeof res.rejection === "string" ? { rejection: res.rejection } : {}) };
+    return {
+      granted: res.granted === true,
+      ...(typeof res.rejection === "string" ? { rejection: res.rejection } : {}),
+      ...(typeof res.queued_behind === "number" ? { queuedBehind: res.queued_behind } : {}),
+    };
   }
 
   async releaseAgent(childId: string): Promise<void> {
     await this.request({ type: "release_agent", child_id: childId });
   }
 
+  requireHostedProtocol(): void {
+    if (this.protocolLevel_ < 6) {
+      throw new Error(
+        "this pi-famulus daemon does not host subagents (protocol " +
+          `${this.protocolLevel_}; need 6). Restart pi so it starts the current daemon.`,
+      );
+    }
+  }
+
+  async agentSpawn(input: {
+    childId: string;
+    runId: string;
+    name: string;
+    argv: string[];
+    cwd: string;
+    env: Record<string, string>;
+  }): Promise<Record<string, unknown>> {
+    this.requireHostedProtocol();
+    return this.request({
+      type: "agent_spawn",
+      child_id: input.childId,
+      run_id: input.runId,
+      name: input.name,
+      argv: input.argv,
+      cwd: input.cwd,
+      env: input.env,
+    }, 20_000);
+  }
+
+  async agentInput(childId: string, op: string, text: string, source = "parent", since?: string): Promise<Record<string, unknown>> {
+    this.requireHostedProtocol();
+    return this.request({
+      type: "agent_input",
+      child_id: childId,
+      op,
+      text,
+      source,
+      ...(since ? { since } : {}),
+    }, 20_000);
+  }
+
+  async agentWatch(childId: string): Promise<void> {
+    this.requireHostedProtocol();
+    await this.request({ type: "agent_watch", child_id: childId });
+  }
+
+  async agentUnwatch(childId: string): Promise<void> {
+    this.requireHostedProtocol();
+    await this.request({ type: "agent_unwatch", child_id: childId });
+  }
+
+  async agentPeers(): Promise<Array<{ childId: string; name: string; runId: string; activity: string; residency: string }>> {
+    this.requireHostedProtocol();
+    const res = await this.request({ type: "agent_peers" });
+    const peers = Array.isArray(res.peers) ? res.peers : [];
+    return peers.flatMap((peer) => {
+      if (!peer || typeof peer !== "object") return [];
+      const row = peer as Record<string, unknown>;
+      if (typeof row.child_id !== "string") return [];
+      return [{
+        childId: row.child_id,
+        name: typeof row.name === "string" ? row.name : row.child_id,
+        runId: typeof row.run_id === "string" ? row.run_id : "",
+        activity: typeof row.activity === "string" ? row.activity : "idle",
+        residency: typeof row.residency === "string" ? row.residency : "",
+      }];
+    });
+  }
+
+  async agentPark(childId: string): Promise<void> {
+    this.requireHostedProtocol();
+    await this.request({ type: "agent_park", child_id: childId });
+  }
+
+  async agentTakeover(childId: string): Promise<void> {
+    this.requireHostedProtocol();
+    await this.request({ type: "agent_takeover", child_id: childId });
+  }
+
+  async hostedLookup(query: { sessionId?: string; sessionFile?: string }): Promise<Record<string, unknown> | null> {
+    if (this.protocolLevel_ < 6) return null;
+    const res = await this.request({
+      type: "hosted_lookup",
+      ...(query.sessionId ? { session_id: query.sessionId } : {}),
+      ...(query.sessionFile ? { session_file: query.sessionFile } : {}),
+    });
+    const hosted = res.hosted;
+    return hosted && typeof hosted === "object" ? hosted as Record<string, unknown> : null;
+  }
+
+  async agentComms(requestId: string, reason: string, message: string): Promise<string> {
+    this.requireHostedProtocol();
+    const res = await this.request({ type: "agent_comms", request_id: requestId, reason, message }, 11 * 60 * 1000);
+    return typeof res.reply === "string" ? res.reply : "";
+  }
+
+  async agentCommsReply(requestId: string, childId: string, message: string): Promise<void> {
+    this.requireHostedProtocol();
+    await this.request({ type: "agent_comms_reply", request_id: requestId, child_id: childId, message });
+  }
+
+  async agentUiResponse(childId: string, rpcId: string, value: Record<string, unknown>, cancelled: boolean): Promise<void> {
+    this.requireHostedProtocol();
+    await this.request({ type: "agent_ui_response", child_id: childId, rpc_id: rpcId, value, cancelled });
+  }
+
+  async agentCache(expiresAt: number | null, tier: string | null, lifetimeMs: number | null): Promise<void> {
+    if (this.protocolLevel_ < 6) return;
+    await this.request({
+      type: "agent_cache",
+      ...(expiresAt !== null ? { expires_at: expiresAt } : {}),
+      ...(tier ? { tier } : {}),
+      ...(lifetimeMs !== null ? { lifetime_ms: lifetimeMs } : {}),
+    });
+  }
+
   /** Daemon status, including optional in-place upgrade metadata. */
   async status(): Promise<ManagerStatusResponse> {
     const res = await this.request({ type: "status" });
@@ -774,6 +910,10 @@ export class ManagerClient {
           ...(this.cwd ? { cwd: this.cwd } : {}),
           extension_version: EXTENSION_VERSION,
           protocol: PROTOCOL,
+          role: this.role,
+          ...(this.sessionFile ? { session_file: this.sessionFile } : {}),
+          ...(this.childId ? { child_id: this.childId } : {}),
+          ...(this.token ? { token: this.token } : {}),
         }),
       );
     });
@@ -865,7 +1005,7 @@ export class ManagerClient {
     waitForAdmission = false,
   ): Promise<Record<string, unknown>> {
     const type = String(msg.type);
-    const retryable = ["wait", "output", "list", "watch", "status", "stop", "mark_background", "start", "acquire_agent", "cancel_acquire_agent", "release_agent"].includes(type);
+    const retryable = ["wait", "output", "list", "watch", "status", "stop", "mark_background", "start", "acquire_agent", "cancel_acquire_agent", "release_agent", "agent_spawn", "agent_watch", "agent_park", "agent_peers", "hosted_lookup"].includes(type);
     const effectiveTimeoutMs = retryable ? Math.max(timeoutMs, RECONNECT_WINDOW_MS + 1000) : timeoutMs;
     return new Promise((resolve, reject) => {
       if (signal?.aborted) {

package/src/pi-command.ts

@@ -0,0 +1,123 @@
+/**
+ * Find the pi command a hosted subagent should be. The daemon never searches
+ * PATH; the extension resolves it where pi is already running.
+ */
+import { existsSync, realpathSync } from "node:fs";
+import { createRequire } from "node:module";
+import { basename } from "node:path";
+export type PiCommand = { argv: string[] } | { error: string };
+
+export function resolvePiArgv(configured?: string | null, argv: readonly string[] = process.argv): PiCommand {
+  const raw = (configured && configured.trim()) || process.env.PI_FAMULUS_PI?.trim() || "";
+  if (raw) {
+    if (raw.startsWith("[")) {
+      try {
+        const parsed = JSON.parse(raw) as unknown;
+        if (Array.isArray(parsed) && parsed.length > 0 && parsed.every((part) => typeof part === "string" && part.length > 0)) {
+          return { argv: parsed as string[] };
+        }
+      } catch {
+        return { error: `PI_FAMULUS_PI / subagent.piCommand is not a JSON argv array: ${raw}` };
+      }
+      return { error: `PI_FAMULUS_PI / subagent.piCommand is not a JSON argv array: ${raw}` };
+    }
+    return { argv: raw.includes(" ") ? splitCommand(raw) : [raw] };
+  }
+  const fromProcess = runningPiArgv(argv);
+  if (fromProcess) return { argv: fromProcess };
+  const exec = process.execPath;
+  try {
+    const req = createRequire(import.meta.url);
+    const pkg = req.resolve("@earendil-works/pi-coding-agent/package.json");
+    const cli = pkg.replace(/package\.json$/, "dist/cli.js");
+    if (existsSync(cli)) return { argv: [exec, cli] };
+  } catch {
+    // The host did not load pi as a resolvable package.
+  }
+  return {
+    error:
+      "cannot find the pi executable that is running this session. Set subagent.piCommand in config.json or PI_FAMULUS_PI to the pi command.",
+  };
+}
+
+const PARENT_FLAGS = new Set([
+  "-ne",
+  "--no-extensions",
+  "-ns",
+  "--no-skills",
+  "-np",
+  "--no-prompt-templates",
+  "-nc",
+  "--no-context-files",
+  "--offline",
+  "--no-mcp",
+]);
+
+/**
+ * Flags from the pi process that is spawning the subagent. The child is a new
+ * process, so it only sees providers and tools that its own command line loads.
+ * Eval and SDK hosts pass those as `-e` on argv (`-ne` plus an explicit faux
+ * provider extension); forwarding them is what lets the child use the same model.
+ */
+export function parentResourceArgs(argv: readonly string[] = process.argv.slice(2)): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "-e" || arg === "--extension") {
+      const value = argv[i + 1];
+      if (value && !value.startsWith("-")) {
+        out.push("-e", value);
+        i++;
+      }
+      continue;
+    }
+    if (PARENT_FLAGS.has(arg)) out.push(arg);
+  }
+  return out;
+}
+
+/**
+ * The pi process that loaded this extension. `node_modules/.bin/pi` is a
+ * symlink (eval and `npm exec`); its path does not contain `pi-coding-agent`,
+ * so matching only that substring misses the process that is actually running.
+ */
+function runningPiArgv(argv: readonly string[]): string[] | null {
+  const entry = argv[1] ?? "";
+  if (!entry || !existsSync(entry)) return null;
+  let real = entry;
+  try {
+    real = realpathSync(entry);
+  } catch {
+    // A broken symlink still has a path; keep the original.
+  }
+  const base = basename(entry).toLowerCase();
+  const namedPi = base === "pi" || base === "pi.cmd" || base === "pi.exe" || entry.includes("pi-coding-agent") || real.includes("pi-coding-agent");
+  if (!namedPi) return null;
+  if (/\.[cm]?js$/i.test(real)) return [process.execPath, real];
+  return [entry];
+}
+
+function splitCommand(raw: string): string[] {
+  const parts: string[] = [];
+  let current = "";
+  let quote: '"' | "'" | null = null;
+  for (const ch of raw) {
+    if (quote) {
+      if (ch === quote) quote = null;
+      else current += ch;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      continue;
+    }
+    if (ch === " ") {
+      if (current) parts.push(current);
+      current = "";
+      continue;
+    }
+    current += ch;
+  }
+  if (current) parts.push(current);
+  return parts;
+}