@nredd/pi-subagents 0.22.0-nredd.8 → 0.22.0-nredd.9

package/src/agent-runner.ts

@@ -23,7 +23,8 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { BUILTIN_TOOL_NAMES, getAgentConfig, getConfig, getMemoryToolNames, getReadOnlyMemoryToolNames, getToolNamesForType } from "./agent-types.js";
-import { runInChildSessionContext } from "./child-context.js";
+import { bindChildResourceLoader, runInChildSessionContext } from "./child-context.js";
+import { type Clock, realClock } from "./clock.js";
 import { buildParentContext, extractText } from "./context.js";
 import { DEFAULT_AGENTS } from "./default-agents.js";
 import { detectEnv } from "./env.js";
@@ -35,10 +36,12 @@ import type { ModelSelection } from "./model-selection.js";
 import {
   createNestedSubagentTools,
   getMaxSubagentDepth,
+  hasNestableTypes,
   NESTED_WORKFLOW_ERROR,
   NESTED_WORKFLOW_NO_AGENT_ERROR,
   type NestedAgentManager,
 } from "./nested-tools.js";
+import { type PlanGate, planGateReason } from "./plan-mode-children.js";
 import { buildAgentPrompt, type PromptExtras } from "./prompts.js";
 import { createHomeResourceLoader } from "./resource-loader.js";
 import { preloadSkills } from "./skill-loader.js";
@@ -59,6 +62,7 @@ export const SUBAGENT_TOOL_NAMES = {
   WORKFLOW: "SubagentWorkflow",
   GET_RESULT: "get_subagent_result",
   STEER: "steer_subagent",
+  STOP: "stop_subagent",
 } as const;
 
 /**
@@ -302,11 +306,10 @@ export function installExtensionToolScope(
     /** Receives the scope check the child's nested-call gate extension applies. */
     nestedCallGate: NestedCallGate;
     /** Why workflow tools are refused. */
-    workflowError?: string;
+    workflowError: string;
   },
 ): void {
-  const { loader, toolNames, disallowedSet, extNames, narrowing, readmitToolNames, nestedCallGate } = ctx;
-  const workflowError = ctx.workflowError ?? NESTED_WORKFLOW_ERROR;
+  const { loader, toolNames, disallowedSet, extNames, narrowing, readmitToolNames, nestedCallGate, workflowError } = ctx;
 
   // The names allowed right now. Mirrors the `ext:` opt-in flip: when any `ext:`
   // selector is present, extension tools become an explicit allowlist — a loaded
@@ -394,8 +397,14 @@ export function installExtensionToolScope(
   };
 }
 
-/** Set once the child's tool scope is installed; until then the gate admits everything. */
-type NestedCallGate = { allows?: (name: string) => boolean };
+/**
+ * Set once the child's tool scope (and, while planning, its Plan check) is
+ * installed; until then the gate admits everything.
+ */
+type NestedCallGate = {
+  allows?: (name: string) => boolean;
+  planReason?: (toolName: string, input: unknown, cwd: string) => string | undefined;
+};
 
 /**
  * Inline extension that applies the subagent's tool scope to calls a tool makes
@@ -411,11 +420,13 @@ function scopeGateExtension(gate: NestedCallGate): InlineExtension {
     name: SCOPE_GATE_NAME,
     hidden: true,
     factory: (ext) => {
-      ext.on("tool_call", (event) =>
-        gate.allows?.(event.toolName) === false
-          ? { block: true, reason: `Tool "${event.toolName}" is not available to this subagent.` }
-          : undefined,
-      );
+      ext.on("tool_call", (event, ctx) => {
+        if (gate.allows?.(event.toolName) === false) {
+          return { block: true, reason: `Tool "${event.toolName}" is not available to this subagent.` };
+        }
+        const reason = gate.planReason?.(event.toolName, event.input, ctx.cwd);
+        return reason === undefined ? undefined : { block: true, reason };
+      });
     },
   };
 }
@@ -495,6 +506,8 @@ export interface AssistantMessageInfo {
 export interface RunOptions {
   /** Backoff before each stale-ctx re-prompt (#145); defaults to 1s, 3s, 9s. `[]` disables recovery. */
   staleRetryDelaysMs?: readonly number[];
