@nredd/pi-subagents 0.22.0-nredd.7 → 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
@@ -12,14 +13,14 @@
 
 import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
-import { defineTool, type ExtensionAPI, type ExtensionCommandContext, type ExtensionContext, type ExtensionFactory, getAgentDir, getSettingsListTheme } from "@earendil-works/pi-coding-agent";
+import { defineTool, type ExtensionAPI, type ExtensionCommandContext, type ExtensionContext, type ExtensionFactory, getSettingsListTheme } from "@earendil-works/pi-coding-agent";
 import { Container, isKeyRelease, Key, matchesKey, type ScrollViewScrollbar, type SettingItem, SettingsList, Spacer, Text } from "@earendil-works/pi-tui";
 import { nanoid } from "nanoid";
 import { Type } from "typebox";
 import { abortable } from "./abortable.js";
 import { hasAgentBadge, renderAgentName } from "./agent-color.js";
-import { buildNewAgentFile, disableInContent, enableInContent, isEmptyStub, locateAgentFile, personalAgentsDir, projectAgentsDir, serializeAgentFile } from "./agent-file-toggle.js";
-import { AgentManager, describeEvicted, isTopLevelAgent, markConsumed } from "./agent-manager.js";
+import { buildNewAgentFile, disableInContent, enableInContent, isEmptyStub, locateAgentFile as locateAgentFileAtHome, personalAgentsDir as personalAgentsDirAtHome, projectAgentsDir, serializeAgentFile } from "./agent-file-toggle.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,24 +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 { cwdParam, isolationParam, resolveAgentInvocationConfig, resolveCwdParam, resolveJoinMode } from "./invocation-config.js";
+import { resolveAgentDir } from "./home-paths.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 { describeModel, describeVirtualModel, isVirtualModel, type ModelRegistry, resolveModel, setAgentModels, setModelAliases, setModelScopeProvider } from "./model-resolver.js";
-import { checkModelScope, isScopeModelsEnabled, setScopeModelsEnabled } from "./model-scope.js";
+import { type ModelFallback, type ModelRegistry, setAgentModels, setModelAliases, setModelScopeProvider } from "./model-resolver.js";
+import { isScopeModelsEnabled, setScopeModelsEnabled } from "./model-scope.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 { createOutputFilePath, ensureOutputFile, getOutputTranscriptDefault, sessionTaskDir, setOutputTranscriptDefault, streamToOutputFile, writeInitialEntry } from "./output-file.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 {
@@ -75,6 +83,7 @@ import {
 } from "./ui/agent-widget.js";
 import { ConversationViewer, getConversationOverlayOptions, type ViewerBackgroundAction } from "./ui/conversation-viewer.js";
 import { FleetList, type FleetUICtx, type FleetWorkflow } from "./ui/fleet-list.js";
+import { FLEET_STATE_ENTRY, FLEET_STATE_VERSION } from "./ui/fleet-state.js";
 import { renderNotification } from "./ui/notification-view.js";
 import { showSchedulesMenu } from "./ui/schedule-menu.js";
 import { selectItem } from "./ui/select-item.js";
@@ -111,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,
@@ -167,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) {
@@ -178,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>` : "";
@@ -191,28 +208,34 @@ 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>`,
-    `<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. */
 function buildDetails(
-  base: Pick<AgentDetails, "displayName" | "description" | "subagentType" | "modelName" | "tags">,
+  base: Pick<AgentDetails, "displayName" | "description" | "subagentType" | "modelName" | "modelNote" | "modelFallback" | "modelTier" | "tags">,
   record: { toolUses: number; startedAt: number; completedAt?: number; status: string; error?: string; id?: string; session?: any; outputFile?: string; lifetimeUsage: LifetimeUsage },
   activity?: AgentActivity,
   overrides?: Partial<AgentDetails>,
@@ -227,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,
@@ -237,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);
 
@@ -252,9 +300,12 @@ 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
       ? record.result.length > resultMaxLen
         ? record.result.slice(0, resultMaxLen) + "…"
@@ -287,12 +338,18 @@ function buildNotificationDetails(record: AgentRecord, resultMaxLen: number, act
  *   agents and those with `extensions: false`.
  */
 export function formatToolsSuffix(cfg: AgentConfig | undefined): string {
-  const tools = cfg?.builtinToolNames;
+  const denied = cfg?.disallowedTools ?? [];
+  const tools = denied.length > 0
+    ? (cfg?.builtinToolNames ?? BUILTIN_TOOL_NAMES).filter((tool) => !denied.includes(tool))
+    : cfg?.builtinToolNames;
+  // Only claim what is known at registration: extensions may supply command
+  // tools (including ssh_exec), so missing bash is not proof of no remote access.
+  const shellNote = tools && !tools.includes("bash") ? "; no built-in shell: cannot run bash commands" : "";
   // `isolated` overrides extensions to false in the runner, so both mean the
   // agent has no extension tools.
   const noExtensionTools = cfg?.isolated === true || cfg?.extensions === false;
   if (tools && tools.length === 0) {
-    return noExtensionTools ? "none" : "no built-ins, extension tools only";
+    return (noExtensionTools ? "none" : "no built-ins, extension tools only") + shellNote;
   }
   const isFullSet = !tools
     || (tools.length === BUILTIN_TOOL_NAMES.length && BUILTIN_TOOL_NAMES.every((t) => tools.includes(t)));
@@ -300,7 +357,7 @@ export function formatToolsSuffix(cfg: AgentConfig | undefined): string {
   // Extension tools resolve at run time, so they cannot be enumerated here, but
   // omitting the fact reads as "built-ins only": an agent that can search the
   // web through an extension then looks web-less, and the work gets routed away.
-  return noExtensionTools ? builtins : `${builtins} + extension tools`;
+  return (noExtensionTools ? builtins : `${builtins} + extension tools`) + shellNote;
 }
 
 /** CLI flag that runs a workflow script at session start. */
@@ -320,6 +377,8 @@ export type { Clock, TimerHandle } from "./clock.js";
 
 /** Optional host dependencies, shared by the scheduler and completion delivery. */
 export interface SubagentsExtensionOptions {
+  /** Home for every user-scoped read and child run. Omitted uses host defaults at call time. */
+  homeDir?: string;
   clock?: Clock;
 }
 
@@ -332,6 +391,10 @@ export default createSubagentsExtension();
 
 function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions) {
   const clock = options.clock ?? realClock;
+  const getAgentDir = () => resolveAgentDir(options.homeDir);
+  const personalAgentsDir = () => personalAgentsDirAtHome(options.homeDir);
+  const locateAgentFile: typeof locateAgentFileAtHome = (name, path, cwd, source) =>
+    locateAgentFileAtHome(name, path, cwd, source, options.homeDir);
   // Child AgentSessions load normal extensions. Re-entering this extension there
   // would create another manager and leak handlers. Nested orchestration is
   // injected as scoped custom tools by the existing manager instead.
@@ -345,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;
@@ -383,11 +446,15 @@ 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()), registry, process.cwd()));
+  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.
-  const bootSettings = loadSettings(process.cwd());
+  const bootSettings = loadSettings(process.cwd(), options.homeDir);
   let strictAgentFiles = bootSettings.strictAgentFiles === true;
   // Strict agent files fail a bind by throwing the host's `ExtensionStartupError`
   // from `session_start`. A host without that class would silently degrade to
@@ -412,7 +479,7 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
 
   /** Reload agents from package/global/project agent dirs and merge with defaults (called on init and each Agent invocation). */
   const reloadCustomAgents = (strict = false) => {
-    const userAgents = loadCustomAgents(process.cwd(), strict);
+    const userAgents = loadCustomAgents(process.cwd(), strict, { homeDir: options.homeDir });
     registerAgents(userAgents);
   };
 
@@ -464,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
@@ -471,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);
@@ -492,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();
   }
@@ -508,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`;
@@ -525,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 } : {}),
             };
           },
         });
