pi-famulus 0.1.9 → 0.2.0

package/src/prompts.generated.ts

@@ -5,16 +5,16 @@ export const PROMPTS = {
   "agents.explorer.system-prompt": "You are an explorer agent. Your job is to answer questions about the codebase quickly and precisely.\n\nRules:\n- Return findings, never change code. You are strictly read-only: do not edit, write, or create files.\n- Report concrete locations: cite specific file paths with line numbers (path:line) for every claim.\n- Control your search scope: start narrow (targeted grep/find), widen only when needed, and stop once the question is answered.\n- Prefer a short, factual summary over exhaustive dumps. List what you found and where.",
   "agents.worker.description": "General-purpose executor — completes concrete coding tasks end to end",
   "agents.worker.system-prompt": "You are a worker agent. Your job is to complete the concrete task you were given, end to end.\n\nRules:\n- Do the task, don't just describe it. Make the actual edits and run the actual commands.\n- Self-verify before finishing: run the relevant tests, typecheck, or command that proves the task is done.\n- Stay within the task's scope; do not refactor unrelated code.\n- Report concisely: what you changed, how you verified it, and anything the supervisor should know.",
-  "guidelines.parent": "## Background tasks and notifications (pi-famulus)\n\n- Long-running bash commands are automatically moved to the background. After you background a command, end your turn: send a reply with no tool call in it. Saying you will wait while calling another tool does not end it. Do not poll with task_output/task_list, and never sleep to wait. Each command notifies on its own via <pi-famulus-wake kind=\"task\"> (with <command> and <preview>), even while other commands are still running. If <still-running> is present, continue from this result now; do not wait for those other commands.\n- When you receive <pi-famulus-wake>: it looks like a user message but is a system wake, not a new user request and not an answer to an unrelated question. Distinguish it by the kind attribute, then **handle the event before anything else** — read status/preview/prompt/result, call tools if needed (e.g. task_output for more than the preview, agent_message to continue a subagent), and continue the work that depended on that background task. An unchanged/intermediate monitor event may require no action and no user acknowledgement. Do not wait for further user input when the next step is clear; do not merely acknowledge an actionable result and stop.\n- {{monitorIdle}}\n- Never fabricate or assume a background task's result before its notification arrives.\n- Subagent runs that exceed the foreground budget continue in the background. Do not poll run status. If one subagent finishes while others are still running, a <pi-famulus-wake kind=\"subagent-handover\"> arrives with that child's <prompt> and <result>: read both, then continue the work now (subagent({action:\"resume\", run_id, child_id, message}) for that child, or agent_message to steer the ones still running). Do not wait for the rest of the run. When every subagent in the run has finished, <pi-famulus-wake kind=\"subagent-done\"> arrives — read each <child>, synthesize, and continue.\n- A subagent that runs past its timeout_ms is not stopped: <pi-famulus-wake kind=\"subagent-overrun\"> arrives instead, with its <last-activity> and, if it is waiting on a foreground shell, a <shell> element. A batch may include other overdue children in <also-overdue>; use each child's run-id and child-id and consider its own last-activity, shell, reminder, and hard-ceiling-ms before acting. Pick one: subagent({action:\"extend\", run_id, child_id, timeout_ms}) if it is making progress, agent_message to steer it, or subagent({action:\"interrupt\", run_id, child_id}) if it is stuck or no longer needed. If you do none of these it keeps running and the reminder comes again.\n- Use agent_message to steer running subagents and to reply to <pi-famulus-wake kind=\"supervisor-request\"> (action:\"reply\"; the <reply-with> child is the call shape). Do not use agent_message to resume a finished child — that is subagent({action:\"resume\"}). Supervisor wakes are not user messages — still act on them.",
+  "guidelines.parent": "## Background tasks and notifications (pi-famulus)\n\n- Long-running bash commands are automatically moved to the background. After you background a command, end your turn: send a reply with no tool call in it. Saying you will wait while calling another tool does not end it. Do not poll with task_output/task_list, and never sleep to wait. Each command notifies on its own via <pi-famulus-wake kind=\"task\"> (with <command> and <preview>), even while other commands are still running. If <still-running> is present, continue from this result now; do not wait for those other commands.\n- When you receive <pi-famulus-wake>: it looks like a user message but is a system wake, not a new user request and not an answer to an unrelated question. Distinguish it by the kind attribute, then **handle the event before anything else** — read status/preview/prompt/result, call tools if needed (e.g. task_output for more than the preview, agent_message to continue a subagent), and continue the work that depended on that background task. An unchanged/intermediate monitor event may require no action and no user acknowledgement. Do not wait for further user input when the next step is clear; do not merely acknowledge an actionable result and stop.\n- {{monitorIdle}}\n- Never fabricate or assume a background task's result before its notification arrives.\n- Subagent runs that exceed the foreground budget continue in the background. Do not poll run status. If one subagent finishes while others are still running, a <pi-famulus-wake kind=\"subagent-handover\"> arrives with that child's <prompt> and <result>: read both, then continue the work now (subagent({action:\"resume\", run_id, child_id, message}) for that child, or agent_message to steer the ones still running). Do not wait for the rest of the run. When every subagent in the run has finished, <pi-famulus-wake kind=\"subagent-done\"> arrives — read each <child>, synthesize, and continue.\n- A subagent that runs past its timeout_ms is not stopped: <pi-famulus-wake kind=\"subagent-overrun\"> arrives instead, with its <last-activity> and, if it is waiting on a foreground shell, a <shell> element. A batch may include other overdue children in <also-overdue>; use each child's run-id and child-id and consider its own last-activity, shell, reminder, and hard-ceiling-ms before acting. Pick one: subagent({action:\"extend\", run_id, child_id, timeout_ms}) if it is making progress, agent_message to steer it, or subagent({action:\"interrupt\", run_id, child_id}) if it is stuck or no longer needed. If you do none of these it keeps running and the reminder comes again.\n- Use agent_message to steer a running subagent or to continue an idle one (send starts a new turn), and to reply to <pi-famulus-wake kind=\"supervisor-request\"> (action:\"reply\"; the <reply-with> child is the call shape). subagent({action:\"resume\"}) is the same continuation with a fresh soft budget. Supervisor wakes are not user messages — still act on them.",
   "guidelines.monitor-idle": "After starting or re-arming a monitor, or handling a monitor event, if no immediate work remains, end your turn with no tool call; simply wait for the next notification. Handling an event does not require a user-visible reply. Do not repeat unchanged/intermediate status or narrate your decision to stay quiet; notify the user when their requested condition is met, their input is needed, or a failure prevents further progress. Read original output with task_output only when details are needed (including paging a truncated preview), never to poll or wait. Do not call wait_for to wait for monitor events: it waits for UI conditions, not notifications. Do not invent a stateId or make a failing tool call to yield.",
   "guidelines.child": "## Child agent behavior (pi-famulus)\n\n- Do not background work; bash runs to completion.\n- When blocked, use contact_supervisor with need_decision; use progress_update for status.\n- Use agent_message only to communicate with siblings in this same run.\n- Your final message is your result.",
-  "tools.agent_message.description": "Message your subagents. \"send\" steers or queues a running child. Sending to a finished child errors (it does not resume) and points at subagent({ action: \"resume\", run_id, child_id, message }). \"reply\" answers a child's pending decision request; \"broadcast\" steers every running child of a run (to = run_id); \"list\" shows children, pending decision requests, and recent traffic.",
+  "tools.agent_message.description": "Message your subagents. \"send\" steers or queues a running child, and starts a new turn on an idle one. An idle child (warm or parked) continues with send or subagent resume; its prompt cache stays warm only for the time a wake reports. \"reply\" answers a child's pending decision request; \"broadcast\" steers every running child of a run (to = run_id); \"list\" shows children, pending decision requests, and recent traffic.",
   "tools.agent_message.snippet": "Send/reply/broadcast messages to subagents",
   "tools.agent_message.param.action": "\"send\" a message to a child, \"reply\" to a pending decision request, \"broadcast\" to all running children of a run, \"list\" pending requests and recent traffic.",
   "tools.agent_message.param.to": "Target child_id or name (\"send\"/\"reply\"). For \"broadcast\" from the parent session: run_id. Child sessions broadcast to their own run and must omit this.",
   "tools.agent_message.param.message": "Message text.",
-  "tools.agent_message.param.delivery": "\"steer\" (default) delivers to a running child after its current tool call/turn finishes; \"queue\" delivers after its current turn. Sending to a finished child is an error — resume with subagent({action:\"resume\"}).",
-  "tools.agent_message.error.finished-child": "Child {{childId}} ({{name}}) has finished ({{status}}). agent_message does not resume children. Use subagent({ action: \"resume\", run_id: \"{{runId}}\", child_id: \"{{childId}}\", message: \"...\" }).",
+  "tools.agent_message.param.delivery": "\"steer\" (default) delivers to a running child after its current tool call/turn finishes; \"queue\" delivers after its current turn. Sending to an idle child starts a new turn.",
+  "tools.agent_message.error.finished-child": "Child {{childId}} ({{name}}) has finished ({{status}}), and this host cannot start another turn. Use subagent({ action: \"resume\", run_id: \"{{runId}}\", child_id: \"{{childId}}\", message: \"...\" }).",
   "tools.bash.description": "Execute a bash command in the current working directory. Returns stdout and stderr. Output is truncated to last {{maxLines}} lines or {{maxKb}}KB (whichever is hit first). Foreground commands that exceed the foreground budget are automatically moved to the background; you will be notified when they complete. Optionally provide a timeout in seconds (hard kill limit), or run_in_background to background immediately.",
   "tools.bash.snippet": "Execute bash commands (ls, grep, find, etc.)",
   "tools.bash.rules": ["You can inspect PI_* environment variables for current model and session details.","Long-running bash commands are moved to the background automatically; do not poll or sleep to wait for them. End your turn (a reply with no tool call) and resume from the task wake when it arrives."],
@@ -23,7 +23,7 @@ export const PROMPTS = {
   "tools.bash.param.run_in_background": "Start the command in the background and return immediately. You will be notified when it completes.",
   "tools.bash.result.backgrounded": "Command \"{{command}}\" moved to background (task_id: {{taskId}}). Output: {{outputPath}}.\nYou will be notified when it completes, even if other commands are still running. Do not poll or sleep: reply to the user now with no tool call, and continue from the <pi-famulus-wake kind=\"task\"> when it arrives.",
   "tools.bash.error.bare-sleep": "Refusing to run a bare sleep/idle-loop command: {{command}}. Do not sleep to wait for background work; completion is delivered via notification. Use the monitor tool to watch for a condition, or run_in_background for long commands.",
-  "tools.child.agent_message.description": "Message sibling subagents in your run, or list pending requests. \"send\" delivers to a running sibling. Sending to a finished sibling errors and does not resume it; resume with subagent({ action: \"resume\", run_id, child_id, message }). \"broadcast\" steers every running sibling in your run; \"list\" shows pending decision requests and recent traffic. Cross-run messaging is rejected.",
+  "tools.child.agent_message.description": "Message sibling subagents in your run, or list pending requests. \"send\" delivers to a running sibling and starts a new turn on an idle one. \"broadcast\" steers every running sibling in your run; \"list\" shows pending decision requests and recent traffic. Cross-run messaging is rejected.",
   "tools.child.agent_message.snippet": "Message sibling subagents in your run",
   "tools.child.bash.description": "Execute a bash command in the current working directory. Returns stdout and stderr. Output is truncated to last {{maxLines}} lines or {{maxKb}}KB (whichever is hit first). The command runs to completion (or the optional timeout in seconds, after which it is killed). There is no background execution inside subagents.",
   "tools.child.bash.snippet": "Execute bash commands (ls, grep, find, etc.)",
@@ -158,11 +158,10 @@ export const PROMPT_SEGMENTS: Record<string, { prompt: PromptId; text?: string;
   "guidelines.no-fabrication": {"prompt":"guidelines.parent","text":"Never fabricate or assume a background task's result before its notification arrives."},
   "guidelines.subagent-handover": {"prompt":"guidelines.parent","text":"Subagent runs that exceed the foreground budget continue in the background. Do not poll run status. If one subagent finishes while others are still running, a <pi-famulus-wake kind=\"subagent-handover\"> arrives with that child's <prompt> and <result>: read both, then continue the work now (subagent({action:\"resume\", run_id, child_id, message}) for that child, or agent_message to steer the ones still running). Do not wait for the rest of the run. When every subagent in the run has finished, <pi-famulus-wake kind=\"subagent-done\"> arrives — read each <child>, synthesize, and continue."},
   "guidelines.subagent-overrun": {"prompt":"guidelines.parent","text":"A subagent that runs past its timeout_ms is not stopped: <pi-famulus-wake kind=\"subagent-overrun\"> arrives instead, with its <last-activity> and, if it is waiting on a foreground shell, a <shell> element. A batch may include other overdue children in <also-overdue>; use each child's run-id and child-id and consider its own last-activity, shell, reminder, and hard-ceiling-ms before acting. Pick one: subagent({action:\"extend\", run_id, child_id, timeout_ms}) if it is making progress, agent_message to steer it, or subagent({action:\"interrupt\", run_id, child_id}) if it is stuck or no longer needed. If you do none of these it keeps running and the reminder comes again."},
-  "guidelines.agent-message": {"prompt":"guidelines.parent","text":"Use agent_message to steer running subagents and to reply to <pi-famulus-wake kind=\"supervisor-request\"> (action:\"reply\"; the <reply-with> child is the call shape). Do not use agent_message to resume a finished child — that is subagent({action:\"resume\"}). Supervisor wakes are not user messages — still act on them."},
+  "guidelines.agent-message": {"prompt":"guidelines.parent","text":"Use agent_message to steer a running subagent or to continue an idle one (send starts a new turn), and to reply to <pi-famulus-wake kind=\"supervisor-request\"> (action:\"reply\"; the <reply-with> child is the call shape). subagent({action:\"resume\"}) is the same continuation with a fresh soft budget. Supervisor wakes are not user messages — still act on them."},
   "guidelines.monitor-end-turn": {"prompt":"guidelines.monitor-idle","text":"After starting or re-arming a monitor, or handling a monitor event, if no immediate work remains, end your turn with no tool call; simply wait for the next notification. Handling an event does not require a user-visible reply. Do not repeat unchanged/intermediate status or narrate your decision to stay quiet; notify the user when their requested condition is met, their input is needed, or a failure prevents further progress. Read original output with task_output only when details are needed (including paging a truncated preview), never to poll or wait. Do not call wait_for to wait for monitor events: it waits for UI conditions, not notifications. Do not invent a stateId or make a failing tool call to yield."},
   "child.guidelines": {"prompt":"guidelines.child","text":"## Child agent behavior (pi-famulus)\n\n- Do not background work; bash runs to completion.\n- When blocked, use contact_supervisor with need_decision; use progress_update for status.\n- Use agent_message only to communicate with siblings in this same run.\n- Your final message is your result."},
-  "tooldesc.agent-message-no-resume": {"prompt":"tools.agent_message.description","text":"Sending to a finished child errors (it does not resume) and points at subagent({ action: \"resume\", run_id, child_id, message }). "},
-  "result.agent-message-use-resume": {"prompt":"tools.agent_message.error.finished-child","pattern":"agent_message does not resume children\\. Use subagent\\(\\{ action: \"resume\", run_id: \".*?\", child_id: \".*?\", message: \"\\.\\.\\.\" \\}\\)\\."},
+  "tooldesc.agent-message-no-resume": {"prompt":"tools.agent_message.description","text":"An idle child (warm or parked) continues with send or subagent resume; its prompt cache stays warm only for the time a wake reports. "},
   "tooldesc.bash-autobg": {"prompt":"tools.bash.description","text":"Foreground commands that exceed the foreground budget are automatically moved to the background; you will be notified when they complete. "},
   "rules.pi-env": {"prompt":"tools.bash.rules","text":"You can inspect PI_* environment variables for current model and session details."},
   "rules.bash-no-poll": {"prompt":"tools.bash.rules","text":"Long-running bash commands are moved to the background automatically; do not poll or sleep to wait for them."},

package/src/subagent/hosted-session.ts

@@ -0,0 +1,268 @@
+/**
+ * ChildSessionAdapter over a daemon-hosted `pi --mode rpc` process.
+ * The runner's timers stay; only the session lives in another process.
+ */
+import { randomUUID } from "node:crypto";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ManagerClient, ManagerEvent } from "../manager-client";
+import { parentResourceArgs, resolvePiArgv } from "../pi-command";
+import { resolveChildModel, type PiRuntimeDeps } from "./pi-runtime";
+import type {
+  ChildRunRequest,
+  ChildSessionAdapter,
+  ChildSessionEvent,
+  ChildTokenUsage,
+  CreateSessionFn,
+} from "./types";
+
+export interface HostedSessionDeps extends PiRuntimeDeps {
+  getClient: () => ManagerClient | null;
+  getHome: () => string;
+  /** This extension's entry file, passed to the child with -e. */
+  extensionEntry: string;
+  piCommand?: string | null;
+  trustProject?: boolean;
+}
+
+interface HostingView {
+  residency: string;
+  activity: string;
+  driver: string;
+  cacheExpiresAt?: number;
+  sessionFile?: string;
+  sessionId?: string;
+}
+
+export function createHostedSessionFn(deps: HostedSessionDeps): CreateSessionFn {
+  return async (req) => {
+    const client = deps.getClient();
+    if (!client || !client.isAvailable()) {
+      throw new Error("pi-famulus daemon is not connected; a subagent needs it to run pi --mode rpc.");
+    }
+    client.requireHostedProtocol();
+    const pi = resolvePiArgv(deps.piCommand);
+    if ("error" in pi) throw new Error(pi.error);
+    const model = resolveChildModel(deps, req);
+    const thinking =
+      model.thinkingOverride ?? req.agent.thinking ?? deps.getParentThinkingLevel() ?? "off";
+    const cwd = deps.getCwd();
+    const promptPath = join(deps.getHome(), "agents", "prompts");
+    mkdirSync(promptPath, { recursive: true });
+    const promptFile = join(promptPath, `${req.childId}.md`);
+    writeFileSync(promptFile, req.agent.systemPrompt);
+    const inherited = parentResourceArgs();
+    const extensionPaths = inherited.filter((_, i) => inherited[i - 1] === "-e");
+    const alreadyLoadsUs = extensionPaths.some((path) => path === deps.extensionEntry);
+    const trustInherited = inherited.some((arg) => arg === "-a" || arg === "--approve" || arg === "-na" || arg === "--no-approve");
+    const argv = [
+      ...pi.argv,
+      "--mode", "rpc",
+      "--session-id", req.childId,
+      "--name", `${req.agent.name}: ${req.name}`,
+      ...inherited,
+      ...(alreadyLoadsUs ? [] : ["-e", deps.extensionEntry]),
+      ...(model.model ? ["--model", `${model.model.provider}/${model.model.id}`] : []),
+      "--thinking", String(thinking),
+      "--append-system-prompt", promptFile,
+      ...(trustInherited ? [] : [deps.getProjectTrusted?.() ? "-a" : "-na"]),
+      ...(req.agent.tools ? ["--tools", req.agent.tools.join(",")] : []),
+    ];
+    const env = { ...process.env } as Record<string, string>;
+    if (req.agent.tools) env.PI_FAMULUS_CHILD_TOOLS = req.agent.tools.join(",");
+    env.PI_FAMULUS_CHILD_RUN = req.runId;
+    env.PI_FAMULUS_CHILD_NAME = req.name;
+    const spawned = await client.agentSpawn({
+      childId: req.childId,
+      runId: req.runId,
+      name: req.name,
+      argv,
+      cwd,
+      env,
+    });
+    let warning = model.warning;
+    try {
+      await client.agentInput(req.childId, "set_steering_mode", "all", "parent");
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      const note = `Steering mode was not set (${message}); queued input may wait until the current turn ends.`;
+      warning = warning ? `${warning} ${note}` : note;
+    }
+    await client.agentWatch(req.childId);
+    const session = new HostedRpcSession(client, req.childId, {
+      warning,
+      resolvedModel: model.model ? `${model.model.provider}/${model.model.id}` : undefined,
+      effectiveThinkingLevel: typeof thinking === "string" ? thinking : undefined,
+      sessionFile: typeof spawned.session_file === "string" ? spawned.session_file : undefined,
+      sessionId: typeof spawned.session_id === "string" ? spawned.session_id : req.childId,
+    });
+    return session;
+  };
+}
+
+class HostedRpcSession implements ChildSessionAdapter {
+  readonly warning?: string;
+  readonly resolvedModel?: string;
+  readonly effectiveThinkingLevel?: string;
+  private readonly listeners = new Set<(event: ChildSessionEvent) => void>();
+  private readonly unsubscribe: () => void;
+  private streaming = false;
+  private lastText = "";
+  private turns: { role: string; text: string }[] = [];
+  private usage: ChildTokenUsage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+  private settle: (() => void) | null = null;
+  private hostingView: HostingView;
+  private disposed = false;
+
+  constructor(
+    private readonly client: ManagerClient,
+    private readonly childId: string,
+    init: { warning?: string; resolvedModel?: string; effectiveThinkingLevel?: string; sessionFile?: string; sessionId?: string },
+  ) {
+    this.warning = init.warning;
+    this.resolvedModel = init.resolvedModel;
+    this.effectiveThinkingLevel = init.effectiveThinkingLevel;
+    this.hostingView = {
+      residency: "warm",
+      activity: "starting",
+      driver: "parent",
+      sessionFile: init.sessionFile,
+      sessionId: init.sessionId,
+    };
+    this.unsubscribe = this.client.onEvent((event) => this.onManagerEvent(event as ManagerEvent & Record<string, unknown>));
+  }
+
+  hosting(): HostingView {
+    return { ...this.hostingView };
+  }
+
+  async prompt(text: string): Promise<void> {
+    const done = this.armSettle();
+    const op = this.streaming ? "prompt_steer" : "prompt";
+    await this.client.agentInput(this.childId, op, text, "parent");
+    if (!this.streaming) await done;
+  }
+
+  async steer(text: string): Promise<void> {
+    await this.client.agentInput(this.childId, "prompt_steer", text, "parent");
+  }
+
+  async followUp(text: string): Promise<void> {
+    await this.client.agentInput(this.childId, "prompt_follow", text, "parent");
+  }
+
+  async abort(): Promise<void> {
+    await this.client.agentInput(this.childId, "abort", "", "parent");
+    this.streaming = false;
+    this.settle?.();
+    this.settle = null;
+  }
+
+  async park(): Promise<void> {
+    await this.client.agentPark(this.childId);
+    this.hostingView.residency = "parked";
+  }
+
+  async waitForIdle(): Promise<void> {
+    if (!this.streaming) return;
+    await this.armSettle();
+  }
+
+  getLastAssistantText(): string | undefined {
+    return this.lastText || undefined;
+  }
+
+  getConversation() {
+    return this.turns.map((turn) => ({ ...turn }));
+  }
+
+  tokenUsage(): ChildTokenUsage {
+    return { ...this.usage };
+  }
+
+  isStreaming(): boolean {
+    return this.streaming;
+  }
+
+  subscribe(listener: (event: ChildSessionEvent) => void): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.unsubscribe();
+    this.settle?.();
+    this.settle = null;
+  }
+
+  private armSettle(): Promise<void> {
+    return new Promise((resolve) => {
+      this.settle = resolve;
+    });
+  }
+
+  private onManagerEvent(event: ManagerEvent & Record<string, unknown>): void {
+    if (event.child_id !== this.childId) return;
+    if (event.event === "agent_state") {
+      this.hostingView = {
+        residency: String(event.residency ?? this.hostingView.residency),
+        activity: String(event.activity ?? this.hostingView.activity),
+        driver: String(event.driver ?? this.hostingView.driver),
+        cacheExpiresAt: typeof event.cache_expires_at === "number" ? event.cache_expires_at : this.hostingView.cacheExpiresAt,
+        sessionFile: typeof event.session_file === "string" ? event.session_file : this.hostingView.sessionFile,
+        sessionId: typeof event.session_id === "string" ? event.session_id : this.hostingView.sessionId,
+      };
+      if (event.activity === "running") this.streaming = true;
+      if (event.activity === "idle" || event.activity === "failed") {
+        this.streaming = false;
+        this.settle?.();
+        this.settle = null;
+      }
+      return;
+    }
+    if (event.event !== "agent_rpc" || !event.record || typeof event.record !== "object") return;
+    const record = event.record as { type?: string; message?: { role?: string; content?: { type?: string; text?: string }[]; usage?: Record<string, unknown> }; toolCallId?: string };
+    const type = record.type ?? "";
+    if (type === "agent_start") this.streaming = true;
+    if (type === "agent_settled") {
+      this.streaming = false;
+      this.settle?.();
+      this.settle = null;
+    }
+    if (type === "message_end" && record.message?.role === "assistant") {
+      const text = (record.message.content ?? []).map((part) => part.text ?? "").join("");
+      if (text) {
+        this.lastText = text;
+        this.turns.push({ role: "assistant", text });
+      }
+      const usage = record.message.usage;
+      if (usage) {
+        this.usage.input += num(usage.input);
+        this.usage.output += num(usage.output);
+        this.usage.cacheRead += num(usage.cacheRead);
+        this.usage.cacheWrite += num(usage.cacheWrite);
+      }
+    }
+    if (type === "message_end" && record.message?.role === "user") {
+      const text = (record.message.content ?? []).map((part) => part.text ?? "").join("");
+      if (text) this.turns.push({ role: "user", text });
+    }
+    const adapted: ChildSessionEvent = {
+      type,
+      ...(record.message?.role ? { role: record.message.role } : {}),
+      ...(record.toolCallId ? { toolCallId: record.toolCallId } : {}),
+    };
+    for (const listener of this.listeners) listener(adapted);
+  }
+}
+
+function num(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+/** Request id for a child→parent decision. */
+export function newCommsRequestId(): string {
+  return `rq_${randomUUID().slice(0, 8)}`;
+}

package/src/subagent/overrun.ts

@@ -38,6 +38,17 @@ export class ChildShellTracker {
     this.sizes.delete(taskId);
   }
 
+  /** A hosted child's shell is observed from the parent session's task_exited. */
+  endByTask(taskId: string): void {
+    for (const [childId, shell] of this.shells) {
+      if (shell.taskId === taskId) {
+        this.shells.delete(childId);
+        this.sizes.delete(taskId);
+        return;
+      }
+    }
+  }
+
   current(childId: string): ChildShell | undefined {
     return this.shells.get(childId);
   }

package/src/subagent/pi-runtime.ts

@@ -157,6 +157,10 @@ interface ResolvedModel {
  * falls back to the parent model with a warning (user-authored files must not
  * hard-fail across machines).
  */
+export function resolveChildModel(deps: PiRuntimeDeps, req: ChildRunRequest): ResolvedModel {
+  return resolveModel(deps, req);
+}
+
 function resolveModel(deps: PiRuntimeDeps, req: ChildRunRequest): ResolvedModel {
   const candidates = modelCandidates(deps);
   const findModel = (provider: string, id: string): Model | undefined =>

package/src/subagent/runner.ts

@@ -99,10 +99,10 @@ export interface InProcessRunnerOptions {
   /** Shared time source and scheduler. */
   clock?: Clock;
   /**
-   * Per-generation admission hook. Awaited before each (re)start; the
-   * releaser gets terminal=false for a resumable interruption so its local
-   * slot can be returned while the child-owned machine permit is retained.
-   * Rejecting cancels the generation as {status:"interrupted", error}.
+   * Per-generation admission hook. Awaited before each (re)start. The
+   * releaser is called with terminal=true when the turn settles, including
+   * an interrupted turn: the machine permit is released and the next turn
+   * acquires again. Rejecting cancels the generation as {status:"interrupted", error}.
    */
   acquire?: (req: ChildRunRequest, ticket: AdmissionTicket) => Promise<(terminal?: boolean) => void>;
   /**
@@ -462,8 +462,17 @@ class InProcessChildHandle implements DisposableChildHandle {
     await this.beginGeneration(message, false, false, gen);
   }
 
+  hosting(): { residency?: string; driver?: string; cacheExpiresAt?: number; sessionFile?: string; sessionId?: string } | undefined {
+    const session = this.session as { hosting?: () => { residency?: string; driver?: string; cacheExpiresAt?: number; sessionFile?: string; sessionId?: string } } | null;
+    return session?.hosting?.();
+  }
+
   async interrupt(): Promise<void> {
-    if (this.status_ !== "running" && this.status_ !== "pending") return;
+    if (this.status_ !== "running" && this.status_ !== "pending") {
+      const session = this.session as { park?: () => Promise<void> } | null;
+      if (session?.park) await session.park();
+      return;
+    }
     this.settle(this.generation, {
       status: "interrupted",
       // A pending turn has produced nothing yet; the last assistant text
@@ -563,8 +572,8 @@ class InProcessChildHandle implements DisposableChildHandle {
           signal: admissionAbort.signal,
         });
         if (this.disposed || this.isSettled(gen)) {
-          // A queued interruption is resumable; only disposal is terminal.
-          release(this.disposed);
+          // The turn is over (interrupted or disposed). The next turn acquires again.
+          release(true);
           return;
         }
         this.releaseSlot = release;
@@ -756,8 +765,9 @@ class InProcessChildHandle implements DisposableChildHandle {
       result.warning = this.session.warning;
     }
     this.status_ = result.status;
-    this.terminalSettle = result.status !== "interrupted" || result.error === "disposed";
-    this.release(this.terminalSettle);
+    // Every settled turn releases its machine permit, including an
+    // interrupted one. The next turn (resume, send, user input) acquires again.
+    this.release(true);
     this.notifyActivity();
     this.resolveResult(result);
   }

package/src/subagent/tool.ts

@@ -140,6 +140,8 @@ export interface SubagentToolDeps {
   /** Agent definition resolver (M5 wires the real loader; default: worker). */
   resolveAgent?: (name: string | undefined) => AgentDefinition;
   /** Selectable models for action:"models" (§4.6); absent → action errors. */
+  /** Receives the watcher for turns started by agent_message send. */
+  registerResumeWatch?: (watch: (childId: string) => void) => void;
   listModels?: () => {
     provider: string;
     id: string;
@@ -346,6 +348,20 @@ export function createSubagentTool(
     return true;
   };
 
+  const armResumeWake = (childId: string): void => {
+    const registry = deps.getRegistry();
+    if (!registry) return;
+    const record = registry.list().find((run) => run.children.some((c) => c.childId === childId));
+    if (!record) return;
+    const handedOver = new Set<string>();
+    void registry.getResult(childId)?.then(() => {
+      if (!notifyChildHandover(registry, record.runId, childId, handedOver)) {
+        notifyRunCompleted(registry, record.runId);
+      }
+    });
+  };
+  deps.registerResumeWatch?.(armResumeWake);
+
   const startRun = async (
     params: SubagentParams,
     signal: AbortSignal | undefined,
@@ -547,7 +563,18 @@ export function createSubagentTool(
       };
     }
 
-    const record = requireRun(registry, params.run_id);
+    const record = params.run_id
+      ? requireRun(registry, params.run_id)
+      : params.child_id
+        ? resolveRunByChild(registry, params.child_id)
+        : undefined;
+    if (!record) {
+      if (params.child_id && !params.run_id) {
+        throw new Error(`unknown child "${params.child_id}" (no run in this session holds it)`);
+      }
+      requireRun(registry, params.run_id);
+      throw new Error("run_id is required for this action");
+    }
 
     if (action === "get") {
       return {
@@ -585,18 +612,45 @@ export function createSubagentTool(
         const known = record.children.map((c) => `${c.name} (${c.childId})`).join(", ");
         throw new Error(`no child "${params.child_id}" in run ${record.runId} (children: ${known})`);
       }
+      const idle = record.children.filter((c) => {
+        if (params.child_id && c.childId !== params.child_id && c.name !== params.child_id) return false;
+        return c.status === "completed" || c.status === "failed" || c.status === "interrupted";
+      });
       for (const child of targets) {
         await registry.handle(child.childId)?.interrupt();
       }
-      const scope = params.child_id ? `subagent ${params.child_id}` : `${targets.length} subagent(s)`;
+      for (const child of idle) {
+        await registry.handle(child.childId)?.interrupt();
+      }
+      const interrupted = [...targets, ...idle].map((c) => c.childId);
+      const scope = params.child_id ? `subagent ${params.child_id}` : `${interrupted.length} subagent(s)`;
       return {
         content: [{ type: "text", text: `Interrupted ${scope} in run ${record.runId}.` }],
-        details: { run_id: record.runId, interrupted: targets.map((c) => c.childId) },
+        details: { run_id: record.runId, interrupted },
       };
     }
 
     if (action === "steer") {
       if (!params.message) throw new Error("message is required for steer");
+      const named = params.child_id
+        ? record.children.find((c) => c.childId === params.child_id || c.name === params.child_id)
+        : record.children.length === 1 ? record.children[0] : undefined;
+      if (named && named.status !== "running" && named.status !== "pending") {
+        const { queuedBehind } = await registry.resumeChild(named.childId, params.message);
+        armResumeWake(named.childId);
+        return {
+          content: [{
+            type: "text",
+            text: fill("tools.subagent.result.resumed", {
+              name: named.name,
+              childId: named.childId,
+              runId: record.runId,
+              queued: queuedText(queuedBehind),
+            }),
+          }],
+          details: { run_id: record.runId, child_id: named.childId, queued_behind: queuedBehind },
+        };
+      }
       const handle = resolveSingleActiveChild(registry, record, params.child_id, "steer");
       await handle.steer(params.message);
       return {
@@ -645,12 +699,7 @@ export function createSubagentTool(
     );
     // Resume is asynchronous. If siblings are still running, hand this child
     // back as soon as it finishes; otherwise the run-complete wake covers it.
-    const handedOver = new Set<string>();
-    void registry.getResult(child.childId)?.then(() => {
-      if (!notifyChildHandover(registry, record.runId, child.childId, handedOver)) {
-        notifyRunCompleted(registry, record.runId);
-      }
-    });
+    armResumeWake(child.childId);
     return {
       content: [
         {
@@ -733,6 +782,18 @@ export function createSubagentTool(
   };
 }
 
+function resolveRunByChild(registry: SubagentRegistry, childIdOrName: string) {
+  const runs = registry.list();
+  const byId = runs.filter((run) => run.children.some((c) => c.childId === childIdOrName));
+  if (byId.length === 1) return byId[0];
+  const byName = runs.filter((run) => run.children.some((c) => c.name === childIdOrName));
+  if (byName.length > 1) {
+    const ids = byName.map((run) => run.runId).join(", ");
+    throw new Error(`child name "${childIdOrName}" is in more than one run (${ids}); pass run_id`);
+  }
+  return byName[0];
+}
+
 /** Resume result clause for a turn waiting for an admission slot ("" when it started at once). */
 function queuedText(queuedBehind: number | null): string {
   if (queuedBehind === null) return "";

package/src/subagent/types.ts

@@ -135,6 +135,8 @@ export interface ChildHandle {
   tokenUsage(): ChildTokenUsage;
   /** Cumulative observed LLM, tool, admission-queue and approximate wall time. */
   wallUsage(): ChildWallUsage;
+  /** Hosted-process view, when this child runs as `pi --mode rpc`. */
+  hosting?(): { residency?: string; driver?: string; cacheExpiresAt?: number; sessionFile?: string; sessionId?: string } | undefined;
 }
 
 /**