+  /** Clock that times the stale-ctx backoff; the manager passes its own. Defaults to native timers. */
+  clock?: Clock;
   /** ExtensionAPI instance — used for pi.exec() instead of execSync. */
   pi: ExtensionAPI;
   /** Manager-assigned id; suffixes session name to disambiguate parallel spawns (e.g. `Explore#a1b2c3d4`). */
@@ -600,6 +613,11 @@ export interface RunOptions {
    * fails at the call that wrote it rather than inside the child.
    */
   structuredOutput?: CompiledSchema;
+  /**
+   * The Plan restriction for this child's runs (#437). Installed once on the
+   * session and read per call; the manager sets `policy` per run.
+   */
+  planGate?: PlanGate;
   /** Runtime bridge for opt-in child-safe nested delegation. */
   nestedRuntime?: {
     manager: NestedAgentManager;
@@ -646,28 +664,40 @@ export interface RunResult {
  */
 function collectResponseText(session: AgentSession) {
   let text = "";
+  let laterTool = false;
+  let previousText = "";
+  let previousLaterTool = false;
   const unsubscribe = session.subscribe((event: AgentSessionEvent) => {
     // message_start also fires for user and toolResult messages — resetting on
     // those would wipe assistant text already collected. Reset only when a new
     // ASSISTANT message begins, so getText() is the last assistant message's text.
     if (event.type === "message_start" && event.message.role === "assistant") {
+      if (text.trim()) {
+        previousText = text;
+        previousLaterTool = laterTool;
+      }
       text = "";
+      laterTool = false;
     }
     if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
       text += event.assistantMessageEvent.delta;
     }
+    if (event.type === "tool_execution_end") {
+      if (text.trim()) laterTool = true;
+      else if (previousText.trim()) previousLaterTool = true;
+    }
   });
-  return { getText: () => text, unsubscribe };
+  return { getText: () => text, getPreviousText: () => previousText, hasLaterTool: () => text.trim() ? laterTool : previousLaterTool, unsubscribe };
 }
 
 /**
  * Get the last non-empty assistant text produced during THIS invocation.
  * `startIndex` is the message count captured before the prompt, so the walk-back
  * never crosses into a previous turn: on a resume whose new turn failed empty,
- * this returns "" instead of the prior turn's answer (#144). Defaults to 0 (a
- * fresh spawn, where the whole history belongs to this run).
+ * this returns "" instead of the prior turn's answer (#144). A fresh spawn passes
+ * 0, since the whole history belongs to that run.
  */
-function getLastAssistantText(session: AgentSession, startIndex = 0): string {
+function getLastAssistantText(session: AgentSession, startIndex: number): string {
   for (let i = session.messages.length - 1; i >= startIndex; i--) {
     const msg = session.messages[i];
     if (msg.role !== "assistant") continue;
@@ -703,7 +733,7 @@ export function forwardModelCall(event: AgentSessionEvent, emit: (event: ModelCa
  * no tool call pending, and a stop that was not an abort, a tool-use handoff or
  * a token-limit cut. Anything else is a teaser or a cut-off report.
  */
-function endedWithReport(session: AgentSession, startIndex = 0): boolean {
+function endedWithReport(session: AgentSession, startIndex: number): boolean {
   for (let i = session.messages.length - 1; i >= startIndex; i--) {
     const msg = session.messages[i];
     if (msg.role !== "assistant") continue;
@@ -768,7 +798,7 @@ async function forceFinalReport(session: AgentSession, startIndex: number, signa
  * Bounded by `startIndex` (like the text fallback) so a resume that produced no
  * assistant message of its own never inherits a PRIOR turn's stop reason.
  */
-function finalTurnError(session: AgentSession, startIndex = 0): string | undefined {
+function finalTurnError(session: AgentSession, startIndex: number): string | undefined {
   for (let i = session.messages.length - 1; i >= startIndex; i--) {
     const msg = session.messages[i];
     if (msg.role !== "assistant") continue;
@@ -789,21 +819,18 @@ const STALE_CTX_RETRY_DELAYS_MS: readonly number[] = [1_000, 3_000, 9_000];
 /** Sent when the session's last step died on a stale ctx; the transcript already holds the work so far. */
 const STALE_CTX_RETRY_PROMPT = "Your previous step was interrupted by a session reload before it produced output. Continue the task from where you left off.";
 
-/** Longest tool output echoed into a partial result. */
-const PARTIAL_TOOL_OUTPUT_CHARS = 1_500;
-
 /**
  * Resolve after `ms`, or as soon as `signal` aborts. Never rejects.
  */
-function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+function sleep(ms: number, signal: AbortSignal | undefined, clock: Clock): Promise<void> {
   return new Promise((resolve) => {
     if (signal?.aborted) return resolve();
     const done = () => {
-      clearTimeout(timer);
+      timer.cancel();
       signal?.removeEventListener("abort", done);
       resolve();
     };
-    const timer = setTimeout(done, ms);
+    const timer = clock.setTimeout(done, ms);
     signal?.addEventListener("abort", done, { once: true });
   });
 }
@@ -822,16 +849,22 @@ function sleep(ms: number, signal?: AbortSignal): Promise<void> {
  * it to repeat side effects (a push, a PR). The continue prompt adds one user
  * turn and nothing else, so the tool batch is never replayed; a tool that did
  * run is in context as a result.
+ *
+ * Kept for stale-ctx failures that routing no longer causes itself: core now hands
+ * `route` the requesting session's context (#581), so another session's reload or
+ * disposal cannot invalidate this request, but an extension callback that captured
+ * a dead ctx can still throw, and only this turns that into a bounded retry and a report.
  */
 export async function retryStaleCtx(
   session: AgentSession,
   startIndex: number,
   signal: AbortSignal | undefined,
   delays: readonly number[] = STALE_CTX_RETRY_DELAYS_MS,
+  clock: Clock = realClock,
 ): Promise<void> {
   for (const delay of delays) {
     if (!isStaleCtxError(finalTurnError(session, startIndex))) return;
-    await sleep(delay, signal);
+    await sleep(delay, signal, clock);
     if (signal?.aborted) return;
     await session.prompt(STALE_CTX_RETRY_PROMPT);
   }
@@ -847,26 +880,29 @@ function mayFollowUp(session: AgentSession, startIndex: number, signal: AbortSig
   return !signal?.aborted && staleCtxOutcome(session, startIndex) === undefined;
 }
 
-/**
- * What a run that died on a stale ctx had done: the last tool calls with the
- * last tool output, so the parent can see side effects (a pushed branch, an
- * opened PR) instead of "No output". Empty when the run did nothing.
- */
+/** Bounded activity only: tool arguments, results and unknown names are never copied. */
 function partialProgress(session: AgentSession, startIndex: number): string {
   const calls: string[] = [];
-  let lastOutput = "";
   for (let i = session.messages.length - 1; i >= startIndex && calls.length < 5; i--) {
     const msg = session.messages[i];
-    if (msg.role === "toolResult" && !lastOutput) lastOutput = extractText(msg.content).trim();
-    if (msg.role === "assistant") {
-      for (const part of [...msg.content].reverse()) {
-        if (part.type === "toolCall" && calls.length < 5) calls.unshift(part.name);
-      }
-    }
+    if (msg.role !== "toolResult") continue;
+    const name = BUILTIN_TOOL_NAMES.includes(msg.toolName) ? msg.toolName : "other tool";
+    calls.unshift(`${name} (${msg.isError ? "failed" : "completed"})`);
   }
-  if (calls.length === 0) return "";
-  const clipped = lastOutput.length > PARTIAL_TOOL_OUTPUT_CHARS ? `${lastOutput.slice(0, PARTIAL_TOOL_OUTPUT_CHARS)}...` : lastOutput;
-  return `Last tool calls: ${calls.join(", ")}.${clipped ? `\nLast tool output:\n${clipped}` : ""}`;
+  return calls.length ? `Latest activity: ${calls.join(", ")}.` : "";
+}
+
+/** Mark prose as earlier progress when subsequent tool results exist. */
+function failureText(session: AgentSession, startIndex: number, text: string, partial: string, laterTool: boolean, streamed: boolean): string {
+  if (!text) return partial;
+  if (streamed) return laterTool ? `Earlier progress:\n${text}\n\n${partial}` : text;
+  let hasLaterResult = false;
+  for (let i = session.messages.length - 1; i >= startIndex; i--) {
+    const msg = session.messages[i];
+    if (msg.role === "assistant" && extractText(msg.content).trim() === text) break;
+    if (msg.role === "toolResult") hasLaterResult = true;
+  }
+  return hasLaterResult ? `Earlier progress:\n${text}\n\n${partial}` : text;
 }
 
 /**
@@ -877,7 +913,7 @@ export function staleCtxOutcome(session: AgentSession, startIndex: number): { fa
   const error = finalTurnError(session, startIndex);
   if (!isStaleCtxError(error)) return undefined;
   return {
-    failure: "interrupted by a session reload or replacement; the agent's model runtime went stale and retries did not recover it",
+    failure: `interrupted by a session reload or replacement; the agent's model runtime went stale and retries did not recover it: ${error}`,
     partial: partialProgress(session, startIndex),
   };
 }
@@ -995,11 +1031,20 @@ export async function runAgent(
 
   // Get parent system prompt for append-mode agents
   const parentSystemPrompt = ctx.getSystemPrompt();
+  const agentDir = resolveAgentDir(options.homeDir);
+  // The child inherits the parent's project-trust decision. Pi otherwise defaults
+  // SettingsManager to trusted, which could load project MCP configuration; resolve
+  // it before resource loading so untrusted skills cannot shadow trusted resources.
+  const projectTrusted = options.configCwd !== undefined && options.configProjectTrusted !== undefined
+    ? options.configProjectTrusted
+    : ctx.isProjectTrusted();
+  const settingsManager = SettingsManager.create(configCwd, agentDir, { projectTrusted });
 
   // Build prompt extras (memory, skill preloading)
   const extras: PromptExtras = {};
   if (options.worktreeBase) extras.worktreeBase = options.worktreeBase;
   if (options.workflow && !options.structuredOutput) extras.workflowChild = true;
+  if (options.planGate?.policy) extras.planMode = true;
 
   // Resolved here, not by each caller: mention and RPC spawns pass no `isolated`,
   // and the agent file's value must hold on every path.
@@ -1013,7 +1058,7 @@ export async function runAgent(
 
   // Skill preloading: when skills is string[], preload their content into prompt
   if (Array.isArray(skills)) {
-    const loaded = preloadSkills(skills, configCwd, options.homeDir);
+    const loaded = await preloadSkills(skills, configCwd, { agentDir, settingsManager, homeDir: options.homeDir });
     if (loaded.length > 0) {
       extras.skillBlocks = loaded;
     }
@@ -1052,10 +1097,13 @@ export async function runAgent(
     ? options.nestedRuntime
     : undefined;
   // One answer for the prompt and the workflow refusal: does this child end up with `Agent`?
-  const agentAvailable = Boolean(
+  // An allowlist that resolves to no enabled agent leaves Agent nothing to
+  // accept; omit the tools rather than advertise "none" as a type (#331, #333).
+  const nestingPossible = Boolean(
     agentConfig?.allowedSubagents && nestedRuntime && !isolated
-      && !agentConfig.disallowedTools?.includes("Agent"),
+      && hasNestableTypes(agentConfig.allowedSubagents, { homeDir: options.homeDir, configCwd, projectTrusted }),
   );
+  const agentAvailable = nestingPossible && !agentConfig?.disallowedTools?.includes("Agent");
   if (agentConfig?.allowedSubagents && !agentAvailable) extras.nestingDisabled = true;
 
   // Build system prompt from agent config
@@ -1074,8 +1122,6 @@ export async function runAgent(
   // Still pass noSkills: true since we don't need the skill loader to load them again.
   const noSkills = skills === false || Array.isArray(skills);
 
-  const agentDir = resolveAgentDir(options.homeDir);
-
   // Extension loading:
   // - true  → all default-discovered extensions
   // - false → none (noExtensions)
@@ -1133,14 +1179,6 @@ export async function runAgent(
           };
         };
 
-  // The child inherits the parent's project-trust decision. pi's SettingsManager
-  // defaults to trusted, so without this a subagent in a project the user declined
-  // to trust would load its `.pi` extensions and settings, and pi's built-in MCP
-  // would start the stdio servers in its `.pi/mcp.json`.
-  const projectTrusted = options.configCwd !== undefined && options.configProjectTrusted !== undefined
-    ? options.configProjectTrusted
-    : ctx.isProjectTrusted();
-  const settingsManager = SettingsManager.create(configCwd, agentDir, { projectTrusted });
   // That trust covers the parent's project (`configCwd`), not a directory a spawn
   // was sent into. The session answers `ctx.isProjectTrusted()` for its own cwd,
   // which pi's MCP uses to read `<cwd>/.pi/mcp.json` — so a cross-directory session
@@ -1187,7 +1225,7 @@ export async function runAgent(
     systemPromptOverride: () => systemPrompt,
     appendSystemPromptOverride: () => [],
   }, options.homeDir);
-  await runInChildSessionContext(() => loader.reload());
+  await bindChildResourceLoader(loader).reload();
 
   // Plain entries in `tools:` are expected to be built-in names (extension tools
   // go through `ext:`), so an unknown name there is unambiguously a typo. Previously
@@ -1272,7 +1310,7 @@ export async function runAgent(
   // set `allowed_subagents` and a nestedRuntime was provided — and never when
   // isolated. Their names collide with EXCLUDED_TOOL_NAMES by design, so the
   // scoping below re-admits them explicitly (registry deny + active-set narrow).
-  const nestedTools = agentConfig?.allowedSubagents && nestedRuntime && !isolated
+  const nestedTools = agentConfig?.allowedSubagents && nestedRuntime && nestingPossible
     ? createNestedSubagentTools({
         manager: nestedRuntime.manager,
         pi: options.pi,
@@ -1481,6 +1519,21 @@ export async function runAgent(
     });
   }
 
+  // Plan mode (#437): outermost, so a call Plan refuses reaches no other hook.
+  // Read per call, because the manager decides the gate per run (spawn, resume).
+  const planGate = options.planGate;
+  if (planGate) {
+    const planReason = (toolName: string, input: unknown, cwd: string) =>
+      planGateReason(planGate, { toolName, input, cwd }, () => session.getAllTools(), readmitToolNames);
+    nestedCallGate.planReason = planReason;
+    const priorBeforeToolCall = session.agent.beforeToolCall;
+    session.agent.beforeToolCall = async (context, signal) => {
+      const reason = planReason(context.toolCall.name, context.args, effectiveCwd);
+      if (reason !== undefined) return { block: true, reason };
+      return priorBeforeToolCall?.(context, signal);
+    };
+  }
+
   options.onSessionCreated?.(session);
 
   const run = observeRun(session, { ...options, maxTurns: resolveEffectiveMaxTurns(type, options.maxTurns) });
@@ -1506,7 +1559,7 @@ export async function runAgent(
     // pi's `session.abort()` is a no-op until a run is active — so a child whose
     // parent is already gone is not prompted at all.
     if (options.signal?.aborted !== true) await session.prompt(effectivePrompt);
-    await retryStaleCtx(session, startLen, options.signal, options.staleRetryDelaysMs);
+    await retryStaleCtx(session, startLen, options.signal, options.staleRetryDelaysMs, options.clock);
 
     // A cap fired. The wrap-up steer is only a request: a model deep in a tool
     // loop keeps calling tools through the grace turns and is then aborted
@@ -1537,7 +1590,7 @@ export async function runAgent(
   }
 
   const stale = staleCtxOutcome(session, startLen);
-  const responseText = collector.getText().trim() || getLastAssistantText(session, startLen) || stale?.partial || "";
+  const text = collector.getText().trim() || getLastAssistantText(session, startLen);
   // A child asked for structured output that never gave any has failed, however
   // articulate its prose was. Reported through `failure` so it travels the same
   // path as a provider error rather than arriving as a successful empty answer.
@@ -1546,12 +1599,14 @@ export async function runAgent(
       ? `The agent's StructuredOutput call did not match the required schema: ${structuredCapture.lastError}`
       : "The agent did not report its answer through StructuredOutput."
     : undefined;
+  const failure = stale?.failure ?? finalTurnError(session, startLen) ?? structuredFailure;
+  const streamed = collector.getText().trim() || collector.getPreviousText().trim();
   return {
-    responseText,
+    responseText: failure ? failureText(session, startLen, streamed || text, stale?.partial ?? partialProgress(session, startLen), collector.hasLaterTool(), Boolean(streamed)) : text,
     session,
     aborted: run.aborted,
     steered: run.steered,
-    failure: stale?.failure ?? finalTurnError(session, startLen) ?? structuredFailure,
+    failure,
     ...(structuredCapture?.json !== undefined ? { structuredJson: structuredCapture.json } : {}),
     ...(structuredRetried ? { structuredRetried } : {}),
   };
@@ -1566,7 +1621,7 @@ export async function runAgent(
 export async function resumeAgent(
   session: AgentSession,
   prompt: string,
-  options: Pick<RunOptions, "staleRetryDelaysMs" | "maxTurns" | "onTurnEnd" | "onTextDelta" | "onModelCall" | "onToolActivity" | "onAssistantUsage" | "onCompaction" | "signal"> & {
+  options: Pick<RunOptions, "staleRetryDelaysMs" | "clock" | "maxTurns" | "onTurnEnd" | "onTextDelta" | "onModelCall" | "onToolActivity" | "onAssistantUsage" | "onCompaction" | "signal"> & {
     /** The agent's type, for its own `max_turns`. */
     type: SubagentType;
   },
@@ -1582,7 +1637,7 @@ export async function resumeAgent(
   try {
     // Already aborted: not prompted, as in `runAgent`.
     if (options.signal?.aborted !== true) await session.prompt(prompt);
-    await retryStaleCtx(session, startLen, options.signal, options.staleRetryDelaysMs);
+    await retryStaleCtx(session, startLen, options.signal, options.staleRetryDelaysMs, options.clock);
     if (run.steered && mayFollowUp(session, startLen, options.signal) && !endedWithReport(session, startLen)) {
       run.finalizing = true;
       if (await forceFinalReport(session, startLen, options.signal)) run.aborted = false;
@@ -1594,9 +1649,12 @@ export async function resumeAgent(
   }
 
   const stale = staleCtxOutcome(session, startLen);
+  const failure = stale?.failure ?? finalTurnError(session, startLen);
+  const text = collector.getText().trim() || getLastAssistantText(session, startLen);
+  const streamed = collector.getText().trim() || collector.getPreviousText().trim();
   return {
-    text: collector.getText().trim() || getLastAssistantText(session, startLen) || stale?.partial || "",
-    failure: stale?.failure ?? finalTurnError(session, startLen),
+    text: failure ? failureText(session, startLen, streamed || text, stale?.partial ?? partialProgress(session, startLen), collector.hasLaterTool(), Boolean(streamed)) : text,
+    failure,
     aborted: run.aborted,
     steered: run.steered,
   };

package/src/child-context.ts

@@ -4,7 +4,13 @@ import { AsyncLocalStorage } from "node:async_hooks";
  * Marks resource loading/session construction performed for a subagent. This is
  * async-context-local so concurrent top-level extension work is unaffected.
  */
-const childSessionContext = new AsyncLocalStorage<boolean>();
+// Pi reloads extension modules with jiti's module cache disabled. The parent
+// runner and the discovered child extension can therefore hold different module
+// instances, but must consult the same async-local session marker.
+const contextKey = Symbol.for("pi-subagents:child-session-context");
+const globals = globalThis as typeof globalThis & { [contextKey]?: AsyncLocalStorage<boolean> };
+const childSessionContext = globals[contextKey] ?? new AsyncLocalStorage<boolean>();
+globals[contextKey] = childSessionContext;
 
 export function inChildSessionContext(): boolean {
   return childSessionContext.getStore() === true;
@@ -13,3 +19,15 @@ export function inChildSessionContext(): boolean {
 export function runInChildSessionContext<T>(fn: () => Promise<T>): Promise<T> {
   return childSessionContext.run(true, fn);
 }
+
+/**
+ * Make every future `reload()` of a child session's loader run in the child
+ * context. A session reload (e.g. an extension calling `ctx.reload()`) calls
+ * `loader.reload()` again and re-runs each extension factory, long after the
+ * construction-time {@link runInChildSessionContext} has exited.
+ */
+export function bindChildResourceLoader<T extends { reload(): Promise<void> }>(loader: T): T {
+  const reload = loader.reload.bind(loader);
+  loader.reload = () => runInChildSessionContext(reload);
+  return loader;
+}

package/src/completion-outbox.ts

@@ -27,18 +27,28 @@ export const NOTIFICATION_HOLD_MS = 200;
 export interface OutboxMessage {
   content: string;
   details: NotificationDetails;
+  /** Agents whose whole result the content carries: sending it reads their result. */
+  delivered?: string[];
+  /** Agents whose whole result the content carries, failures included: the parent has seen it, though it stays unread in FleetView. */
+  noticed?: string[];
 }
 
 /**
  * A notification for one or more agents, built when they finished: a resume
  * before the send must not rewrite it. Reading an agent's result cancels its
- * id, and an item left with none is dropped; `build` gets the ids still pending.
+ * id, and an item left with none is dropped; `build` gets the ids still pending
+ * and the result length the batch allots each (see `notification-result.ts`).
  */
 export interface OutboxItem {
   ids: string[];
-  build(ids: readonly string[]): OutboxMessage;
+  /** Each agent's full result length, for the batch to split its budget by. */
+  resultChars?: Readonly<Record<string, number>>;
+  build(ids: readonly string[], caps: Readonly<Record<string, number>>): OutboxMessage;
 }
 
+/** Result length per agent of one batch, from each agent's full length. */
+export type ResultAllotment = (chars: Readonly<Record<string, number>>) => Record<string, number>;
+
 export class CompletionOutbox {
   private items: OutboxItem[] = [];
   private timer: TimerHandle | undefined;
@@ -50,6 +60,8 @@ export class CompletionOutbox {
     private parentRunning: () => boolean,
     /** Shared with the scheduler by hosts that control time in-process. */
     private clock: Clock = realClock,
+    /** Splits a batch's result budget; by default nothing is allotted and each item keeps its own cap. */
+    private allot: ResultAllotment = () => ({}),
   ) {}
 
   /** A newer completion of the same agent (a resume) replaces its pending one. */
@@ -101,7 +113,10 @@ export class CompletionOutbox {
     this.timer = undefined;
     const items = this.items;
     this.items = [];
-    const messages = items.map(item => item.build(item.ids));
+    const chars: Record<string, number> = {};
+    for (const item of items) for (const id of item.ids) if (item.resultChars?.[id] !== undefined) chars[id] = item.resultChars[id];
+    const caps = this.allot(chars);
+    const messages = items.map(item => item.build(item.ids, caps));
     return messages.length > 0 ? combine(messages) : undefined;
   }
 
@@ -118,8 +133,12 @@ export class CompletionOutbox {
 function combine(messages: OutboxMessage[]): OutboxMessage {
   if (messages.length === 1) return messages[0];
   const [first, ...rest] = messages.flatMap(({ details: { others, ...own } }) => [own, ...(others ?? [])]);
+  const delivered = messages.flatMap(m => m.delivered ?? []);
+  const noticed = messages.flatMap(m => m.noticed ?? []);
   return {
     content: `${messages.length} background tasks finished.\n\n${messages.map(m => m.content).join("\n\n")}`,
     details: { ...first, others: rest },
+    ...(delivered.length > 0 ? { delivered } : {}),
+    ...(noticed.length > 0 ? { noticed } : {}),
   };
 }

package/src/cross-extension-rpc.ts

@@ -16,6 +16,7 @@
 import { isTopLevelAgent } from "./agent-manager.js";
 import type { ModelRegistry } from "./model-resolver.js";
 import { selectModel } from "./model-selection.js";
+import { planSteerBlocked, planSteerRefusal } from "./plan-mode-children.js";
 import type { AgentRecord } from "./types.js";
 
 /** Minimal event bus interface needed by the RPC handlers. */
@@ -39,11 +40,11 @@ export interface SpawnCapable {
   awaitStartup(id: string): Promise<void>;
   abort(id: string): boolean;
   /**
-   * The record behind an id, for the stop handler's ownership check. Narrowed
-   * to the two fields `isTopLevelAgent` reads, so the RPC layer keeps its
-   * deliberately shallow view of the manager.
+   * The record behind an id, for the stop and steer handlers' ownership check
+   * and the steer handler's Plan check. Narrowed to the fields those read, so
+   * the RPC layer keeps its deliberately shallow view of the manager.
    */
-  getRecord(id: string): Pick<AgentRecord, "parentAgentId" | "workflowId"> | undefined;
+  getRecord(id: string): Pick<AgentRecord, "parentAgentId" | "workflowId" | "status" | "planGate"> | undefined;
   /**
    * Mark a settled agent's result as read by the caller, suppressing the
    * completion notification — what `get_subagent_result` does when it returns
@@ -152,10 +153,11 @@ export function registerRpcHandlers(deps: RpcDeps): RpcHandle {
   // a live hole: no RPC hands out agent ids, so a caller has no ordinary way to
   // name one it does not own — but the guard is cheap and the id may leak some
   // other way. Same refuse-what-we-should-not-touch stance as `consume` below.
-  const assertOwned = (agentId: string): void => {
+  const assertOwned = (agentId: string) => {
     const record = manager.getRecord(agentId);
     if (!record) throw new Error("Agent not found");
     if (!isTopLevelAgent(record)) throw new Error("Agent is owned by another agent or workflow");
+    return record;
   };
 
   const unsubStop = handleRpc<{ requestId: string; agentId: string }>(
@@ -187,7 +189,9 @@ export function registerRpcHandlers(deps: RpcDeps): RpcHandle {
   const unsubSteer = handleRpc<{ requestId: string; agentId: string; message: unknown }>(
     events, "subagents:rpc:steer", ({ agentId, message }) => {
       if (typeof message !== "string" || message.trim().length === 0) throw new Error("Steer message must be a non-empty string");
-      assertOwned(agentId);
+      const record = assertOwned(agentId);
+      // Same refusal as `steer_subagent`, so another extension cannot steer a pre-Plan agent into edits.
+      if (planSteerBlocked(record, events)) throw new Error(planSteerRefusal(agentId));
       if (!manager.steer(agentId, message)) throw new Error("Agent is not running");
     },
   );

package/src/custom-agents.ts

@@ -6,6 +6,7 @@ import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { basename, join } from "node:path";
 import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
 import { BUILTIN_TOOL_NAMES } from "./agent-types.js";
+import { errorMessage } from "./error-message.js";
 import { resolveAgentDir } from "./home-paths.js";
 import {
   isPackageResourceExcluded,
@@ -290,7 +291,7 @@ function readAgentFile(path: string, strict: boolean): { frontmatter: Record<str
   try {
     return parseAgentFrontmatter<Record<string, unknown>>(readFileSync(path, "utf-8"));
   } catch (err) {
-    const reason = err instanceof Error ? err.message : String(err);
+    const reason = errorMessage(err);
     if (strict) throw new Error(`${path}: ${reason}`);
     warnIfNew(`Skipping agent file ${path}: ${reason}`);
     return undefined;