@@ -538,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
@@ -564,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,
@@ -571,6 +704,8 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
       durationMs,
       tokens,
       usage,
+      // Stamped by the only caller, the settle path, just before this runs.
+      settleSeq: record.settleSeq,
     };
   }
 
@@ -580,19 +715,84 @@ 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 {
+      ...(record?.modelTier ? { modelTier: record.modelTier } : {}),
+      ...(record?.modelFallback ? { modelFallback: record.modelFallback } : {}),
+      ...(modelSelectionNote(record) ? { modelNote: modelSelectionNote(record) } : {}),
+    };
+  }
+
+  /** The `subagents:record` history entry; the ONE builder, shared by live completion and the detached spool. */
+  function historyRecord(record: AgentRecord): Record<string, unknown> {
+    return {
+      id: record.id, type: record.type, description: record.description,
+      status: record.status, result: record.result, error: record.error,
+      startedAt: record.startedAt, completedAt: record.completedAt,
+      ...(record.modelFallback ? { modelFallback: record.modelFallback } : {}),
+      ...(record.modelTier ? { modelTier: record.modelTier } : {}),
+    };
+  }
+
+  /**
+   * 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),
-        record: {
-          id: record.id, type: record.type, description: record.description,
-          status: record.status, result: record.result, error: record.error,
-          startedAt: record.startedAt, completedAt: record.completedAt,
+        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 */ }
   }
@@ -602,18 +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 {
-      if (result.record) pi.appendEntry("subagents:record", result.record);
+      // 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) => {
@@ -631,21 +875,13 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
       return;
     }
 
