@cad0p/pi-subagents-tintinweb 0.14.2 → 0.22.0

package/src/index.ts

@@ -10,46 +10,50 @@
  *   /agents                 — Interactive agent management menu
  */
 
-import { appendFileSync, existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
-import { defineTool, type ExtensionAPI, type ExtensionCommandContext, type ExtensionContext, getAgentDir, getMarkdownTheme, getSettingsListTheme } from "@earendil-works/pi-coding-agent";
-import { Container, Key, Markdown, matchesKey, type SettingItem, SettingsList, Spacer, Text } from "@earendil-works/pi-tui";
+import { defineTool, type ExtensionAPI, type ExtensionCommandContext, type ExtensionContext, getAgentDir, getMarkdownTheme, getSettingsListTheme, keyText, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Container, Key, Markdown, matchesKey, type SettingItem, SettingsList, Spacer, Text, truncateToWidth } from "@earendil-works/pi-tui";
 import { Type } from "@sinclair/typebox";
-import { AgentManager } from "./agent-manager.js";
+import { AgentManager, type SpawnOptions } from "./agent-manager.js";
 import { getDefaultMaxTurns, getGraceTurns, normalizeMaxTurns, SUBAGENT_TOOL_NAMES, setDefaultMaxTurns, setGraceTurns, steerAgent } from "./agent-runner.js";
-import { BUILTIN_TOOL_NAMES, getAgentConfig, getAllTypes, getAvailableTypes, isDefaultsDisabled, registerAgents, resolveType, setDefaultsDisabled } from "./agent-types.js";
+import { BUILTIN_TOOL_NAMES, getAgentConfig, getAllTypes, getAvailableTypes, getFallbackSubagent, IMPLICIT_FALLBACK, isDefaultsDisabled, isFallbackResolvable, NO_FALLBACK, registerAgents, resolveSpawnType, resolveType, setDefaultsDisabled, setFallbackSubagent } from "./agent-types.js";
+import { saveCheckpoint } from "./checkpoint.js";
+import { inChildSessionContext } from "./child-context.js";
 import { type RpcHandle, registerRpcHandlers } from "./cross-extension-rpc.js";
 import { loadCustomAgents } from "./custom-agents.js";
-import { isModelInScope, readEnabledModels, resolveEnabledModels } from "./enabled-models.js";
-import { GroupJoinManager } from "./group-join.js";
-import { resolveAgentInvocationConfig, resolveJoinMode } from "./invocation-config.js";
-import { type ModelRegistry, resolveModel } from "./model-resolver.js";
-import { createOutputFilePath, streamToOutputFile, writeInitialEntry } from "./output-file.js";
+import { isolationParam, resolveAgentInvocationConfig } from "./invocation-config.js";
+import { describeModel, type ModelRegistry, resolveModel } from "./model-resolver.js";
+import { isScopeModelsEnabled, modelScopeWarning, setScopeModelsEnabled } from "./model-scope.js";
+import { getMaxSubagentDepth, setMaxSubagentDepth } from "./nested-tools.js";
+import { createOutputFilePath, getOutputTranscriptDefault, setOutputTranscriptDefault, streamToOutputFile, writeInitialEntry } from "./output-file.js";
+import { formatLifetimeTokens, renderAgentReport, setReportShowCost } from "./result-report.js";
 import { SubagentScheduler } from "./schedule.js";
 import { resolveStorePath, ScheduleStore } from "./schedule-store.js";
-import { applyAndEmitLoaded, RESULT_PREVIEW_MAX_CHARS_CEILING, type SubagentsSettings, saveAndEmitChanged, type ToolDescriptionMode } from "./settings.js";
+import { applyAndEmitLoaded, DEFAULT_SHOW_COST, FAILURE_PREVIEW_MAX_CHARS_CEILING, fallbackRow, loadSettings, type SubagentsSettings, saveAndEmitChanged, type ToolDescriptionMode } from "./settings.js";
 import { getStatusNote } from "./status-note.js";
-import { type AgentConfig, type AgentInvocation, type AgentRecord, type JoinMode, type NotificationDetails, type ResultPreviewMode, type SubagentType, type WidgetMode } from "./types.js";
+import { safeTruncate, stripControlChars, toSingleLine } from "./text-safety.js";
+import { type AgentConfig, type AgentInvocation, type AgentRecord, type SubagentType, type WidgetMode } from "./types.js";
 import {
   type AgentActivity,
   type AgentDetails,
   AgentWidget,
   buildInvocationTags,
-  describeActivity,
   fgPreservingNestedStyles,
+  formatCost,
   formatDuration,
   formatMs,
   formatTokens,
   formatTurns,
   getDisplayName,
   getPromptModeLabel,
-  SPINNER,
   type Theme,
   type UICtx,
 } from "./ui/agent-widget.js";
 import { FleetList, type FleetUICtx } from "./ui/fleet-list.js";
 import { showSchedulesMenu } from "./ui/schedule-menu.js";
-import { addUsage, getLifetimeTotal, getSessionContextPercent, type LifetimeUsage } from "./usage.js";
+import { addUsage, formatSessionContext, getLifetimeCost, getLifetimeTotal, getSessionContextPercent, type LifetimeUsage, PendingUsagePool, toReportedUsage } from "./usage.js";
+import { isWorktreeIsolationEnabled, setWorktreeIsolationEnabled } from "./worktree.js";
 
 // ---- Shared helpers ----
 
@@ -58,38 +62,11 @@ function textResult<D>(msg: string, details?: D) {
   return { content: [{ type: "text" as const, text: msg }], details };
 }
 
-/** Derive the `.checkpoints.md` path from `outputFile`. Mirrors the
- *  `record.outputFile` gate (undefined when suppressed). Appends the suffix
- *  unconditionally — a `replace(/\.output$/, ...)` would silently return the
- *  transcript path unchanged if `outputFile` ever lacked the suffix. */
-function checkpointsFilePath(outputFile: string | undefined): string | undefined {
-  if (!outputFile) return undefined;
-  return `${outputFile}.checkpoints.md`;
-}
-
-export function renderRunningAgentStatus(
-  frame: string,
-  statsText: string,
-  activity: string,
-  theme: Pick<Theme, "fg">,
-): Container {
-  const container = new Container();
-  container.addChild(new Text(theme.fg("accent", frame) + (statsText ? " " + statsText : ""), 0, 0));
-  container.addChild(new Text(theme.fg("dim", `  ⎿  ${activity}`), 0, 0));
-  return container;
-}
-
-/** Format an agent's lifetime token total, or "" when zero. */
-function formatLifetimeTokens(o: { lifetimeUsage: LifetimeUsage }): string {
-  const t = getLifetimeTotal(o.lifetimeUsage);
-  return t > 0 ? formatTokens(t) : "";
-}
-
 /**
  * Create an AgentActivity state and spawn callbacks for tracking tool usage.
- * Used by both foreground and background paths to avoid duplication.
+ * Used by the background spawn and resume paths to avoid duplication.
  */
-function createActivityTracker(maxTurns?: number, onStreamUpdate?: () => void) {
+function createActivityTracker(maxTurns?: number) {
   const state: AgentActivity = {
     activeTools: new Map(),
     toolUses: 0,
@@ -110,22 +87,18 @@ function createActivityTracker(maxTurns?: number, onStreamUpdate?: () => void) {
         }
         state.toolUses++;
       }
-      onStreamUpdate?.();
     },
     onTextDelta: (_delta: string, fullText: string) => {
       state.responseText = fullText;
-      onStreamUpdate?.();
     },
     onTurnEnd: (turnCount: number) => {
       state.turnCount = turnCount;
-      onStreamUpdate?.();
     },
     onSessionCreated: (session: any) => {
       state.session = session;
     },
-    onAssistantUsage: (usage: { input: number; output: number; cacheWrite: number }) => {
+    onAssistantUsage: (usage: LifetimeUsage) => {
       addUsage(state.lifetimeUsage, usage);
-      onStreamUpdate?.();
     },
   };
 
@@ -134,244 +107,248 @@ function createActivityTracker(maxTurns?: number, onStreamUpdate?: () => void) {
 
 /**
  * Advertised thinking levels, ordered to mirror pi-ai's EXTENDED_THINKING_LEVELS
- * (`off` + every `ThinkingLevel`). Single source for the Agent tool description,
- * the generated-agent template, and the `/agents` wizard so these lists can't
- * drift behind pi again (#147). Availability of any level still depends on the
- * host pi version and the selected model — pi clamps unsupported levels down.
+ * (`off` + every `ThinkingLevel`). Single source for the generated-agent template
+ * and the `/agents` wizard so these lists can't drift behind pi again (#147).
+ * Availability of any level still depends on the host pi version and the
+ * selected model — pi clamps unsupported levels down.
  */
 const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
 
-/**
- * Salvaged partial output of a failed run, as a labeled suffix for the error
- * surfaces (or "" if the run produced nothing). `record.result` is bounded to
- * the run's own turns, so this is never a stale earlier answer (#144).
- */
-function partialOutputSuffix(record: AgentRecord): string {
-  const partial = record.result?.trim();
-  return partial ? `\n\nPartial output before the failure:\n${partial}` : "";
+/** Human-readable status word for the completion report header. */
+function getStatusWord(status: string): string {
+  switch (status) {
+    case "completed": return "completed";
+    case "error": return "error";
+    case "stopped": return "stopped";
+    case "aborted": return "aborted";
+    case "steered": return "wrapped up (turn limit)";
+    default: return sanitizeHeaderText(String(status)) || "unknown";
+  }
 }
 
-/** Human-readable status label for agent completion. */
-function getStatusLabel(status: string, error?: string): string {
+/** Completion-report glyph: success only for terminal success statuses. */
+function getStatusGlyph(status: string): string {
   switch (status) {
-    case "error": return `Error: ${error ?? "unknown"}`;
-    case "aborted": return "Aborted (max turns exceeded)";
-    case "steered": return "Wrapped up (turn limit)";
-    case "stopped": return "Stopped";
-    default: return "Done";
+    case "completed":
+    case "steered": return "✓";
+    case "error":
+    case "stopped":
+    case "aborted": return "✗";
+    default: return "○";
   }
 }
 
-/** Escape XML special characters to prevent injection in structured notifications. */
-function escapeXml(s: string): string {
-  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+/**
+ * Collapse newlines/CRs/tabs and strip control/invisible characters from text
+ * that is composed into the report header or metadata lines.
+ */
+function sanitizeHeaderText(s: string): string {
+  return toSingleLine(s);
 }
 
-// Collapsed preview line limit - matches pi's read/write tool precedent
-const COLLAPSED_PREVIEW_LINES = 10;
-const PLAIN_MODE_EXPANDED_LINE_CAP = 30; // Preserves upstream renderer's expanded-mode line cap. Plain mode is the backward-compatibility path; markdown mode is uncapped per spec.
-const PLAIN_MODE_COLLAPSED_CHAR_CAP = 80; // Preserves upstream renderer's first-line preview char cap. Plain mode is the backward-compatibility path.
 const DEFAULT_FAILURE_PREVIEW_MAX_CHARS = 65536; // 64 KiB at ASCII.
+const HEADER_PREVIEW_MAX_CHARS = 300; // ~one wrapped line; description/error are untrusted input.
 
-/** Truncate to maxChars UTF-16 code units, never splitting a surrogate pair. */
-function safeTruncate(s: string, maxChars: number): string {
-  if (s.length <= maxChars) return s;
-  const high = s.charCodeAt(maxChars - 1);
-  return high >= 0xD800 && high <= 0xDBFF ? s.slice(0, maxChars - 1) : s.slice(0, maxChars);
+/** Bound a sanitized header field to the shared preview cap, marking truncation. */
+function headerPreview(s: string): string {
+  return s.length > HEADER_PREVIEW_MAX_CHARS ? `${safeTruncate(s, HEADER_PREVIEW_MAX_CHARS)}…` : s;
 }
 
-/** Build the preview body shared by XML payload + UI details. Caps failure-mode bodies; success/aborted/steered uncapped. */
-function buildResultPreview(record: AgentRecord, settings: SubagentsSettings): string {
-  const body = record.result ?? record.error ?? "";
-  if (!body) return "No output.";
-  const isFailure = record.status === "error" || record.status === "stopped";
-  if (isFailure && typeof settings.failurePreviewMaxChars !== "number") {
-    throw new Error("buildResultPreview: failurePreviewMaxChars must be a number on failure status");
-  }
-  const cap = isFailure ? (settings.failurePreviewMaxChars as number) : Number.POSITIVE_INFINITY;
-  return body.length > cap
-    ? safeTruncate(body, cap) + "\n…(truncated, see transcript)"
-    : body;
+const INSTRUCTION_PREVIEW_SCAN_CHARS = 512;   // per-render sanitizer window for the steer preview
+const INSTRUCTION_PREVIEW_COLS = 80;          // column budget for the steer preview
+
+/** Expanded body copy of a parent→child instruction — full text, no caps. */
+function instructionBody(raw: string, theme: Pick<Theme, "fg">): string {
+  const text = stripControlChars(raw).trimEnd();
+  if (!text.trim()) return "";   // whitespace-only → no stray blank line
+  return text
+    .split("\n")
+    .map((l) => theme.fg("dim", `  ${l}`))
+    .join("\n");
 }
 
-/** @internal Format a structured task notification matching Claude Code's <task-notification> XML. */
-export function formatTaskNotification(record: AgentRecord, settings: SubagentsSettings): string {
-  const status = getStatusLabel(record.status, record.error);
-  const durationMs = record.completedAt ? record.completedAt - record.startedAt : 0;
-  const totalTokens = getLifetimeTotal(record.lifetimeUsage);
-  const contextPercent = getSessionContextPercent(record.session);
-  const ctxXml = contextPercent !== null ? `<context_percent>${Math.round(contextPercent)}</context_percent>` : "";
-  const compactXml = record.compactionCount ? `<compactions>${record.compactionCount}</compactions>` : "";
-
-  const resultPreview = buildResultPreview(record, settings);
-
-  return [
-    `<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>`,
-    `<usage><total_tokens>${totalTokens}</total_tokens><tool_uses>${record.toolUses}</tool_uses>${ctxXml}${compactXml}<duration_ms>${durationMs}</duration_ms></usage>`,
-    `</task-notification>`,
-  ].filter(Boolean).join('\n');
+/** Pure hint formatter — no global keybinding dependency, exported for tests. */
+export function formatInstructionHint(key: string, theme: Pick<Theme, "fg">): string {
+  return key ? theme.fg("dim", ` (${key} to expand)`) : "";
 }
 
-/** Build AgentDetails from a base + record-specific fields. */
-function buildDetails(
-  base: Pick<AgentDetails, "displayName" | "description" | "subagentType" | "modelName" | "tags">,
-  record: { toolUses: number; startedAt: number; completedAt?: number; status: string; error?: string; id?: string; session?: any; lifetimeUsage: LifetimeUsage },
-  activity?: AgentActivity,
-  overrides?: Partial<AgentDetails>,
-): AgentDetails {
-  return {
-    ...base,
-    toolUses: record.toolUses,
-    tokens: formatLifetimeTokens(record),
-    turnCount: activity?.turnCount,
-    maxTurns: activity?.maxTurns,
-    durationMs: (record.completedAt ?? Date.now()) - record.startedAt,
-    status: record.status as AgentDetails["status"],
-    agentId: record.id,
-    error: record.error,
-    ...overrides,
-  };
+/** ` (ctrl+o to expand)` for the user's current binding — omitted when unbound/headless. */
+function instructionHint(theme: Pick<Theme, "fg">): string {
+  return formatInstructionHint(keyText("app.tools.expand"), theme);
 }
 
-/** @internal Build notification details for the custom message renderer. */
-export function buildNotificationDetails(record: AgentRecord, settings: SubagentsSettings, activity?: AgentActivity): NotificationDetails {
-  const totalTokens = getLifetimeTotal(record.lifetimeUsage);
-
-  const resultPreview = buildResultPreview(record, settings);
-
-  return {
-    id: record.id,
-    description: record.description,
-    status: record.status,
-    toolUses: record.toolUses,
-    turnCount: activity?.turnCount ?? 0,
-    maxTurns: activity?.maxTurns,
-    totalTokens,
-    durationMs: record.completedAt ? record.completedAt - record.startedAt : 0,
-    outputFile: record.outputFile,
-    error: record.error,
-    resultPreview,
-  };
+/** The settings contract for the failure preview cap: a positive integer within the settings ceiling. */
+function isValidFailurePreviewCap(value: number): boolean {
+  return Number.isInteger(value) && value >= 1 && value <= FAILURE_PREVIEW_MAX_CHARS_CEILING;
 }
 
-/** @internal Render notification header with icon, description, status, and stats. */
-export function subagentNotificationRenderHeader(d: NotificationDetails, theme: any): any {
-  const isError = d.status === "error" || d.status === "stopped" || d.status === "aborted";
-  const icon = isError ? theme.fg("error", "✗") : theme.fg("success", "✓");
-  const statusText = isError ? d.status
-    : d.status === "steered" ? "completed (steered)"
-    : "completed";
-
-  // Line 1: icon + agent description + status
-  let line = `${icon} ${theme.bold(d.description)} ${theme.fg("dim", statusText)}`;
-
-  // Line 2: stats
-  const parts: string[] = [];
-  if (d.turnCount > 0) parts.push(formatTurns(d.turnCount, d.maxTurns));
-  if (d.toolUses > 0) parts.push(`${d.toolUses} tool use${d.toolUses === 1 ? "" : "s"}`);
-  if (d.totalTokens > 0) parts.push(formatTokens(d.totalTokens));
-  if (d.durationMs > 0) parts.push(formatMs(d.durationMs));
-  if (parts.length) {
-    line += "\n  " + parts.map(p => theme.fg("dim", p)).join(" " + theme.fg("dim", "·") + " ");
+/**
+ * @internal Coerce the in-memory failure preview cap for the send path:
+ * an out-of-contract value (a settings regression) falls back to the default
+ * instead of throwing away the completion. Warns once per invalid episode —
+ * a valid value re-arms the latch so a later distinct regression warns again,
+ * while a still-broken value does not log on every completion.
+ */
+let warnedInvalidFailurePreviewCap = false;
+export function effectiveFailurePreviewCap(value: number): number {
+  if (isValidFailurePreviewCap(value)) {
+    warnedInvalidFailurePreviewCap = false;
+    return value;
   }
-
-  return new Text(line, 0, 0);
+  if (!warnedInvalidFailurePreviewCap) {
+    warnedInvalidFailurePreviewCap = true;
+    console.warn(
+      `[pi-subagents] ignoring out-of-contract failurePreviewMaxChars (${String(value)}); using the default ${DEFAULT_FAILURE_PREVIEW_MAX_CHARS} for this notification`,
+    );
+  }
+  return DEFAULT_FAILURE_PREVIEW_MAX_CHARS;
 }
 
-/** @internal Render notification body with markdown or plain mode dispatch. */
-export function subagentNotificationRenderBody(d: NotificationDetails, expanded: boolean, mode: ResultPreviewMode, theme: any): any {
-  if (mode === "markdown") {
-    let body = d.resultPreview;
-    if (!expanded) {
-      const lines = body.split("\n");
-      if (lines.length > COLLAPSED_PREVIEW_LINES) {
-        const remaining = lines.length - COLLAPSED_PREVIEW_LINES;
-        body = lines.slice(0, COLLAPSED_PREVIEW_LINES).join("\n") + `\n… (${remaining} more lines, ctrl+O to expand)`;
-      }
-    }
-    
-    const container = new Container();
-    if (body.trim()) {
-      container.addChild(new Markdown(body, 2, 0, getMarkdownTheme()));
-    }
-    if (d.outputFile) {
-      container.addChild(new Text(theme.fg("muted", `  transcript: ${d.outputFile}`), 0, 0));
-    }
-    return container;
-  } else {
-    let bodyText = "";
-    if (expanded) {
-      const lines = d.resultPreview.split("\n").slice(0, PLAIN_MODE_EXPANDED_LINE_CAP);
-      for (const l of lines) bodyText += (bodyText ? "\n" : "") + theme.fg("dim", `  ${l}`);
-    } else {
-      const preview = d.resultPreview.split("\n")[0]?.slice(0, PLAIN_MODE_COLLAPSED_CHAR_CAP) ?? "";
-      bodyText = theme.fg("dim", `  ⎿  ${preview}`);
-    }
+/** Grace window between an agent settling and its completion notification being
+ *  sent, so a parent that pulls the result first can still cancel the nudge. */
+export const NUDGE_HOLD_MS = 200;
 
-    if (d.outputFile) {
-      bodyText += (bodyText ? "\n" : "") + theme.fg("muted", `  transcript: ${d.outputFile}`);
-    }
+/** Max turns for the AI-generation wizard run. Exported for the wizard tests,
+ *  which tell the generator run apart from other spawns by this value. */
+export const WIZARD_MAX_TURNS = 5;
 
-    return new Text(bodyText, 0, 0);
+/** Validate and return `failurePreviewMaxChars` — user-set input, untrusted until checked. */
+function failurePreviewCap(settings: SubagentsSettings): number {
+  const cap = settings.failurePreviewMaxChars;
+  if (typeof cap !== "number" || !isValidFailurePreviewCap(cap)) {
+    throw new Error("failurePreviewMaxChars must be a positive integer within the settings ceiling on failure status");
   }
+  return cap;
 }
 
-/** @internal Main subagent notification renderer. */
-export function subagentNotificationRenderer(message: { details?: NotificationDetails }, options: { expanded: boolean }, theme: any, resultPreviewMode: ResultPreviewMode, resultPreviewExpanded: boolean): any {
-  const d = message.details;
-  if (!d) return undefined;
+/** Build the `Result:` body. Caps failure-mode bodies; success/aborted/steered uncapped. */
+function buildResultPreview(record: AgentRecord, settings: SubagentsSettings): string {
+  const isFailure = record.status === "error" || record.status === "stopped";
+  // Terminal-safety strip only: markdown structure and XML-ish text pass
+  // through untouched, while escape/control bytes (OSC clipboard writes and
+  // links, CSI screen clears, C0/C1, invisible format characters) never reach
+  // the terminal.
+  const body = stripControlChars(String(record.result ?? record.error ?? ""));
+  // Validate before the empty-body return: the metadata `Error:` line uses the
+  // same cap and must see the same validated value.
+  const cap = isFailure ? failurePreviewCap(settings) : Number.POSITIVE_INFINITY;
+  if (!body) return "No output.";
+  return body.length > cap
+    ? safeTruncate(body, cap) + "\n…(truncated, see transcript)"
+    : body;
+}
 
-  const effectiveExpanded = resultPreviewExpanded ? true : options.expanded;
+/**
+ * @internal Format a background completion as a markdown report. The report is
+ * both the parent model's context and the text pi renders in its default
+ * custom-message box: terminal control sequences are stripped from every field
+ * while markdown stays intact, and the body goes last (an unbalanced fence in
+ * it cannot swallow the metadata above).
+ *
+ * `showCost` is the user's setting, passed in rather than read here so the
+ * formatter stays a pure function of its arguments. It gates this report only:
+ * a figure the orchestrator was not asked to track is one it may start reporting
+ * unprompted, so the setting covers LLM context too, not just what a human sees.
+ */
+export function formatTaskNotification(record: AgentRecord, settings: SubagentsSettings, showCost = false): string {
+  const durationMs = record.completedAt ? record.completedAt - record.startedAt : 0;
+  const totalTokens = getLifetimeTotal(record.lifetimeUsage);
+  const context = formatSessionContext(record.session);
 
-  function renderOne(d: NotificationDetails): any {
-    const header = subagentNotificationRenderHeader(d, theme);
-    const body = subagentNotificationRenderBody(d, effectiveExpanded, resultPreviewMode, theme);
-    const container = new Container();
-    container.addChild(header);
-    container.addChild(body);
-    return container;
+  const stats: string[] = [];
+  const turnCount = record.turnCount ?? 0;
+  if (Number.isFinite(turnCount) && turnCount > 0) {
+    stats.push(formatTurns(turnCount, Number.isFinite(record.effectiveMaxTurns) ? record.effectiveMaxTurns : undefined));
   }
-
-  const all = [d, ...(d.others ?? [])];
-  if (all.length === 1) {
-    return renderOne(all[0]);
-  } else {
-    const container = new Container();
-    for (let i = 0; i < all.length; i++) {
-      if (i > 0) container.addChild(new Spacer());
-      container.addChild(renderOne(all[i]));
-    }
-    return container;
+  if (Number.isFinite(record.toolUses) && record.toolUses > 0) stats.push(`${record.toolUses} tool use${record.toolUses === 1 ? "" : "s"}`);
+  if (Number.isFinite(totalTokens) && totalTokens > 0) stats.push(formatTokens(totalTokens));
+  // Omitted when there is no cost to show, so an unpriced model reports tokens
+  // and no dollars rather than a `$0.00` that reads as measured-and-free.
+  const cost = showCost ? formatCost(getLifetimeCost(record.lifetimeUsage)) : "";
+  if (cost) stats.push(cost);
+  if (context !== null) stats.push(`ctx ${context}`);
+  if (Number.isFinite(record.compactionCount) && record.compactionCount > 0) stats.push(`⇊${record.compactionCount}`);
+  if (Number.isFinite(durationMs) && durationMs > 0) stats.push(formatMs(durationMs));
+
+  const descriptionText = sanitizeHeaderText(String(record.description ?? ""));
+  const description = headerPreview(descriptionText) || "(no description)";
+  let header = `**${getStatusGlyph(String(record.status))} Subagent ${getStatusWord(record.status)}: ${description}**`;
+  const errorText = record.error && (record.status === "error" || record.status === "stopped")
+    ? sanitizeHeaderText(String(record.error))
+    : "";
+  const errorPreview = headerPreview(errorText);
+  if (errorPreview) header += ` — ${errorPreview}`;
+  header += getStatusNote(record.status);
+  if (stats.length > 0) header += ` · ${stats.join(" · ")}`;
+
+  const metadata = [`Agent: ${sanitizeHeaderText(String(record.id))}`];
+  if (record.outputFile) metadata.push(`Transcript: ${sanitizeHeaderText(String(record.outputFile))}`);
+  const body = buildResultPreview(record, settings);
+  // The header only previews the error. When a partial result replaces the error
+  // in the body, carry the full sanitized error here so its tail is not lost.
+  if (errorText.length > HEADER_PREVIEW_MAX_CHARS && record.result != null) {
+    const cap = failurePreviewCap(settings); // same validated cap as the body
+    const fullError = errorText.length > cap ? `${safeTruncate(errorText, cap)}\n…(truncated, see transcript)` : errorText;
+    metadata.push(`Error: ${fullError}`);
   }
+
+  return [header, "", metadata.join("\n"), "", "Result:", "", body].join("\n");
 }
 
 export default function (pi: ExtensionAPI) {
-  // ---- Register custom notification renderer ----
-  pi.registerMessageRenderer<NotificationDetails>(
-    "subagent-notification",
-    (message, { expanded }, theme) => {
-      return subagentNotificationRenderer(message, { expanded }, theme, resultPreviewMode, resultPreviewExpanded);
-    }
-  );
+  // Read directly rather than waiting for applyAndEmitLoaded below: this decides
+  // the initial load, which happens hundreds of lines before settings are applied.
+  let strictAgentFiles = loadSettings(process.cwd()).strictAgentFiles === true;
 
   /** Reload agents from project/global custom agent dirs and merge with defaults (called on init and each Agent invocation). */
-  const reloadCustomAgents = () => {
-    const userAgents = loadCustomAgents(process.cwd());
+  const reloadCustomAgents = (strict = false) => {
+    const userAgents = loadCustomAgents(process.cwd(), strict);
     registerAgents(userAgents);
   };
 
-  // Initial load
-  reloadCustomAgents();
+  // Initial load — the only strict one. A bad edit mid-session must not kill the
+  // session on the next unrelated spawn, so every later reload keeps warning.
+  reloadCustomAgents(strictAgentFiles);
 
   // ---- Agent activity tracking + widget ----
   const agentActivity = new Map<string, AgentActivity>();
 
+  // ---- Usage reporting (`reportUsage`/`showCost` default on, `showModel` off; see SubagentsSettings) ----
+  /** Attach subagent spend to tool results, so the parent session counts it. */
+  let reportUsage = true;
+  function isReportUsageEnabled(): boolean { return reportUsage; }
+  function setReportUsage(b: boolean): void {
+    reportUsage = b;
+    // Whatever accumulated while it was on is stale the moment it goes off:
+    // draining it later would bill the parent for a window the user opted out
+    // of, in one lump, on some unrelated later tool call.
+    if (!b) pendingUsage.drain();
+  }
+  /** Show `~$X` next to token counts in the subagent surfaces. */
+  let showCost = DEFAULT_SHOW_COST;
+  function isShowCostEnabled(): boolean { return showCost; }
+  function setShowCost(b: boolean): void {
+    showCost = b;
+    // The report renderer keeps its own copy of this flag because both report
+    // callers must agree (see `setReportShowCost`). That copy is module state
+    // shared with every activation in this process, so a CHILD session's
+    // settings load must not clobber the root's decision — the nested
+    // `get_subagent_result` renders for the same user, in the same session.
+    if (!inChildSessionContext()) setReportShowCost(b);
+    widget.update();
+    fleet.update();
+  }
+  /** Name the model and thinking level on the widget's running rows. */
+  let showModel = false;
+  function isShowModelEnabled(): boolean { return showModel; }
+  function setShowModel(b: boolean): void { showModel = b; widget.update(); }
+  /**
+   * Subagent spend the parent session has not been told about yet. Fed from the
+   * manager's per-message hook (the one place each message is seen exactly once)
+   * and drained onto the next tool result this extension returns.
+   */
+  const pendingUsage = new PendingUsagePool();
+
   // ---- Cancellable pending notifications ----
   // Holds notifications briefly so get_subagent_result can cancel them before
   // they reach pi.sendMessage (fire-and-forget — once sent, a custom message
@@ -389,7 +366,10 @@ export default function (pi: ExtensionAPI) {
   // firing; the send closures re-check it at fire time.
   const pendingNudges = new Map<string, ReturnType<typeof setTimeout>>();
   const parkedNudges = new Map<string, () => void>();
-  const NUDGE_HOLD_MS = 200;
+  /** Poll interval while the wizard waits for a queued generator to start. The
+   *  wizard is interactive, so it re-checks the record until it leaves `queued`
+   *  (or is stopped) instead of blocking on a promise that does not exist yet. */
+  const WIZARD_QUEUE_POLL_MS = 100;
   let mainTurnActive = false;
 
   function scheduleNudge(key: string, send: () => void, delay = NUDGE_HOLD_MS) {
@@ -447,19 +427,20 @@ export default function (pi: ExtensionAPI) {
     for (const [key, send] of parked) scheduleNudge(key, send);
   });
 
-  // ---- Individual nudge helper (async join mode) ----
+  // ---- Completion notification ----
   function emitIndividualNudge(record: AgentRecord) {
     if (record.resultConsumed) return;  // re-check at send time
 
-    const notification = formatTaskNotification(record, { failurePreviewMaxChars });
-    const footer = record.outputFile ? `\nFull transcript available at: ${record.outputFile}` : '';
-
-    pi.sendMessage<NotificationDetails>({
-      customType: "subagent-notification",
-      content: notification + footer,
-      display: true,
-      details: buildNotificationDetails(record, { failurePreviewMaxChars }, agentActivity.get(record.id)),
-    }, { deliverAs: "steer", triggerTurn: true });
+    try {
+      pi.sendMessage({
+        customType: "subagent-notification",
+        content: formatTaskNotification(record, { failurePreviewMaxChars: effectiveFailurePreviewCap(failurePreviewMaxChars) }, showCost),
+        display: true,
+      }, { deliverAs: "steer", triggerTurn: true });
+    } catch (err) {
+      // Nudge release paths swallow throws; surface the drop with the agent id.
+      console.warn(`[pi-subagents] failed to send completion notification for ${record.id}: ${err instanceof Error ? err.message : String(err)}`);
+    }
   }
 
   function sendIndividualNudge(record: AgentRecord) {
@@ -470,40 +451,6 @@ export default function (pi: ExtensionAPI) {
     widget.update();
   }
 
-  // ---- Group join manager ----
-  const groupJoin = new GroupJoinManager(
-    (records, partial) => {
-      for (const r of records) { agentActivity.delete(r.id); widget.markFinished(r.id); fleet.onAgentFinished(r.id); }
-
-      const groupKey = `group:${records.map(r => r.id).join(",")}`;
-      scheduleNudge(groupKey, () => {
-        // Re-check at send time
-        const unconsumed = records.filter(r => !r.resultConsumed);
-        if (unconsumed.length === 0) { widget.update(); return; }
-
-        const notifications = unconsumed.map(r => formatTaskNotification(r, { failurePreviewMaxChars })).join('\n\n');
-        const label = partial
-          ? `${unconsumed.length} agent(s) finished (partial — others still running)`
-          : `${unconsumed.length} agent(s) finished`;
-
-        const [first, ...rest] = unconsumed;
-        const details = buildNotificationDetails(first, { failurePreviewMaxChars }, agentActivity.get(first.id));
-        if (rest.length > 0) {
-          details.others = rest.map(r => buildNotificationDetails(r, { failurePreviewMaxChars }, agentActivity.get(r.id)));
-        }
-
-        pi.sendMessage<NotificationDetails>({
-          customType: "subagent-notification",
-          content: `Background agent group completed: ${label}\n\n${notifications}\n\nUse get_subagent_result for full output.`,
-          display: true,
-          details,
-        }, { deliverAs: "steer", triggerTurn: true });
-      });
-      widget.update();
-    },
-    30_000,
-  );
-
   /** 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;
@@ -516,6 +463,19 @@ export default function (pi: ExtensionAPI) {
     const tokens = total > 0
       ? { input: u.input, output: u.output, total }
       : undefined;
+    // The whole run's spend as a pi `Usage` — pi's convention for handing spend
+    // to a consumer, so `usage.cost.total` and `usage.cacheRead` are where a
+    // listener already expects them and anything pi adds to `Usage` arrives
+    // without a change here. Omitted when nothing was spent, so "spent nothing"
+    // and "never ran" stay distinguishable. Ungated by either setting: those
+    // govern what a human is shown and what the parent session counts, not what
+    // a subscriber asked for.
+    //
+    // `tokens` above is the other convention, kept as it shipped: a flat view
+    // model like pi's own `SessionStats`, carrying the DISPLAY total, which
+    // excludes cacheRead (#38). The two answer different questions and neither
+    // derives from the other.
+    const usage = toReportedUsage(u);
     return {
       id: record.id,
       type: record.type,
@@ -526,11 +486,16 @@ export default function (pi: ExtensionAPI) {
       toolUses: record.toolUses,
       durationMs,
       tokens,
+      usage,
     };
   }
 
-  // Background completion: route through group join or send individual nudge
+  // Background completion: send one notification per agent
   const manager = new AgentManager((record) => {
+    // Nested children report only through their owning parent's scoped tools.
+    // Keep them out of top-level lifecycle, transcript, notification, and UI
+    // channels — nothing in the main session can act on them.
+    if (record.parentAgentId) return;
     // Emit lifecycle event based on terminal status
     const isError = record.status === "error" || record.status === "stopped" || record.status === "aborted";
     const eventData = buildEventData(record);
@@ -556,21 +521,10 @@ export default function (pi: ExtensionAPI) {
       return;
     }
 
-    // If this agent is pending batch finalization (debounce window still open),
-    // don't send an individual nudge — finalizeBatch will pick it up retroactively.
-    if (currentBatchAgents.some(a => a.id === record.id)) {
-      widget.update();
-      return;
-    }
-
-    const result = groupJoin.onAgentComplete(record);
-    if (result === 'pass') {
-      sendIndividualNudge(record);
-    }
-    // 'held' → do nothing, group will fire later
-    // 'delivered' → group callback already fired
+    sendIndividualNudge(record);
     widget.update();
   }, undefined, (record) => {
+    if (record.parentAgentId) return;
     // Emit started event when agent transitions to running (including from queue)
     pi.events.emit("subagents:started", {
       id: record.id,
@@ -578,6 +532,7 @@ export default function (pi: ExtensionAPI) {
       description: record.description,
     });
   }, (record, info) => {
+    if (record.parentAgentId) return;
     // Emit compacted event when agent's session compacts (preserves count on record).
     pi.events.emit("subagents:compacted", {
       id: record.id,
@@ -587,6 +542,48 @@ export default function (pi: ExtensionAPI) {
       tokensBefore: info.tokensBefore,
       compactionCount: record.compactionCount,
     });
+  }, (record, usage) => {
+    // Every assistant message from every agent — nested included, exactly once.
+    // Parked here until a tool result can carry it back to the parent session;
+    // see `PendingUsagePool`. Skipped entirely when the feature is off, so no
+    // pool grows in a session that will never drain it.
+    if (reportUsage) pendingUsage.add(usage);
+    // The same message, live, for anyone keeping their own ledger — a footer
+    // that breaks spend down by agent type and thinking level, say. This is the
+    // one place every agent's spend passes through, which is why it is emitted
+    // here and not from the lifecycle events: those fire for top-level agents
+    // only, once, at the end, so a nested child would never be counted and a
+    // running agent would read as free until it stopped. Deliberately ungated by
+    // `reportUsage` — that decides whether the parent session's own totals
+    // include this spend, not whether it happened.
+    //
+    // `model` and `thinking` are read off the record per message, not captured
+    // at spawn: the record is authoritative only once the session exists and pi
+    // has clamped the level to the model (see `onSessionCreated` in
+    // agent-manager.ts).
+    const reported = toReportedUsage(usage);
+    if (!reported) return;
+    // A key whose value is unknown is omitted, never `undefined`: `model` and
+    // `thinking` until the session has reported them, `parentAgentId` on a
+    // top-level agent.
+    const invocation = record.invocation;
+    pi.events.emit("subagents:usage", {
+      id: record.id,
+      type: record.type,
+      description: record.description,
+      ...(invocation?.modelId !== undefined ? { model: invocation.modelId } : {}),
+      ...(invocation?.thinking !== undefined ? { thinking: invocation.thinking } : {}),
+      // Set only when the caller did not get the level it asked for (pi clamped
+      // it to the model), so a ledger can show `low (asked minimal)` instead of
+      // silently relabelling.
+      ...(invocation?.requestedThinking !== undefined ? { requestedThinking: invocation.requestedThinking } : {}),
+      depth: record.depth ?? 1,
+      ...(record.parentAgentId !== undefined ? { parentAgentId: record.parentAgentId } : {}),
+      usage: reported,
+    });
+  }, (record, message) => {
+    if (record.parentAgentId) return;
+    pi.events.emit("subagents:steered", { id: record.id, message });
   });
 
   // Expose manager via Symbol.for() global registry for cross-package access.
@@ -599,12 +596,40 @@ export default function (pi: ExtensionAPI) {
   // session's entry. The first activation (the root session) wins; child
   // activations leave it alone.
   const MANAGER_KEY = Symbol.for("pi-subagents:manager");
+  // Every caller-supplied spawn that reaches the manager from outside the Agent
+  // tool goes through here, so `fallbackSubagent` gates cross-extension callers
+  // too (#183). The RPC layer already throws for an unresolvable model rather
+  // than falling back silently; a bad agent type should not be quieter. Throws
+  // become error envelopes at the RPC boundary. Reload first so an agent file
+  // added mid-session is spawnable here too, not only through the Agent tool.
+  //
+  // Cross-package callers may supply arbitrary options. Nested ownership and
+  // config-root metadata are internal capabilities issued only by the scoped
+  // nested tools — a forged `parentAgentId` would hide a top-level agent from
+  // every surface, and `rootSessionId` names a transcript directory, so a
+  // forged value is a path-traversal primitive.
+  const spawnTopLevel = (piRef: ExtensionAPI, ctxRef: ExtensionContext, type: SubagentType, prompt: string, options: SpawnOptions) => {
+    reloadCustomAgents();
+    const dispatch = resolveSpawnType(type);
+    if (!dispatch.ok) throw new Error(dispatch.message);
+    const safeOptions: SpawnOptions = { ...options };
+    delete safeOptions.parentAgentId;
+    delete safeOptions.depth;
+    delete safeOptions.maxSubagentDepth;
+    delete safeOptions.configCwd;
+    delete safeOptions.rootSessionId;
+    return manager.spawn(piRef, ctxRef, dispatch.type, prompt, safeOptions);
+  };
   const registryEntry = {
     waitForAll: () => manager.waitForAll(),
     hasRunning: () => manager.hasRunning(),
-    spawn: (piRef: any, ctx: any, type: string, prompt: string, options: any) =>
-      manager.spawn(piRef, ctx, type, prompt, options),
-    getRecord: (id: string) => manager.getRecord(id),
+    spawn: spawnTopLevel,
+    // `listAgents` stays unfiltered on purpose: the subagent-facing `checkpoint`
+    // tool resolves its own nested record through it by session id.
+    getRecord: (id: string) => {
+      const record = manager.getRecord(id);
+      return record?.parentAgentId ? undefined : record;
+    },
     listAgents: () => manager.listAgents(),
   };
   const ownsManagerRegistry = (globalThis as any)[MANAGER_KEY] === undefined;
@@ -612,6 +637,52 @@ export default function (pi: ExtensionAPI) {
     (globalThis as any)[MANAGER_KEY] = registryEntry;
   }
 
+  /**
+   * Wrap a tool so its results carry back whatever subagent spend the parent
+   * session has not been told about yet (see `PendingUsagePool`).
+   *
+   * Pi copies `AgentToolResult.usage` onto the persisted tool-result message and
+   * folds it into `getSessionStats()`, which is what the footer, the statusline
+   * and `/cost` read — so this is the whole of "report usage to the parent".
+   *
+   * No tool-call-id guard: `ToolDefinition.execute` takes a `string` here, and
+   * every caller of a registered tool in this fork is pi itself, which always
+   * has one. There is no in-process clone that invokes a tool from a discarded
+   * fork of the conversation, so a result this extension produces always becomes
+   * a real message and its usage is always counted.
+   */
+  function withUsageReporting(tool: ToolDefinition): ToolDefinition {
+    const execute = tool.execute;
+    return {
+      ...tool,
+      execute: async (toolCallId, params, signal, onUpdate, ctx) => {
+        const result = await execute(toolCallId, params, signal, onUpdate, ctx);
+        if (!reportUsage) return result;
+        const usage = pendingUsage.drain();
+        return usage ? { ...result, usage } : result;
+      },
+    };
+  }
+
+  /**
+   * Register a parent-facing tool — never in a subagent session.
+   *
+   * A subagent session re-activates this extension in the same process, and its
+   * local manager is empty: an `Agent` registered there could only spawn into a
+   * manager nobody reads. Worse, an opted-in child receives the nested `Agent`
+   * as an SDK custom tool, so registering ours too would put two definitions of
+   * the same name in one registry and leave the survivor to pi's precedence.
+   * Skipping the child activation makes the child's single `Agent` a
+   * construction-time guarantee. Every other child has these names stripped from
+   * its allowlist (EXCLUDED_TOOL_NAMES), so nothing changes for them.
+   *
+   * Every parent-facing tool is registered through here, so this is also the one
+   * place that attaches pending subagent spend to a tool result.
+   */
+  const registerParentTool = (tool: ToolDefinition): void => {
+    if (!inChildSessionContext()) pi.registerTool(withUsageReporting(tool));
+  };
+
   // --- Cross-extension RPC via pi.events ---
   let currentCtx: ExtensionContext | undefined;
   // RPC handlers + the `subagents:ready` broadcast are wired on `session_start`
@@ -657,7 +728,34 @@ export default function (pi: ExtensionAPI) {
         events: pi.events,
         pi,
         getCtx: () => currentCtx,
-        manager,
+        // Same capability boundary as the manager registry: a cross-extension
+        // caller cannot forge nested ownership, and cannot stop, steer or
+        // consume a nested child it does not own.
+        manager: {
+          spawn: spawnTopLevel,
+          getRecord: (id) => manager.getRecord(id),
+          abort: (id) => {
+            const record = manager.getRecord(id);
+            return !record?.parentAgentId && manager.abort(id);
+          },
+          // What `get_subagent_result` does when it returns a settled result:
+          // mark it read and cancel the parked completion notification, so the
+          // caller that already showed the model this result does not pay for a
+          // second copy of it.
+          consumeResult: (id) => {
+            // Ownership is the RPC layer's job (assertOwned); settledness is not —
+            // it never looks at status. Consuming a running agent would set
+            // resultConsumed and suppress the completion notification it is still
+            // owed, so this stays the same gate the local get_subagent_result has.
+            const record = manager.getRecord(id);
+            if (!record) return false;
+            if (record.status === "running" || record.status === "queued") return false;
+            record.resultConsumed = true;
+            cancelNudge(record.id);
+            return true;
+          },
+          steer: (id, message) => manager.steer(id, message),
+        },
       });
       // Broadcast readiness so extensions loaded alongside us can discover us.
       // Emitting after all factories have run (rather than at factory time)
@@ -674,10 +772,12 @@ export default function (pi: ExtensionAPI) {
 
   // On shutdown, abort all agents immediately and clean up.
   // If the session is going down, there's nothing left to consume agent results.
-  pi.on("session_shutdown", async () => {
+  pi.on("session_shutdown", async (event) => {
     rpcHandle?.unsubSpawn();
     rpcHandle?.unsubStop();
     rpcHandle?.unsubPing();
+    rpcHandle?.unsubConsume();
+    rpcHandle?.unsubSteer();
     rpcHandle = undefined;
     currentCtx = undefined;
     // Only release the global slot if this activation claimed it — a child
@@ -693,35 +793,37 @@ export default function (pi: ExtensionAPI) {
     mainTurnActive = false;
     fleet.dispose();
     manager.dispose();
+    // Every agent is stopped and every child session has shut down, so no more
+    // `subagents:usage` can arrive from THIS session. A ledger flushing in its
+    // own `session_shutdown` may have run before this handler aborted the agents
+    // (handlers run in load order) and missed their last messages; this is the
+    // point after which a synchronous final flush is complete.
+    //
+    // Not only an exit: pi also emits `session_shutdown` for `resume`, `reload`,
+    // `/new` and `/fork`, where the process lives on and the next session starts
+    // emitting `subagents:usage` again. The reason is carried so a listener can
+    // tell a final flush from a mid-process one.
+    pi.events.emit("subagents:disposed", { reason: event.reason });
   });
 
   // Live widget: show running agents above editor.
-  // widgetMode (default "background") selects what the widget shows: "all" =
-  // every agent; "background" = hide foreground (they already render inline as
-  // the Agent tool result, so showing them here too is a duplicate, #118), keep
-  // everything else; "off" = hide the widget entirely. Read live at render time.
-  let widgetMode: WidgetMode = "background";
+  // widgetMode (default "all") selects what the widget shows: "all" = every
+  // agent; "off" = hide the widget entirely. Read live at render time.
+  let widgetMode: WidgetMode = "all";
   function getWidgetMode(): WidgetMode { return widgetMode; }
-  const widget = new AgentWidget(manager, agentActivity, getWidgetMode);
+  const widget = new AgentWidget(manager, agentActivity, getWidgetMode, isShowCostEnabled, isShowModelEnabled);
   function setWidgetMode(m: WidgetMode): void { widgetMode = m; widget.update(); }
 
   // Claude Code-style FleetView: navigable list of main + subagents below the editor.
-  const fleet = new FleetList(manager, agentActivity);
+  const fleet = new FleetList(manager, agentActivity, isShowCostEnabled);
   let fleetViewEnabled = true;
   function isFleetViewEnabled(): boolean { return fleetViewEnabled; }
   function setFleetViewEnabled(b: boolean): void { fleetViewEnabled = b; fleet.setEnabled(b); }
 
-  // Project/global default for writing the subagent .output transcript. A custom
-  // agent's `output_transcript` frontmatter overrides this per spawn; when the
-  // frontmatter is silent, this default applies. Read live at spawn time.
-  let outputTranscriptDefault = true;
-  function getOutputTranscriptDefault(): boolean { return outputTranscriptDefault; }
-  function setOutputTranscript(b: boolean): void { outputTranscriptDefault = b; }
-
-  // ---- Join mode configuration ----
-  let defaultJoinMode: JoinMode = 'smart';
-  function getDefaultJoinMode(): JoinMode { return defaultJoinMode; }
-  function setDefaultJoinMode(mode: JoinMode) { defaultJoinMode = mode; }
+  // Project/global default for writing the subagent .output transcript lives in
+  // output-file.ts (both spawn paths read it). A custom agent's
+  // `output_transcript` frontmatter overrides it per spawn; when the frontmatter
+  // is silent, that default applies. Read live at spawn time.
 
   // Master switch for the schedule subagent feature. Defaults to enabled.
   // Read once at extension init (before tool registration) so the Agent tool's
@@ -734,22 +836,13 @@ export default function (pi: ExtensionAPI) {
   function setSchedulingEnabled(b: boolean) { schedulingEnabled = b; }
 
   // ---- Scope models configuration ----
-  // When enabled, subagent model choices are validated against `enabledModels`
-  // from pi's settings — both global `<agentDir>/settings.json` and
-  // project-local `<cwd>/.pi/settings.json` (project overrides global).
-  // Off by default; opt-in via `/agents → Settings`. See docstring on
-  // SubagentsSettings.scopeModels for the hard-error vs warn-and-proceed
-  // policy and its rationale.
-  let scopeModelsEnabled = false;
-  function isScopeModelsEnabled(): boolean { return scopeModelsEnabled; }
-  function setScopeModelsEnabled(enabled: boolean): void { scopeModelsEnabled = enabled; }
-
-  // ---- Result preview configuration ----
-  let resultPreviewMode: ResultPreviewMode = "markdown";
-  let resultPreviewExpanded = true;
+  // The enable flag and the validation policy live in model-scope.ts, so the
+  // nested delegation tools enforce the same allowlist the top-level Agent tool
+  // does. Off by default; opt-in via `/agents → Settings`. See the
+  // SubagentsSettings.scopeModels docstring for the warn-and-proceed policy.
+
+  // ---- Failure preview configuration ----
   let failurePreviewMaxChars = DEFAULT_FAILURE_PREVIEW_MAX_CHARS;
-  function setResultPreviewMode(mode: ResultPreviewMode): void { resultPreviewMode = mode; }
-  function setResultPreviewExpanded(expanded: boolean): void { resultPreviewExpanded = expanded; }
   function setFailurePreviewMaxChars(chars: number): void { failurePreviewMaxChars = chars; }
 
   // ---- Disable default agents configuration ----
@@ -772,49 +865,6 @@ export default function (pi: ExtensionAPI) {
   function getToolDescriptionMode(): ToolDescriptionMode { return toolDescriptionMode; }
   function setToolDescriptionMode(mode: ToolDescriptionMode): void { toolDescriptionMode = mode; }
 
-  // ---- Batch tracking for smart join mode ----
-  // Collects background agent IDs spawned in the current turn for smart grouping.
-  // Uses a debounced timer: each new agent resets the 100ms window so that all
-  // parallel tool calls (which may be dispatched across multiple microtasks by the
-  // framework) are captured in the same batch.
-  let currentBatchAgents: { id: string; joinMode: JoinMode }[] = [];
-  let batchFinalizeTimer: ReturnType<typeof setTimeout> | undefined;
-  let batchCounter = 0;
-
-  /** Finalize the current batch: if 2+ smart-mode agents, register as a group. */
-  function finalizeBatch() {
-    batchFinalizeTimer = undefined;
-    const batchAgents = [...currentBatchAgents];
-    currentBatchAgents = [];
-
-    const smartAgents = batchAgents.filter(a => a.joinMode === 'smart' || a.joinMode === 'group');
-    if (smartAgents.length >= 2) {
-      const groupId = `batch-${++batchCounter}`;
-      const ids = smartAgents.map(a => a.id);
-      groupJoin.registerGroup(groupId, ids);
-      // Retroactively process agents that already completed during the debounce window.
-      // Their onComplete fired but was deferred (agent was in currentBatchAgents),
-      // so we feed them into the group now.
-      for (const id of ids) {
-        const record = manager.getRecord(id);
-        if (!record) continue;
-        record.groupId = groupId;
-        if (record.completedAt != null && !record.resultConsumed) {
-          groupJoin.onAgentComplete(record);
-        }
-      }
-    } else {
-      // No group formed — send individual nudges for any agents that completed
-      // during the debounce window and had their notification deferred.
-      for (const { id } of batchAgents) {
-        const record = manager.getRecord(id);
-        if (record?.completedAt != null && !record.resultConsumed) {
-          sendIndividualNudge(record);
-        }
-      }
-    }
-  }
-
   // Grab UI context from first tool execution + clear lingering widget on new turn
   pi.on("tool_execution_start", async (_event, ctx) => {
     widget.setUICtx(ctx.ui as UICtx);
@@ -873,17 +923,21 @@ export default function (pi: ExtensionAPI) {
       setMaxConcurrent: (n) => manager.setMaxConcurrent(n),
       setDefaultMaxTurns,
       setGraceTurns,
-      setDefaultJoinMode,
       setSchedulingEnabled,
       setScopeModels: setScopeModelsEnabled,
-      setResultPreviewMode,
-      setResultPreviewExpanded,
+      setStrictAgentFiles: (b) => { strictAgentFiles = b; },
       setFailurePreviewMaxChars,
       setDisableDefaultAgents: setDisableDefaultAgents,
       setToolDescriptionMode: setToolDescriptionMode,
       setFleetView: setFleetViewEnabled,
       setWidgetMode: setWidgetMode,
-      setOutputTranscript: setOutputTranscript,
+      setOutputTranscript: setOutputTranscriptDefault,
+      setMaxSubagentDepth: setMaxSubagentDepth,
+      setWorktreeIsolation: setWorktreeIsolationEnabled,
+      setFallbackSubagent: setFallbackSubagent,
+      setReportUsage,
+      setShowCost,
+      setShowModel,
     },
     (event, payload) => pi.events.emit(event, payload),
   );
@@ -901,7 +955,8 @@ export default function (pi: ExtensionAPI) {
         description:
           'Opt-in only — fire later instead of now. Omit to run immediately (the default, almost always correct). ' +
           'Formats: 6-field cron ("0 0 9 * * 1" = 9am Mon), interval ("5m"/"1h"), one-shot ("+10m" or ISO). ' +
-          'Forces run_in_background; incompatible with inherit_context and resume. Returns job ID.',
+          'Interval delays are capped by the JS timer ceiling (~24.8 days); one-shot dates further out stay scheduled and arm at a later session start once closer. ' +
+          'Incompatible with inherit_context and resume. Returns job ID.',
       }),
     ),
   };
@@ -912,6 +967,21 @@ export default function (pi: ExtensionAPI) {
     ? `\n- Use \`schedule\` only when the user explicitly asked for scheduled / recurring / delayed execution (e.g. "every Monday", "in an hour"). Don't auto-schedule from vague intent like "monitor X" — run once now or ask.`
     : "";
 
+  // Same trade as scheduleParam/scheduleGuideline above: `isolationParam` drops
+  // the field from the schema when the project set `worktreeIsolation: false`,
+  // so the prose has to go with it. Left in, it would teach the model to pass a
+  // parameter that isn't declared — accepted (TypeBox sets no
+  // `additionalProperties: false`) and then silently dropped by the resolver.
+  // 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.`
+    : "";
+
+  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.`
+    : "";
+
   // 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.
@@ -922,10 +992,9 @@ Custom agents: .pi/agents/<name>.md (project) or ${getAgentDir()}/agents/<name>.
 
 Notes:
 - description: 3-5 words (shown in UI). Prompts must be self-contained — the agent has not seen this conversation.
-- Parallel work: one message, multiple Agent calls, run_in_background: true on each. You are notified when background agents finish — never poll or sleep.
-- 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.
-- isolation: "worktree" runs the agent in an isolated git worktree; changes land on a branch.`;
+- You will be notified on subagent completion/failure — never poll or sleep.
+- 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}`;
 
   const fullAgentToolDescription = `Launch a new agent to handle complex, multi-step tasks autonomously. Each agent type has specific capabilities and tools available to it.
 
@@ -943,18 +1012,12 @@ If the target is already known, use a direct tool — \`read\` for a known path,
 ## Usage notes
 
 - Always include a short (3-5 word) description summarizing what the agent will do (shown in UI).
-- When you launch multiple agents for independent work, send them in a single message with multiple tool uses, with run_in_background: true on each, so they run concurrently. If the user specifies that they want agents run "in parallel", you MUST send a single message with multiple tool calls. Foreground calls run sequentially — only one executes at a time.
-- When the agent is done, it returns a single message back to you. The result is not visible to the user — to show the user, send a text message with a concise summary.
+- When an agent finishes or fails, you will be notified on subagent completion/failure — do NOT poll or sleep waiting for it.
 - Trust but verify: an agent's summary describes what it intended to do, not necessarily what it did. When an agent writes or edits code, check the actual changes before reporting work as done.
-- Use run_in_background for work you don't need immediately. You will be notified when it completes — do NOT poll or sleep waiting for it. Continue with other work or respond to the user instead.
-- Foreground vs background: use foreground (default) when you need the agent's results before you can proceed. Use background when you have genuinely independent work to do in parallel.
 - 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 send mid-run messages to a running subagent.
 - 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 thinking to control extended thinking level.
-- Use inherit_context if the agent needs the parent conversation history.
-- Use isolation: "worktree" to run the agent in an isolated git worktree (safe parallel file modifications). The worktree is automatically cleaned up if the agent makes no changes; otherwise the path and branch are returned in the result.${scheduleGuideline}
+- Use inherit_context if the agent needs the parent conversation history.${isolationGuideline}${scheduleGuideline}
 
 ## Writing the prompt
 
@@ -978,6 +1041,7 @@ Terse command-style prompts produce shallow, generic work.
       typeList: buildTypeListText,
       compactTypeList: buildCompactTypeListText,
       agentDir: getAgentDir,
+      isolationGuideline: () => isolationGuideline,
       scheduleGuideline: () => scheduleGuideline,
     };
     // Replacement callback (not a string) — agent descriptions may contain `$&` etc.
@@ -1016,7 +1080,7 @@ Terse command-style prompts produce shallow, generic work.
     return fullAgentToolDescription;
   })();
 
-  pi.registerTool(defineTool({
+  registerParentTool(defineTool({
     name: SUBAGENT_TOOL_NAMES.AGENT,
     label: "Agent",
     description: agentToolDescription,
@@ -1024,7 +1088,7 @@ Terse command-style prompts produce shallow, generic work.
     promptGuidelines: [
       "Use Agent with specialized agents when the task matches an agent type's description. Subagents are valuable for parallelizing independent queries or for protecting the main context window from excessive results, but should not be used excessively when not needed. Importantly, avoid duplicating work that subagents are already doing — if you delegate research to a subagent, do not also perform the same searches yourself.",
       "For broad codebase exploration or research, spawn Agent with an appropriate subagent_type (e.g. Explore). Otherwise use direct tools (read, grep, find) when the target is already known.",
-      "When an agent runs in the background, you will be notified on completion — do not poll or sleep waiting for it. Continue with other work instead.",
+      "You will be notified on subagent completion/failure — do not poll or sleep waiting for it. Continue with other work instead.",
       "Trust but verify: an agent's summary describes intent, not outcome. When an agent writes or edits code, check the actual changes before reporting work as done.",
     ],
     parameters: Type.Object({
@@ -1037,22 +1101,12 @@ Terse command-style prompts produce shallow, generic work.
       subagent_type: Type.String({
         description: `The type of specialized agent to use. Available types: ${getAvailableTypes().join(", ")}. Custom agents from .pi/agents/*.md (project) or ${getAgentDir()}/agents/*.md (global) are also available.`,
       }),
-      thinking: Type.Optional(
-        Type.String({
-          description: `Thinking level: ${THINKING_LEVELS.join(", ")}. Overrides agent default.`,
-        }),
-      ),
       max_turns: Type.Optional(
         Type.Number({
           description: "Maximum number of agentic turns before stopping. Omit for unlimited (default).",
           minimum: 1,
         }),
       ),
-      run_in_background: Type.Optional(
-        Type.Boolean({
-          description: "Set to true to run in background. Returns agent ID immediately. You will be notified on completion.",
-        }),
-      ),
       resume: Type.Optional(
         Type.String({
           description: "Optional agent ID to resume from. Continues from previous context.",
@@ -1068,34 +1122,40 @@ Terse command-style prompts produce shallow, generic work.
           description: "If true, fork parent conversation into the agent. Default: false (fresh context).",
         }),
       ),
-      isolation: Type.Optional(
-        Type.Literal("worktree", {
-          description: 'Set to "worktree" to run the agent in a temporary git worktree (isolated copy of the repo). Changes are saved to a branch on completion.',
-        }),
-      ),
+      ...isolationParam(isWorktreeIsolationEnabled()),
       ...scheduleParam,
     }),
 
     // ---- Custom rendering: Claude Code style ----
 
-    renderCall(args, theme) {
-      const displayName = args.subagent_type ? getDisplayName(args.subagent_type) : "Agent";
-      const desc = args.description ?? "";
-      return new Text("▸ " + theme.fg("toolTitle", theme.bold(displayName)) + (desc ? "  " + theme.fg("muted", desc) : ""), 0, 0);
+    renderCall(args, theme, context) {
+      const displayName = typeof args.subagent_type === "string" ? toSingleLine(getDisplayName(args.subagent_type)) : "Agent";
+      const desc = typeof args.description === "string" ? headerPreview(toSingleLine(args.description)) : "";
+      const marker = context.expanded ? "▾" : "▸";
+      let head = marker + " " + theme.fg("toolTitle", theme.bold(displayName));
+      if (desc) head += "  " + theme.fg("muted", desc);
+
+      if (context.expanded) {
+        const raw = typeof (args as { prompt?: unknown })?.prompt === "string" ? (args as { prompt: string }).prompt : "";
+        const body = instructionBody(raw, theme);
+        if (body) return new Text(head + "\n" + body, 0, 0);
+      }
+      return new Text(head, 0, 0);
     },
 
-    renderResult(result, { expanded, isPartial }, theme) {
+    renderResult(result, { expanded }, theme, context) {
       const details = result.details as AgentDetails | undefined;
+      // Display copies only: `execute` hands the model the raw child text.
       if (!details) {
         const text = result.content[0]?.type === "text" ? result.content[0].text : "";
-        return new Text(text, 0, 0);
+        return new Text(typeof text === "string" ? stripControlChars(text) : "", 0, 0);
       }
 
       // Helper: build "haiku · thinking: high · ↻5≤30 · 3 tool uses · 33.8k tokens" stats string
       const stats = (d: AgentDetails) => {
         const parts: string[] = [];
-        if (d.modelName) parts.push(d.modelName);
-        if (d.tags) parts.push(...d.tags);
+        if (d.modelName) parts.push(toSingleLine(d.modelName));
+        if (d.tags) parts.push(...d.tags.map(t => toSingleLine(t)));
         if (d.turnCount != null && d.turnCount > 0) {
           parts.push(formatTurns(d.turnCount, d.maxTurns));
         }
@@ -1104,59 +1164,22 @@ Terse command-style prompts produce shallow, generic work.
         return parts.map(p => fgPreservingNestedStyles(theme, "dim", p)).join(" " + theme.fg("dim", "·") + " ");
       };
 
-      // ---- While running (streaming) ----
-      if (isPartial || details.status === "running") {
-        const frame = SPINNER[details.spinnerFrame ?? 0];
-        const s = stats(details);
-        return renderRunningAgentStatus(frame, s, details.activity ?? "thinking…", theme);
-      }
-
       // ---- Background agent launched ----
       if (details.status === "background") {
-        return new Text(theme.fg("dim", `  ⎿  Running in background (ID: ${details.agentId})`), 0, 0);
-      }
-
-      // ---- Completed / Steered ----
-      if (details.status === "completed" || details.status === "steered") {
-        const duration = formatMs(details.durationMs);
-        const isSteered = details.status === "steered";
-        const icon = isSteered ? theme.fg("warning", "✓") : theme.fg("success", "✓");
-        const s = stats(details);
-        let line = icon + (s ? " " + s : "");
-        line += " " + theme.fg("dim", "·") + " " + theme.fg("dim", duration);
-
-        if (expanded) {
-          const resultText = result.content[0]?.type === "text" ? result.content[0].text : "";
-          if (resultText) {
-            const lines = resultText.split("\n").slice(0, 50);
-            for (const l of lines) {
-              line += "\n" + theme.fg("dim", `  ${l}`);
-            }
-            if (resultText.split("\n").length > 50) {
-              line += "\n" + theme.fg("muted", "  ... (read the .output transcript file for full detail)");
-            }
-          }
-        } else {
-          const doneText = isSteered ? "Wrapped up (turn limit)" : "Done";
-          line += "\n" + theme.fg("dim", `  ⎿  ${doneText}`);
-        }
-        return new Text(line, 0, 0);
-      }
-
-      // ---- Stopped (user-initiated abort) ----
-      if (details.status === "stopped") {
-        const s = stats(details);
-        let line = theme.fg("dim", "■") + (s ? " " + s : "");
-        line += "\n" + theme.fg("dim", "  ⎿  Stopped");
-        return new Text(line, 0, 0);
+        const hint = !expanded && typeof (context.args as { prompt?: unknown })?.prompt === "string"
+          ? instructionHint(theme)
+          : "";
+        return new Text(theme.fg("dim", `  ⎿  Running in background (ID: ${details.agentId})${hint}`), 0, 0);
       }
 
       // ---- Error / Aborted (hard max_turns) ----
+      // Legacy fallthrough: a replayed pre-change row carrying a retired inline
+      // status (running/completed/steered/stopped) lands here.
       const s = stats(details);
       let line = theme.fg("error", "✗") + (s ? " " + s : "");
 
       if (details.status === "error") {
-        line += "\n" + theme.fg("error", `  ⎿  Error: ${details.error ?? "unknown"}`);
+        line += "\n" + theme.fg("error", `  ⎿  Error: ${toSingleLine(String(details.error ?? "")) || "unknown"}`);
       } else {
         line += "\n" + theme.fg("warning", "  ⎿  Aborted (max turns exceeded)");
       }
@@ -1166,7 +1189,7 @@ Terse command-style prompts produce shallow, generic work.
 
     // ---- Execute ----
 
-    execute: async (toolCallId, params, signal, onUpdate, ctx) => {
+    execute: async (_toolCallId, params, _signal, _onUpdate, ctx) => {
       // Ensure we have UI context for widget rendering
       widget.setUICtx(ctx.ui as UICtx);
 
@@ -1174,50 +1197,40 @@ Terse command-style prompts produce shallow, generic work.
       reloadCustomAgents();
 
       const rawType = params.subagent_type as SubagentType;
-      const resolved = resolveType(rawType);
-      const subagentType = resolved ?? "general-purpose";
-      const fellBack = resolved === undefined;
-
-      const displayName = getDisplayName(subagentType);
+      // Single decision point for dispatch (#183): unknown, disabled and
+      // case-ambiguous types are refused here, BEFORE anything spawns, so a
+      // background or scheduled call can't start running the wrong agent while
+      // the caller is still unaware. `fallbackSubagent` decides whether an
+      // unresolvable type falls back or fails closed.
+      const dispatch = resolveSpawnType(rawType);
+      // `resume` replays a stored session and ignores `subagent_type` entirely,
+      // but the parameter is required by the schema — so gating it here would
+      // make a live agent unresumable the moment its type is deleted, disabled,
+      // or gains a case-clashing sibling. Only a real spawn is gated.
+      if (!dispatch.ok && !params.resume) return textResult(dispatch.message);
+      const subagentType = dispatch.ok ? dispatch.type : rawType;
+      // What the caller actually asked for, named once: `fellBackFrom` is "" for
+      // a blank request, so reading it inline invites the `??`-vs-`||` slip that
+      // would persist an empty type into a scheduled job.
+      const requestedType = (dispatch.ok && dispatch.fellBackFrom) || subagentType;
+      // Computed at resolution rather than after the run, so the schedule and
+      // background branches carry it too. 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
+        ? `Note: Unknown agent type "${dispatch.fellBackFrom}" — using ${resolveType(subagentType) ? subagentType : "the fallback agent config"}.\n\n`
+        : "";
 
       // Get agent config (if any)
       const customConfig = getAgentConfig(subagentType);
 
-      const resolvedConfig = resolveAgentInvocationConfig(customConfig, params);
-
-      // Resolve model from agent frontmatter only (no LLM-authored override).
-      let model = ctx.model;
-      if (resolvedConfig.modelInput) {
-        const resolved = resolveModel(resolvedConfig.modelInput, ctx.modelRegistry);
-        if (typeof resolved !== "string") {
-          model = resolved;
-        }
-        // config-specified but unresolvable: silent fallback to parent (existing behavior)
-      }
-
-      // Scope validation: the effective resolved model is checked against the
-      // user's enabledModels list (read in `enabled-models.ts`).
-      //
-      // Design: scopeModels guards against frontmatter-pinned or parent-inherited
-      // models drifting out of the user's allowlist. Both warn and proceed —
-      // frontmatter is authoritative (the agent's author/installer chose it),
-      // and the parent's model was chosen by the user when starting the session.
-      // See SubagentsSettings.scopeModels docstring for the full policy.
-      if (isScopeModelsEnabled() && model) {
-        const allowed = resolveEnabledModels(readEnabledModels(ctx.cwd), ctx.modelRegistry, ctx.cwd);
-        if (allowed && !isModelInScope(model, allowed)) {
-          const agentLabel = customConfig?.displayName ?? subagentType;
-          const modelLabel = resolvedConfig.modelInput ?? `${model.provider}/${model.id}`;
-          ctx.ui.notify(
-            `Agent "${agentLabel}" using out-of-scope model "${modelLabel}"`,
-            "warning",
-          );
-        }
-      }
+      const resolvedConfig = resolveAgentInvocationConfig(customConfig, params, {
+        worktreeAllowed: isWorktreeIsolationEnabled(),
+      });
 
       const thinking = resolvedConfig.thinking;
       const inheritContext = resolvedConfig.inheritContext;
-      const runInBackground = resolvedConfig.runInBackground;
       const isolated = resolvedConfig.isolated;
       const isolation = resolvedConfig.isolation;
       // Whether this spawn writes its .output transcript. Per-agent
@@ -1232,35 +1245,54 @@ Terse command-style prompts produce shallow, generic work.
         writeInitialEntry(rec.outputFile, agentId, params.prompt, ctx.cwd);
       };
 
-      const parentModelId = ctx.model?.id;
-      const effectiveModelId = model?.id;
-      const modelName = effectiveModelId && effectiveModelId !== parentModelId
-        ? (model?.name ?? effectiveModelId).replace(/^Claude\s+/i, "").toLowerCase()
-        : undefined;
       const effectiveMaxTurns = normalizeMaxTurns(resolvedConfig.maxTurns ?? getDefaultMaxTurns());
-      const agentInvocation: AgentInvocation = {
-        modelName,
-        thinking,
-        // Explicit value only — the default fallback would just add noise.
-        // Normalize so `0` (unlimited) doesn't surface as a misleading "max turns: 0".
-        maxTurns: normalizeMaxTurns(resolvedConfig.maxTurns),
-        isolated,
-        inheritContext,
-        runInBackground,
-        isolation,
-      };
-      // Tool-result render shows the mode label too; viewer's header already does.
-      const modeLabel = getPromptModeLabel(subagentType);
-      const { tags: invocationTags } = buildInvocationTags(agentInvocation);
-      const agentTags = modeLabel ? [modeLabel, ...invocationTags] : invocationTags;
-      const detailBase = {
-        displayName,
-        description: params.description,
-        subagentType,
-        modelName,
-        tags: agentTags.length > 0 ? agentTags : undefined,
+
+      // Resolve the call's model from agent frontmatter only (no LLM-authored
+      // override). Shared by fresh spawns and scheduled registrations: a
+      // schedule registers a job here and the pinned model resolves at fire
+      // time, but the scope warning still belongs to registration. A resume
+      // continues the record's session and model, so it does not warn, and its
+      // row never uses the call-resolved model.
+      let model = ctx.model;
+      if (resolvedConfig.modelInput) {
+        const resolved = resolveModel(resolvedConfig.modelInput, ctx.modelRegistry);
+        if (typeof resolved !== "string") {
+          model = resolved;
+        }
+        // config-specified but unresolvable: silent fallback to parent (existing behavior)
+      }
+
+      // Scope validation: the effective resolved model is checked against the
+      // user's enabledModels list. Policy lives in model-scope.ts so the nested
+      // delegation tools apply the same allowlist to a nested spawn.
+      //
+      // Call this only where the model is accepted for use — after a schedule
+      // job is registered, or once a spawn is admitted — so a refused call
+      // never warns for work that never happens. The resume path never calls it.
+      // A throwing notify is swallowed: the warning is advisory and cannot
+      // fail the accepted call.
+      const warnOnOutOfScopeModel = (): void => {
+        const warning = modelScopeWarning({
+          model,
+          cwd: ctx.cwd,
+          modelRegistry: ctx.modelRegistry,
+          agentLabel: toSingleLine(customConfig?.displayName ?? subagentType),
+          modelInput: resolvedConfig.modelInput,
+        });
+        if (!warning) return;
+        try {
+          ctx.ui.notify(warning, "warning");
+        } catch { /* ignore notification errors */ }
       };
 
+      // Display name for the resolved model, captured in the fresh-spawn
+      // invocation snapshot. Unconditional, not "only when it differs from the
+      // parent": a thinking level reads as a property of a model, and an agent
+      // that inherited the 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 ? describeModel(model) : { modelName: undefined, modelId: undefined };
+
       // ---- Schedule: register a job, don't spawn now ----
       if (params.schedule) {
         if (!isSchedulingEnabled()) {
@@ -1272,9 +1304,6 @@ Terse command-style prompts produce shallow, generic work.
         if (params.inherit_context) {
           return textResult("Cannot combine `schedule` with `inherit_context` — there is no parent conversation at fire time.");
         }
-        if (params.run_in_background === false) {
-          return textResult("Cannot combine `schedule` with `run_in_background: false` — scheduled jobs always run in background.");
-        }
         if (!scheduler.isActive()) {
           return textResult("Scheduler is not active in this session yet. Try again after the session has fully started.");
         }
@@ -1283,16 +1312,19 @@ Terse command-style prompts produce shallow, generic work.
             name: params.description as string,
             description: params.description as string,
             schedule: params.schedule as string,
-            subagent_type: subagentType,
+            // The caller's own name, not the substitute — the scheduler re-resolves
+            // at fire time, and the original is what a user edits.
+            subagent_type: requestedType,
             prompt: params.prompt as string,
             thinking: thinking,
             max_turns: effectiveMaxTurns,
             isolated: isolated,
             isolation: isolation,
           });
+          warnOnOutOfScopeModel();
           const next = scheduler.getNextRun(job.id);
           return textResult(
-            `Scheduled "${job.name}" (id: ${job.id}, type: ${job.scheduleType}). ` +
+            `${fallbackNote}Scheduled "${job.name}" (id: ${job.id}, type: ${job.scheduleType}). ` +
             `Next run: ${next ?? "(unknown)"}. ` +
             `Manage via /agents → Scheduled jobs.`,
           );
@@ -1301,32 +1333,103 @@ Terse command-style prompts produce shallow, generic work.
         }
       }
 
-      // Resume existing agent
+      // Resume existing agent — kick off a background resume and return an envelope.
       if (params.resume) {
         const existing = manager.getRecord(params.resume);
-        if (!existing) {
+        // Nested records are reachable only through their spawning agent's
+        // scoped tools; the top-level tool treats them as absent.
+        if (!existing || existing.parentAgentId) {
           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.`);
-        }
-        const record = await manager.resume(params.resume, params.prompt, signal);
-        if (!record) {
-          return textResult(`Failed to resume agent "${params.resume}".`);
+        // Running (including the start prologue, where `settled` may still hold
+        // the prior run's `true`), queued, or winding down — starting now would
+        // race the previous run's settle handler. A queued record has no session
+        // yet, so the active check precedes the session check.
+        if (existing.status === "running" || existing.status === "queued" || existing.settled === false) {
+          return textResult(`Agent "${params.resume}" is still active (running, queued, or winding down) — wait for it to finish before resuming.`);
         }
-        // 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(detailBase, record));
+        if (!existing.session) return textResult(`Agent "${params.resume}" has no active session to resume.`);
+        const { state: resumeState, callbacks: resumeCallbacks } = createActivityTracker(existing.effectiveMaxTurns);
+        const resumeStart = existing.session.messages.length;
+        const record = manager.resume(params.resume, params.prompt, resumeCallbacks);
+        if (!record) return textResult(`Failed to resume agent "${params.resume}".`);
+        // Only once the resume is accepted — a refused resume must not drop the
+        // prior run's still-pending completion nudge.
+        cancelNudge(params.resume);
+        // The session already exists, so onSessionCreated never fires for a resume;
+        // seed it here so the widget/viewer can render the context-fill (NN%).
+        resumeState.session = existing.session;
+        agentActivity.set(record.id, resumeState);
+        if (record.outputFile && record.session) {
+          record.outputCleanup = streamToOutputFile(record.session, record.outputFile, record.id, ctx.cwd, resumeStart);
         }
+        widget.markRunning(record.id);
+        widget.ensureTimer(); widget.update(); fleet.ensureTimer(); fleet.update();
+        // The row's model fields come from the resumed record's resolved
+        // invocation: a resume continues the session's own model, so deriving
+        // them from the call's subagent_type would mix identities. Records
+        // spawned outside the Agent tool (RPC, scheduler, wizard) capture no
+        // invocation — the row then carries only record-owned values (the
+        // effective max turns), never the call's model/strategy settings,
+        // which this resume does not apply. The conversation viewer reads
+        // `record.invocation` directly and renders nothing for those records;
+        // the widget renders from the activity tracker and the record's
+        // type/description.
+        const displayInvocation: AgentInvocation = existing.invocation ?? {
+          maxTurns: existing.effectiveMaxTurns,
+        };
+        const { modelName: resumeModelName, tags: resumeInvocationTags } = buildInvocationTags(displayInvocation);
+        const resumeModeLabel = getPromptModeLabel(existing.type);
+        const resumeTags = resumeModeLabel ? [resumeModeLabel, ...resumeInvocationTags] : resumeInvocationTags;
         return textResult(
-          record.result?.trim() || "No output.",
-          buildDetails(detailBase, record),
+          `Agent resumed in background.\nAgent ID: ${record.id}\nType: ${getDisplayName(existing.type)}\nDescription: ${record.description}\n` +
+          (record.outputFile ? `Output file: ${record.outputFile}\n` : "") +
+          `\nYou will be notified on subagent completion/failure.\n` +
+          `Use get_subagent_result to retrieve full results, or steer_subagent to send it messages.\n` +
+          `Do not duplicate this agent's work.`,
+          {
+            // Row identity mirrors the envelope text above: the record's type
+            // and description, not the resume call's subagent_type/description.
+            displayName: getDisplayName(existing.type),
+            description: record.description,
+            subagentType: existing.type,
+            modelName: resumeModelName,
+            tags: resumeTags.length > 0 ? resumeTags : undefined,
+            toolUses: record.toolUses,
+            tokens: "",
+            durationMs: 0,
+            status: "background" as const,
+            agentId: record.id,
+          },
         );
       }
 
       // Background execution
-      if (runInBackground) {
+      {
+        const displayName = getDisplayName(subagentType);
+        const agentInvocation: AgentInvocation = {
+          modelName,
+          modelId,
+          thinking,
+          // Explicit value only — the default fallback would just add noise.
+          // Normalize so `0` (unlimited) doesn't surface as a misleading "max turns: 0".
+          maxTurns: normalizeMaxTurns(resolvedConfig.maxTurns),
+          isolated,
+          inheritContext,
+          isolation,
+        };
+        // Tool-result render shows the mode label too; viewer's header already does.
+        const modeLabel = getPromptModeLabel(subagentType);
+        const { tags: invocationTags } = buildInvocationTags(agentInvocation);
+        const agentTags = modeLabel ? [modeLabel, ...invocationTags] : invocationTags;
+        const detailBase = {
+          displayName,
+          description: params.description,
+          subagentType,
+          modelName,
+          tags: agentTags.length > 0 ? agentTags : undefined,
+        };
+
         const { state: bgState, callbacks: bgCallbacks } = createActivityTracker(effectiveMaxTurns);
 
         // Wrap onSessionCreated to wire output file streaming.
@@ -1350,192 +1453,68 @@ Terse command-style prompts produce shallow, generic work.
             isolated,
             inheritContext,
             thinkingLevel: thinking,
-            isBackground: true,
             isolation,
             invocation: agentInvocation,
+            rootSessionId: ctx.sessionManager.getSessionId(),
             ...bgCallbacks,
           });
         } catch (err) {
           return textResult(err instanceof Error ? err.message : String(err));
         }
+        warnOnOutOfScopeModel();
 
-        // 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);
+        // Set the output file synchronously after spawn, before the event loop
+        // yields — onSessionCreated is async so this is safe.
         const record = manager.getRecord(id);
-        if (record && joinMode) {
-          record.joinMode = joinMode;
-          record.toolCallId = toolCallId;
-          attachTranscript(record, id);
+        if (record) attachTranscript(record, id);
+
+        // A spawned record can settle before spawn returns: a `subagents:started`
+        // listener stopping it, or an already-aborted parent signal. The
+        // completion callback already removed its activity entry, so re-adding
+        // one would render a `↻1` finished row for a run that never executed a
+        // turn, and the widget timers have no live run to update. The stop
+        // notification remains the delivery for these runs.
+        if (record && record.settled !== true) {
+          agentActivity.set(id, bgState);
+          widget.ensureTimer();
+          widget.update();
+          fleet.ensureTimer();
+          fleet.update();
         }
 
-        if (joinMode == null || joinMode === 'async') {
-          // Foreground/no join mode or explicit async — not part of any batch
-        } else {
-          // smart or group — add to current batch
-          currentBatchAgents.push({ id, joinMode });
-          // Debounce: reset timer on each new agent so parallel tool calls
-          // dispatched across multiple event loop ticks are captured together
-          if (batchFinalizeTimer) clearTimeout(batchFinalizeTimer);
-          batchFinalizeTimer = setTimeout(finalizeBatch, 100);
-        }
-
-        agentActivity.set(id, bgState);
-        widget.ensureTimer();
-        widget.update();
-        fleet.ensureTimer();
-        fleet.update();
-
         // Emit created event
         pi.events.emit("subagents:created", {
           id,
           type: subagentType,
           description: params.description,
-          isBackground: true,
         });
 
         const isQueued = record?.status === "queued";
         return textResult(
-          `Agent ${isQueued ? "queued" : "started"} in background.\n` +
+          `${fallbackNote}Agent ${isQueued ? "queued" : "started"} in background.\n` +
           `Agent ID: ${id}\n` +
           `Type: ${displayName}\n` +
           `Description: ${params.description}\n` +
           (record?.outputFile ? `Output file: ${record.outputFile}\n` : "") +
           (isQueued ? `Position: queued (max ${manager.getMaxConcurrent()} concurrent)\n` : "") +
-          `\nYou will be notified when this agent completes.\n` +
+          `\nYou will be notified on subagent completion/failure.\n` +
           `Use get_subagent_result to retrieve full results, or steer_subagent to send it messages.\n` +
           `Do not duplicate this agent's work.`,
           { ...detailBase, toolUses: 0, tokens: "", durationMs: 0, status: "background" as const, agentId: id },
         );
       }
 
-      // Foreground (synchronous) execution — stream progress via onUpdate
-      let spinnerFrame = 0;
-      const startedAt = Date.now();
-      let fgId: string | undefined;
-
-      const streamUpdate = () => {
-        const details: AgentDetails = {
-          ...detailBase,
-          toolUses: fgState.toolUses,
-          tokens: formatLifetimeTokens(fgState),
-          turnCount: fgState.turnCount,
-          maxTurns: fgState.maxTurns,
-          durationMs: Date.now() - startedAt,
-          status: "running",
-          activity: describeActivity(fgState.activeTools, fgState.responseText),
-          spinnerFrame: spinnerFrame % SPINNER.length,
-        };
-        onUpdate?.({
-          content: [{ type: "text", text: `${fgState.toolUses} tool uses...` }],
-          details: details as any,
-        });
-      };
-
-      const { state: fgState, callbacks: fgCallbacks } = createActivityTracker(effectiveMaxTurns, streamUpdate);
-
-      // 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.
-      const origOnSession = fgCallbacks.onSessionCreated;
-      fgCallbacks.onSessionCreated = (session: any) => {
-        origOnSession(session);
-        for (const a of manager.listAgents()) {
-          if (a.session === session) {
-            fgId = a.id;
-            agentActivity.set(a.id, fgState);
-            widget.ensureTimer();
-            fleet.ensureTimer();
-            fleet.update();
-            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)
-      const spinnerInterval = setInterval(() => {
-        spinnerFrame++;
-        streamUpdate();
-      }, 80);
-
-      streamUpdate();
-
-      let record: AgentRecord;
-      try {
-        const fgResult = await manager.spawnAndWait(pi, ctx, subagentType, params.prompt, {
-          description: params.description,
-          model,
-          maxTurns: effectiveMaxTurns,
-          isolated,
-          inheritContext,
-          thinkingLevel: thinking,
-          isolation,
-          invocation: agentInvocation,
-          signal,
-          ...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);
-        });
-        record = fgResult.record;
-      } catch (err) {
-        clearInterval(spinnerInterval);
-        return textResult(err instanceof Error ? err.message : String(err));
-      }
-
-      clearInterval(spinnerInterval);
-
-      // Clean up foreground agent from widget
-      if (fgId) {
-        agentActivity.delete(fgId);
-        widget.markFinished(fgId);
-        fleet.onAgentFinished(fgId);
-      }
-
-      // Get final token count
-      const tokenText = formatLifetimeTokens(fgState);
-
-      const details = buildDetails(detailBase, record, fgState, { tokens: tokenText });
-
-      // "general-purpose" may itself be unregistered (defaults disabled, no
-      // user override) — getConfig then uses the hardcoded fallback config.
-      const fallbackNote = fellBack
-        ? `Note: Unknown agent type "${rawType}" — using ${resolveType("general-purpose") ? "general-purpose" : "the fallback agent config"}.\n\n`
-        : "";
-
-      if (record.status === "error") {
-        // Error headline + any partial output the run produced before failing.
-        return textResult(`${fallbackNote}Agent failed: ${record.error}${partialOutputSuffix(record)}`, details);
-      }
-
-      const durationMs = (record.completedAt ?? Date.now()) - record.startedAt;
-      const statsParts = [`${record.toolUses} tool uses`];
-      if (tokenText) statsParts.push(tokenText);
-      return textResult(
-        `${fallbackNote}Agent completed in ${formatMs(durationMs)} (${statsParts.join(", ")})${getStatusNote(record.status)}.\n\n` +
-        (record.result?.trim() || "No output."),
-        details,
-      );
     },
   }));
 
   // ---- get_subagent_result tool ----
 
-  pi.registerTool(defineTool({
+  registerParentTool(defineTool({
     name: SUBAGENT_TOOL_NAMES.GET_RESULT,
     label: "Get Agent Result",
     description:
-      "Check status and retrieve results from a background agent. Use the agent ID returned by Agent with run_in_background.",
-    promptSnippet: "Check status and retrieve results from a background agent",
+      "Check a subagent's status and retrieve its result. Use the agent ID returned by the Agent tool.",
+    promptSnippet: "Check a subagent's status and retrieve its result",
     parameters: Type.Object({
       agent_id: Type.String({
         description: "The agent ID to check.",
@@ -1543,201 +1522,124 @@ Terse command-style prompts produce shallow, generic work.
     }),
     execute: async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
       const record = manager.getRecord(params.agent_id);
-      if (!record) {
+      // Nested records belong to their spawning agent's scoped tools only.
+      if (!record || record.parentAgentId) {
         return textResult(`Agent not found: "${params.agent_id}". It may have been cleaned up.`);
       }
 
-      // existsSync gates cover out-of-band file deletion (checkpointsFileOk is latching-true).
-      const checkpointsCandidate = checkpointsFilePath(record.outputFile);
-      const checkpointsPath =
-        record.checkpointsFileOk && checkpointsCandidate && existsSync(checkpointsCandidate)
-          ? checkpointsCandidate
-          : undefined;
-      const transcriptPath =
-        record.outputFile && existsSync(record.outputFile) ? record.outputFile : undefined;
-
-      if (record.status === "running") {
-        return textResult(renderRunning(record, checkpointsPath, transcriptPath));
+      // Mark result as consumed — suppresses the completion notification. Safe
+      // for every status: only a settled record has a nudge parked, and a
+      // running/queued one has none to cancel.
+      if (record.status !== "running" && record.status !== "queued") {
+        record.resultConsumed = true;
+        cancelNudge(params.agent_id);
       }
 
-      // Queued agent: has not started running yet. Return a short shape with no
-      // file paths and no result body, mirroring the `running` early return.
-      if (record.status === "queued") {
-        return textResult(renderQueued(record));
-      }
-
-      // Mark result as consumed — suppresses the completion notification.
-      // Queued agents return above; this block only runs for terminal statuses.
-      // Note: for group-batched agents the nudge is keyed `group:<ids>`, so
-      // cancelNudge(agent_id) is a no-op there — the group send closure's
-      // resultConsumed re-check is what filters this agent out instead.
-      record.resultConsumed = true;
-      cancelNudge(params.agent_id);
-
-      // Attach notification details so renderResult can render the report as
-      // markdown, mirroring the completion notification the parent just
-      // suppressed by consuming synchronously.
-      const details = buildNotificationDetails(record, { failurePreviewMaxChars }, agentActivity.get(record.id));
-
-      if (record.status === "error") {
-        return textResult(renderTerminal(record, checkpointsPath, transcriptPath, true), details);
-      }
-      return textResult(renderTerminal(record, checkpointsPath, transcriptPath, false), details);
+      return textResult(renderAgentReport(record));
     },
 
-    renderResult(result, { expanded }, theme) {
-      const details = result.details as NotificationDetails | undefined;
-      if (!details) {
-        const text = result.content[0]?.type === "text" ? result.content[0].text : "";
-        return new Text(text, 0, 0);
-      }
-      const effectiveExpanded = resultPreviewExpanded ? true : expanded;
-      const container = new Container();
-      container.addChild(subagentNotificationRenderHeader(details, theme));
-      container.addChild(subagentNotificationRenderBody(details, effectiveExpanded, resultPreviewMode, theme));
-      return container;
+    renderResult(result, _options, theme) {
+      const report = result.content[0]?.type === "text" ? result.content[0].text : "";
+      // Display copy only: the tool text returned to the parent model keeps its
+      // raw result/error bodies; the builders collapse its single-line metadata.
+      const display = typeof report === "string" ? stripControlChars(report) : "";
+      return display
+        ? new Markdown(display, 0, 0, getMarkdownTheme(), { color: (t) => theme.fg("toolOutput", t) })
+        : new Text("", 0, 0);
     },
   }));
 
-  /** Queued subagent: no file paths, result body, or footer — nothing produced yet. */
-  function renderQueued(record: AgentRecord): string {
-    const displayName = getDisplayName(record.type);
-    return (
-      `Agent: ${record.id} (queued — not started yet)\n` +
-      `Type: ${displayName} | Description: ${record.description}\n\n` +
-      `This agent is waiting to start. It will begin running when a concurrent-agent slot frees up.`
-    );
-  }
-
-  /** Running subagent: header (turn/elapsed), latest checkpoint, file paths, polling-discouragement footer. */
-  function renderRunning(
-    record: AgentRecord,
-    checkpointsPath: string | undefined,
-    transcriptPath: string | undefined,
-  ): string {
-    const displayName = getDisplayName(record.type);
-    const turn = record.turnCount ?? 0;
-    const maxTurns = record.effectiveMaxTurns;
-    const elapsedSeconds = Math.round((Date.now() - record.startedAt) / 1000);
-    const turnLabel = maxTurns != null ? `turn ${turn}/${maxTurns}` : `turn ${turn}`;
-
-    let output =
-      `Agent: ${record.id} (still running — ${turnLabel}, ${elapsedSeconds}s elapsed)\n` +
-      `Type: ${displayName} | Description: ${record.description}\n\n`;
-
-    if (record.lastCheckpoint) {
-      output +=
-        `Latest checkpoint (turn ${record.lastCheckpoint.turn}):\n` +
-        `  ${record.lastCheckpoint.summary}\n\n`;
-      output += fileSection(checkpointsPath, transcriptPath, footerForPaths(checkpointsPath, transcriptPath, true));
-    } else {
-      output += `No checkpoint yet — the subagent hasn't called the checkpoint tool.\n\n`;
-      output += fileSection(checkpointsPath, transcriptPath,
-        "  grep or read the transcript for detail on what it's doing. Do not poll repeatedly.");
-    }
-    return output;
-  }
-
-  /** Completed/errored subagent: completed header, result or error block, latest checkpoint, file paths. */
-  function renderTerminal(
-    record: AgentRecord,
-    checkpointsPath: string | undefined,
-    transcriptPath: string | undefined,
-    errored: boolean,
-  ): string {
-    const header = completedHeader(record);
-    const body = errored
-      ? `Error: ${record.error}${partialOutputSuffix(record)}`
-      : record.result?.trim() || "No output.";
-
-    let output = `${header}\n\n${body}`;
-    if (record.lastCheckpoint) {
-      output +=
-        `\n\nLatest checkpoint (turn ${record.lastCheckpoint.turn}):\n` +
-        `  ${record.lastCheckpoint.summary}`;
-    }
-    output += "\n\n" + fileSection(checkpointsPath, transcriptPath, footerForPaths(checkpointsPath, transcriptPath, false));
-    return output;
-  }
-
-  /** Shared header for completed/errored shapes (Status + stats + status note). */
-  function completedHeader(record: AgentRecord): string {
-    const displayName = getDisplayName(record.type);
-    const duration = formatDuration(record.startedAt, record.completedAt);
-    const tokens = formatLifetimeTokens(record);
-    const contextPercent = getSessionContextPercent(record.session);
-    const statsParts = [`Tool uses: ${record.toolUses}`];
-    if (tokens) statsParts.push(tokens);
-    if (contextPercent !== null) statsParts.push(`Context: ${Math.round(contextPercent)}%`);
-    if (record.compactionCount) statsParts.push(`Compactions: ${record.compactionCount}`);
-    statsParts.push(`Duration: ${duration}`);
-    return (
-      `Agent: ${record.id}\n` +
-      `Type: ${displayName} | Status: ${record.status}${getStatusNote(record.status)} | ${statsParts.join(" | ")}\n` +
-      `Description: ${record.description}`
-    );
-  }
-
-  /** The checkpoint-history / full-transcript path block, aligned to a shared column, plus the footer. */
-  function fileSection(
-    checkpointsPath: string | undefined,
-    transcriptPath: string | undefined,
-    footer: string,
-  ): string {
-    let s = "";
-    if (checkpointsPath) s += `Checkpoint history: ${checkpointsPath}\n`;
-    if (transcriptPath) s += `Full transcript:   ${transcriptPath}\n`;
-    s += footer;
-    return s;
-  }
-
-  /** Footer matching the paths actually rendered (existsSync can suppress either independently). */
-  function footerForPaths(
-    checkpointsPath: string | undefined,
-    transcriptPath: string | undefined,
-    running: boolean,
-  ): string {
-    const suffix = running ? " Do not poll repeatedly." : "";
-    if (checkpointsPath && transcriptPath) {
-      return `  grep or read the checkpoints / transcript for more detail.${suffix}`;
-    }
-    if (checkpointsPath) {
-      return `  grep or read the checkpoints file for more detail.${suffix}`;
-    }
-    return `  grep or read the transcript for more detail.${suffix}`;
-  }
-
   // ---- steer_subagent tool ----
 
-  pi.registerTool(defineTool({
+  type SteerOutcome = "sent" | "queued" | "not-found" | "not-running" | "failed";
+  const steerResult = (msg: string, steerOutcome: SteerOutcome) => textResult(msg, { steerOutcome });
+
+  registerParentTool(defineTool({
     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. Only works on running agents.",
-    promptSnippet: "Send a steering message to redirect a running background agent",
+      "Send a steering message to a subagent. 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.",
+    promptSnippet: "Send a steering message to redirect a subagent",
     parameters: Type.Object({
       agent_id: Type.String({
-        description: "The agent ID to steer (must be currently running).",
+        description: "The agent ID to steer (must be running or queued).",
       }),
       message: Type.String({
         description: "The steering message to send. This will appear as a user message in the agent's conversation.",
       }),
     }),
+
+    renderCall(args, theme, context) {
+      const a = (args ?? {}) as { agent_id?: unknown; message?: unknown };
+      const agentId = typeof a.agent_id === "string" ? a.agent_id : "";
+      const raw = typeof a.message === "string" ? a.message : "";
+      const state = context.state as { steerDesc?: string };
+
+      // Freeze the first resolved description so record eviction cannot flip the row.
+      if (!state.steerDesc && agentId) {
+        const desc = toSingleLine(manager.getRecord(agentId)?.description);
+        if (desc) state.steerDesc = desc;
+      }
+      // Both header parts are display copies: sanitize + cap.
+      const target = headerPreview(state.steerDesc ?? "") || headerPreview(toSingleLine(agentId));
+
+      const marker = context.expanded ? "▾" : "▸";
+      let head = marker + " " + theme.fg("toolTitle", theme.bold("Steer"));
+      if (target) head += "  " + theme.fg("muted", target);
+
+      // Expanded: the result renderer owns the body once a result exists; while the
+      // call is still pending (no result applied, e.g. replay after an abort) the
+      // call shows it so the instruction is never invisible. The body is
+      // built only when it can be shown, so collapsed renders stay O(preview window).
+      if (context.expanded) {
+        const body = context.isPartial ? instructionBody(raw, theme) : "";
+        return new Text(body ? head + "\n" + body : head, 0, 0);
+      }
+
+      const plain = toSingleLine(safeTruncate(raw, INSTRUCTION_PREVIEW_SCAN_CHARS));
+      const shown = truncateToWidth(plain, INSTRUCTION_PREVIEW_COLS, "…");
+      // A blind 512-unit cut hides content without changing `plain`.
+      const hidden = shown !== plain || raw.length > INSTRUCTION_PREVIEW_SCAN_CHARS || /[\n\r\t]/.test(raw);
+      if (!shown) return new Text(head + (hidden ? instructionHint(theme) : ""), 0, 0);
+      const hint = hidden ? instructionHint(theme) : "";
+      return new Text(head + "  " + theme.fg("muted", shown) + hint, 0, 0);
+    },
+
+    renderResult(result, { expanded }, theme, context) {
+      const outcome = (result.details as { steerOutcome?: SteerOutcome } | undefined)?.steerOutcome;
+      const failure = outcome === "not-found" || outcome === "not-running" || outcome === "failed";
+      // A synthetic abort/error result carries no details.
+      const color = context.isError || failure ? "error" : "dim";
+      const text = result.content[0]?.type === "text" ? result.content[0].text : "";
+      const cleaned = typeof text === "string" ? stripControlChars(text).trimEnd() : "";
+      const status = cleaned.trim()
+        ? cleaned.split("\n").map((l) => theme.fg(color, `  ⎿  ${l}`)).join("\n")
+        : "";
+      const raw = typeof (context.args as { message?: unknown })?.message === "string"
+        ? (context.args as { message: string }).message
+        : "";
+      const body = instructionBody(raw, theme);
+      if (expanded && body) {
+        return new Text(body + (status ? "\n" + status : ""), 0, 0);
+      }
+      return new Text(status, 0, 0);
+    },
+
     execute: async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
       const record = manager.getRecord(params.agent_id);
-      if (!record) {
-        return textResult(`Agent not found: "${params.agent_id}". It may have been cleaned up.`);
+      if (!record || record.parentAgentId) {
+        return steerResult(`Agent not found: "${params.agent_id}". It may have been cleaned up.`, "not-found");
       }
-      if (record.status !== "running") {
-        return textResult(`Agent "${params.agent_id}" is not running (status: ${record.status}). Cannot steer a non-running agent.`);
+      if (record.status !== "running" && record.status !== "queued") {
+        return steerResult(`Agent "${params.agent_id}" is not running (status: ${record.status}). Cannot steer a non-running agent.`, "not-running");
       }
       if (!record.session) {
         // Session not ready yet — queue the steer for delivery once initialized
         if (!record.pendingSteers) record.pendingSteers = [];
         record.pendingSteers.push(params.message);
         pi.events.emit("subagents:steered", { id: record.id, message: params.message });
-        return textResult(`Steering message queued for agent ${record.id}. It will be delivered once the session initializes.`);
+        return steerResult(`Steering message queued for agent ${record.id}. It will be delivered once the session initializes.`, "queued");
       }
 
       try {
@@ -1750,12 +1652,13 @@ Terse command-style prompts produce shallow, generic work.
         stateParts.push(`${record.toolUses} tool ${record.toolUses === 1 ? "use" : "uses"}`);
         if (contextPercent !== null) stateParts.push(`context ${Math.round(contextPercent)}% full`);
         if (record.compactionCount) stateParts.push(`${record.compactionCount} compaction${record.compactionCount === 1 ? "" : "s"}`);
-        return textResult(
+        return steerResult(
           `Steering message sent to agent ${record.id}. The agent will process it after its current tool execution.\n` +
           `Current state: ${stateParts.join(" · ")}`,
+          "sent",
         );
       } catch (err) {
-        return textResult(`Failed to steer agent: ${err instanceof Error ? err.message : String(err)}`);
+        return steerResult(`Failed to steer agent: ${err instanceof Error ? err.message : String(err)}`, "failed");
       }
     },
   }));
@@ -1788,31 +1691,7 @@ Terse command-style prompts produce shallow, generic work.
         if (!record) {
           return textResult("Checkpoint failed: agent record not found.");
         }
-
-        const turn = record.turnCount ?? 0;
-        const maxTurns = record.effectiveMaxTurns;
-        const elapsedSeconds = Math.round((Date.now() - record.startedAt) / 1000);
-        record.lastCheckpoint = { turn, summary: params.summary };
-
-        // Best-effort: a write failure (disk full, missing parent dir) returns a soft
-        // warning instead of crashing the call. checkpointsFileOk is latching-true —
-        // see AgentRecord.checkpointsFileOk for the suppression contract.
-        const checkpointsPath = checkpointsFilePath(record.outputFile);
-        const maxTurnsLabel = maxTurns != null ? `/${maxTurns}` : "";
-        if (checkpointsPath) {
-          try {
-            appendFileSync(
-              checkpointsPath,
-              `## Turn ${turn}${maxTurnsLabel} — ${elapsedSeconds}s elapsed\n${params.summary}\n\n`,
-              "utf-8",
-            );
-            record.checkpointsFileOk = true;
-          } catch (err) {
-            return textResult(`Checkpoint saved in memory, but file write failed: ${err instanceof Error ? err.message : String(err)}.`);
-          }
-        }
-
-        return textResult(`Checkpoint saved (turn ${turn}${maxTurnsLabel}, ${elapsedSeconds}s).`);
+        return textResult(saveCheckpoint(record, params.summary));
       },
     }));
   }
@@ -1860,7 +1739,7 @@ Terse command-style prompts produce shallow, generic work.
     const options: string[] = [];
 
     // Running agents entry (only if there are active agents)
-    const agents = manager.listAgents();
+    const agents = manager.listAgents().filter(a => !a.parentAgentId);
     if (agents.length > 0) {
       const running = agents.filter(a => a.status === "running" || a.status === "queued").length;
       const done = agents.filter(a => a.status === "completed" || a.status === "steered").length;
@@ -1936,14 +1815,17 @@ Terse command-style prompts produce shallow, generic work.
       const cfg = getAgentConfig(name);
       const disabled = cfg?.enabled === false;
       const model = getModelLabel(name, ctx.modelRegistry);
+      const displayName = toSingleLine(name);
       return {
         id: name,
-        label: `${sourceIndicator(cfg)}${name}`,
-        currentValue: model,
-        description: disabled ? "(disabled)" : (cfg?.description ?? name),
+        label: `${sourceIndicator(cfg)}${displayName}`,
+        currentValue: toSingleLine(model),
+        description: disabled ? "(disabled)" : toSingleLine(cfg?.description ?? name),
         // Single-value list so Enter "activates" the row (fires onChange with the
-        // agent's id) without offering anything to actually cycle.
-        values: [model],
+        // agent's id) without offering anything to actually cycle. The value is
+        // the sanitized display copy: SettingsList copies values[0] back into
+        // currentValue on activation, so a raw label would reappear.
+        values: [toSingleLine(model)],
       };
     });
 
@@ -1981,16 +1863,16 @@ Terse command-style prompts produce shallow, generic work.
   }
 
   async function showRunningAgents(ctx: ExtensionCommandContext) {
-    const agents = manager.listAgents();
+    const agents = manager.listAgents().filter(a => !a.parentAgentId);
     if (agents.length === 0) {
       ctx.ui.notify("No agents.", "info");
       return;
     }
 
     const options = agents.map(a => {
-      const dn = getDisplayName(a.type);
+      const dn = toSingleLine(getDisplayName(a.type));
       const dur = formatDuration(a.startedAt, a.completedAt);
-      return `${dn} (${a.description}) · ${a.toolUses} tools · ${a.status} · ${dur}`;
+      return `${dn} (${toSingleLine(a.description)}) · ${a.toolUses} tools · ${toSingleLine(a.status)} · ${dur}`;
     });
 
     const choice = await ctx.ui.select("Running agents", options);
@@ -2020,9 +1902,9 @@ Terse command-style prompts produce shallow, generic work.
       (tui, theme, keybindings, done) => {
         return new ConversationViewer(tui, session, record, activity, theme, done, () => {
           if (manager.abort(record.id)) {
-            ctx.ui.notify(`Stopped "${record.description}".`, "info");
+            ctx.ui.notify(`Stopped "${toSingleLine(record.description)}".`, "info");
           }
-        }, keybindings, (message: string) => manager.steer(record.id, message));
+        }, keybindings, (message: string) => manager.steer(record.id, message), showCost);
       },
       {
         overlay: true,
@@ -2034,7 +1916,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");
+      ctx.ui.notify(`Agent config not found for "${toSingleLine(name)}".`, "warning");
       return;
     }
 
@@ -2059,33 +1941,33 @@ Terse command-style prompts produce shallow, generic work.
       menuOptions = ["Edit", "Disable", "Delete", "Back"];
     }
 
-    const choice = await ctx.ui.select(name, menuOptions);
+    const choice = await ctx.ui.select(toSingleLine(name), menuOptions);
     if (!choice || choice === "Back") return;
 
     if (choice === "Edit" && file) {
       const content = readFileSync(file.path, "utf-8");
-      const edited = await ctx.ui.editor(`Edit ${name}`, content);
+      const edited = await ctx.ui.editor(`Edit ${toSingleLine(name)}`, content);
       if (edited !== undefined && edited !== content) {
         const { writeFileSync } = await import("node:fs");
         writeFileSync(file.path, edited, "utf-8");
         reloadCustomAgents();
-        ctx.ui.notify(`Updated ${file.path}`, "info");
+        ctx.ui.notify(`Updated ${toSingleLine(file.path)}`, "info");
       }
     } else if (choice === "Delete") {
       if (file) {
-        const confirmed = await ctx.ui.confirm("Delete agent", `Delete ${name} from ${file.location} (${file.path})?`);
+        const confirmed = await ctx.ui.confirm("Delete agent", `Delete ${toSingleLine(name)} from ${file.location} (${toSingleLine(file.path)})?`);
         if (confirmed) {
           unlinkSync(file.path);
           reloadCustomAgents();
-          ctx.ui.notify(`Deleted ${file.path}`, "info");
+          ctx.ui.notify(`Deleted ${toSingleLine(file.path)}`, "info");
         }
       }
     } else if (choice === "Reset to default" && file) {
-      const confirmed = await ctx.ui.confirm("Reset to default", `Delete override ${file.path} and restore embedded default?`);
+      const confirmed = await ctx.ui.confirm("Reset to default", `Delete override ${toSingleLine(file.path)} and restore embedded default?`);
       if (confirmed) {
         unlinkSync(file.path);
         reloadCustomAgents();
-        ctx.ui.notify(`Restored default ${name}`, "info");
+        ctx.ui.notify(`Restored default ${toSingleLine(name)}`, "info");
       }
     } else if (choice.startsWith("Eject")) {
       await ejectAgent(ctx, name, cfg);
@@ -2109,7 +1991,7 @@ Terse command-style prompts produce shallow, generic work.
 
     const targetPath = join(targetDir, `${name}.md`);
     if (existsSync(targetPath)) {
-      const overwrite = await ctx.ui.confirm("Overwrite", `${targetPath} already exists. Overwrite?`);
+      const overwrite = await ctx.ui.confirm("Overwrite", `${toSingleLine(targetPath)} already exists. Overwrite?`);
       if (!overwrite) return;
     }
 
@@ -2129,18 +2011,21 @@ Terse command-style prompts produce shallow, generic work.
     else if (Array.isArray(cfg.skills)) fmFields.push(`skills: ${cfg.skills.join(", ")}`);
     if (cfg.disallowedTools?.length) fmFields.push(`disallowed_tools: ${cfg.disallowedTools.join(", ")}`);
     if (cfg.inheritContext) fmFields.push("inherit_context: true");
-    if (cfg.runInBackground) fmFields.push("run_in_background: true");
     if (cfg.outputTranscript === false) fmFields.push("output_transcript: false");
     if (cfg.isolated) fmFields.push("isolated: true");
     if (cfg.memory) fmFields.push(`memory: ${cfg.memory}`);
     if (cfg.isolation) fmFields.push(`isolation: ${cfg.isolation}`);
+    if (cfg.allowedSubagents !== undefined) {
+      fmFields.push(`allowed_subagents: ${cfg.allowedSubagents === "all" ? "all" : cfg.allowedSubagents.join(", ")}`);
+    }
+    if (cfg.maxSubagentDepth !== undefined) fmFields.push(`max_subagent_depth: ${cfg.maxSubagentDepth}`);
 
     const content = `---\n${fmFields.join("\n")}\n---\n\n${cfg.systemPrompt}\n`;
 
     const { writeFileSync } = await import("node:fs");
     writeFileSync(targetPath, content, "utf-8");
     reloadCustomAgents();
-    ctx.ui.notify(`Ejected ${name} to ${targetPath}`, "info");
+    ctx.ui.notify(`Ejected ${toSingleLine(name)} to ${toSingleLine(targetPath)}`, "info");
   }
 
   /** Disable an agent: set enabled: false in its .md file, or create a stub for built-in defaults. */
@@ -2150,14 +2035,14 @@ Terse command-style prompts produce shallow, generic work.
       // Existing file — set enabled: false in frontmatter (idempotent)
       const content = readFileSync(file.path, "utf-8");
       if (content.includes("\nenabled: false\n")) {
-        ctx.ui.notify(`${name} is already disabled.`, "info");
+        ctx.ui.notify(`${toSingleLine(name)} is already disabled.`, "info");
         return;
       }
       const updated = content.replace(/^---\n/, "---\nenabled: false\n");
       const { writeFileSync } = await import("node:fs");
       writeFileSync(file.path, updated, "utf-8");
       reloadCustomAgents();
-      ctx.ui.notify(`Disabled ${name} (${file.path})`, "info");
+      ctx.ui.notify(`Disabled ${toSingleLine(name)} (${toSingleLine(file.path)})`, "info");
       return;
     }
 
@@ -2175,7 +2060,7 @@ Terse command-style prompts produce shallow, generic work.
     const { writeFileSync } = await import("node:fs");
     writeFileSync(targetPath, "---\nenabled: false\n---\n", "utf-8");
     reloadCustomAgents();
-    ctx.ui.notify(`Disabled ${name} (${targetPath})`, "info");
+    ctx.ui.notify(`Disabled ${toSingleLine(name)} (${toSingleLine(targetPath)})`, "info");
   }
 
   /** Enable a disabled agent by removing enabled: false from its frontmatter. */
@@ -2191,11 +2076,11 @@ Terse command-style prompts produce shallow, generic work.
     if (updated.trim() === "---\n---" || updated.trim() === "---\n---\n") {
       unlinkSync(file.path);
       reloadCustomAgents();
-      ctx.ui.notify(`Enabled ${name} (removed ${file.path})`, "info");
+      ctx.ui.notify(`Enabled ${toSingleLine(name)} (removed ${toSingleLine(file.path)})`, "info");
     } else {
       writeFileSync(file.path, updated, "utf-8");
       reloadCustomAgents();
-      ctx.ui.notify(`Enabled ${name} (${file.path})`, "info");
+      ctx.ui.notify(`Enabled ${toSingleLine(name)} (${toSingleLine(file.path)})`, "info");
     }
   }
 
@@ -2232,7 +2117,7 @@ Terse command-style prompts produce shallow, generic work.
 
     const targetPath = join(targetDir, `${name}.md`);
     if (existsSync(targetPath)) {
-      const overwrite = await ctx.ui.confirm("Overwrite", `${targetPath} already exists. Overwrite?`);
+      const overwrite = await ctx.ui.confirm("Overwrite", `${toSingleLine(targetPath)} already exists. Overwrite?`);
       if (!overwrite) return;
     }
 
@@ -2256,11 +2141,18 @@ extensions: <true (inherit all MCP/extension tools), false (none), or comma-sepa
 skills: <true (inherit all), false (none), or comma-separated skill names to preload into prompt. Default: true>
 disallowed_tools: <comma-separated tool names to block, even if otherwise available. Omit for none>
 inherit_context: <true to fork parent conversation into agent so it sees chat history. Default: false>
-run_in_background: <true to run in background by default. Default: false>
 output_transcript: <false to write no transcript file or path for this agent. Independent of persist_session. Default: true>
 isolated: <true for no extension/MCP tools, only built-in tools. Default: false>
-memory: <"user" (global), "project" (per-project), or "local" (gitignored per-project) for persistent memory. Omit for none>
-isolation: <"worktree" to run in isolated git worktree. Omit for normal>
+memory: <"user" (global), "project" (per-project), or "local" (gitignored per-project) for persistent memory. Omit for none>${
+      // Offering the field on a project that turned worktrees off would bake a
+      // request that is refused at spawn time into a file that outlives the
+      // session. Built per invocation, so this read is live.
+      isWorktreeIsolationEnabled()
+        ? `\nisolation: <"worktree" to run in isolated git worktree; "off" to refuse one even when the caller asks. Omit for normal>`
+        : ""
+    }
+allowed_subagents: <"all", a comma-separated list of agent types this agent may delegate to, or omit for no nested delegation>
+max_subagent_depth: <optional per-agent nesting cap; can only lower the project's maxSubagentDepth>
 ---
 
 <system prompt body — instructions for the agent>
@@ -2273,25 +2165,49 @@ Guidelines for choosing settings:
 - Use prompt_mode: replace for fully custom agents with their own personality/instructions
 - Set inherit_context: true if the agent needs to know what was discussed in the parent conversation
 - Set isolated: true if the agent should NOT have access to MCP servers or other extensions
-- Set output_transcript: false to skip writing this agent's transcript; this alone doesn't keep the run off disk (persist_session, isolation: worktree commits, and memory still write) — set those too if that's the goal
+- Set output_transcript: false to skip writing this agent's transcript; it doesn't keep the run off disk — every run writes a pi session file while it runs (kept after it settles only with persist_session: true), and isolation: worktree commits and memory still write
 - Only include frontmatter fields that differ from defaults — omit fields where the default is fine
 
 Write the file using the write tool. Only write the file, nothing else.`;
 
-    const { record } = await manager.spawnAndWait(pi, ctx, "general-purpose", generatePrompt, {
-      description: `Generate ${name} agent`,
-      maxTurns: 5,
-    });
-
-    if (record.status === "error") {
-      ctx.ui.notify(`Generation failed: ${record.error}`, "warning");
+    let id: string;
+    try {
+      // Deliberately outside `resolveSpawnType`: this is the extension's own
+      // generator, not a caller-supplied spawn, and it wants the all-tools tier.
+      // Routing it through `fallbackSubagent: none` would break the wizard for
+      // users who opted into strict dispatch.
+      id = manager.spawn(pi, ctx, "general-purpose", generatePrompt, {
+        description: `Generate ${name} agent`,
+        maxTurns: WIZARD_MAX_TURNS,
+      });
+    } catch (err) {
+      ctx.ui.notify(`Generation failed: ${err instanceof Error ? err.message : String(err)}`, "warning");
       return;
     }
+    const record = manager.getRecord(id)!;
+    // Stop polling when the record settles (stopped/error) or leaves the
+    // manager entirely — dispose() clears the map without touching the
+    // status, so the identity check keeps this from spinning forever.
+    while (manager.getRecord(id) === record && record.status === "queued") {
+      await new Promise((r) => setTimeout(r, WIZARD_QUEUE_POLL_MS));
+    }
+    // The record left the manager without settling (a dispose() that clears
+    // the map without aborting first): the run never started, so report the
+    // cancellation instead of toasting a completed-then-missing file. Real
+    // teardown aborts before it disposes — this keeps a dispose-without-abort
+    // eviction from falling through to the created/not-created toast.
+    if (manager.getRecord(id) !== record) {
+      ctx.ui.notify("Generation cancelled.", "info");
+      return;
+    }
+    await record.promise;                       // undefined when stopped-while-queued → resolves
+    if (record.status === "error") { ctx.ui.notify(`Generation failed: ${toSingleLine(record.error)}`, "warning"); return; }
+    if (record.status === "stopped") { ctx.ui.notify("Generation cancelled.", "info"); return; }
 
     reloadCustomAgents();
 
     if (existsSync(targetPath)) {
-      ctx.ui.notify(`Created ${targetPath}`, "info");
+      ctx.ui.notify(`Created ${toSingleLine(targetPath)}`, "info");
     } else {
       ctx.ui.notify("Agent generation completed but file was not created. Check the agent output.", "warning");
     }
@@ -2368,14 +2284,14 @@ ${systemPrompt}
     const targetPath = join(targetDir, `${name}.md`);
 
     if (existsSync(targetPath)) {
-      const overwrite = await ctx.ui.confirm("Overwrite", `${targetPath} already exists. Overwrite?`);
+      const overwrite = await ctx.ui.confirm("Overwrite", `${toSingleLine(targetPath)} already exists. Overwrite?`);
       if (!overwrite) return;
     }
 
     const { writeFileSync } = await import("node:fs");
     writeFileSync(targetPath, content, "utf-8");
     reloadCustomAgents();
-    ctx.ui.notify(`Created ${targetPath}`, "info");
+    ctx.ui.notify(`Created ${toSingleLine(targetPath)}`, "info");
   }
 
   function snapshotSettings(): SubagentsSettings {
@@ -2385,27 +2301,51 @@ ${systemPrompt}
       // normalizeMaxTurns() in agent-runner.ts (which maps 0 → undefined).
       defaultMaxTurns: getDefaultMaxTurns() ?? 0,
       graceTurns: getGraceTurns(),
-      defaultJoinMode: getDefaultJoinMode(),
+      maxSubagentDepth: getMaxSubagentDepth(),
       schedulingEnabled: isSchedulingEnabled(),
       scopeModels: isScopeModelsEnabled(),
-      resultPreviewMode,
-      resultPreviewExpanded,
+      strictAgentFiles,
       failurePreviewMaxChars,
       disableDefaultAgents: isDefaultsDisabled(),
       toolDescriptionMode: getToolDescriptionMode(),
       fleetView: isFleetViewEnabled(),
       widgetMode: getWidgetMode(),
       outputTranscript: getOutputTranscriptDefault(),
+      worktreeIsolation: isWorktreeIsolationEnabled(),
+      // Deliberately NOT `?? "general-purpose"`: every settings change writes the
+      // whole snapshot, and materializing the implicit default would turn it into
+      // explicit configuration — which then fails loudly if general-purpose later
+      // goes away. undefined is dropped by JSON.stringify.
+      fallbackSubagent: getFallbackSubagent(),
+      reportUsage: isReportUsageEnabled(),
+      showCost: isShowCostEnabled(),
+      showModel: isShowModelEnabled(),
     };
   }
 
-  const NUMERIC_IDS = new Set(["maxConcurrent", "defaultMaxTurns", "graceTurns", "failurePreviewMaxChars"]);
+  const NUMERIC_IDS = new Set(["maxConcurrent", "defaultMaxTurns", "graceTurns", "maxSubagentDepth", "failurePreviewMaxChars"]);
 
   async function showSettings(ctx: ExtensionCommandContext) {
     function buildItems(): SettingItem[] {
       const mc = manager.getMaxConcurrent();
       const dmt = getDefaultMaxTurns() ?? 0;
       const gt = getGraceTurns();
+      const msd = getMaxSubagentDepth();
+      // Label what unset actually does — it targets general-purpose even when
+      // that is unregistered (the permissive hardcoded tier), so showing "none"
+      // there would advertise strict dispatch for the most permissive state.
+      // `values` still offers only resolvable targets, so the user cannot
+      // persist a fallback that would hard-error on every dispatch.
+      // The row must never show a value that is absent from `values`: pi-tui's
+      // cycle handler computes `values.indexOf(currentValue)` and writes
+      // `values[0]` on -1, so a missing current value turns one Enter into a
+      // silent rewrite to whatever happens to be first — a custom agent, once the
+      // defaults are disabled. Including the current value makes Enter mean
+      // "cycle from what is shown", which is what every other row means.
+      const fallback = fallbackRow(getFallbackSubagent(), getAvailableTypes(), NO_FALLBACK, isFallbackResolvable);
+      const fallbackValue = fallback.value;
+      const fallbackValues = fallback.values;
+      const fallbackUnresolvable = fallback.unresolvable;
 
       return [
         {
@@ -2430,11 +2370,11 @@ ${systemPrompt}
           values: [String(gt)],
         },
         {
-          id: "joinMode",
-          label: "Join mode",
-          description: "Default join mode for background agents",
-          currentValue: getDefaultJoinMode(),
-          values: ["smart", "async", "group"],
+          id: "maxSubagentDepth",
+          label: "Nested depth",
+          description: "Hard cap on nested delegation — main is 0, its subagents 1 (0/1 = nesting off, Enter to type)",
+          currentValue: String(msd),
+          values: [String(msd)],
         },
         {
           id: "schedulingEnabled",
@@ -2451,17 +2391,10 @@ ${systemPrompt}
           values: ["on", "off"],
         },
         {
-          id: "resultPreviewMode",
-          label: "Result preview mode",
-          description: "Render result body as markdown or plain text",
-          currentValue: resultPreviewMode,
-          values: ["markdown", "plain"],
-        },
-        {
-          id: "resultPreviewExpanded",
-          label: "Result preview expanded by default",
-          description: "Always show expanded result preview, ignoring pi's expanded flag",
-          currentValue: resultPreviewExpanded ? "on" : "off",
+          id: "strictAgentFiles",
+          label: "Strict agent files",
+          description: "Fail startup on an unreadable/unparseable agent .md instead of skipping it with a warning",
+          currentValue: strictAgentFiles ? "on" : "off",
           values: ["on", "off"],
         },
         {
@@ -2485,6 +2418,49 @@ ${systemPrompt}
           currentValue: getOutputTranscriptDefault() ? "on" : "off",
           values: ["on", "off"],
         },
+        {
+          id: "worktreeIsolation",
+          label: "Worktree isolation",
+          description:
+            "Allow isolation: worktree to copy the repo. Off refuses worktrees on every path immediately — for repos where a copy costs too much time or disk — and drops the `isolation` param from the Agent tool spec on next pi session.",
+          currentValue: isWorktreeIsolationEnabled() ? "on" : "off",
+          values: ["on", "off"],
+        },
+        {
+          id: "fallbackSubagent",
+          label: "Fallback agent",
+          description:
+            `Agent used when subagent_type is unknown, disabled, or ambiguous; "${NO_FALLBACK}" rejects the call instead (strict dispatch)` +
+            (fallbackUnresolvable
+              ? " — currently unresolvable: that agent is deleted, disabled, or a default with Disable defaults on, so unknown types are refused"
+              : ""),
+          currentValue: fallbackValue,
+          values: fallbackValues,
+        },
+        {
+          id: "reportUsage",
+          label: "Report usage to session",
+          description:
+            "Add subagent tokens and cost to this session's own totals, so pi's footer and /cost stop reading a delegating session as nearly free. Reported on the next tool result (agents that finish in the background are counted on the one after). Context-window % is unaffected.",
+          currentValue: isReportUsageEnabled() ? "on" : "off",
+          values: ["on", "off"],
+        },
+        {
+          id: "showCost",
+          label: "Show cost",
+          description:
+            "Show an estimated `~$0.0042` beside subagent token counts in the widget, fleet view, conversation viewer, results and notifications. Priced by pi from the model's rates — omitted entirely for a model it has no rates for.",
+          currentValue: isShowCostEnabled() ? "on" : "off",
+          values: ["on", "off"],
+        },
+        {
+          id: "showModel",
+          label: "Show model",
+          description:
+            "Name the model driving each agent, and the thinking level it is running at, on the widget's running rows. The conversation viewer shows the pair either way — this adds it to the widget, where the row is already dense.",
+          currentValue: isShowModelEnabled() ? "on" : "off",
+          values: ["on", "off"],
+        },
         {
           id: "fleetView",
           label: "Fleet view",
@@ -2495,9 +2471,9 @@ ${systemPrompt}
         {
           id: "widgetMode",
           label: "Widget",
-          description: "Above-editor agent widget: all = every agent; background = hide foreground (they already render inline); off = hide the widget.",
+          description: "Above-editor agent widget: all = every agent; off = hide the widget.",
           currentValue: getWidgetMode(),
-          values: ["all", "background", "off"],
+          values: ["all", "off"],
         },
         {
           id: "toolDescriptionMode",
@@ -2531,9 +2507,17 @@ ${systemPrompt}
           setGraceTurns(n);
           notifyApplied(ctx, `Grace turns set to ${n}`);
         }
-      } else if (id === "joinMode") {
-        setDefaultJoinMode(value as JoinMode);
-        notifyApplied(ctx, `Default join mode set to ${value}`);
+      } else if (id === "maxSubagentDepth") {
+        const n = parseInt(value, 10);
+        if (n >= 0) {
+          setMaxSubagentDepth(n);
+          notifyApplied(
+            ctx,
+            n <= 1
+              ? "Nested delegation disabled"
+              : `Nested depth set to ${n}. Applies to agents started from now on.`,
+          );
+        }
       } else if (id === "schedulingEnabled") {
         const enabled = value === "on";
         if (enabled === isSchedulingEnabled()) {
@@ -2550,30 +2534,83 @@ ${systemPrompt}
         const enabled = value === "on";
         setScopeModelsEnabled(enabled);
         notifyApplied(ctx, `Scope models ${enabled ? "enabled" : "disabled"}`);
-      } else if (id === "resultPreviewMode") {
-        setResultPreviewMode(value as ResultPreviewMode);
-        notifyApplied(ctx, `Result preview mode set to ${value}`);
-      } else if (id === "resultPreviewExpanded") {
-        const expanded = value === "on";
-        setResultPreviewExpanded(expanded);
-        notifyApplied(ctx, `Result preview expanded by default ${expanded ? "enabled" : "disabled"}`);
+      } else if (id === "strictAgentFiles") {
+        const enabled = value === "on";
+        strictAgentFiles = enabled;
+        notifyApplied(ctx, `Strict agent files ${enabled ? "enabled" : "disabled"}. Takes effect on next pi session.`);
+      } else if (id === "worktreeIsolation") {
+        const enabled = value === "on";
+        setWorktreeIsolationEnabled(enabled);
+        // The refusal is live, but the tool schema is built at registration, so
+        // the isolation parameter only appears/disappears next session.
+        notifyApplied(
+          ctx,
+          `Worktree isolation ${enabled ? "enabled" : "disabled"}. Tool parameter updates on next pi session.`,
+        );
+      } else if (id === "fallbackSubagent") {
+        // The row's value list is built when the menu opens, so a toggle in the
+        // same menu (Disable defaults) can leave it stale. Persisting a fallback
+        // that dispatch would then refuse is the one outcome to avoid: keep the
+        // current value and say why, rather than writing a broken one.
+        if (fallbackRow(value, getAvailableTypes(), NO_FALLBACK, isFallbackResolvable).unresolvable) {
+          // pi-tui has already written the refused value into the row, so put the
+          // real one back or the next Enter cycles past a value the user can no
+          // longer select.
+          list?.updateValue("fallbackSubagent", getFallbackSubagent() ?? IMPLICIT_FALLBACK);
+          ctx.ui.notify(`Agent "${value}" is not available — fallback unchanged.`, "warning");
+          return;
+        }
+        setFallbackSubagent(value);
+        notifyApplied(
+          ctx,
+          value === NO_FALLBACK
+            ? "Unknown or disabled agent types will now be rejected"
+            : `Unknown agent types will fall back to ${value}`,
+        );
       } else if (id === "failurePreviewMaxChars") {
         const n = parseInt(value, 10);
-        if (n >= 1 && n <= RESULT_PREVIEW_MAX_CHARS_CEILING) {
+        if (n >= 1 && n <= FAILURE_PREVIEW_MAX_CHARS_CEILING) {
           setFailurePreviewMaxChars(n);
           notifyApplied(ctx, `Failure preview max chars set to ${n}`);
         }
       } else if (id === "disableDefaultAgents") {
         const enabled = value === "on";
+        // The setter re-registers the registry itself, so the next spawn already
+        // sees the toggle; this applier only has to report what it orphaned.
         setDisableDefaultAgents(enabled);
-        notifyApplied(ctx, `Default agents ${enabled ? "disabled" : "enabled"}. Tool spec change takes effect on next pi session.`);
+        const orphaned = fallbackRow(getFallbackSubagent(), getAvailableTypes(), NO_FALLBACK, isFallbackResolvable)
+          .unresolvable;
+        notifyApplied(
+          ctx,
+          `Default agents ${enabled ? "disabled" : "enabled"}. Tool spec change takes effect on next pi session.` +
+            (orphaned
+              ? ` Fallback agent "${getFallbackSubagent()}" no longer resolves — unknown agent types will be refused until it is changed.`
+              : ""),
+        );
       } else if (id === "outputTranscript") {
         const enabled = value === "on";
-        setOutputTranscript(enabled);
+        setOutputTranscriptDefault(enabled);
         notifyApplied(ctx, `Output transcript ${enabled ? "enabled" : "disabled"} by default`);
       } else if (id === "toolDescriptionMode") {
         setToolDescriptionMode(value as ToolDescriptionMode);
         notifyApplied(ctx, `Tool description set to ${value}. Takes effect on next pi session.`);
+      } else if (id === "reportUsage") {
+        const enabled = value === "on";
+        setReportUsage(enabled);
+        notifyApplied(
+          ctx,
+          enabled
+            ? "Subagent usage now counted in this session's totals"
+            : "Subagent usage no longer counted in this session's totals",
+        );
+      } else if (id === "showCost") {
+        const enabled = value === "on";
+        setShowCost(enabled);
+        notifyApplied(ctx, `Cost display ${enabled ? "enabled" : "disabled"}`);
+      } else if (id === "showModel") {
+        const enabled = value === "on";
+        setShowModel(enabled);
+        notifyApplied(ctx, `Model display ${enabled ? "enabled" : "disabled"}`);
       } else if (id === "fleetView") {
         const enabled = value === "on";
         setFleetViewEnabled(enabled);
@@ -2584,7 +2621,7 @@ ${systemPrompt}
       }
     }
 
-    let list: SettingsList;
+    let list: SettingsList | undefined;
     // Track current selection index directly (SettingsList doesn't expose it).
     // Updated on arrow keys so Enter knows which field is selected immediately.
     let currentIndex = 0;
@@ -2605,7 +2642,7 @@ ${systemPrompt}
       const container = new Container();
       container.addChild(new Text("⚙  Subagent Settings", 0, 0));
       container.addChild(new Spacer(1));
-      container.addChild(list);
+      if (list) container.addChild(list);
 
       return {
         render: (w: number) => container.render(w),
@@ -2623,24 +2660,21 @@ ${systemPrompt}
             done(items[currentIndex].id);
             return;
           }
-          list.handleInput?.(data);
+          list?.handleInput?.(data);
         },
       };
     });
 
     // If a numeric field ID was returned, prompt for typed input
     if (result && NUMERIC_IDS.has(result)) {
-      const current = result === "maxConcurrent"
-        ? String(manager.getMaxConcurrent())
-        : result === "defaultMaxTurns"
-          ? String(getDefaultMaxTurns() ?? 0)
-          : String(getGraceTurns());
-
-      const label = result === "maxConcurrent"
-        ? "Max concurrency (1+)"
-        : result === "defaultMaxTurns"
-          ? "Default max turns (0 = unlimited)"
-          : "Grace turns (1+)";
+      const numericPrompt: Record<string, { current: string; label: string }> = {
+        maxConcurrent: { current: String(manager.getMaxConcurrent()), label: "Max concurrency (1+)" },
+        defaultMaxTurns: { current: String(getDefaultMaxTurns() ?? 0), label: "Default max turns (0 = unlimited)" },
+        graceTurns: { current: String(getGraceTurns()), label: "Grace turns (1+)" },
+        maxSubagentDepth: { current: String(getMaxSubagentDepth()), label: "Nested depth (0/1 = nesting off)" },
+        failurePreviewMaxChars: { current: String(failurePreviewMaxChars), label: "Failure preview max chars (1+)" },
+      };
+      const { current, label } = numericPrompt[result];
 
       // Loop until user enters a valid integer or cancels (Esc / null).
       // Silently trims whitespace; rejects non-numeric input by re-prompting.