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

package/src/index.ts

@@ -4,7 +4,8 @@
  * Tools:
  *   Agent             — LLM-callable: spawn a sub-agent
  *   get_subagent_result  — LLM-callable: check background agent status/result
- *   steer_subagent       — LLM-callable: send a steering message to a running agent
+ *   steer_subagent       — LLM-callable: steer a running agent, or resume a finished one
+ *   stop_subagent        — LLM-callable: stop a running or queued agent, or a workflow run
  *
  * Commands:
  *   /agents                 — Interactive agent management menu
@@ -19,7 +20,7 @@ import { Type } from "typebox";
 import { abortable } from "./abortable.js";
 import { hasAgentBadge, renderAgentName } from "./agent-color.js";
 import { buildNewAgentFile, disableInContent, enableInContent, isEmptyStub, locateAgentFile as locateAgentFileAtHome, personalAgentsDir as personalAgentsDirAtHome, projectAgentsDir, serializeAgentFile } from "./agent-file-toggle.js";
-import { AgentManager, describeEvicted, isTopLevelAgent, markConsumed } from "./agent-manager.js";
+import { AgentManager, describeEvicted, isTopLevelAgent, markConsumed, type OwnedPending } from "./agent-manager.js";
 import { getAgentConversation, getDefaultMaxTurns, getGraceTurns, getRememberAgents, normalizeMaxTurns, resolveEffectiveMaxTurns, SUBAGENT_TOOL_NAMES, setDefaultMaxTurns, setGraceTurns, setRememberAgents, steerAgent } from "./agent-runner.js";
 import { rowDescription, sourceIndicator, sourceLegend } from "./agent-source-badge.js";
 import { BUILTIN_TOOL_NAMES, getAgentConfig, getAllTypes, getAvailableTypes, getConfig, getFallbackSubagent, isDefaultsDisabled, NO_FALLBACK, registerAgents, resolveSpawnType, resolveType, setDefaultsDisabled, setFallbackSubagent } from "./agent-types.js";