+    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", {
-      id: record.id, type: record.type, description: record.description,
-      status: record.status, result: record.result, error: record.error,
-      startedAt: record.startedAt, completedAt: record.completedAt,
-    });
+    pi.appendEntry("subagents:record", historyRecord(record));
 
     // Skip notification if result was already consumed via get_subagent_result
     if (record.resultConsumed) {
@@ -680,11 +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,
+      ...eventFields(record),
     });
   }, (record, info) => {
     if (!isTopLevelAgent(record)) return;
@@ -696,6 +935,7 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
       reason: info.reason,
       tokensBefore: info.tokensBefore,
       compactionCount: record.compactionCount,
+      ...eventFields(record),
     });
   }, (record, usage) => {
     // Every assistant message from every agent — nested included, exactly once.
@@ -731,7 +971,8 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
       // clamped it to the model, or an agent file outranked it), so a ledger
       // can show `low (asked minimal)` instead of silently relabelling.
       ...(invocation?.requestedThinking !== undefined ? { requestedThinking: invocation.requestedThinking } : {}),
-      depth: record.depth ?? 1,
+      ...fallbackFields(record),
+      depth: record.depth,
       ...(record.parentAgentId !== undefined ? { parentAgentId: record.parentAgentId } : {}),
       ...(record.workflowId !== undefined ? { workflowId: record.workflowId } : {}),
       usage: reported,
@@ -739,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);
+  }, 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.).
@@ -810,10 +1070,19 @@ 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.
     delete safeOptions.blocking;
+    // The spawn path's own disclosure; a caller-supplied one could hide a
+    // fallback or invent one. The runner reports the real outcome itself.
+    delete safeOptions.modelFallback;
+    delete safeOptions.modelSelection;
+    delete safeOptions.modelTier;
+    delete safeOptions.previousModelTier;
+    delete safeOptions.previousModelFallback;
     return spawnResolved(piRef, ctxRef, type, prompt, safeOptions);
   };
 
@@ -828,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 = {
@@ -847,6 +1121,7 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
 
   // --- Cross-extension RPC via pi.events ---
   let currentCtx: ExtensionContext | undefined;
+  let unwatchFleetSchedules: (() => void) | undefined;
   // RPC handlers + the `subagents:ready` broadcast are wired on `session_start`
   // (a bound lifecycle event), not at factory time. pi runs every extension
   // factory before the `extensions:` filter and only fires lifecycle events for
@@ -862,7 +1137,7 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
   // Session-scoped: store is constructed inside session_start once sessionId
   // is available. Mirrors pi-chonky-tasks's session-scoped task store —
   // schedules reset on /new, restore on /resume.
-  const scheduler = new SubagentScheduler({ clock: options.clock });
+  const scheduler = new SubagentScheduler({ clock: options.clock, homeDir: options.homeDir });
 
   function startScheduler(ctx: ExtensionContext) {
     try {
@@ -884,6 +1159,7 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
   // bound session_start, so a filtered-out activation never advertises (#142).
   pi.on("session_start", async (_event, ctx) => {
     currentCtx = ctx;
+    restoreFleetDisclosure(ctx);
     // Pi resolves project trust before the first session starts, so this is the
     // earliest honest answer. The activation-time load defaulted to untrusted,
     // so a trusted project's `packages[]` only becomes visible now.
@@ -899,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;
     }
@@ -911,6 +1187,7 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
       widget.setUICtx(ctx.ui);
       fleet.setUICtx(ctx.ui as any);
       watchHandoffKey(ctx.ui);
+      unwatchFleetSchedules ??= pi.events.on("subagents:scheduled", () => fleet.update());
     }
     manager.clearCompleted(true);
     const sessionFile = ctx.sessionManager?.getSessionFile?.();
@@ -919,12 +1196,15 @@ 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
     // fires once per activation, but a double-bind must not leak listeners.
     if (!rpcHandle) {
       rpcHandle = registerRpcHandlers({
+        homeDir: options.homeDir,
         events: pi.events,
         pi,
         getCtx: () => currentCtx,
@@ -944,6 +1224,7 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
             if (!record || record.parentAgentId) return false;
             if (record.status === "running" || record.status === "queued") return false;
             markConsumed(record, clock.now());
+            fleet.acknowledgeFailure(record.id);
             outbox.cancel(record.id);
             return true;
           },
@@ -956,6 +1237,7 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
       pi.events.emit("subagents:ready", {});
     }
     if (isSchedulingEnabled() && !scheduler.isActive()) startScheduler(ctx);
+    fleet.update(); // restored quota-parked jobs have no agent record
     // Stack `@handle` suggestions on pi's built-in autocomplete. Registered at
     // most once per activation: pi appends wrappers to a list it never prunes,
     // so a second call would layer a duplicate provider on the first. TUI only
@@ -981,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
@@ -1080,62 +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,
-          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" };
     }
 
@@ -1169,7 +1398,7 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
       // Not awaited: the clone runs a full model turn, and prompt() is blocked
       // until this hook returns. The user gets their prompt back immediately
       // and the agent appears in the widget when it starts.
-      void runMentionClone({ ctx, type, message: mention.message, agentTool: registeredAgentTool })
+      void runMentionClone({ ctx, type, message: mention.message, agentTool: registeredAgentTool, homeDir: options.homeDir })
         .then(async (result) => {
           if (result.spawned) return;
           // A clone that could not run must not swallow the mention: start the
@@ -1186,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",
             );
           }
@@ -1195,7 +1424,7 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
     }
 
     try {
-      // Nothing else to pass: runAgent resolves model, thinking, max turns and
+      // Nothing else to pass: the manager resolves model; runAgent resolves thinking, max turns and
       // `isolated` from the agent's own config when the spawn omits them, and the
       // manager's onStart/onComplete callbacks own the widget, the fleet list
       // and the completion notification — the same contract the scheduler and
@@ -1210,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" };
   });
@@ -1227,9 +1456,12 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
   // to this session (see detached-results.ts). Only agents that cannot outlive the
   // session are aborted.
   pi.on("session_shutdown", async (event: { reason?: string }) => {
+    fleet.flushState(); // appendEntry must run before this activation loses its context
     const sessionFile = currentCtx?.sessionManager?.getSessionFile?.();
     unwatchDetached?.();
     unwatchDetached = undefined;
+    unwatchAnnounce?.();
+    unwatchAnnounce = undefined;
     rpcHandle?.unsubSpawn();
     rpcHandle?.unsubStop();
     rpcHandle?.unsubPing();
@@ -1260,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."); }
       }
     }
@@ -1276,6 +1513,8 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
     widget.dispose();
     outbox.dispose();
     fleet.dispose();
+    unwatchFleetSchedules?.();
+    unwatchFleetSchedules = undefined;
     unsubHandoffKey?.();
     unsubHandoffKey = undefined;
     handoffKeyUi = undefined;
@@ -1290,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),
         });
       }
@@ -1340,16 +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,
-        });
-      }
+      // 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();
@@ -1412,6 +1652,18 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
     getFullscreenScrollbar, backgroundActionFor, isShowModelEnabled,
     // 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 => {
+      pi.appendEntry(FLEET_STATE_ENTRY, { ...state, version: FLEET_STATE_VERSION });
+    });
+  }
+  pi.on("session_tree", (_event, ctx) => {
+    restoreFleetDisclosure(ctx);
+    fleet.update();
+  });
   /** What the Agent tool row reads at render time, so its summary stays live. */
   const agentRowLive: AgentRowLive = {
     getRecord: (id) => manager.getRecord(id),
@@ -1552,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
@@ -1571,24 +1917,31 @@ 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).
     if (opts.outputTranscript) {
       existing.outputFile = createOutputFilePath(ctx.cwd, id, ctx.sessionManager.getSessionId());
       ensureOutputFile(existing.outputFile);
+      // A fresh transcript for a later resume must still say what the agent ran on.
+      if (existing.modelFallback) appendModelFallbackEntry(existing.outputFile, id, existing.modelFallback);
+      if (existing.modelTier) appendModelTierEntry(existing.outputFile, id, existing.modelTier);
     }
     // 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 —
@@ -1642,6 +1995,8 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
       type: existing.type,
       description: existing.description,
       isBackground: true,
+      ...(record.status === "queued" && priorSettleSeq !== undefined ? { queuedAfterSettleSeq: priorSettleSeq, queuedResumeSeq: resumeSeq } : {}),
+      ...eventFields(existing),
     });
 
     return record;
@@ -1662,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");
   };
 
@@ -1685,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. */
@@ -1714,6 +2080,7 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
       setBudgetPolicy,
       setDefaultMaxTurns,
       setGraceTurns,
+      setNotificationResultChars: (n) => { notificationResultChars = n; },
       setDefaultJoinMode,
       setBackgroundByDefault,
       setSchedulingEnabled,
@@ -1740,6 +2107,8 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
       setPackageWorkflows: setPackageWorkflowsGate,
     },
     (event, payload) => pi.events.emit(event, payload),
+    process.cwd(),
+    options.homeDir,
   );
 
   // ---- Agent tool ----
@@ -1774,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.
@@ -1794,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.
 
@@ -1819,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 specify a different model (as "provider/modelId", or fuzzy e.g. "haiku", "sonnet").
+- ${modelGuideline()}
 - Use thinking to control extended thinking level.
 - Use inherit_context if the agent needs the parent conversation history.${isolationGuideline}${scheduleGuideline}
 