@@ -31,6 +32,7 @@ import { loadCustomAgents } from "./custom-agents.js";
 import {
   type DetachedResult,
   drainDetached,
+  listAllRunningDetached,
   listRunningDetached,
   registerRunningDetached,
   spoolDetached,
@@ -38,27 +40,30 @@ import {
   watchDetached,
 } from "./detached-results.js";
 import { readEnabledModels, resolveEnabledModels } from "./enabled-models.js";
+import { errorMessage } from "./error-message.js";
 import { GroupJoinManager } from "./group-join.js";
 import { resolveAgentDir } from "./home-paths.js";
-import { cwdParam, isolationParam, resolveAgentInvocationConfig, resolveCwdParam, resolveJoinMode } from "./invocation-config.js";
+import { cwdParam, isolationParam, resolveAgentInvocationConfig, resolveCwdParam } from "./invocation-config.js";
 import { describeMention, handleBase, isReservedHandle, parseMention, resolveHandleToType, stripAgentPrefix } from "./mention.js";
 import { runMentionClone } from "./mention-clone.js";
 import { applyModelCallEvent, type ModelCallEvent } from "./model-call.js";
 import { type ModelFallback, type ModelRegistry, setAgentModels, setModelAliases, setModelScopeProvider } from "./model-resolver.js";
 import { isScopeModelsEnabled, setScopeModelsEnabled } from "./model-scope.js";
-import { admitModelSelection, describeSelection, modelRequest, modelSelectionNote, selectModel } from "./model-selection.js";
-import { tierDisclosure } from "./model-tiers.js";
+import { admitModelSelection, describeSelection, modelIdentityNote, modelRequest, modelSelectionNote, selectModel } from "./model-selection.js";
+import { configuredTierNames, tierDisclosure } from "./model-tiers.js";
 import { getMaxSubagentDepth, setMaxSubagentDepth } from "./nested-tools.js";
+import { clipNotice, DEFAULT_NOTIFICATION_RESULT_CHARS, fairShares, GROUP_PREVIEW_RESULT_CHARS, NOTIFICATION_RESULT_CHARS_CEILING, type NoticeFrame, type NoticeParts, PREVIEW_RESULT_CHARS, previewResult, renderNotice } from "./notification-result.js";
 import { appendModelFallbackEntry, appendModelTierEntry, createOutputFilePath, ensureOutputFile, getOutputTranscriptDefault, sessionTaskDir, setOutputTranscriptDefault, streamToOutputFile, writeInitialEntry } from "./output-file.js";
 import { getPackageAgentsGate, getPackageWorkflowsGate, invalidatePackageCache, isProjectTrusted, packageNameForPath, setPackageAgentsGate, setPackageWorkflowsGate, setProjectTrusted } from "./package-resources.js";
+import { answerPlanGateQueries, PLAN_PARK_REFUSAL, PLAN_SCHEDULE_REFUSAL, planningNow, planSteerBlocked, planSteerRefusal } from "./plan-mode-children.js";
 import { getBudgetPolicy, setBudgetPolicy } from "./process-budget.js";
 import { checkAdmission, describeBlock, mayPark, modelRef, QUOTA_RESTART_GRACE_MS } from "./quota-admission.js";
 import { SubagentScheduler } from "./schedule.js";
 import { resolveStorePath, ScheduleStore } from "./schedule-store.js";
 import { applyAndEmitLoaded, loadSettings, type SubagentsSettings, saveAndEmitChanged, type ToolDescriptionMode } from "./settings.js";
 import { hostStartupErrorClass } from "./startup-error.js";
-import { getForegroundOutcomeNote, getStatusNote, partialOutputSuffix } from "./status-note.js";
-import { type AgentConfig, type AgentInvocation, type AgentMentionMode, type AgentRecord, type JoinMode, type NotificationDetails, type SubagentType, type ViewerMarkdownMode, type WidgetMode } from "./types.js";
+import { getForegroundOutcomeNote, getStatusNote, partialOutputSuffix, resumeHint } from "./status-note.js";
+import { type AgentConfig, type AgentInvocation, type AgentMentionMode, type AgentRecord, type AgentTombstone, type JoinMode, type NotificationDetails, type SubagentType, type ViewerMarkdownMode, type WidgetMode } from "./types.js";
 import { createMentionProvider, mentionRoster, type TypeInfo } from "./ui/agent-mention.js";
 import { AgentCallView, AgentResultView, type AgentRowLive, keepRowTicking, keepTicking } from "./ui/agent-row.js";
 import {
@@ -115,7 +120,7 @@ function formatLifetimeTokens(o: { lifetimeUsage: LifetimeUsage }): string {
  * Create an AgentActivity state and spawn callbacks for tracking tool usage.
  * Used by both foreground and background paths to avoid duplication.
  */
-function createActivityTracker(maxTurns?: number, onStreamUpdate?: () => void, clock: Clock = realClock) {
+function createActivityTracker(maxTurns: number | undefined, onStreamUpdate: (() => void) | undefined, clock: Clock) {
   const state: AgentActivity = {
     activeTools: new Map(),
     toolUses: 0,
@@ -171,6 +176,11 @@ function createActivityTracker(maxTurns?: number, onStreamUpdate?: () => void, c
  */
 const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
 
+/** Run time of an agent: frozen at `completedAt` once settled, else measured to `now`. */
+function recordElapsedMs(record: { startedAt: number; completedAt?: number }, now: number): number {
+  return (record.completedAt ?? now) - record.startedAt;
+}
+
 /** Human-readable status label for agent completion. */
 function getStatusLabel(status: string, error?: string): string {
   switch (status) {
@@ -182,10 +192,13 @@ function getStatusLabel(status: string, error?: string): string {
   }
 }
 
-/** Format a structured task notification matching Claude Code's <task-notification> XML. */
-function formatTaskNotification(record: AgentRecord, resultMaxLen: number, showCost = false): string {
+/**
+ * Format a structured task notification matching Claude Code's <task-notification> XML.
+ * Everything but the `<result>` is read now; `renderNotice` fills that in.
+ */
+function formatTaskNotification(record: AgentRecord, showCost: boolean): NoticeFrame {
   const status = getStatusLabel(record.status, record.error);
-  const durationMs = record.completedAt ? record.completedAt - record.startedAt : 0;
+  const durationMs = recordElapsedMs(record, Date.now());
   const totalTokens = getLifetimeTotal(record.lifetimeUsage);
   const contextPercent = getSessionContextPercent(record.session);
   const ctxXml = contextPercent !== null ? `<context_percent>${Math.round(contextPercent)}</context_percent>` : "";
@@ -195,24 +208,29 @@ function formatTaskNotification(record: AgentRecord, resultMaxLen: number, showC
   const cost = showCost ? getLifetimeCost(record.lifetimeUsage) : 0;
   const costXml = cost > 0 ? `<estimated_cost_usd>${cost.toFixed(4)}</estimated_cost_usd>` : "";
 
-  const resultPreview = record.result
-    ? record.result.length > resultMaxLen
-      ? record.result.slice(0, resultMaxLen) + "\n...(truncated, use get_subagent_result for full output)"
-      : record.result
-    : "No output.";
+  const modelNote = [modelSelectionNote(record), modelIdentityNote(record)].filter(Boolean).join("\n");
+  const hint = resumeHint(record);
 
-  return [
+  const head = [
     `<task-notification>`,
     `<task-id>${record.id}</task-id>`,
     record.toolCallId ? `<tool-use-id>${escapeXml(record.toolCallId)}</tool-use-id>` : null,
     record.outputFile ? `<output-file>${escapeXml(record.outputFile)}</output-file>` : null,
     `<status>${escapeXml(status)}</status>`,
-    `<summary>Agent "${escapeXml(record.description)}" ${record.status}${getStatusNote(record.status)}</summary>`,
-    modelSelectionNote(record) ? `<model-note>${escapeXml(modelSelectionNote(record))}</model-note>` : null,
-    `<result>${escapeXml(resultPreview)}</result>`,
+    `<summary>Agent "${escapeXml(record.description)}" ${record.status}${getStatusNote(record.status, record.stoppedBy)}${hint ? ` (${hint})` : ""}</summary>`,
+    modelNote ? `<model-note>${escapeXml(modelNote)}</model-note>` : null,
+  ].filter(Boolean).join('\n');
+  const tail = [
     `<usage><total_tokens>${totalTokens}</total_tokens><tool_uses>${record.toolUses}</tool_uses>${ctxXml}${compactXml}${costXml}<duration_ms>${durationMs}</duration_ms></usage>`,
     `</task-notification>`,
-  ].filter(Boolean).join('\n');
+  ].join('\n');
+  return { head, tail };
+}
+
+/** What a full-result notice carries: the same text `get_subagent_result` returns for a finished agent. */
+function noticeBody(record: AgentRecord): string {
+  if (record.status === "error") return `Error: ${record.error ?? "unknown"}${partialOutputSuffix(record)}`;
+  return record.result?.trim() || "No output.";
 }
 
 /** Build AgentDetails from a base + record-specific fields. */
@@ -232,7 +250,7 @@ function buildDetails(
     cost: getLifetimeCost(record.lifetimeUsage),
     turnCount: activity?.turnCount,
     maxTurns: activity?.maxTurns,
-    durationMs: (record.completedAt ?? Date.now()) - record.startedAt,
+    durationMs: recordElapsedMs(record, Date.now()),
     status: record.status as AgentDetails["status"],
     agentId: record.id,
     error: record.error,
@@ -242,6 +260,31 @@ function buildDetails(
 }
 
 /** Build notification details for the custom message renderer. */
+
+/**
+ * The settle report for owned agents still pending, or `undefined` when none
+ * are. Every package's settle notice shares one shape,
+ * `Run ended with N <work>, armed: <what wakes the parent>`, and names only
+ * its own work, so one package saying nothing of its own is armed cannot read
+ * as "nothing at all is armed" beside another's armed monitor.
+ *
+ * A background agent's completion notice starts a parent turn in every join
+ * mode. Two edges qualify that: after a session switch the notice is spooled
+ * for the session it belongs to and lands when that session is live again, and
+ * a held send that outlives a tearing-down `pi -p` is dropped. Foreground
+ * agents and RPC spawns without `isBackground` are marked consumed at settle
+ * and notify nobody, so they are named as not armed.
+ */
+function formatOwnedPendingNotice({ notifying, silent }: OwnedPending): string | undefined {
+  const total = notifying + silent;
+  if (total === 0) return undefined;
+  const plural = (n: number) => (n === 1 ? "" : "s");
+  const armed = notifying > 0
+    ? `${notifying} agent completion notice${plural(notifying)} ${notifying === 1 ? "wakes" : "wake"} the parent`
+    : "no agent completion notice wakes the parent";
+  const unarmed = silent > 0 ? `; ${silent} foreground or RPC-spawned agent${plural(silent)} will not` : "";
+  return `Run ended with ${total} agent${plural(total)} running or queued, armed: ${armed}${unarmed}`;
+}
 function buildNotificationDetails(record: AgentRecord, resultMaxLen: number, activity?: AgentActivity): NotificationDetails {
   const totalTokens = getLifetimeTotal(record.lifetimeUsage);
 
@@ -257,9 +300,10 @@ function buildNotificationDetails(record: AgentRecord, resultMaxLen: number, act
     // data, and a notification rendered before a mid-session toggle should not
     // be stuck with the old answer.
     totalCost: getLifetimeCost(record.lifetimeUsage),
-    durationMs: record.completedAt ? record.completedAt - record.startedAt : 0,
+    durationMs: recordElapsedMs(record, Date.now()),
     outputFile: record.outputFile,
     error: record.error,
+    resumeHint: resumeHint(record) || undefined,
     modelNote: modelSelectionNote(record) || undefined,
     modelTier: record.modelTier,
     resultPreview: record.result
@@ -364,7 +408,7 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
   try {
     getBudgetPolicy();
   } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
+    const message = errorMessage(error);
     if (!StartupError) throw new Error(message + " This host also lacks ExtensionStartupError; upgrade pi before retrying.", { cause: error });
     pi.on("session_start", async () => { throw new StartupError(message, { cause: error }); });
     return;
@@ -402,7 +446,11 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
   });
 
   // Fuzzy model names ("opus") prefer what the user enabled in pi's settings.
-  setModelScopeProvider(registry => resolveEnabledModels(readEnabledModels(process.cwd(), options.homeDir), registry, process.cwd(), options.homeDir));
+  setModelScopeProvider((registry, context) => {
+    const cwd = context?.cwd ?? process.cwd();
+    const homeDir = context?.homeDir ?? options.homeDir;
+    return resolveEnabledModels(readEnabledModels(cwd, homeDir), registry, cwd, homeDir);
+  });
 
   // Read directly rather than waiting for applyAndEmitLoaded below: these decide
   // the initial load, which happens hundreds of lines before settings are applied.
@@ -483,6 +531,8 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
     persistSettings(ctx, `Viewer markdown set to ${mode}`);
   }
   const pendingUsage = new PendingUsagePool();
+  /** Result characters a completion notice carries per agent; `0` keeps the preview (see notification-result.ts). */
+  let notificationResultChars = DEFAULT_NOTIFICATION_RESULT_CHARS;
 
   // ---- Completion delivery ----
   // Every completion notification goes through the outbox, which sends what is
@@ -490,15 +540,62 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
   // completion-outbox.ts). Each is built when the agent finishes, and reading
   // the result (get_subagent_result, rpc consume) cancels it before it is sent.
   const outbox = new CompletionOutbox(
-    (message) => pi.sendMessage<NotificationDetails>({
-      customType: "subagent-notification",
-      content: message.content,
-      display: true,
-      details: message.details,
-    }, { deliverAs: "steer", triggerTurn: true }),
+    (message) => {
+      pi.sendMessage<NotificationDetails>({
+        customType: "subagent-notification",
+        content: message.content,
+        display: true,
+        details: message.details,
+      }, { deliverAs: "steer", triggerTurn: true });
+      for (const id of message.noticed ?? []) {
+        const record = manager.getRecord(id);
+        // A resume started since: that run's notice says nothing about this one.
+        if (record && record.status !== "running" && record.status !== "queued") record.noticeDelivered = true;
+      }
+      // The whole result reached the parent, as get_subagent_result would hand it over.
+      for (const id of message.delivered ?? []) {
+        const record = manager.getRecord(id);
+        // A resume started since: that run's result is still unread.
+        if (!record || record.status === "running" || record.status === "queued") continue;
+        markConsumed(record, clock.now());
+      }
+    },
     () => currentCtx?.signal !== undefined,
     options.clock,
+    (chars) => {
+      if (notificationResultChars === 0) return {};
+      const ids = Object.keys(chars);
+      const shares = fairShares(ids.map(id => chars[id]), notificationResultChars);
+      return Object.fromEntries(ids.map((id, i) => [id, shares[i]]));
+    },
   );
+
+  /**
+   * `record`'s notice, read now so a resume before the send cannot rewrite it.
+   * `render` fills in the result clipped to the share the batch allots it, or
+   * the `notificationResultChars: 0` preview of `previewChars`.
+   */
+  function snapshotNotice(record: AgentRecord, previewChars: number) {
+    const frame = formatTaskNotification(record, showCost);
+    const details = buildNotificationDetails(record, previewChars, agentActivity.get(record.id));
+    if (notificationResultChars === 0) {
+      // A preview never counts as the whole result, even a short one: reap notices stay on.
+      const text = renderNotice(frame, record.result ? previewResult(record.result, previewChars) : "No output.");
+      return { id: record.id, details, chars: undefined, parts: undefined, render: (_share?: number) => ({ text, delivered: false, complete: false }) };
+    }
+    const parts: NoticeParts = {
+      ...frame, body: noticeBody(record), cap: notificationResultChars, outputFile: record.outputFile,
+      // A failure stays unread: delivering its notice must not acknowledge it in FleetView (README, FleetView).
+      failed: record.status === "error" || record.status === "aborted",
+    };
+    return { id: record.id, details, chars: parts.body.length, parts, render: (share?: number) => clipNotice(parts, share) };
+  }
+
+  /** Full result lengths of the notices that have one, for the batch budget. */
+  function resultCharsOf(notices: readonly ReturnType<typeof snapshotNotice>[]): Record<string, number> | undefined {
+    const withChars = notices.filter(n => n.chars !== undefined);
+    return withChars.length > 0 ? Object.fromEntries(withChars.map(n => [n.id, n.chars])) : undefined;
+  }
   // A queued result wait must observe completion before its held notification
   // can fire, so successful waits can still suppress that redundant nudge.
   const QUEUE_WAIT_POLL_MS = Math.floor(NOTIFICATION_HOLD_MS / 4);
@@ -511,11 +608,19 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
     // cannot be formatted is skipped, as a failed send always was.
     try {
       const footer = record.outputFile ? `\nFull transcript available at: ${record.outputFile}` : '';
-      const message = {
-        content: formatTaskNotification(record, 500, showCost) + footer,
-        details: buildNotificationDetails(record, 500, agentActivity.get(record.id)),
-      };
-      outbox.add({ ids: [record.id], build: () => message });
+      const notice = snapshotNotice(record, PREVIEW_RESULT_CHARS);
+      outbox.add({
+        ids: [record.id],
+        resultChars: resultCharsOf([notice]),
+        build: (_ids, caps) => {
+          const { text, delivered, complete } = notice.render(caps[notice.id]);
+          return {
+            content: text + footer, details: notice.details,
+            ...(delivered ? { delivered: [notice.id] } : {}),
+            ...(complete ? { noticed: [notice.id] } : {}),
+          };
+        },
+      });
     } catch { /* ignore stale completion side-effect errors */ }
     widget.update();
   }
@@ -527,15 +632,21 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
 
       const members = records.filter(r => !r.resultConsumed).flatMap(r => {
         try {
-          return [{ id: r.id, text: formatTaskNotification(r, 300, showCost), details: buildNotificationDetails(r, 300, agentActivity.get(r.id)) }];
+          return [snapshotNotice(r, GROUP_PREVIEW_RESULT_CHARS)];
         } catch { return []; /* as in sendIndividualNudge */ }
       });
+      // Only the preview needs the pointer; a clipped full result carries its own.
+      const trailer = notificationResultChars === 0 ? "\n\nUse get_subagent_result for full output." : "";
       if (members.length > 0) {
         outbox.add({
           ids: members.map(m => m.id),
-          build: (ids) => {
+          resultChars: resultCharsOf(members),
+          build: (ids, caps) => {
             const unread = members.filter(m => ids.includes(m.id));
-            const notifications = unread.map(m => m.text).join('\n\n');
+            const rendered = unread.map(m => ({ id: m.id, ...m.render(caps[m.id]) }));
+            const notifications = rendered.map(m => m.text).join('\n\n');
+            const delivered = rendered.filter(m => m.delivered).map(m => m.id);
+            const noticed = rendered.filter(m => m.complete).map(m => m.id);
             const label = partial
               ? `${unread.length} agent(s) finished (partial — others still running)`
               : `${unread.length} agent(s) finished`;
@@ -544,8 +655,10 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
             const details = first.details;
             if (rest.length > 0) details.others = rest.map(m => m.details);
             return {
-              content: `Background agent group completed: ${label}\n\n${notifications}\n\nUse get_subagent_result for full output.`,
+              content: `Background agent group completed: ${label}\n\n${notifications}${trailer}`,
               details,
+              ...(delivered.length > 0 ? { delivered } : {}),
+              ...(noticed.length > 0 ? { noticed } : {}),
             };
           },
         });
@@ -557,7 +670,7 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
 
   /** Helper: build event data for lifecycle events from an AgentRecord. */
   function buildEventData(record: AgentRecord) {
-    const durationMs = record.completedAt ? record.completedAt - record.startedAt : Date.now() - record.startedAt;
+    const durationMs = recordElapsedMs(record, Date.now());
     // All three fields are lifetime-accumulated (Σ over every assistant message_end),
     // so they survive compaction together — input + output ≤ total always.
     // tokens is omitted when nothing was ever produced (e.g. agent errored before
@@ -583,6 +696,7 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
       id: record.id,
       type: record.type,
       description: record.description,
+      ...eventFields(record),
       result: record.result,
       error: record.error,
       status: record.status,
@@ -590,8 +704,8 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
       durationMs,
       tokens,
       usage,
-      // Present only on a fallback, so the payload keeps its shape otherwise.
-      ...fallbackFields(record),
+      // Stamped by the only caller, the settle path, just before this runs.
+      settleSeq: record.settleSeq,
     };
   }
 
@@ -601,6 +715,30 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
    */
   let detachedSessionFile: string | undefined;
 
+  /**
+   * Every lifecycle event's identity fields, then `fallbackFields`. `handle` (`explore-2`)
+   * and `spawnSeq` are always set: every caller announces a top-level agent, which the
+   * manager gives a handle, and the manager stamps `spawnSeq` on every record it creates.
+   * `name` (the handle drawn from the spawner's `name`, `auth-audit-2`), `nameBase` (that
+   * name before collision numbering, `auth-audit`) and `previousId` (the evicted id a
+   * reopen continues) are each omitted when absent, so a listener such as pi-todo can
+   * match an agent by what the parent typed, not only its id. `spawnSeq` orders the spawn
+   * against other spawns and `settleSeq`s, queued time included.
+   */
+  const lifecycleRuns = new WeakMap<AgentRecord, number>();
+  function eventFields(record: AgentRecord | undefined): Record<string, unknown> {
+    return {
+      handle: record?.handle,
+      ...(record?.alias ? { name: record.alias } : {}),
+      ...(record?.nameBase ? { nameBase: record.nameBase } : {}),
+      ...(record?.previousId ? { previousId: record.previousId } : {}),
+      spawnSeq: record?.spawnSeq,
+      ...(record && lifecycleRuns.has(record) ? { runSeq: lifecycleRuns.get(record) } : {}),
+      wakesParent: record?.isBackground === true,
+      ...fallbackFields(record),
+    };
+  }
+
   /** `modelFallback` + `modelNote` event fields, or nothing. Only what is KNOWN when the event fires. */
   function fallbackFields(record: AgentRecord | undefined): Record<string, unknown> {
     return {
@@ -621,15 +759,40 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
     };
   }
 
+  /**
+   * A survivor's lifecycle payload for a session that never heard its spawn: the
+   * orphaned manager's own `spawnSeq`/`runSeq`/`settleSeq` count a different sequence
+   * than this one, so they are dropped rather than compared. Only background runs
+   * survive a switch (`AgentManager.detach`), so `wakesParent` is already true.
+   */
+  function survivorEventData(data: Record<string, unknown>): Record<string, unknown> {
+    const { spawnSeq: _spawn, runSeq: _run, settleSeq: _settle, ...rest } = data;
+    return rest;
+  }
+
+  /** The terminal lifecycle channel for a settled record; shared by the live and the detached path. */
+  function lifecycleChannel(record: AgentRecord): "subagents:failed" | "subagents:completed" {
+    return record.status === "error" || record.status === "stopped" || record.status === "aborted"
+      ? "subagents:failed" : "subagents:completed";
+  }
+
   function spoolDetachedResult(sessionFile: string, record: AgentRecord) {
     if (record.resultConsumed) return;
     const footer = record.outputFile ? `\nFull transcript available at: ${record.outputFile}` : "";
     try {
+      const notice = snapshotNotice(record, PREVIEW_RESULT_CHARS);
       spoolDetached(sessionFile, {
         id: record.id,
-        content: formatTaskNotification(record, 500, showCost) + footer,
-        details: buildNotificationDetails(record, 500),
+        content: notice.render().text + footer,
+        details: notice.details,
         record: historyRecord(record),
+        evicted: manager.evictionNotes([record.id]),
+        tombstones: manager.evictionTombstones([record.id]),
+        lifecycle: {
+          channel: lifecycleChannel(record),
+          data: survivorEventData(buildEventData(record)),
+        },
+        ...(notice.parts ? { notice: { ...notice.parts, footer } } : {}),
       });
     } catch { /* spool unwritable: the transcript file still has the result */ }
   }
@@ -639,22 +802,62 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
     for (const result of drainDetached(sessionFile)) deliverDetachedResult(result);
   }
 
+  /**
+   * Announce every agent still running in an orphaned manager, which this session never
+   * heard spawn, so lifecycle listeners (e.g. pi-todo) see their owners alive instead of lost.
+   * Runs at every `session_start` and on `subagents:announce_survivors`, for a listener that
+   * bound after it. Survivors registered under the current session file are announced as
+   * `subagents:started` (armed: their results spool here and wake this session). All others,
+   * whatever switch left them (`/fork`, `/resume`, `/new`, `/reload`), are announced as
+   * `subagents:other_session_survivor` with the `sessionFile` they wake instead, and arm nothing here.
+   */
+  function announceSurvivors() {
+    const current = currentCtx?.sessionManager?.getSessionFile?.();
+    for (const { sessionFile, agent } of listAllRunningDetached()) {
+      const { record } = agent;
+      const own = sessionFile === current;
+      const { wakesParent: _wakes, ...fields } = eventFields(record);
+      pi.events.emit(own ? "subagents:started" : "subagents:other_session_survivor", survivorEventData({
+        id: record.id,
+        type: record.type,
+        description: record.description,
+        ...fields,
+        ...(own ? { wakesParent: true } : { sessionFile }),
+      }));
+    }
+  }
+
   function deliverDetachedResult(result: DetachedResult) {
     try {
+      // First: the notice names this id, and a read of it must not say "not found".
+      for (const note of result.evicted ?? []) manager.rememberEvicted(note);
+      for (const entry of result.tombstones ?? []) manager.rememberTombstone(entry);
+      // Before the notice: a listener must see the owner settle, not stay "running".
+      if (result.lifecycle) pi.events.emit(result.lifecycle.channel, result.lifecycle.data);
       if (result.record) {
         pi.appendEntry("subagents:record", result.record);
         fleet.ingestFailure(result.record);
         fleet.update();
       }
       const details = result.details as NotificationDetails;
+      // Re-clipped here, so it shares the budget of whatever lands with it. Its
+      // record lives in the orphaned manager, so nothing is marked read.
+      const notice = typeof result.notice?.body === "string" ? result.notice : undefined;
       outbox.add({
         ids: [details.id, ...(details.others?.map(other => other.id) ?? [])],
-        build: () => ({ content: result.content, details }),
+        ...(notice ? { resultChars: { [details.id]: notice.body.length } } : {}),
+        build: (_ids, caps) => notice
+          ? { content: clipNotice(notice, caps[details.id]).text + notice.footer, details }
+          : { content: result.content, details },
       });
     } catch { /* session already gone again; the transcript file still has the result */ }
   }
 
   let unwatchDetached: (() => void) | undefined;
+  let unwatchAnnounce: (() => void) | undefined;
+
+  // At load, before pi-plan-mode's session_start ask: Plan admits `Agent` only with this gate (#437).
+  answerPlanGateQueries(pi.events);
 
   // Background completion: route through group join or send individual nudge
   const manager = new AgentManager((record) => {
@@ -674,13 +877,8 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
 
     if (!record.resultConsumed) fleet.ingestFailure(record);
     // Emit lifecycle event based on terminal status
-    const isError = record.status === "error" || record.status === "stopped" || record.status === "aborted";
-    const eventData = buildEventData(record);
-    if (isError) {
-      pi.events.emit("subagents:failed", eventData);
-    } else {
-      pi.events.emit("subagents:completed", eventData);
-    }
+    record.settleSeq = manager.nextSequence();
+    pi.events.emit(lifecycleChannel(record), buildEventData(record));
 
     // Persist final record for cross-extension history reconstruction
     pi.appendEntry("subagents:record", historyRecord(record));
@@ -718,12 +916,14 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
       fleet.ensureTimer();
       fleet.update();
     }
+    // Bind later handoff announcements to this exact run.
+    lifecycleRuns.set(record, manager.nextSequence());
     // Emit started event when agent transitions to running (including from queue)
     pi.events.emit("subagents:started", {
       id: record.id,
       type: record.type,
       description: record.description,
-      ...fallbackFields(record),
+      ...eventFields(record),
     });
   }, (record, info) => {
     if (!isTopLevelAgent(record)) return;
@@ -735,7 +935,7 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
       reason: info.reason,
       tokensBefore: info.tokensBefore,
       compactionCount: record.compactionCount,
-      ...fallbackFields(record),
+      ...eventFields(record),
     });
   }, (record, usage) => {
     // Every assistant message from every agent — nested included, exactly once.
@@ -772,7 +972,7 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
       // can show `low (asked minimal)` instead of silently relabelling.
       ...(invocation?.requestedThinking !== undefined ? { requestedThinking: invocation.requestedThinking } : {}),
       ...fallbackFields(record),
-      depth: record.depth ?? 1,
+      depth: record.depth,
       ...(record.parentAgentId !== undefined ? { parentAgentId: record.parentAgentId } : {}),
       ...(record.workflowId !== undefined ? { workflowId: record.workflowId } : {}),
       usage: reported,
@@ -780,7 +980,26 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
   }, (record, message) => {
     if (!isTopLevelAgent(record)) return;
     pi.events.emit("subagents:steered", { id: record.id, message });
-  }, clock, options.homeDir);
+  }, clock, options.homeDir, (record) => {
+    // Stopped before it ever started: no result and no notice, but a listener that heard
+    // `subagents:created` must still see it end. Same payload as a settled stop.
+    if (!isTopLevelAgent(record) || detachedSessionFile !== undefined) return;
+    record.settleSeq = manager.nextSequence();
+    pi.events.emit("subagents:failed", buildEventData(record));
+  }, (note) => {
+    // The retention sweep dropped a result nobody read: say so now, where the parent sees it on
+    // its next turn, instead of leaving `Agent not found` to be discovered by a later lookup (#330).
+    pi.sendMessage({
+      customType: "subagent-reaped",
+      content: `${describeEvicted(note)}. Its result was never read and its record is gone; reopen it with steer_subagent or Agent resume if its session is still saved.`,
+      display: true,
+    }, { deliverAs: "nextTurn" });
+  });
+
+  // A live survivor of an orphaned manager keeps its handle: reusing it would make a lifecycle listener
+  // that keys by handle read this manager's newer agent and the survivor as one.
+  manager.reservedHandles = () =>
+    listAllRunningDetached().flatMap(({ agent }) => [agent.record.handle, agent.record.alias].filter((h): h is string => !!h));
 
   // Expose manager via Symbol.for() global registry for cross-package access.
   // Standard Node.js pattern for cross-package singletons (used by OpenTelemetry, etc.).
@@ -851,6 +1070,8 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
     // Bypasses handle allocation, so a forged value would duplicate a live
     // agent's name and make `@handle` ambiguous. Same rule: dispatcher only.
     delete safeOptions.reclaim;
+    // Would make the new agent claim an evicted agent's id on lifecycle events.
+    delete safeOptions.previousId;
     // Every spawn through here is DETACHED — the caller gets an id back and
     // awaits nothing. A forged `blocking` would charge it to the foreground
     // pool and could defer it behind a queue whose gate nobody is holding.
@@ -876,7 +1097,12 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
     const byId = manager.getRecord(ref);
     if (byId) return byId;
     const resolved = manager.resolveMention(ref);
-    return resolved?.kind === "live" ? resolved.record : undefined;
+    if (resolved?.kind === "live") return resolved.record;
+    // Survivors of a /reload, /new or /resume live in the orphaned manager, so
+    // this fresh one has never heard of them (#330). Same live records, so
+    // reading and steering them work unchanged.
+    const survivors = listRunningDetached(currentCtx?.sessionManager?.getSessionFile?.()).map(d => d.record);
+    return survivors.find(r => r.id === ref) ?? survivors.find(r => r.handle === ref || r.alias === ref);
   };
 
   const registryEntry = {
@@ -949,7 +1175,7 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
       reloadCustomAgents(strictLoad);
     } catch (err) {
       if (strictLoad && StartupError) {
-        throw new StartupError(err instanceof Error ? err.message : String(err), { cause: err });
+        throw new StartupError(errorMessage(err), { cause: err });
       }
       throw err;
     }
@@ -970,6 +1196,8 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
       unwatchDetached = watchDetached(sessionFile, () => deliverDetached(sessionFile));
       deliverDetached(sessionFile);
     }
+    announceSurvivors();
+    unwatchAnnounce ??= pi.events.on("subagents:announce_survivors", announceSurvivors);
     // Orphans from the previous instance are already registered; show them now.
     fleet.update();
     // Guard mirrors the `!scheduler.isActive()` pattern below: session_start
@@ -1035,7 +1263,7 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
 
   /** Agent types `@` can start, in the shape the roster wants. */
   const mentionTypes = (): TypeInfo[] =>
-    getAvailableTypes().map(name => ({ name, description: getAgentConfig(name)?.description ?? name }));
+    getAvailableTypes().map(name => ({ name, description: getAgentConfig(name)!.description }));
 
   /**
    * `@handle message` typed at the prompt addresses that agent instead of the
@@ -1134,65 +1362,9 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
     if (resolved?.kind === "tombstone") {
       const entry = resolved.entry;
       const target = `@${entry.alias ?? entry.handle}`;
-
-      // Checked here rather than left to SessionManager.open: that runs inside
-      // runAgent, whose rejection lands on the record as an agent error, not in
-      // the catch below. A `/new` in another pi window or a manual delete makes
-      // the conversation unrecoverable (Claude Code's `not_reachable`), so drop
-      // the entry — a row that can only ever fail is worse than none — and say
-      // so rather than quietly sending this message to an unrelated agent.
-      if (!existsSync(entry.sessionFile)) {
-        manager.dropTombstone(entry.handle);
-        ctx.ui.notify(`Could not resume ${target} — its session is gone.`, "warning");
-        return { action: "handled" };
-      }
-
-      // The Agent tool deliberately falls back to general-purpose for a type it
-      // cannot resolve (#183), which covers a deleted file AND a merely
-      // disabled one. A resume must not inherit that: reopening this
-      // conversation under a different agent's prompt and tools is not
-      // continuing it, and the new record would re-tombstone under the
-      // substitute, so the handle would never find its way back.
-      reloadCustomAgents();
-      const dispatch = resolveSpawnType(entry.type);
-      if (!dispatch.ok || dispatch.fellBackFrom !== undefined) {
-        // The tombstone stays: re-enabling the agent makes the handle work
-        // again, which a drop would foreclose.
-        ctx.ui.notify(`Could not resume ${target} — the ${entry.type} agent is no longer available.`, "warning");
-        return { action: "handled" };
-      }
-
-      try {
-        // spawnResolved, not spawnTopLevel: the latter strips
-        // `resumeSessionFile` and `reclaim` as untrusted. This path is the
-        // exception — both come from a tombstone this extension wrote.
-        const id = spawnResolved(pi, ctx, dispatch.type, mention.message, {
-          description: entry.description,
-          reclaim: { handle: entry.handle, alias: entry.alias },
-          resumeSessionFile: entry.sessionFile,
-          // Historical disclosures never replace the continuation's current selection.
-          ...(entry.modelFallback ? { previousModelFallback: entry.modelFallback } : {}),
-          ...(entry.modelTier ? { previousModelTier: entry.modelTier } : {}),
-          isBackground: true,
-        });
-        // The agent may still be starting — wait, so a startup failure lands in
-        // the catch below instead of being announced as a resume.
-        await manager.awaitStartup(id);
-        // The tombstone deliberately stays. `resolveMention` prefers the live
-        // record holding these same names, so it cannot shadow the resume — and
-        // if this run dies before establishing its own session, the original
-        // transcript is still the right thing for the next mention to reopen.
-        // Once the resumed record is evicted it overwrites this entry in place,
-        // keyed by the same handle, so nothing accumulates.
-        ctx.ui.notify(`Resuming ${target}`, "info");
-      } catch (err) {
-        // The type is already settled above, so what is left is a spawn-time
-        // failure: a strict worktree-isolation error, an unusable cwd.
-        ctx.ui.notify(
-          `Could not resume ${target}: ${err instanceof Error ? err.message : String(err)}`,
-          "warning",
-        );
-      }
+      const reopened = await reopenEvicted(ctx, entry, mention.message);
+      if (reopened.ok) ctx.ui.notify(`Resuming ${target}`, "info");
+      else ctx.ui.notify(couldNotResume(target, reopened.failure), "warning");
       return { action: "handled" };
     }
 
@@ -1243,7 +1415,7 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
             ctx.ui.notify(`Started ${label} directly — ${result.error}`, "warning");
           } catch (err) {
             ctx.ui.notify(
-              `Could not start ${label}: ${err instanceof Error ? err.message : String(err)}`,
+              `Could not start ${label}: ${errorMessage(err)}`,
               "error",
             );
           }
@@ -1267,7 +1439,7 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
       await manager.awaitStartup(id);
       ctx.ui.notify(`Started @${handleBase(type)}`, "info");
     } catch (err) {
-      ctx.ui.notify(`Could not start @${handleBase(type)}: ${err instanceof Error ? err.message : String(err)}`, "error");
+      ctx.ui.notify(`Could not start @${handleBase(type)}: ${errorMessage(err)}`, "error");
     }
     return { action: "handled" };
   });
@@ -1288,6 +1460,8 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
     const sessionFile = currentCtx?.sessionManager?.getSessionFile?.();
     unwatchDetached?.();
     unwatchDetached = undefined;
+    unwatchAnnounce?.();
+    unwatchAnnounce = undefined;
     rpcHandle?.unsubSpawn();
     rpcHandle?.unsubStop();
     rpcHandle?.unsubPing();
@@ -1318,7 +1492,12 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
       }
       const pending = outbox.takePending();
       if (pending) {
-        try { spoolDetached(sessionFile, { id: nanoid(8), ...pending }); }
+        // Not sent here: the session that reads the spool is the one that sees it.
+        const { delivered: _unsent, noticed: _unseen, ...spooled } = pending;
+        const heldIds = [pending.details.id, ...(pending.details.others?.map(other => other.id) ?? [])];
+        const evicted = manager.evictionNotes(heldIds);
+        const tombstones = manager.evictionTombstones(heldIds);
+        try { spoolDetached(sessionFile, { id: nanoid(8), ...spooled, evicted, tombstones }); }
         catch { console.error("[pi-subagents] Could not spool held completion notices; results remain in their transcripts."); }
       }
     }
@@ -1350,7 +1529,7 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
         registerRunningDetached(sessionFile, {
           record,
           activity: agentActivity.get(record.id),
-          abort: () => manager.abort(record.id),
+          abort: (by) => manager.abort(record.id, by),
           steer: (message) => manager.steer(record.id, message),
         });
       }
@@ -1400,17 +1579,17 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
       wake();
       sent++;
       // It is a background agent from here on, so announce it as one — as a
-      // detached resume re-announces an existing id.
-      const record = manager.getRecord(id);
-      if (record) {
-        pi.events.emit("subagents:created", {
-          id,
-          type: record.type,
-          description: record.description,
-          isBackground: true,
-          ...fallbackFields(record),
-        });
-      }
+      // detached resume re-announces an existing id. `sendToBackground` only
+      // hands off a record it holds.
+      const record = manager.getRecord(id)!;
+      pi.events.emit("subagents:created", {
+        id,
+        type: record.type,
+        description: record.description,
+        isBackground: true,
+        backgroundHandoff: true,
+        ...eventFields(record),
+      });
     }
     if (sent > 0) {
       widget.ensureTimer();
@@ -1474,6 +1653,7 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
     // Agents the previous instance of this session left running (/reload, /new, ...).
     () => listRunningDetached(currentCtx?.sessionManager?.getSessionFile?.()), clock);
   fleet.setParkedSource(() => scheduler.list().filter(job => job.enabled && job.quotaParked && job.lastStatus !== "running").length);
+  fleet.setStopAll(stopAllRunning);
   /** Replay UI-only state from the active branch, like workflow/goal custom snapshots. */
   function restoreFleetDisclosure(ctx: ExtensionContext): void {
     fleet.restoreSession(() => ctx.sessionManager?.getBranch?.() ?? [], state => {
@@ -1624,6 +1804,100 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
     return getAgentConfig(record.type)?.maxTurns ?? explicit ?? record.invocation?.maxTurns ?? getDefaultMaxTurns();
   }
 
+  /** Why `reopenEvicted` did not reopen; `type-unavailable` keeps the tombstone, `session-gone` drops it. */
+  type ReopenFailure =
+    | { reason: "session-gone" }
+    | { reason: "type-unavailable"; type: string }
+    | { reason: "spawn-failed"; message: string };
+
+  /** The one wording both reopen callers use, `target` being `@handle` or `agent "<id>"`. */
+  function couldNotResume(target: string, failure: ReopenFailure): string {
+    switch (failure.reason) {
+      case "session-gone": return `Could not resume ${target} — its session is gone.`;
+      case "type-unavailable": return `Could not resume ${target} — the ${failure.type} agent is no longer available.`;
+      case "spawn-failed": return `Could not resume ${target}: ${failure.message}`;
+    }
+  }
+
+  /**
+   * Reopen an evicted agent's conversation from its session file. An ordinary
+   * spawn carrying that file, so the new record picks up the widget, fleet row,
+   * transcript and completion notification unchanged, and `reclaim` hands it
+   * back the names the tombstone was holding. Always detached.
+   *
+   * Shared by `@handle message` and the Agent tool's `resume` of an evicted id
+   * (#330); they differ only in how they report the outcome, see
+   * `couldNotResume`. The evicted id is linked to the new one before the first
+   * await, so a second resume of the old id in the same turn finds the live
+   * record instead of reopening the file twice.
+   */
+  async function reopenEvicted(
+    ctx: ExtensionContext,
+    entry: AgentTombstone,
+    prompt: string,
+    opts: { maxTurns?: number } = {},
+  ): Promise<{ ok: true; id: string } | { ok: false; failure: ReopenFailure }> {
+    // Checked here rather than left to SessionManager.open: that runs inside
+    // runAgent, whose rejection lands on the record as an agent error, not in
+    // the catch below. A `/new` in another pi window or a manual delete makes
+    // the conversation unrecoverable (Claude Code's `not_reachable`), so drop
+    // the entry — a row that can only ever fail is worse than none — and say
+    // so rather than quietly sending this message to an unrelated agent.
+    if (!existsSync(entry.sessionFile)) {
+      manager.dropTombstone(entry.handle);
+      return { ok: false, failure: { reason: "session-gone" } };
+    }
+
+    // The Agent tool deliberately falls back to general-purpose for a type it
+    // cannot resolve (#183), which covers a deleted file AND a merely
+    // disabled one. A resume must not inherit that: reopening this
+    // conversation under a different agent's prompt and tools is not
+    // continuing it, and the new record would re-tombstone under the
+    // substitute, so the handle would never find its way back.
+    reloadCustomAgents();
+    const dispatch = resolveSpawnType(entry.type);
+    if (!dispatch.ok || dispatch.fellBackFrom !== undefined) {
+      // The tombstone stays: re-enabling the agent makes the handle work
+      // again, which a drop would foreclose.
+      return { ok: false, failure: { reason: "type-unavailable", type: entry.type } };
+    }
+
+    let id: string | undefined;
+    try {
+      // spawnResolved, not spawnTopLevel: the latter strips
+      // `resumeSessionFile` and `reclaim` as untrusted. This path is the
+      // exception — both come from a tombstone this extension wrote.
+      id = spawnResolved(pi, ctx, dispatch.type, prompt, {
+        description: entry.description,
+        maxTurns: opts.maxTurns,
+        reclaim: { handle: entry.handle, alias: entry.alias },
+        previousId: entry.id,
+        resumeSessionFile: entry.sessionFile,
+        // Historical disclosures never replace the continuation's current selection.
+        ...(entry.modelFallback ? { previousModelFallback: entry.modelFallback } : {}),
+        ...(entry.modelTier ? { previousModelTier: entry.modelTier } : {}),
+        isBackground: true,
+      });
+      manager.linkSuccessor(entry.id, id);
+      // The agent may still be starting — wait, so a startup failure lands in
+      // the catch below instead of being announced as a resume.
+      await manager.awaitStartup(id);
+      // The tombstone deliberately stays. `resolveMention` prefers the live
+      // record holding these same names, so it cannot shadow the resume — and
+      // if this run dies before establishing its own session, the original
+      // transcript is still the right thing for the next mention to reopen.
+      // Once the resumed record is evicted it overwrites this entry in place,
+      // keyed by the same handle, so nothing accumulates.
+      return { ok: true, id };
+    } catch (err) {
+      // The type is already settled above, so what is left is a spawn-time
+      // failure: a strict worktree-isolation error, an unusable cwd.
+      // A run that never started is no successor: the old id reopens again next time.
+      if (id !== undefined) manager.unlinkSuccessor(entry.id);
+      return { ok: false, failure: { reason: "spawn-failed", message: errorMessage(err) } };
+    }
+  }
+
   /**
    * Launch a detached resume of an existing agent and wire everything a
    * re-running agent needs: transcript anchoring, activity tracking, join-mode
@@ -1643,13 +1917,16 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
     opts: { outputTranscript: boolean; maxTurns?: number; toolCallId?: string },
   ): Promise<AgentRecord | undefined> {
     const id = existing.id;
-    const joinMode = resolveJoinMode(defaultJoinMode, true);
+    const priorSettleSeq = existing.settleSeq;
+    const resumeSeq = manager.nextSequence();
+    // A resume always runs detached, and a detached run joins by the default mode.
+    const joinMode = defaultJoinMode;
     // Assigned unconditionally: the completion notification carries this as
     // `<tool-use-id>`, so a mention-resume (which passes none) has to CLEAR the
     // id left by the spawn that created the record. Keeping it would point the
     // orchestrator's new result at a tool call that was answered runs ago.
     existing.toolCallId = opts.toolCallId;
-    if (joinMode) existing.joinMode = joinMode;
+    existing.joinMode = joinMode;
     // Reuse the agent's transcript rather than starting a fresh one: the
     // path is deterministic per agent+session, so writing an initial entry
     // would truncate the previous run's turns (see ensureOutputFile).
@@ -1663,7 +1940,8 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
     // Anchor streaming past the turns already on disk, captured BEFORE the
     // run starts. The resumed prompt lands as an ordinary user message at
     // this index, so it is written exactly once.
-    const transcriptAnchor = existing.session?.messages.length ?? 0;
+    // Both callers resume only a record that still holds its session.
+    const transcriptAnchor = existing.session!.messages.length;
 
     const { state: bgState, callbacks: bgCallbacks } = createActivityTracker(normalizeMaxTurns(opts.maxTurns), undefined, clock);
     // resumeAgent has no onSessionCreated — the session predates this run —
@@ -1717,7 +1995,8 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
       type: existing.type,
       description: existing.description,
       isBackground: true,
-      ...fallbackFields(existing),
+      ...(record.status === "queued" && priorSettleSeq !== undefined ? { queuedAfterSettleSeq: priorSettleSeq, queuedResumeSeq: resumeSeq } : {}),
+      ...eventFields(existing),
     });
 
     return record;
@@ -1738,17 +2017,28 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
     outbox.onTurnEnd(event.message.role === "assistant" ? event.message.stopReason : undefined);
   });
   pi.on("agent_end", () => outbox.onAgentEnd());
-  pi.on("agent_settled", () => outbox.onAgentEnd());
+  pi.on("agent_settled", () => {
+    outbox.onAgentEnd();
+    // The run is over but owned agents are not: say so, and say what will
+    // wake the parent, instead of leaving a quiet prompt that looks like
+    // finished work. `currentCtx` is set at `session_start` and cleared only at
+    // `session_shutdown`, and pi settles a run only inside a live session, so
+    // it is defined here.
+    const pending = manager.ownedPending();
+    const message = formatOwnedPendingNotice(pending);
+    if (message) currentCtx?.ui.notify(message, pending.notifying > 0 ? "info" : "warning");
+  });
 
   /** Build the full type list text dynamically from available agents only. */
   const buildTypeListText = () => {
     const available = getAvailableTypes();
 
     return available.map((name) => {
-      const cfg = getAgentConfig(name);
-      const modelSuffix = cfg?.model ? ` (${getModelLabelFromConfig(cfg.model)})` : "";
+      // Every available type is registered, so its config exists.
+      const cfg = getAgentConfig(name)!;
+      const modelSuffix = cfg.model ? ` (${getModelLabelFromConfig(cfg.model)})` : "";
       const toolsSuffix = ` (Tools: ${formatToolsSuffix(cfg)})`;
-      return `- ${name}: ${cfg?.description ?? name}${modelSuffix}${toolsSuffix}`;
+      return `- ${name}: ${cfg.description}${modelSuffix}${toolsSuffix}`;
     }).join("\n");
   };
 
@@ -1761,8 +2051,8 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
   /** Compact type list: one line per agent, first sentence only. */
   const buildCompactTypeListText = () =>
     getAvailableTypes().map((name) => {
-      const cfg = getAgentConfig(name);
-      return `- ${name}: ${firstSentence(cfg?.description ?? name)} (Tools: ${formatToolsSuffix(cfg)})`;
+      const cfg = getAgentConfig(name)!;
+      return `- ${name}: ${firstSentence(cfg.description)} (Tools: ${formatToolsSuffix(cfg)})`;
     }).join("\n");
 
   /** Derive a short model label from a model string. */
@@ -1790,6 +2080,7 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
       setBudgetPolicy,
       setDefaultMaxTurns,
       setGraceTurns,
+      setNotificationResultChars: (n) => { notificationResultChars = n; },
       setDefaultJoinMode,
       setBackgroundByDefault,
       setSchedulingEnabled,
@@ -1852,13 +2143,35 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
   // With no per-result note by design, the model would have every reason to go
   // on reporting a `pi-agent-*` branch that was never created.
   const isolationGuideline = isWorktreeIsolationEnabled()
-    ? `\n- Use isolation: "worktree" to give the agent its own git worktree (safe parallel file modifications); leave it unset, or pass "off", for none. The worktree is removed when the agent finishes; if it made changes, they are committed to a branch and the branch is named in the result. The worktree is made from the repo containing \`cwd\` (default: the session cwd); when the target repo is not the session cwd, pass its path as \`cwd\`.`
+    ? `\n- Use isolation: "worktree" to give the agent its own git worktree (safe parallel file modifications); leave it unset, or pass "off", for none. The worktree is removed when the agent finishes unless cleanup fails (the result then names the retained path); if it made changes, they are committed to a branch and the branch is named in the result. The worktree is made from the repo containing \`cwd\` (default: the session cwd); when the target repo is not the session cwd, pass its path as \`cwd\`.`
     : "";
 
   const isolationCompactGuideline = isWorktreeIsolationEnabled()
-    ? `\n- isolation: "worktree" gives the agent its own git worktree (removed on completion); changes land on a branch named in the result. Pass \`cwd\` to isolate a repo other than the session cwd.`
+    ? `\n- isolation: "worktree" gives the agent its own git worktree (removed unless cleanup fails); changes land on a branch named in the result. Pass \`cwd\` to isolate a repo other than the session cwd.`
     : "";
 
+  // Tier keys only: members are profile config (router or enterprise manifest),
+  // and teaching fuzzy names here is how model ids leak into calls, where an
+  // explicit `model` beats `agentModels` and bypasses the router.
+  const tierGuidance = (): string | undefined => {
+    const tiers = configuredTierNames();
+    return tiers.length === 0
+      ? undefined
+      : `Configured tiers: ${tiers.map((tier) => `@${tier}`).join(", ")}. Prefer a tier over a model id.`;
+  };
+  const modelGuideline = (): string => {
+    const tiers = tierGuidance();
+    return tiers
+      ? `Use model to select a tier. ${tiers}`
+      : 'Use model to select a configured tier (e.g. "@cheap"), an exact "provider/modelId", or a fuzzy tool-call input (e.g. "haiku").';
+  };
+  const modelParamDescription = (): string => {
+    const tiers = tierGuidance();
+    return tiers
+      ? `Optional model override. ${tiers} "provider/modelId" is also accepted. Explicit values win over agentModels and the agent definition.`
+      : 'Optional model override. Accepts a configured tier (e.g. "@cheap"), "provider/modelId", or fuzzy name (e.g. "haiku"). Explicit values win over agentModels and the agent definition.';
+  };
+
   // Compact Agent tool description (#91, `toolDescriptionMode: "compact"`) —
   // the same load-bearing facts as the full version at ~75% fewer tokens, for
   // small/local models. Per-option details live in the param descriptions.
@@ -1872,7 +2185,7 @@ Notes:
 - Parallel work: one message, multiple Agent calls — they run concurrently.
 - Subagents run in the background by default; you'll be notified when one completes. Pass run_in_background: false only when your very next action depends on the result and nothing else could usefully happen while it runs. Never fabricate or predict a pending agent's results — if the user asks before the notification arrives, say it's still running.
 - The result is not shown to the user — summarize it for them. Verify an agent's claimed code changes before reporting work done.
-- resume continues a previous agent by ID; steer_subagent messages a running one.${isolationCompactGuideline}`;
+- resume continues a previous agent by ID; steer_subagent messages one, steering it mid-run or resuming it once finished.${isolationCompactGuideline}`;
 
   const fullAgentToolDescription = () => `Launch a new agent to handle complex, multi-step tasks autonomously. Each agent type has specific capabilities and tools available to it.
 
@@ -1897,10 +2210,11 @@ If the target is already known, use a direct tool — \`read\` for a known path,
 - **Foreground vs background**: Pass \`run_in_background: false\` only when your very next action depends on the agent's result and nothing else could usefully happen while it runs — e.g., a research agent whose finding gates the edit you're about to make. Otherwise let it run in the background (the default) — this includes fire-and-forget work, independent investigations, and anything where the user might hand you something else in the meantime. Wanting the result "next" is not enough on its own.
 - **Don't race**: after launching a background agent, you know nothing about its results. Never fabricate or predict them in any format — not as prose, summary, or structured output. The completion notification arrives in a later turn; it is never something you write yourself. If the user asks before it lands, say the agent is still running — give status, not a guess.
 - Use resume with an agent ID to continue a previous agent's work. A new (non-resume) Agent call starts a fresh agent with no memory of prior runs, so the prompt must be self-contained.
-- Use steer_subagent to send mid-run messages to a running background agent.
+- Use steer_subagent to message an agent: it steers a running agent mid-run and resumes a finished one in the background, like resume.
+- Use stop_subagent to end an agent or workflow you no longer need, e.g. once a sibling has answered. A steer asking it to stop is read only after its current tool call and can be ignored.
 - Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, etc.), since it is not aware of the user's intent.
 - If an agent's description says it should be used proactively, try to use it without the user having to ask for it first.
-- Use model to select a configured tier (e.g. "@cheap"), an exact "provider/modelId", or a fuzzy tool-call input (e.g. "haiku").
+- ${modelGuideline()}
 - Use thinking to control extended thinking level.
 - Use inherit_context if the agent needs the parent conversation history.${isolationGuideline}${scheduleGuideline}
 
@@ -1949,7 +2263,7 @@ Terse command-style prompts produce shallow, generic work.
         if (text) return renderToolDescriptionTemplate(text);
         console.warn(`[pi-subagents] ${path} is empty — ignoring`);
       } catch (err) {
-        console.warn(`[pi-subagents] failed to read ${path}: ${err instanceof Error ? err.message : String(err)}`);
+        console.warn(`[pi-subagents] failed to read ${path}: ${errorMessage(err)}`);
       }
     }
     return undefined;
@@ -2001,8 +2315,7 @@ Terse command-style prompts produce shallow, generic work.
       }),
       model: Type.Optional(
         Type.String({
-          description:
-            'Optional model override. Accepts a configured tier (e.g. "@cheap"), "provider/modelId", or fuzzy name (e.g. "haiku"). Explicit values win over agentModels and the agent definition.',
+          description: modelParamDescription(),
         }),
       ),
       thinking: Type.Optional(
@@ -2023,7 +2336,7 @@ Terse command-style prompts produce shallow, generic work.
       ),
       resume: Type.Optional(
         Type.String({
-          description: "Optional agent ID to resume from. Continues from previous context. Resumes detached like any other spawn; pass run_in_background: false to block and get the result inline. The resumed run gets a fresh max_turns budget. An agent can only be resumed once its current run has finished — use steer_subagent to reach one mid-run.",
+          description: "Optional agent ID to resume from. Continues from previous context. Resumes detached like any other spawn; pass run_in_background: false to block and get the result inline. The resumed run gets a fresh max_turns budget. An agent can only be resumed once its current run has finished — use steer_subagent to reach one mid-run. An evicted agent's conversation is reopened from disk, background only, under a NEW Agent ID: use that id from then on (the old one also resolves to it).",
         }),
       ),
       isolated: Type.Optional(
@@ -2200,11 +2513,12 @@ Terse command-style prompts produce shallow, generic work.
         rec ? rec.modelFallback : modelFallback;
       /** A resume's lead-in: the record's note only (the type note describes a spawn, not a resume). */
       const resumeNoteFor = (rec: AgentRecord): string => {
-        const note = modelNoteOf(rec);
+        const note = [modelNoteOf(rec), modelIdentityNote(rec)].filter(Boolean).join("\n");
         return note ? `${note}\n\n` : "";
       };
       const fallbackNoteFor = (rec: AgentRecord | undefined): string => {
-        const modelNote = modelNoteOf(rec);
+        // No record means a schedule or quota park, reselected at fire time: no identity claim.
+        const modelNote = [modelNoteOf(rec), modelIdentityNote(rec)].filter(Boolean).join("\n");
         return typeNote + (modelNote ? `${modelNote}\n\n` : "");
       };
       const detailBase = {
@@ -2272,6 +2586,7 @@ Terse command-style prompts produce shallow, generic work.
         if (!scheduler.isActive()) {
           return textResult("Scheduler is not active in this session yet. Try again after the session has fully started.");
         }
+        if (planningNow(pi.events)) return textResult(PLAN_SCHEDULE_REFUSAL);
         try {
           const job = scheduler.addJob({
             name: params.description as string,
@@ -2294,18 +2609,57 @@ Terse command-style prompts produce shallow, generic work.
             `Manage via /agents → Scheduled jobs.`,
           );
         } catch (err) {
-          return textResult(err instanceof Error ? err.message : String(err));
+          return textResult(errorMessage(err));
         }
       }
 
       // Resume existing agent
       if (params.resume) {
-        const existing = manager.getRecord(params.resume);
-        if (!existing || !isTopLevelAgent(existing)) {
+        // An evicted id that was reopened resolves to the newest record of the
+        // same conversation, so it never reopens the session file twice (#330).
+        const latest = manager.latestId(params.resume);
+        const continued = latest === params.resume ? "" : `Agent ${params.resume} continues as ${latest}; use that id from now on.\n`;
+        const existing = manager.getRecord(latest);
+        if (!existing) {
+          // Evicted by the retention sweep, but a persisted conversation is
+          // still on disk: reopen it, as `@handle` does.
+          const entry = manager.listTombstones().find(t => t.id === latest);
+          if (!entry) {
+            // Evicted with no session file left to reopen: `rememberAgents` off, or the tombstone was dropped.
+            const note = manager.getEvictedNote(latest);
+            const gone = note?.nameTaken
+              ? `its name "${note.nameTaken}" now belongs to another agent, so its saved session was not kept reopenable.`
+              : "no saved session is left to reopen.";
+            const why = note ? `Cannot resume agent "${latest}": ${gone}\n${describeEvicted(note)}` : agentNotFound(latest);
+            return textResult(`${continued}${why}`);
+          }
+          // The reopen is a fresh detached spawn: nothing can block on it here.
+          if (!runInBackground) {
+            return textResult(
+              `${continued}Agent "${latest}" was evicted; its conversation reopens only in the background, under a new Agent ID. ` +
+              "Call Agent again with this resume and run_in_background: true.",
+            );
+          }
+          const reopened = await reopenEvicted(ctx, entry, params.prompt, {
+            maxTurns: getAgentConfig(entry.type)?.maxTurns ?? params.max_turns,
+          });
+          if (!reopened.ok) return textResult(`${continued}${couldNotResume(`agent "${latest}"`, reopened.failure)}`);
+          // No `.output` line: like every non-tool spawn it writes none, and
+          // the session file it reopened is the full transcript.
+          return textResult(
+            `${continued}Agent resumed in background, reopening evicted agent ${latest}.\n` +
+            `Agent ID: ${reopened.id} (new; ${params.resume} also resolves to it)\n` +
+            `Type: ${entry.type}\n` +
+            `Session file: ${entry.sessionFile}\n` +
+            `\nYou will be notified when this agent completes.\n` +
+            `Use get_subagent_result to retrieve full results, or steer_subagent to send it messages.`,
+          );
+        }
+        if (!isTopLevelAgent(existing)) {
           return textResult(`Agent not found: "${params.resume}". It may have been cleaned up.`);
         }
         if (!existing.session) {
-          return textResult(`Agent "${params.resume}" has no active session to resume.`);
+          return textResult(`${continued}Agent "${existing.id}" has no active session to resume.`);
         }
         // Not `effectiveMaxTurns`: that was resolved for `subagent_type`, which
         // a resume ignores, so it may describe another agent.
@@ -2323,7 +2677,7 @@ Terse command-style prompts produce shallow, generic work.
         // instead of letting it read as a generic failure.
         if (existing.status === "running" || existing.status === "queued") {
           return textResult(
-            `Agent "${params.resume}" is still ${existing.status} — it can only be resumed once its current run finishes.\n` +
+            `${continued}Agent "${existing.id}" is still ${existing.status} — it can only be resumed once its current run finishes.\n` +
             `Use steer_subagent to send it a message mid-run, or get_subagent_result to wait for it.`,
           );
         }
@@ -2342,7 +2696,7 @@ Terse command-style prompts produce shallow, generic work.
 
           const isQueued = record.status === "queued";
           return textResult(
-            `${resumeNoteFor(record)}Agent ${isQueued ? "queued" : "resumed"} in background.\n` +
+            `${continued}${resumeNoteFor(record)}Agent ${isQueued ? "queued" : "resumed"} in background.\n` +
             `Agent ID: ${id}\n` +
             `Type: ${existing.type}\n` +
             (record.outputFile ? `Output file: ${record.outputFile}\n` : "") +
@@ -2365,7 +2719,7 @@ Terse command-style prompts produce shallow, generic work.
         fleet.update();
         let record: AgentRecord | undefined;
         try {
-          record = await manager.resume(params.resume, params.prompt, signal, {
+          record = await manager.resume(existing.id, params.prompt, signal, {
             maxTurns: resumeMaxTurns,
             onTurnEnd: resumeCallbacks.onTurnEnd,
             onTextDelta: resumeCallbacks.onTextDelta,
@@ -2387,7 +2741,7 @@ Terse command-style prompts produce shallow, generic work.
           return textResult(`${resumeNoteFor(record)}Agent failed: ${record.error}${partialOutputSuffix(record)}`, buildDetails(detailBaseFor(record), record, resumeState));
         }
         return textResult(
-          `${resumeNoteFor(record)}${record.result?.trim() || "No output."}`,
+          `${continued}${resumeNoteFor(record)}${record.result?.trim() || "No output."}`,
           buildDetails(detailBaseFor(record), record, resumeState),
         );
       }
@@ -2426,6 +2780,7 @@ Terse command-style prompts produce shallow, generic work.
         if (!canPark || !mayPark(quotaBlock)) {
           throw new Error(`${selection?.tier ? `${modelNoteOf(undefined)}\n` : ""}${describeBlock(quotaBlock)} The agent was not started.`);
         }
+        if (planningNow(pi.events)) throw new Error(`${describeBlock(quotaBlock)} ${PLAN_PARK_REFUSAL}`);
         const job = scheduler.addJob({
           name: `${params.description} (quota ${nanoid(4)})`,
           description: params.description as string,
@@ -2443,7 +2798,7 @@ Terse command-style prompts produce shallow, generic work.
         });
         return textResult(
           `${fallbackNoteFor(undefined)}${describeBlock(quotaBlock)} Queued "${job.name}" (id: ${job.id}) to start at ` +
-          `${scheduler.getNextRun(job.id) ?? job.schedule}. Manage via /agents → Scheduled jobs.`,
+          `${job.schedule}. Manage via /agents → Scheduled jobs.`,
         );
       }
 
@@ -2452,8 +2807,7 @@ Terse command-style prompts produce shallow, generic work.
         const { state: bgState, callbacks: bgCallbacks } = createActivityTracker(effectiveMaxTurns, undefined, clock);
 
         // Wrap onSessionCreated to wire output file streaming.
-        // The callback lazily reads record.outputFile (set right after spawn)
-        // rather than closing over a value that doesn't exist yet.
+        // The callback reads record.outputFile prepared before launch.
         let id: string;
         const origBgOnSession = bgCallbacks.onSessionCreated;
         bgCallbacks.onSessionCreated = (session: any) => {
@@ -2481,18 +2835,17 @@ Terse command-style prompts produce shallow, generic work.
           cwd,
           invocation: agentInvocation,
           rootSessionId: ctx.sessionManager.getSessionId(),
+          onPrepare: (agentId) => attachTranscript(manager.getRecord(agentId), agentId),
           ...bgCallbacks,
         });
 
-        // Set output file + join mode synchronously after spawn, before the
-        // event loop yields — onSessionCreated is async so this is safe.
-        const joinMode = resolveJoinMode(defaultJoinMode, true);
-        const record = manager.getRecord(id);
-        if (record && joinMode) {
-          record.joinMode = joinMode;
-          record.toolCallId = toolCallId;
-          attachTranscript(record, id);
-        }
+        // `spawn` has not yielded yet, so the join mode and tool-call id are set before the
+        // record's session starts.
+        const joinMode = defaultJoinMode;
+        // `spawn` registered the record before returning its id.
+        const record = manager.getRecord(id)!;
+        record.joinMode = joinMode;
+        record.toolCallId = toolCallId;
 
         // With isolation: "worktree" the agent isn't running yet — the repo
         // copy is an awaited git call. Wait for it here, after the synchronous
@@ -2514,7 +2867,7 @@ Terse command-style prompts produce shallow, generic work.
           type: subagentType,
           description: params.description,
           isBackground: true,
-          ...fallbackFields(manager.getRecord(id)),
+          ...eventFields(manager.getRecord(id)),
         });
 
         return backgroundResult(id, record);
@@ -2573,8 +2926,7 @@ Terse command-style prompts produce shallow, generic work.
       const { state: fgState, callbacks: fgCallbacks } = createActivityTracker(effectiveMaxTurns, streamUpdate, clock);
 
       // Wire session creation: register in widget + stream to output file.
-      // The output file path is set synchronously after spawn (below),
-      // before onSessionCreated fires — same pattern as background agents.
+      // The output file path is prepared before launch, as for background agents.
       const origOnSession = fgCallbacks.onSessionCreated;
       fgCallbacks.onSessionCreated = (session: any) => {
         origOnSession(session);
@@ -2592,16 +2944,11 @@ Terse command-style prompts produce shallow, generic work.
             widget.ensureTimer();
             fleet.ensureTimer();
             fleet.update();
+            // Stream conversation to output file (foreground agent logging)
+            if (a.outputFile) a.outputCleanup = streamToOutputFile(session, a.outputFile, a.id, ctx.cwd);
             break;
           }
         }
-        // Stream conversation to output file (foreground agent logging)
-        if (fgId) {
-          const rec = manager.getRecord(fgId);
-          if (rec?.outputFile) {
-            rec.outputCleanup = streamToOutputFile(session, rec.outputFile, fgId, ctx.cwd);
-          }
-        }
       };
 
       // Animate spinner at ~80ms (smooth rotation through 10 braille frames)
@@ -2640,12 +2987,12 @@ Terse command-style prompts produce shallow, generic work.
           // widget and the `finally` cleanup below, none of which should see an
           // agent that has no session and may never get one.
           onQueued: (_id, ahead) => { queuedAhead = ahead; streamUpdate(); },
+          onPrepare: (agentId) => attachTranscript(manager.getRecord(agentId), agentId),
           ...fgCallbacks,
         }, (fgAgentId) => {
-          // onSpawned: called synchronously after spawn, before onSessionCreated fires.
-          // Set up the output file so streamToOutputFile can pick it up.
-          const fgRec = manager.getRecord(fgAgentId);
-          attachTranscript(fgRec, fgAgentId);
+          // onSpawned fires after the run promise exists, before onSessionCreated.
+          // Running, so the manager still holds it: only settled records are removed.
+          const fgRec = manager.getRecord(fgAgentId)!;
           // Fires once the run promise exists, i.e. the agent is running. From
           // here until this call returns, the run can be handed off.
           handoffId = fgAgentId;
@@ -2653,10 +3000,8 @@ Terse command-style prompts produce shallow, generic work.
             // What a background spawn sets up front: the notification names
             // this tool call, and it reports alone — its spawn batch is long
             // closed.
-            if (fgRec) {
-              fgRec.toolCallId = toolCallId;
-              fgRec.joinMode = "async";
-            }
+            fgRec.toolCallId = toolCallId;
+            fgRec.joinMode = "async";
             backgrounded = true;
             wakeBackgrounded();
           });
@@ -2690,7 +3035,7 @@ Terse command-style prompts produce shallow, generic work.
         return textResult(`${fallbackNoteFor(record)}Agent failed: ${record.error}${partialOutputSuffix(record)}`, details);
       }
 
-      const durationMs = (record.completedAt ?? Date.now()) - record.startedAt;
+      const durationMs = recordElapsedMs(record, Date.now());
       const statsParts = [`${record.toolUses} tool uses`];
       if (tokenText) statsParts.push(tokenText);
       if (showCost) {
@@ -2698,7 +3043,7 @@ Terse command-style prompts produce shallow, generic work.
         if (costText) statsParts.push(costText);
       }
       return textResult(
-        `${fallbackNoteFor(record)}Agent completed in ${formatMs(durationMs)} (${statsParts.join(", ")})${getForegroundOutcomeNote(record.status)}.\n\n` +
+        `${fallbackNoteFor(record)}Agent completed in ${formatMs(durationMs)} (${statsParts.join(", ")})${getForegroundOutcomeNote(record.status, record.stoppedBy)}.\n\n` +
         (record.result?.trim() || "No output."),
         details,
       );
@@ -2781,7 +3126,8 @@ Terse command-style prompts produce shallow, generic work.
     // run's progress log here would put O(log) work in the render loop.
     return [...workflowTasks.values()].map(task => ({
       id: task.id,
-      name: task.meta?.name ?? task.workflowName ?? task.id,
+      // Every task here is created from a parsed `meta`, which also names the run.
+      name: task.meta!.name,
       status: task.status,
       doneCount: task.doneCount,
       totalCount: task.agentCount,
@@ -2826,7 +3172,7 @@ Terse command-style prompts produce shallow, generic work.
       });
       completeWorkflowTask(task, result);
     } catch (err) {
-      failWorkflowTask(task, err instanceof Error ? err.message : String(err));
+      failWorkflowTask(task, errorMessage(err));
     }
   }
 
@@ -2843,7 +3189,7 @@ Terse command-style prompts produce shallow, generic work.
       content: formatWorkflowNotification(task),
       details: {
         id: task.id,
-        description: `Workflow ${task.workflowName ?? task.id}`,
+        description: `Workflow ${task.meta!.name}`,
         status: task.status === "completed" ? "completed" : task.status === "killed" ? "stopped" : "error",
         toolUses: task.totalToolCalls,
         // A workflow has agents, not turns; rendering "↻0" would be noise.
@@ -2974,7 +3320,7 @@ Terse command-style prompts produce shallow, generic work.
       try {
         meta = extractMeta(resolved.script).meta;
       } catch (err) {
-        return textResult(err instanceof Error ? err.message : String(err));
+        return textResult(errorMessage(err));
       }
 
       const runId = workflowRunId();
@@ -2992,7 +3338,7 @@ Terse command-style prompts produce shallow, generic work.
       } catch (err) {
         savedPath = undefined;
         journalPath = undefined;
-        console.warn(`[pi-subagents] could not persist workflow script: ${err instanceof Error ? err.message : String(err)}`);
+        console.warn(`[pi-subagents] could not persist workflow script: ${errorMessage(err)}`);
       }
 
       const replay = resumeFrom !== undefined ? readJournal(resumeFrom.journalPath) : undefined;
@@ -3027,7 +3373,7 @@ Terse command-style prompts produce shallow, generic work.
             `Task ID: ${runId}\n` +
             (task.scriptPath ? `Script: ${task.scriptPath}\n` : "") +
             (task.resumedFrom !== undefined
-              ? `Resuming ${task.resumedFrom}: ${task.replay?.length ?? 0} recorded call(s) available to replay.\n`
+              ? `Resuming ${task.resumedFrom}: ${task.replay!.length} recorded call(s) available to replay.\n`
               : params.resumeFromRunId !== undefined
                 ? `Nothing to replay from ${params.resumeFromRunId} — every agent runs live.\n`
                 : "") +
@@ -3152,7 +3498,7 @@ Terse command-style prompts produce shallow, generic work.
     try {
       script = readFileSync(path, "utf-8");
     } catch (err) {
-      report(`Could not read ${path}: ${err instanceof Error ? err.message : String(err)}`, "warning");
+      report(`Could not read ${path}: ${errorMessage(err)}`, "warning");
       return;
     }
 
@@ -3160,7 +3506,7 @@ Terse command-style prompts produce shallow, generic work.
     try {
       meta = extractMeta(script).meta;
     } catch (err) {
-      report(err instanceof Error ? err.message : String(err), "warning");
+      report(errorMessage(err), "warning");
       return;
     }
 
@@ -3199,7 +3545,7 @@ Terse command-style prompts produce shallow, generic work.
     name: SUBAGENT_TOOL_NAMES.GET_RESULT,
     label: "Get Agent Result",
     description:
-      "Check status and retrieve a background agent's full result — its completion notification carries only a preview. Use the agent ID returned by Agent.",
+      "Check status and retrieve a background agent's full result: use it while the agent runs, or when its completion notification says the result was truncated. Use the agent ID returned by Agent.",
     promptSnippet: "Check status and retrieve results from a background agent",
     parameters: Type.Object({
       agent_id: Type.String({
@@ -3248,7 +3594,7 @@ Terse command-style prompts produce shallow, generic work.
 
       let output =
         `Agent: ${record.id}\n` +
-        `Type: ${displayName} | Status: ${record.status}${getStatusNote(record.status)} | ${statsParts.join(" | ")}\n` +
+        `Type: ${displayName} | Status: ${record.status}${getStatusNote(record.status, record.stoppedBy)} | ${statsParts.join(" | ")}\n` +
         `Description: ${record.description}\n` +
         (modelSelectionNote(record) ? `${modelSelectionNote(record)}\n` : "") +
         `\n`;
@@ -3286,23 +3632,46 @@ Terse command-style prompts produce shallow, generic work.
     name: SUBAGENT_TOOL_NAMES.STEER,
     label: "Steer Agent",
     description:
-      "Send a steering message to a running agent. The message will interrupt the agent after its current tool execution " +
-      "and be injected into its conversation, allowing you to redirect its work mid-run. A queued agent gets the message when it starts.",
-    promptSnippet: "Send a steering message to redirect a running background agent",
+      "Send a message to an agent. A running agent is interrupted after its current tool execution and the message is injected into its conversation, " +
+      "allowing you to redirect its work mid-run. A queued agent gets the message when it starts. A finished agent is resumed in the background " +
+      "with its full history and the message as its next prompt, exactly like Agent's resume; you will be notified when it completes. " +
+      "A stopped agent is not resumed. To end an agent's run, use stop_subagent: a steer is read only after its current tool call, and the agent may ignore it.",
+    promptSnippet: "Send a message to a background agent: steer it mid-run, or resume it once finished",
     parameters: Type.Object({
       agent_id: Type.String({
-        description: "The agent ID to steer (must be running or queued). The agent's handle also works — its `name` if you gave it one, otherwise its type (`explore`, `explore-2`).",
+        description: "The agent ID to message. The agent's handle also works — its `name` if you gave it one, otherwise its type (`explore`, `explore-2`).",
       }),
       message: Type.String({
-        description: "The steering message to send. This will appear as a user message in the agent's conversation.",
+        description: "The message to send. This will appear as a user message in the agent's conversation.",
       }),
     }),
-    execute: async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
-      const record = resolveAgentRef(params.agent_id);
-      if (!record || !isTopLevelAgent(record)) return textResult(agentNotFound(params.agent_id));
-      if (record.status !== "running" && record.status !== "queued") {
-        return textResult(`Agent "${params.agent_id}" is not running (status: ${record.status}). Cannot steer a finished agent.`);
+    execute: async (toolCallId, params, signal, onUpdate, ctx) => {
+      // An evicted id that was reopened answers as the record it continues under (#330).
+      const latest = manager.latestId(params.agent_id);
+      const record = resolveAgentRef(latest);
+      if (record && !isTopLevelAgent(record)) return textResult(agentNotFound(params.agent_id));
+      if (record?.status !== "running" && record?.status !== "queued") {
+        // Finished: continue it, as Claude Code's SendMessage does. An evicted
+        // record is known only by its note; Agent's resume reopens its session
+        // from disk or explains why it cannot.
+        const finished = record ?? manager.getEvictedNote(latest);
+        if (!finished) return textResult(agentNotFound(params.agent_id));
+        if (finished.status === "stopped") {
+          return textResult(`Agent "${finished.id}" was stopped (status: stopped). steer_subagent does not resume a stopped agent.`);
+        }
+        // The Agent tool's own resume path, not a copy: same reopen, turn
+        // budget, transcript and result. `subagent_type` is the record's own,
+        // so its frontmatter governs as it does for an `@handle` resume.
+        return agentTool.execute(toolCallId, {
+          resume: latest === params.agent_id ? finished.id : params.agent_id,
+          prompt: params.message,
+          description: finished.description,
+          subagent_type: finished.type,
+          run_in_background: true,
+        }, signal, onUpdate, ctx);
       }
+      // Running or queued under no Plan policy: a steer from a planning parent would drive edits.
+      if (planSteerBlocked(record, pi.events)) return textResult(planSteerRefusal(record.id));
       if (!record.session) {
         // Queued for a concurrency slot, or running with its session still
         // being built: either way the manager flushes `pendingSteers` into the
@@ -3334,24 +3703,124 @@ Terse command-style prompts produce shallow, generic work.
           `Current state: ${stateParts.join(" · ")}`,
         );
       } catch (err) {
-        return textResult(`Failed to steer agent: ${err instanceof Error ? err.message : String(err)}`);
+        return textResult(`Failed to steer agent: ${errorMessage(err)}`);
       }
     },
   }));
 
+  // ---- stop_subagent tool ----
+
+  /** A workflow run a stop can still reach: running or paused, not already told to stop. */
+  const isLiveWorkflow = (task: WorkflowTask) => (task.status === "running" || task.status === "paused") && !task.abortController.signal.aborted;
+
+  /** Survivors of a session switch, still running in the orphaned manager (#330). */
+  const runningSurvivors = () => listRunningDetached(currentCtx?.sessionManager?.getSessionFile?.());
+
+  /**
+   * Agents a stop can reach: this session's own running or queued top-level
+   * agents, then survivors. Never a nested or workflow child: those belong to
+   * their owner, which stops them with itself (#446's ownership invariant).
+   */
+  function stoppableAgents(): AgentRecord[] {
+    const own = manager.listAgents().filter(r => isTopLevelAgent(r) && (r.status === "running" || r.status === "queued"));
+    return [...own, ...runningSurvivors().map(d => d.record).filter(r => r.status === "running")];
+  }
+
+  /** Stop one top-level agent through the manager that owns it, this one or an orphan's. */
+  function stopAgent(record: AgentRecord, by?: AgentRecord["stoppedBy"]): boolean {
+    if (manager.getRecord(record.id) === record) return manager.abort(record.id, by);
+    return !!runningSurvivors().find(d => d.record === record)?.abort(by);
+  }
+
+  /** What a stop that matched nothing lists instead: everything still running or queued. */
+  function describeStoppable(): string {
+    const lines = [
+      ...stoppableAgents().map(r => `- ${r.id} @${r.alias ?? r.handle} (${r.status}): ${r.description}`),
+      ...[...workflowTasks.values()].filter(isLiveWorkflow).map(t => `- ${t.id} workflow "${t.meta!.name}" (${t.status})`),
+    ];
+    return lines.length > 0 ? `Running or queued:\n${lines.join("\n")}` : "Nothing is running or queued.";
+  }
+
+  /**
+   * Stop every running or queued top-level agent, survivor, and workflow run
+   * (whose agents stop with it). A scheduled job that has not fired is not
+   * running, so it is untouched. The human-side stop: records stay unmarked.
+   */
+  function stopAllRunning(): { agents: number; workflows: number } {
+    const runs = [...workflowTasks.values()].filter(isLiveWorkflow);
+    for (const task of runs) task.abortController.abort();
+    return { agents: stoppableAgents().filter(record => stopAgent(record)).length, workflows: runs.length };
+  }
+
+  registerToolReportingUsage(defineTool({
+    name: SUBAGENT_TOOL_NAMES.STOP,
+    label: "Stop Agent",
+    description:
+      "Stop (cancel, kill) a running or queued background agent, or a SubagentWorkflow run by the run id it returned. " +
+      "Use it when an agent's work is no longer wanted, e.g. a sibling already answered. Unlike steer_subagent, the agent cannot ignore it: " +
+      "the run is aborted at once, its current tool call gets the abort signal, and it starts no further tool call. Its status becomes `stopped`. " +
+      "A running agent's partial output, and any worktree branch with changes, arrives in one completion notice; a queued agent never starts. " +
+      "A workflow stops with all of its agents. A stopped agent is not resumed. " +
+      "A run of another extension's `workflow` tool is not ours to stop: use that extension's control (e.g. `workflow_control` with action `stop`).",
+    promptSnippet: "Stop or cancel a running background agent or workflow",
+    // Plan mode admits a trusted tool only on `readOnlyHint`. Stopping edits no
+    // file and starts nothing; it only ends work already running, so it must
+    // stay callable in Plan, where an orchestrator should still be able to
+    // stand a fan-out down.
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    parameters: Type.Object({
+      agent_id: Type.String({
+        description: "The agent ID to stop. Its handle or name also works. A SubagentWorkflow run id stops that workflow run.",
+      }),
+    }),
+    execute: async (_toolCallId, params) => {
+      const task = workflowTasks.get(params.agent_id);
+      if (task && isLiveWorkflow(task)) {
+        // Marked first: the run's notice is written when it settles, after this returns.
+        task.stoppedBy = "parent";
+        task.abortController.abort();
+        return textResult(`Workflow "${task.meta!.name}" (${task.id}) stopped, with its agents. A completion notice follows.`);
+      }
+      if (task && (task.status === "running" || task.status === "paused")) {
+        // Told to stop, still unwinding: not "not running", and nothing more to do.
+        return textResult(`Workflow "${task.meta!.name}" (${task.id}) is already stopping. A completion notice follows.`);
+      }
+      const latest = manager.latestId(params.agent_id);
+      const found = resolveAgentRef(latest);
+      const record = found && isTopLevelAgent(found) ? found : undefined;
+      if (record?.status !== "running" && record?.status !== "queued") {
+        const status = record?.status ?? task?.status ?? manager.getEvictedNote(latest)?.status;
+        const what = status ? `"${params.agent_id}" is not running (status: ${status})` : `No agent or workflow "${params.agent_id}"`;
+        return { ...textResult(`${what}, so there is nothing to stop.\n${describeStoppable()}`), isError: true };
+      }
+      const wasQueued = record.status === "queued";
+      stopAgent(record, "parent");
+      const statsParts = [`Tool uses: ${record.toolUses}`];
+      const tokens = formatLifetimeTokens(record);
+      if (tokens) statsParts.push(tokens);
+      return textResult(
+        `Agent ${record.id} stopped.\n` +
+        `Type: ${getDisplayName(record.type)} | Status: ${record.status} | ${statsParts.join(" | ")}\n` +
+        `Description: ${record.description}\n\n` +
+        (wasQueued
+          ? "It was still queued, so it never started and no completion notice follows."
+          : "It starts no further tool call. One completion notice with its partial output follows."),
+      );
+    },
+  }));
+
   // ---- /agents interactive menu ----
 
   // Directory resolution and the frontmatter edits live in agent-file-toggle.ts
   // so they are reachable from tests — this command handler is only registered
   // through `registerCommand`, which every test mocks.
 
-  function getModelLabel(type: string, registry?: ModelRegistry): string {
+  function getModelLabel(type: string, registry: ModelRegistry, cwd: string): string {
     const cfg = getAgentConfig(type);
     const input = modelRequest(type, cfg?.model).requested;
     if (!input) return "inherit";
     const label = getModelLabelFromConfig(input);
-    if (!registry) return label;
-    const selection = selectModel({ homeDir: options.homeDir, agentType: type, definitionModel: cfg?.model, parentModel: undefined, registry, cwd: currentCtx?.cwd ?? process.cwd() });
+    const selection = selectModel({ homeDir: options.homeDir, agentType: type, definitionModel: cfg?.model, parentModel: undefined, registry, cwd });
     if (typeof selection === "string" || selection.outcome === "fallback" || !selection.model) {
       return `${label} (unavailable, fallback: inherit)`;
     }
@@ -3379,6 +3848,9 @@ Terse command-style prompts produce shallow, generic work.
       const done = agents.filter(a => a.status === "completed" || a.status === "steered").length;
       options.push(`Running agents (${agents.length}) — ${running} running, ${done} done`);
     }
+    // Survivors and workflow runs count too: they are what the chord stops.
+    const stoppable = stoppableAgents().length + [...workflowTasks.values()].filter(isLiveWorkflow).length;
+    if (stoppable > 0) options.push(`Stop all running (${stoppable})`);
 
     // Agent types list
     if (allNames.length > 0) {
@@ -3417,6 +3889,12 @@ Terse command-style prompts produce shallow, generic work.
     if (choice.startsWith("Running agents (")) {
       await showRunningAgents(ctx);
       await showAgentsMenu(ctx);
+    } else if (choice.startsWith("Stop all running (")) {
+      if (await ctx.ui.confirm("Stop all running", "Stop every running or queued agent and workflow?")) {
+        const { agents: stoppedAgents, workflows } = stopAllRunning();
+        ctx.ui.notify(`Stopped ${stoppedAgents} agent(s) and ${workflows} workflow(s).`, "info");
+      }
+      await showAgentsMenu(ctx);
     } else if (choice.startsWith("Agent types (")) {
       await showAllAgentsList(ctx);
       await showAgentsMenu(ctx);
@@ -3460,7 +3938,7 @@ Terse command-style prompts produce shallow, generic work.
     // it: the `▪` badge says a package won, not which one.
     const items: SettingItem[] = allNames.map((name, i) => {
       const cfg = configs[i];
-      const model = getModelLabel(name, ctx.modelRegistry);
+      const model = getModelLabel(name, ctx.modelRegistry, ctx.cwd);
       return {
         id: name,
         label: `${sourceIndicator(cfg)}${name}`,
@@ -3538,9 +4016,9 @@ Terse command-style prompts produce shallow, generic work.
       (tui, theme, keybindings, done) => {
         overlayOptions = getConversationOverlayOptions(tui);
         return new ConversationViewer(tui, session, record, activity, theme, done, () => {
-          if (manager.abort(record.id)) {
-            ctx.ui.notify(`Stopped "${record.description}".`, "info");
-          }
+          // The viewer offers stop only while the agent is running or queued, which `abort` always honours.
+          manager.abort(record.id);
+          ctx.ui.notify(`Stopped "${record.description}".`, "info");
         }, keybindings, (message: string) => manager.steer(record.id, message), showCost, getViewerMarkdown, (mode) => chooseViewerMarkdown(mode, ctx), getFullscreenScrollbar(),
         backgroundActionFor(record, message => ctx.ui.notify(message, "info")), clock);
       },
@@ -3569,10 +4047,9 @@ Terse command-style prompts produce shallow, generic work.
         ? ["Eject (export as .md)", "Back"]
         : ["Eject (export as .md)", "Disable", "Back"];
     } else if (disabled && file) {
-      // Disabled agent with a file — offer Enable
-      menuOptions = isDefault
-        ? ["Enable", "Edit", "Reset to default", "Delete", "Back"]
-        : ["Enable", "Edit", "Delete", "Back"];
+      // Disabled agent with a file — offer Enable. Never a built-in: a built-in is only ever
+      // disabled by the very file that replaces it, which makes the entry a user definition.
+      menuOptions = ["Enable", "Edit", "Delete", "Back"];
     } else if (isDefault && !file) {
       // Default agent with no .md override
       menuOptions = ["Eject (export as .md)", "Disable", "Back"];
@@ -3878,7 +4355,8 @@ Write the file using the write tool. Only write the file, nothing else.`;
     else if (modelChoice === "sonnet") model = "anthropic/claude-sonnet-4-6";
     else if (modelChoice === "opus") model = "anthropic/claude-opus-4-6";
     else if (modelChoice === "custom...") {
-      model = (await ctx.ui.input("Model (provider/modelId)")) || undefined;
+      // A blank answer writes no `model:` line, exactly as no answer does.
+      model = await ctx.ui.input("Model (provider/modelId)");
     }
 
     // 5. Thinking
@@ -3930,6 +4408,7 @@ Write the file using the write tool. Only write the file, nothing else.`;
       // normalizeMaxTurns() in agent-runner.ts (which maps 0 → undefined).
       defaultMaxTurns: getDefaultMaxTurns() ?? 0,
       graceTurns: getGraceTurns(),
+      notificationResultChars,
       defaultJoinMode: getDefaultJoinMode(),
       backgroundByDefault: getBackgroundByDefault(),
       schedulingEnabled: isSchedulingEnabled(),
@@ -4010,6 +4489,7 @@ Write the file using the write tool. Only write the file, nothing else.`;
 
   const NUMERIC_IDS = new Set([
     "maxConcurrent", "maxConcurrentForeground", "defaultMaxTurns", "graceTurns", "maxSubagentDepth",
+    "notificationResultChars",
   ]);
 
   async function showSettings(ctx: ExtensionCommandContext) {
@@ -4063,6 +4543,13 @@ Write the file using the write tool. Only write the file, nothing else.`;
           currentValue: String(msd),
           values: [String(msd)],
         },
+        {
+          id: "notificationResultChars",
+          label: "Notice result chars",
+          description: "Result characters a completion notice carries per agent (0 = 500-char preview, Enter to type)",
+          currentValue: String(notificationResultChars),
+          values: [String(notificationResultChars)],
+        },
         {
           id: "joinMode",
           label: "Join mode",
@@ -4260,6 +4747,14 @@ Write the file using the write tool. Only write the file, nothing else.`;
           setGraceTurns(n);
           notifyApplied(ctx, `Grace turns set to ${n}`);
         }
+      } else if (id === "notificationResultChars") {
+        const n = parseInt(value, 10);
+        if (n >= 0 && n <= NOTIFICATION_RESULT_CHARS_CEILING) {
+          notificationResultChars = n;
+          notifyApplied(ctx, n === 0
+            ? "Completion notices carry a 500-char preview"
+            : `Completion notices carry up to ${n} result chars per agent`);
+        }
       } else if (id === "maxSubagentDepth") {
         const n = parseInt(value, 10);
         if (n >= 0) {
@@ -4401,7 +4896,8 @@ Write the file using the write tool. Only write the file, nothing else.`;
         const enabled = value === "on";
         setRememberAgents(enabled);
         notifyApplied(ctx, `Remember agents ${enabled ? "enabled" : "disabled"}`);
-      } else if (id === "widgetMode") {
+      } else {
+        // widgetMode, the last row: every id `buildItems` offers has an arm.
         setWidgetMode(value as WidgetMode);
         notifyApplied(ctx, `Widget set to ${value}`);
       }
@@ -4461,7 +4957,9 @@ Write the file using the write tool. Only write the file, nothing else.`;
             ? String(getDefaultMaxTurns() ?? 0)
             : result === "maxSubagentDepth"
               ? String(getMaxSubagentDepth())
-              : String(getGraceTurns());
+              : result === "notificationResultChars"
+                ? String(notificationResultChars)
+                : String(getGraceTurns());
 
       const label = result === "maxConcurrent"
         ? "Max concurrency (1+)"
@@ -4471,7 +4969,9 @@ Write the file using the write tool. Only write the file, nothing else.`;
             ? "Default max turns (0 = unlimited)"
             : result === "maxSubagentDepth"
               ? "Nested depth (0/1 = nesting off)"
-              : "Grace turns (1+)";
+              : result === "notificationResultChars"
+                ? `Notice result chars (0 = preview, max ${NOTIFICATION_RESULT_CHARS_CEILING})`
+                : "Grace turns (1+)";
 
       // Loop until user enters a valid integer or cancels (Esc / null).
       // Silently trims whitespace; rejects non-numeric input by re-prompting.