@@ -1871,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;
@@ -1923,8 +2315,7 @@ Terse command-style prompts produce shallow, generic work.
       }),
       model: Type.Optional(
         Type.String({
-          description:
-            'Optional model override. Accepts "provider/modelId" or fuzzy name (e.g. "haiku", "sonnet"). Omit to use the agent type\'s default.',
+          description: modelParamDescription(),
         }),
       ),
       thinking: Type.Optional(
@@ -1945,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(
@@ -2040,7 +2431,7 @@ Terse command-style prompts produce shallow, generic work.
       // foreground path. Resume deliberately doesn't: it replays the stored
       // session and ignores `subagent_type` entirely, so a note about type
       // substitution would be describing something that didn't happen.
-      const fallbackNote = dispatch.ok && dispatch.fellBackFrom !== undefined
+      const typeNote = dispatch.ok && dispatch.fellBackFrom !== undefined
         ? `Note: Unknown agent type "${dispatch.fellBackFrom}" — using ${resolveType(subagentType) ? subagentType : "the fallback agent config"}.\n\n`
         : "";
 
@@ -2050,36 +2441,22 @@ Terse command-style prompts produce shallow, generic work.
       const customConfig = getAgentConfig(subagentType);
 
       const resolvedConfig = resolveAgentInvocationConfig(customConfig, params, {
-        agentType: subagentType,
         worktreeAllowed: isWorktreeIsolationEnabled(),
         defaultRunInBackground: getBackgroundByDefault(),
       });
 
-      // Resolve an explicit tool-call model first; agent config supplies only a default.
-      let model = ctx.model;
-      if (resolvedConfig.modelInput) {
-        const resolved = resolveModel(resolvedConfig.modelInput, ctx.modelRegistry);
-        if (typeof resolved === "string") {
-          if (resolvedConfig.modelFromParams) return textResult(resolved);
-          // config-specified: silent fallback to parent
-        } else {
-          model = resolved;
-        }
-      }
-
-      // Scope validation: the effective resolved model is checked against the
-      // user's enabledModels list. Policy (hard error vs warn-and-proceed) lives
-      // in model-scope.ts so the nested delegation tools apply the same rule.
-      const scopeVerdict = checkModelScope({
-        model,
-        cwd: ctx.cwd,
-        modelRegistry: ctx.modelRegistry,
-        callerSupplied: resolvedConfig.modelFromParams,
-        agentLabel: customConfig?.displayName ?? subagentType,
-        modelInput: resolvedConfig.modelInput,
+      // A live resume keeps its record's selection, ignoring new model inputs.
+      const selection = params.resume ? undefined : selectModel({
+        homeDir: options.homeDir,
+        agentType: subagentType, definitionModel: customConfig?.model, paramModel: params.model,
+        parentModel: ctx.model, registry: ctx.modelRegistry, cwd: ctx.cwd, agentLabel: customConfig?.displayName,
       });
-      if (scopeVerdict.kind === "error") return textResult(scopeVerdict.message);
-      if (scopeVerdict.kind === "warn") ctx.ui.notify(scopeVerdict.message, "warning");
+      if (typeof selection === "string") return { ...textResult(selection), isError: true };
+      const tierBlock = selection?.tierBinding && !params.schedule ? await admitModelSelection(selection, ctx.modelRegistry, pi.events) : undefined;
+      const model = selection?.model;
+      const modelFallback = selection?.fallback;
+
+      if (selection?.scopeWarning) ctx.ui.notify(selection.scopeWarning, "warning");
 
       const thinking = resolvedConfig.thinking;
       const inheritContext = resolvedConfig.inheritContext;
@@ -2088,7 +2465,7 @@ Terse command-style prompts produce shallow, generic work.
       const isolation = resolvedConfig.isolation;
       // Undefined = the session cwd. The manager validates it (absolute,
       // existing directory) at spawn and again at start.
-      const cwd = resolveCwdParam(params.cwd, ctx.cwd);
+      const cwd = resolveCwdParam(params.cwd, ctx.cwd, options.homeDir);
       // Whether this spawn writes its .output transcript. Per-agent
       // frontmatter (`output_transcript`) wins; otherwise the project/global
       // default applies. `attachTranscript` below is the SOLE gate — every
@@ -2106,9 +2483,7 @@ Terse command-style prompts produce shallow, generic work.
       // parent's model used to show the level with nothing to attach it to.
       // This is the pre-session snapshot — agent-manager overwrites it with the
       // effective values the moment a session reports them.
-      const { modelName, modelId } = model
-        ? isVirtualModel(model) ? describeVirtualModel(model) : describeModel(model)
-        : { modelName: undefined, modelId: undefined };
+      const { modelName, modelId } = describeSelection(selection, ctx.modelRegistry);
       const effectiveMaxTurns = normalizeMaxTurns(resolvedConfig.maxTurns ?? getDefaultMaxTurns());
       const agentInvocation: AgentInvocation = {
         modelName,
@@ -2126,11 +2501,34 @@ Terse command-style prompts produce shallow, generic work.
       const modeLabel = getPromptModeLabel(subagentType);
       const { tags: invocationTags } = buildInvocationTags(agentInvocation);
       const agentTags = modeLabel ? [modeLabel, ...invocationTags] : invocationTags;
+      /**
+       * The lead-in for a result: the type note, then the model note. The model
+       * note is read off the record the shared spawn path created. Before a
+       * record exists (scheduling) it is this call's own resolution, the only
+       * one there is. Never recomputed for a resume, which runs on its old session.
+       */
+      const modelNoteOf = (rec: AgentRecord | undefined): string | undefined =>
+        modelSelectionNote(rec ?? { modelFallback, modelTier: selection?.tier }) || undefined;
+      const modelFallbackOf = (rec: AgentRecord | undefined): ModelFallback | undefined =>
+        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), modelIdentityNote(rec)].filter(Boolean).join("\n");
+        return note ? `${note}\n\n` : "";
+      };
+      const fallbackNoteFor = (rec: AgentRecord | undefined): string => {
+        // 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 = {
         displayName,
         description: params.description,
         subagentType,
         modelName,
+        modelNote: modelNoteOf(undefined),
+        modelFallback: modelFallbackOf(undefined),
+        modelTier: selection?.tier ? tierDisclosure(selection.tier) : undefined,
         tags: agentTags.length > 0 ? agentTags : undefined,
       };
 
@@ -2148,7 +2546,10 @@ Terse command-style prompts produce shallow, generic work.
        * buildInvocationTags would silently drop `twin`.
        */
       const detailBaseFor = (rec: AgentRecord | undefined): typeof detailBase => {
-        if (!rec?.invocation) return detailBase;
+        // A record's disclosure outranks this call's, even before its session
+        // reports an invocation: resume reuses the old session, so this call's
+        // config says nothing about what ran.
+        if (!rec?.invocation) return rec ? { ...detailBase, modelNote: modelNoteOf(rec), modelFallback: modelFallbackOf(rec), modelTier: rec.modelTier } : detailBase;
         const type = rec.type;
         const { modelName: recModelName, tags } = buildInvocationTags(rec.invocation);
         const recModeLabel = getPromptModeLabel(type);
@@ -2158,6 +2559,9 @@ Terse command-style prompts produce shallow, generic work.
           description: rec.description,
           subagentType: type,
           modelName: recModelName,
+          modelNote: modelNoteOf(rec),
+          modelFallback: modelFallbackOf(rec),
+          modelTier: rec.modelTier,
           tags: recTags.length > 0 ? recTags : undefined,
         };
       };
@@ -2182,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,
@@ -2191,7 +2596,7 @@ Terse command-style prompts produce shallow, generic work.
             // at fire time, and the original is what a user edits.
             subagent_type: requestedType,
             prompt: params.prompt as string,
-            model: params.model as string | undefined,
+            model: selection?.requested?.startsWith("@") ? selection.requested : params.model as string | undefined,
             thinking: thinking,
             max_turns: effectiveMaxTurns,
             isolated: isolated,
@@ -2199,23 +2604,62 @@ Terse command-style prompts produce shallow, generic work.
           });
           const next = scheduler.getNextRun(job.id);
           return textResult(
-            `${fallbackNote}Scheduled "${job.name}" (id: ${job.id}, type: ${job.scheduleType}). ` +
+            `${fallbackNoteFor(undefined)}Scheduled "${job.name}" (id: ${job.id}, type: ${job.scheduleType}). ` +
             `Next run: ${next ?? "(unknown)"}. ` +
             `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.
@@ -2233,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.`,
           );
         }
@@ -2252,7 +2696,7 @@ Terse command-style prompts produce shallow, generic work.
 
           const isQueued = record.status === "queued";
           return textResult(
-            `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` : "") +
@@ -2275,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,
@@ -2294,10 +2738,10 @@ Terse command-style prompts produce shallow, generic work.
         // A failed resume surfaces the error, plus any partial output THIS
         // resume produced (never the previous turn's answer, #144).
         if (record.status === "error") {
-          return textResult(`Agent failed: ${record.error}${partialOutputSuffix(record)}`, buildDetails(detailBaseFor(record), record, resumeState));
+          return textResult(`${resumeNoteFor(record)}Agent failed: ${record.error}${partialOutputSuffix(record)}`, buildDetails(detailBaseFor(record), record, resumeState));
         }
         return textResult(
-          record.result?.trim() || "No output.",
+          `${continued}${resumeNoteFor(record)}${record.result?.trim() || "No output."}`,
           buildDetails(detailBaseFor(record), record, resumeState),
         );
       }
@@ -2308,7 +2752,7 @@ Terse command-style prompts produce shallow, generic work.
       const backgroundResult = (id: string, record: AgentRecord | undefined) => {
         const isQueued = record?.status === "queued";
         return textResult(
-          `${fallbackNote}Agent ${isQueued ? "queued" : "started"} in background.\n` +
+          `${fallbackNoteFor(record)}Agent ${isQueued ? "queued" : "started"} in background.\n` +
           `Agent ID: ${id}\n` +
           `Type: ${displayName}\n` +
           `Description: ${params.description}\n` +
@@ -2327,21 +2771,25 @@ Terse command-style prompts produce shallow, generic work.
       // exhaustion policy says fail now (`wait: false`). Anything else fails
       // now, with the reset, rather than starting on an exhausted provider.
       const dispatchModel = model ?? ctx.model;
-      const quotaBlock = dispatchModel ? await checkAdmission(pi.events, modelRef(dispatchModel), undefined, clock) : undefined;
+      const quotaBlock = selection?.tierBinding ? tierBlock
+        : dispatchModel ? await checkAdmission(pi.events, modelRef(dispatchModel), undefined, clock) : undefined;
       if (quotaBlock) {
         // A parked job is a scheduled job, which has no `cwd` to carry.
         const canPark = runInBackground && !inheritContext && cwd === undefined && mayPark(quotaBlock)
           && isSchedulingEnabled() && scheduler.isActive();
         if (!canPark || !mayPark(quotaBlock)) {
-          throw new Error(`${describeBlock(quotaBlock)} The agent was not started.`);
+          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,
           schedule: new Date(quotaBlock.resetAt + QUOTA_RESTART_GRACE_MS).toISOString(),
           subagent_type: requestedType,
           prompt: params.prompt as string,
-          model: dispatchModel ? modelRef(dispatchModel) : undefined,
+          // Keep the request, not today's configured/parent pick. Fire-time
+          // selection must still apply agentModels and aliases.
+          model: selection?.requested?.startsWith("@") ? selection.requested : params.model,
           thinking,
           max_turns: effectiveMaxTurns,
           isolated,
@@ -2349,8 +2797,8 @@ Terse command-style prompts produce shallow, generic work.
           quotaParked: true,
         });
         return textResult(
-          `${fallbackNote}${describeBlock(quotaBlock)} Queued "${job.name}" (id: ${job.id}) to start at ` +
-          `${scheduler.getNextRun(job.id) ?? job.schedule}. Manage via /agents → Scheduled jobs.`,
+          `${fallbackNoteFor(undefined)}${describeBlock(quotaBlock)} Queued "${job.name}" (id: ${job.id}) to start at ` +
+          `${job.schedule}. Manage via /agents → Scheduled jobs.`,
         );
       }
 
@@ -2359,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) => {
@@ -2375,6 +2822,7 @@ Terse command-style prompts produce shallow, generic work.
         // tool call failed, whereas a returned message reads to the model as a
         // subagent that ran and reported this (#179).
         id = manager.spawn(pi, ctx, subagentType, params.prompt, {
+          modelSelection: selection,
           description: params.description,
           name: params.name as string | undefined,
           model,
@@ -2387,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
@@ -2420,6 +2867,7 @@ Terse command-style prompts produce shallow, generic work.
           type: subagentType,
           description: params.description,
           isBackground: true,
+          ...eventFields(manager.getRecord(id)),
         });
 
         return backgroundResult(id, record);
@@ -2478,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);
@@ -2497,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)
@@ -2528,6 +2970,7 @@ Terse command-style prompts produce shallow, generic work.
       let fgResult: { record: AgentRecord } | undefined;
       try {
         fgResult = await Promise.race([manager.spawnAndWait(pi, ctx, subagentType, params.prompt, {
+          modelSelection: selection,
           description: params.description,
           name: params.name as string | undefined,
           model,
@@ -2544,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;
@@ -2557,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();
           });
@@ -2591,10 +3032,10 @@ Terse command-style prompts produce shallow, generic work.
 
       if (record.status === "error") {
         // Error headline + any partial output the run produced before failing.
-        return textResult(`${fallbackNote}Agent failed: ${record.error}${partialOutputSuffix(record)}`, details);
+        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) {
@@ -2602,7 +3043,7 @@ Terse command-style prompts produce shallow, generic work.
         if (costText) statsParts.push(costText);
       }
       return textResult(
-        `${fallbackNote}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,
       );
@@ -2685,13 +3126,15 @@ 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,
       startedAt: task.startTime,
       ...(task.endTime !== undefined ? { completedAt: task.endTime } : {}),
       tokens: task.totalTokens,
+      observationKey: task,
     }));
   }
 
@@ -2708,6 +3151,7 @@ Terse command-style prompts produce shallow, generic work.
         args: task.args,
         signal: task.abortController.signal,
         host: createWorkflowHost({
+          homeDir: options.homeDir,
           pi,
           ctx,
           manager,
@@ -2728,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));
     }
   }
 
@@ -2745,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.
@@ -2865,6 +3309,7 @@ Terse command-style prompts produce shallow, generic work.
           ? { scriptPath: resumeFrom.scriptPath }
           : params,
         ctx.cwd,
+        options.homeDir,
       );
       if (!resolved.ok) return textResult(resolved.message);
 
@@ -2875,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();
@@ -2893,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;
@@ -2928,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`
                 : "") +
@@ -3053,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;
     }
 
@@ -3061,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;
     }
 
@@ -3100,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({
@@ -3149,8 +3594,10 @@ 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` +
-        `Description: ${record.description}\n\n`;
+        `Type: ${displayName} | Status: ${record.status}${getStatusNote(record.status, record.stoppedBy)} | ${statsParts.join(" | ")}\n` +
+        `Description: ${record.description}\n` +
+        (modelSelectionNote(record) ? `${modelSelectionNote(record)}\n` : "") +
+        `\n`;
 
       if (record.status === "running") {
         output += "Agent is still running. Use wait: true or check back later.";
@@ -3163,6 +3610,7 @@ Terse command-style prompts produce shallow, generic work.
       // Mark result as consumed — suppresses the completion notification
       if (record.status !== "running" && record.status !== "queued") {
         markConsumed(record, clock.now());
+        fleet.acknowledgeFailure(record.id);
         outbox.cancel(record.id);
       }
 
@@ -3184,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
@@ -3232,32 +3703,134 @@ 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);
-    if (!cfg?.model) return "inherit"; // no model configured → really inherits parent
-    const label = getModelLabelFromConfig(cfg.model);
-    if (!registry) return label;
-    const resolved = resolveModel(cfg.model, registry);
-    // Configured but unresolvable: the runtime silently falls back to the parent
-    // model, so flag it (and the fallback) rather than hiding the config.
-    if (typeof resolved === "string") return `${label} (unavailable, fallback: inherit)`;
+    const input = modelRequest(type, cfg?.model).requested;
+    if (!input) return "inherit";
+    const label = getModelLabelFromConfig(input);
+    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)`;
+    }
+    const resolved = selection.model;
     // Surface what it actually resolved to when that differs from the config —
     // e.g. a provider fallback or a looser version pin. Cosmetic separator/date
     // differences are normalized away so an effectively-identical match stays quiet.
     const resolvedFull = `${resolved.provider}/${resolved.id}`;
     const norm = (s: string) => s.toLowerCase().replace(/\./g, "-").replace(/-\d{8}$/, "");
-    if (norm(cfg.model) === norm(resolvedFull)) return label;
+    if (norm(input) === norm(resolvedFull)) return label;
     return `${label} (→ ${resolvedFull.replace(/-\d{8}$/, "")})`;
   }
 
@@ -3275,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) {
@@ -3313,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);
@@ -3337,7 +3919,7 @@ Terse command-style prompts produce shallow, generic work.
    */
   function packageNameOf(cfg: AgentConfig | undefined): string | undefined {
     if (cfg?.source !== "package" || !cfg.sourcePath) return undefined;
-    return packageNameForPath(cfg.sourcePath, process.cwd());
+    return packageNameForPath(cfg.sourcePath, process.cwd(), "agents", { homeDir: options.homeDir });
   }
 
   async function showAllAgentsList(ctx: ExtensionCommandContext) {
@@ -3356,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}`,
@@ -3391,8 +3973,9 @@ Terse command-style prompts produce shallow, generic work.
       };
     });
 
-    if (selected && getAgentConfig(selected)) {
-      await showAgentDetail(ctx, selected);
+    const cfg = selected ? getAgentConfig(selected) : undefined;
+    if (selected && cfg) {
+      await showAgentDetail(ctx, selected, cfg);
       await showAllAgentsList(ctx);
     }
   }
@@ -3433,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);
       },
@@ -3446,13 +4029,7 @@ Terse command-style prompts produce shallow, generic work.
     );
   }
 
-  async function showAgentDetail(ctx: ExtensionCommandContext, name: string) {
-    const cfg = getAgentConfig(name);
-    if (!cfg) {
-      ctx.ui.notify(`Agent config not found for "${name}".`, "warning");
-      return;
-    }
-
+  async function showAgentDetail(ctx: ExtensionCommandContext, name: string, cfg: AgentConfig) {
     const isPackage = cfg.source === "package";
     const file = locateAgentFile(name, cfg.sourcePath, undefined, cfg.source);
     const isDefault = cfg.isDefault === true;
@@ -3470,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"];
@@ -3779,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
@@ -3831,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(),
@@ -3862,6 +4440,8 @@ Write the file using the write tool. Only write the file, nothing else.`;
       maxActiveSubagents: undefined,
       nestedSubagentReserve: undefined,
       modelAliases: undefined,
+      modelTiers: undefined,
+      modelResolution: undefined,
       agentModels: undefined,
       reportUsage: isReportUsageEnabled(),
       showCost: isShowCostEnabled(),
@@ -3909,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) {
@@ -3962,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",
@@ -4159,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) {
@@ -4300,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}`);
       }
@@ -4360,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+)"
@@ -4370,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.