@narumitw/pi-subagents 3.3.3 → 3.4.1

package/dist/index.ts

@@ -4,37 +4,43 @@ import {
   CHILD_COMMUNICATION_TOOL_NAMES,
   prepareTimeoutArguments,
   resolveTimeoutMs
-} from "./chunks/chunk-ZOAFWLDJ.ts";
+} from "./chunks/chunk-PRIDTAJL.ts";
 import {
   addAttachmentIgnoreRules,
+  assertChildModelPair,
+  assertChildModelState,
+  assertTrustedChildResources,
   isAbortError,
   isRecord,
   isWithin,
+  parseReadinessFrame,
   realpath,
   throwIfAttachmentAborted,
   toPosixPath,
   toolSourceId
-} from "./chunks/chunk-3FCHXUKZ.ts";
+} from "./chunks/chunk-B3RWNGDX.ts";
 import {
   BROKER_CREDENTIAL_FD,
   CHILD_READINESS_FD,
-  CHILD_READINESS_FD_ENV,
+  MAX_BOOTSTRAP_BYTES,
   MAX_IDENTIFIER_LENGTH,
   MAX_MESSAGE_BYTES,
   MAX_READINESS_FRAME_BYTES,
   MessageBroker,
   assertChildBootstrapCapacity,
   childBootstrapEnvironment,
+  optionalIdentifier,
+  requiredIdentifier,
   sanitizeTerminalText,
   serializeChildBootstrap,
   validateMessage
-} from "./chunks/chunk-YMVSJ5GE.ts";
+} from "./chunks/chunk-YV2P6XJX.ts";
 import {
   CHILD_CORE_TOOL_NAMES,
   DEFAULT_SUBAGENT_TOOLS,
   SUBAGENT_THINKING_LEVELS,
   TERMINAL_JOB_STATES
-} from "./chunks/chunk-FY5HIU6Y.ts";
+} from "./chunks/chunk-5OXDVXXO.ts";
 
 // src/display-text.ts
 function sanitizeSubagentDisplayText(value) {
@@ -102,8 +108,8 @@ import { dirname, join } from "node:path";
 import { getAgentDir, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 var DEFAULT_SUBAGENT_SETTINGS = Object.freeze({
   showWidget: true,
-  showJobId: true,
-  showTools: true,
+  showJobId: false,
+  showTools: false,
   showTiming: true
 });
 var SETTINGS_KEYS = Object.keys(DEFAULT_SUBAGENT_SETTINGS);
@@ -263,10 +269,68 @@ import * as path from "node:path";
 import { StringDecoder } from "node:string_decoder";
 import { fileURLToPath } from "node:url";
 import { getPackageDir } from "@earendil-works/pi-coding-agent";
+
+// src/rpc-line-decoder.ts
+var MAX_EVENT_LINE_BYTES = 256 * 1024;
+var JsonLineDecoder = class {
+  constructor(onValue, onMalformed) {
+    this.onValue = onValue;
+    this.onMalformed = onMalformed;
+  }
+  onValue;
+  onMalformed;
+  fragments = [];
+  bytes = 0;
+  dropping = false;
+  decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+  push(chunk) {
+    const data = typeof chunk === "string" ? Buffer.from(chunk, "utf8") : chunk;
+    let offset = 0;
+    while (offset < data.length) {
+      const newline = data.indexOf(10, offset);
+      const end = newline < 0 ? data.length : newline;
+      const fragment = data.subarray(offset, end);
+      if (!this.dropping) {
+        if (this.bytes + fragment.length > MAX_EVENT_LINE_BYTES) {
+          this.clear();
+          this.dropping = true;
+          this.onMalformed();
+        } else if (fragment.length > 0) {
+          this.fragments.push(Buffer.from(fragment));
+          this.bytes += fragment.length;
+        }
+      }
+      if (newline < 0) return;
+      this.complete();
+      offset = newline + 1;
+    }
+  }
+  finish() {
+    this.complete();
+  }
+  complete() {
+    const dropping = this.dropping;
+    const line = Buffer.concat(this.fragments, this.bytes);
+    this.clear();
+    this.dropping = false;
+    if (dropping || line.length === 0) return;
+    try {
+      const text = this.decoder.decode(line);
+      if (text.trim()) this.onValue(JSON.parse(text));
+    } catch {
+      this.onMalformed();
+    }
+  }
+  clear() {
+    this.fragments = [];
+    this.bytes = 0;
+  }
+};
+
+// src/process.ts
 var CORE_PACKAGE_NAME = "@earendil-works/pi-coding-agent";
 var MAX_OUTPUT_BYTES = 32 * 1024;
 var MAX_ERROR_BYTES = 8 * 1024;
-var MAX_EVENT_LINE_BYTES = 256 * 1024;
 var RPC_RESPONSE_TIMEOUT_MS = 3e4;
 var KILL_GRACE_MS = 1e3;
 var MAX_WINDOWS_COMMAND_LINE_CODE_UNITS = 32767;
@@ -302,15 +366,9 @@ function buildPiArgs(request) {
   ];
   if (request.tools.includes("codemode")) args.push("-e", "builtin:codemode");
   for (const extension of request.extensions) args.push("-e", extension.path);
-  if (requiresReadinessAttestation(request)) args.push("-e", childReadinessProbePath());
+  args.push("-e", childReadinessProbePath());
   for (const skill of request.skills) args.push("--skill", skill);
-  args.push(
-    "--model",
-    request.model,
-    "--thinking",
-    request.thinkingLevel,
-    request.projectTrusted ? "--approve" : "--no-approve"
-  );
+  args.push("--thinking", request.thinkingLevel, request.projectTrusted ? "--approve" : "--no-approve");
   args.push("--tools", selectedChildTools(request).join(","));
   return args;
 }
@@ -346,9 +404,6 @@ function childCommunicationBridgePath() {
 function childReadinessProbePath() {
   return fileURLToPath(new URL("./child-readiness-probe.ts", import.meta.url));
 }
-function requiresReadinessAttestation(request) {
-  return request.tools.includes("codemode") || request.extensions.length > 0;
-}
 function selectedChildTools(request) {
   return [
     .../* @__PURE__ */ new Set([
@@ -361,8 +416,8 @@ function selectedChildTools(request) {
 async function executeProcess(invocation, request) {
   const timeoutMs = resolveTimeoutMs(request.timeout);
   const expectedTools = selectedChildTools(request);
-  const expectReadiness = requiresReadinessAttestation(request);
-  if (expectReadiness) assertChildBootstrapCapacity(expectedTools);
+  const selection = { provider: request.provider, model: request.model, thinkingLevel: request.thinkingLevel };
+  assertChildBootstrapCapacity(expectedTools, selection);
   let latestOutput = "";
   let terminalOutput;
   let terminalStopReason;
@@ -397,7 +452,7 @@ async function executeProcess(invocation, request) {
   };
   let malformedEvents = 0;
   let rpcCounter = 0;
-  let attachmentStartupPending = expectReadiness;
+  let attachmentReady = false;
   let attachmentStartupError;
   const pendingCommands = /* @__PURE__ */ new Map();
   let rpcInputError;
@@ -436,7 +491,9 @@ async function executeProcess(invocation, request) {
   const decoder = new JsonLineDecoder(
     (value) => {
       const event = value;
-      if (expectReadiness && event.type === "extension_error" && (event.event === "session_start" || event.event === "resources_discover") && !attachmentStartupError) {
+      if (event.type === "extension_error" && ["session_start", "resources_discover", "model_select", "thinking_level_select"].includes(
+        String(event.event)
+      ) && !attachmentStartupError) {
         const detail = typeof event.error === "string" && event.error ? redactAttachmentPaths(sanitizeTerminalText(event.error), request) : "Unknown error.";
         attachmentStartupError = `Subagent attachment startup failed during ${event.event}: ${detail}`;
         return;
@@ -444,7 +501,9 @@ async function executeProcess(invocation, request) {
       if (event.type === "response" && typeof event.id === "string") {
         const pending = pendingCommands.get(event.id);
         if (!pending) return;
-        if (event.success === true) {
+        if (event.command !== pending.command) {
+          rejectPendingCommand(event.id, new Error("Subagent RPC response returned an invalid command."));
+        } else if (event.success === true) {
           resolvePendingCommand(event.id, event);
         } else {
           rejectPendingCommand(
@@ -483,8 +542,9 @@ async function executeProcess(invocation, request) {
     },
     () => {
       malformedEvents++;
-      if (attachmentStartupPending && !attachmentStartupError) {
+      if (!attachmentReady && !attachmentStartupError) {
         attachmentStartupError = "Subagent attachment startup emitted malformed or oversized RPC output.";
+        failRpcInput(new Error(attachmentStartupError));
       }
     }
   );
@@ -498,10 +558,10 @@ async function executeProcess(invocation, request) {
     let timedOut = false;
     let completed = false;
     let ready = false;
-    let attachmentReady = !expectReadiness;
     let promptStarted = false;
     let readinessPipe;
     let deadline;
+    let startupDeadline;
     let forceClose;
     let escalation;
     let termination;
@@ -512,6 +572,7 @@ async function executeProcess(invocation, request) {
         if (settled) return;
         settled = true;
         if (deadline) clearTimeout(deadline);
+        if (startupDeadline) clearTimeout(startupDeadline);
         if (forceClose) clearTimeout(forceClose);
         if (escalation) clearTimeout(escalation);
         request.signal.removeEventListener("abort", onAbort);
@@ -526,6 +587,8 @@ async function executeProcess(invocation, request) {
     const terminate = (code) => {
       if (settled || terminating) return;
       terminating = true;
+      rejectPendingCommands(new Error("Subagent RPC process is terminating."));
+      if (startupDeadline) clearTimeout(startupDeadline);
       if (deadline) {
         clearTimeout(deadline);
         deadline = void 0;
@@ -561,15 +624,14 @@ async function executeProcess(invocation, request) {
     try {
       const environment = {
         ...globalThis.process.env,
-        ...childBootstrapEnvironment(expectReadiness),
+        ...childBootstrapEnvironment(true),
         PI_SUBAGENT_DEPTH: String((Number.parseInt(globalThis.process.env.PI_SUBAGENT_DEPTH ?? "0", 10) || 0) + 1)
       };
-      if (!expectReadiness) delete environment[CHILD_READINESS_FD_ENV];
       process2 = spawn(invocation.command, invocation.args, {
         cwd: request.cwd,
         detached: globalThis.process.platform !== "win32",
         shell: false,
-        stdio: expectReadiness ? ["pipe", "pipe", "pipe", "pipe", "pipe"] : ["pipe", "pipe", "pipe", "pipe"],
+        stdio: ["pipe", "pipe", "pipe", "pipe", "pipe"],
         env: environment
       });
     } catch (error2) {
@@ -626,8 +688,10 @@ async function executeProcess(invocation, request) {
       });
     };
     const startPrompt = () => {
-      if (!spawned || !attachmentReady || promptStarted || settled || cancelled || terminating) return;
+      if (!spawned || !attachmentReady || promptStarted || settled || cancelled || terminating || request.signal.aborted)
+        return;
       promptStarted = true;
+      if (startupDeadline) clearTimeout(startupDeadline);
       void sendCommand(
         { type: "prompt", message: `Task: ${request.task}` },
         () => {
@@ -664,11 +728,18 @@ async function executeProcess(invocation, request) {
     };
     const failReadiness = (message) => {
       if (settled || terminating || attachmentReady) return;
-      errorMessage = truncateText(redactAttachmentPaths(message, request), MAX_ERROR_BYTES).text;
+      const limited = truncateText(redactAttachmentPaths(sanitizeTerminalText(message), request), MAX_ERROR_BYTES);
+      errorMessage = limited.text;
+      truncated ||= limited.truncated;
       terminate(1);
     };
     const confirmAttachmentStartup = () => {
-      void sendCommand({ type: "get_state" }, void 0, request.signal).then(async () => {
+      void sendCommand(
+        { type: "get_state" },
+        (response) => assertChildModelState(response.data, request),
+        request.signal
+      ).then(async () => {
+        if (settled || terminating || request.signal.aborted) return;
         if (attachmentStartupError) throw new Error(attachmentStartupError);
         if (!request.projectTrusted) {
           await sendCommand(
@@ -677,8 +748,8 @@ async function executeProcess(invocation, request) {
             request.signal
           );
         }
+        if (settled || terminating || request.signal.aborted) return;
         if (attachmentStartupError) throw new Error(attachmentStartupError);
-        attachmentStartupPending = false;
         attachmentReady = true;
         startPrompt();
       }).catch((error2) => {
@@ -691,7 +762,9 @@ async function executeProcess(invocation, request) {
       spawned = true;
       startPrompt();
     });
-    if (expectReadiness) {
+    {
+      startupDeadline = setTimeout(() => failReadiness("Subagent child readiness timed out."), RPC_RESPONSE_TIMEOUT_MS);
+      startupDeadline.unref();
       const candidate = process2.stdio[CHILD_READINESS_FD];
       if (!candidate || !("on" in candidate)) {
         errorMessage = "Subagent readiness pipe is unavailable.";
@@ -714,6 +787,7 @@ async function executeProcess(invocation, request) {
           let frame;
           try {
             frame = parseReadinessFrame(buffer, expectedTools.length);
+            if (frame.ok) assertChildModelPair(frame.model, request);
           } catch (error2) {
             failReadiness(error2 instanceof Error ? error2.message : String(error2));
             return;
@@ -779,7 +853,8 @@ async function executeProcess(invocation, request) {
         credentialPipe.end(
           serializeChildBootstrap({
             communication: request.communication,
-            expectedTools: expectReadiness ? expectedTools : []
+            expectedTools,
+            selection
           })
         );
       } catch {
@@ -920,62 +995,6 @@ function killImmediateChild(process2) {
   } catch {
   }
 }
-function assertTrustedChildResources(value, cwd) {
-  const invalid = () => new Error("Subagent child resource attestation returned invalid commands.");
-  if (!value || typeof value !== "object" || Array.isArray(value)) throw invalid();
-  const commands = value.commands;
-  if (!Array.isArray(commands)) throw invalid();
-  let canonicalCwd;
-  try {
-    canonicalCwd = fs2.realpathSync(cwd);
-  } catch {
-    throw invalid();
-  }
-  for (const command of commands) {
-    if (!command || typeof command !== "object" || Array.isArray(command)) throw invalid();
-    const entry = command;
-    if (entry.source !== "skill" && entry.source !== "prompt") continue;
-    const resourcePath = entry.sourceInfo?.path;
-    if (typeof resourcePath !== "string" || !resourcePath) throw invalid();
-    const lexicalPath = path.resolve(cwd, resourcePath);
-    let canonicalPath;
-    try {
-      canonicalPath = fs2.realpathSync(lexicalPath);
-    } catch {
-      throw invalid();
-    }
-    if (isWithin(cwd, lexicalPath) || isWithin(canonicalCwd, canonicalPath)) {
-      throw new Error("Subagent child cannot load project resources because the project is not trusted.");
-    }
-  }
-}
-function parseReadinessFrame(buffer, expectedToolCount) {
-  if (buffer.byteLength === 0) {
-    throw new Error("Subagent readiness pipe closed without a result.");
-  }
-  const text = buffer.toString("utf8");
-  const newline = text.indexOf("\n");
-  if (newline < 0 || newline !== text.length - 1) {
-    throw new Error("Subagent readiness pipe returned an invalid frame.");
-  }
-  let value;
-  try {
-    value = JSON.parse(text.slice(0, newline));
-  } catch {
-    throw new Error("Subagent readiness pipe returned malformed JSON.");
-  }
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw new Error("Subagent readiness pipe returned an invalid result.");
-  }
-  const record = value;
-  if (record.ok === true && Object.keys(record).length === 2 && Array.isArray(record.sources) && record.sources.length === expectedToolCount && record.sources.every((source) => typeof source === "string" && /^[a-f0-9]{64}$/u.test(source))) {
-    return { ok: true, sources: record.sources };
-  }
-  if (record.ok === false && Object.keys(record).length === 2 && typeof record.error === "string" && record.error.length > 0 && Buffer.byteLength(record.error, "utf8") <= MAX_ERROR_BYTES) {
-    return { ok: false, error: sanitizeTerminalText(record.error) };
-  }
-  throw new Error("Subagent readiness pipe returned an invalid result.");
-}
 function redactAttachmentPaths(value, request) {
   return redactAttachmentPathVariants(value, attachmentPathVariants(request));
 }
@@ -1043,58 +1062,6 @@ ${bytes.subarray(bytes.length - Math.max(0, maxBytes - 18)).toString("utf8").rep
     truncated: true
   };
 }
-var JsonLineDecoder = class {
-  constructor(onValue, onMalformed) {
-    this.onValue = onValue;
-    this.onMalformed = onMalformed;
-  }
-  onValue;
-  onMalformed;
-  buffer = "";
-  dropping = false;
-  decoder = new StringDecoder("utf8");
-  push(chunk) {
-    this.buffer += typeof chunk === "string" ? chunk : this.decoder.write(chunk);
-    this.drain(false);
-  }
-  finish() {
-    this.buffer += this.decoder.end();
-    this.drain(true);
-    this.buffer = "";
-    this.dropping = false;
-  }
-  drain(flush) {
-    while (true) {
-      const newline = this.buffer.indexOf("\n");
-      if (newline < 0) break;
-      const line = this.buffer.slice(0, newline).replace(/\r$/u, "");
-      this.buffer = this.buffer.slice(newline + 1);
-      if (this.dropping) {
-        this.dropping = false;
-        continue;
-      }
-      this.parse(line);
-    }
-    if (!flush && Buffer.byteLength(this.buffer, "utf8") > MAX_EVENT_LINE_BYTES) {
-      this.onMalformed();
-      this.buffer = "";
-      this.dropping = true;
-    }
-    if (flush && this.buffer && !this.dropping) this.parse(this.buffer.replace(/\r$/u, ""));
-  }
-  parse(line) {
-    if (!line.trim()) return;
-    if (Buffer.byteLength(line, "utf8") > MAX_EVENT_LINE_BYTES) {
-      this.onMalformed();
-      return;
-    }
-    try {
-      this.onValue(JSON.parse(line));
-    } catch {
-      this.onMalformed();
-    }
-  }
-};
 
 // src/resource-attachments.ts
 import { existsSync, statSync as statSync3 } from "node:fs";
@@ -1442,9 +1409,7 @@ function resolveResourcePath(value, kind, cwd, canonicalCwd, projectTrusted) {
   if (!stats.isFile() && !stats.isDirectory()) {
     throw new Error(`Subagent ${kind} path must reference a file or directory.`);
   }
-  if (!projectTrusted && (isWithin(cwd, lexicalPath) || isWithin(canonicalCwd, canonicalPath))) {
-    throw new Error(`Subagent ${kind} cannot load a project path because the project is not trusted.`);
-  }
+  assertProjectPathTrusted(lexicalPath, canonicalPath, kind, cwd, canonicalCwd, projectTrusted);
   return canonicalPath;
 }
 async function assertResolvableExtensionAttachment(extensionPath, cwd, canonicalCwd, projectTrusted, signal) {
@@ -1863,7 +1828,6 @@ var SubagentRuntime = class {
   now;
   counter = 0;
   generation = 0;
-  deliveryEnabled = false;
   sessionActive = false;
   omittedJobs = 0;
   jobListeners = /* @__PURE__ */ new Set();
@@ -1872,7 +1836,6 @@ var SubagentRuntime = class {
     this.generation++;
     this.jobs.clear();
     this.omittedJobs = 0;
-    this.deliveryEnabled = true;
     this.sessionActive = true;
     this.notifyJobsChanged();
   }
@@ -1889,7 +1852,9 @@ var SubagentRuntime = class {
       jobId: job.jobId,
       task: job.taskText,
       state: job.state,
+      ...job.modelOverrides,
       thinkingLevel: job.thinkingLevel,
+      defaultThinkingLevel: job.defaultThinkingLevel,
       elapsedMs: Math.max(0, now - (job.startedAt ?? job.createdAt)),
       ...job.timeout !== void 0 ? { timeout: job.timeout } : {},
       tools: [...job.tools]
@@ -1905,6 +1870,7 @@ var SubagentRuntime = class {
     if (active >= MAX_ACTIVE_JOBS) {
       throw new Error(`Active subagent job limit reached (${MAX_ACTIVE_JOBS}).`);
     }
+    const { provider, model } = input;
     const jobId = `job_${this.now().toString(36)}_${(++this.counter).toString(36)}`;
     const communication = this.broker.issueCredentials({
       jobId,
@@ -1931,7 +1897,9 @@ var SubagentRuntime = class {
       controller,
       tools: effectiveTools,
       taskText: input.task,
+      modelOverrides: { ...input.modelOverrides },
       thinkingLevel: input.thinkingLevel,
+      defaultThinkingLevel: input.defaultThinkingLevel,
       terminal,
       resolveTerminal,
       controlReady,
@@ -1939,7 +1907,6 @@ var SubagentRuntime = class {
       rejectControl,
       sendQueue: Promise.resolve(),
       limitations: [],
-      deliverySent: false,
       generation: this.generation
     };
     this.jobs.set(jobId, job);
@@ -1966,7 +1933,8 @@ var SubagentRuntime = class {
           toolSources: Object.fromEntries(
             Object.entries(input.toolSources).map(([tool, sources]) => [tool, [...sources]])
           ),
-          model: input.model,
+          provider,
+          model,
           thinkingLevel: input.thinkingLevel,
           cwd: input.cwd,
           timeout: input.timeout,
@@ -2100,7 +2068,6 @@ var SubagentRuntime = class {
   }
   async shutdown() {
     if (!this.sessionActive) return;
-    this.deliveryEnabled = false;
     this.sessionActive = false;
     const active = [...this.jobs.values()].filter((job) => !isTerminal(job.state));
     await Promise.allSettled(
@@ -2154,8 +2121,7 @@ var SubagentRuntime = class {
     this.prune();
   }
   deliver(job) {
-    if (!this.deliveryEnabled || job.deliverySent || job.generation !== this.generation) return;
-    job.deliverySent = true;
+    if (!this.sessionActive || job.generation !== this.generation) return;
     const payload = this.waitResult(job, false);
     try {
       this.pi.sendMessage(
@@ -2165,7 +2131,7 @@ var SubagentRuntime = class {
           display: true,
           details: payload
         },
-        { deliverAs: "steer" }
+        { deliverAs: "steer", triggerTurn: true }
       );
     } catch {
     }
@@ -2276,6 +2242,20 @@ var SpawnParameters = Type.Object(
       description: "Self-contained task, constraints, and expected result. Maximum 50 KiB.",
       maxLength: MAX_TASK_BYTES
     }),
+    provider: Type.Optional(
+      Type.String({
+        description: "Exact child provider ID. Defaults to the main agent's effective provider at spawn time.",
+        minLength: 1,
+        maxLength: MAX_BOOTSTRAP_BYTES
+      })
+    ),
+    model: Type.Optional(
+      Type.String({
+        description: "Exact model ID within the selected provider. Defaults independently to the main agent's effective model ID at spawn time. Unlisted models fail without fallback.",
+        minLength: 1,
+        maxLength: MAX_BOOTSTRAP_BYTES
+      })
+    ),
     tools: Type.Optional(
       Type.Array(
         StringEnum(CHILD_CORE_TOOL_NAMES, {
@@ -2410,23 +2390,25 @@ function registerSubagentTools(pi, dependencies = {}) {
       if (ctx.cwd !== cwd || ctx.isProjectTrusted() !== projectTrusted) {
         throw new Error("Subagent spawn context changed during attachment validation; retry the request.");
       }
-      if (tools.includes("codemode") || attachments.extensions.length > 0) {
-        assertChildBootstrapCapacity([.../* @__PURE__ */ new Set([...attachments.effectiveTools, ...CHILD_COMMUNICATION_TOOL_NAMES])]);
-      }
-      const model = resolveChildModel(ctx, attachments.extensions.length > 0);
-      const thinkingLevel = resolveThinkingLevel(params.thinkingLevel ?? ctx.thinkingLevel ?? pi.getThinkingLevel());
+      const { provider, model, modelOverrides } = resolveChildModel(ctx, params, attachments.extensions.length > 0);
+      const defaultThinkingLevel = resolveThinkingLevel(ctx.thinkingLevel ?? pi.getThinkingLevel());
+      const thinkingLevel = resolveThinkingLevel(params.thinkingLevel ?? defaultThinkingLevel);
       resolveTimeoutMs(params.timeout);
       assertChildCommandCapacity(
         {
           tools,
           skills: attachments.skills,
           extensions: attachments.extensions,
-          model,
           thinkingLevel,
           projectTrusted
         },
         dependencies.platform
       );
+      assertChildBootstrapCapacity(selectedChildTools({ tools, extensions: attachments.extensions }), {
+        provider,
+        model,
+        thinkingLevel
+      });
       throwIfAborted2(signal, "Subagent spawn was cancelled");
       return toolResult(
         runtime.start({
@@ -2435,8 +2417,11 @@ function registerSubagentTools(pi, dependencies = {}) {
           skills: attachments.skills,
           extensions: attachments.extensions,
           toolSources: attachments.toolSources,
+          provider,
           model,
+          modelOverrides,
           thinkingLevel,
+          defaultThinkingLevel,
           cwd,
           timeout: params.timeout,
           projectTrusted
@@ -2573,19 +2558,47 @@ function resolveTools(value) {
   }
   return tools;
 }
-function resolveChildModel(ctx, hasAttachedExtensions) {
-  const model = ctx.model;
-  if (!model) throw new Error("Subagent model is unavailable because no main-agent model is selected.");
-  const provider = sanitizeTerminalText(model.provider).slice(0, 128);
-  if (!hasAttachedExtensions && ctx.modelRegistry.getRegisteredProviderIds().includes(model.provider)) {
-    throw new Error(`Subagent model provider ${provider} is unavailable because children disable parent extensions.`);
+function resolveChildModel(ctx, overrides, hasAttachedExtensions) {
+  const parent = ctx.model;
+  if (!parent && (overrides.provider === void 0 || overrides.model === void 0)) {
+    throw new Error("Subagent model is unavailable because no main-agent model is selected.");
+  }
+  const provider = validateModelIdentifier(
+    overrides.provider === void 0 ? parent?.provider : overrides.provider,
+    "provider"
+  );
+  const model = validateModelIdentifier(overrides.model === void 0 ? parent?.id : overrides.model, "model");
+  const displayProvider = sanitizeTerminalText(provider).slice(0, 128);
+  if (!hasAttachedExtensions && ctx.modelRegistry.getRegisteredProviderIds().includes(provider)) {
+    throw new Error(
+      `Subagent model provider ${displayProvider} is unavailable because children disable parent extensions.`
+    );
   }
-  if (ctx.modelRegistry.getProviderAuthStatus(model.provider).source === "runtime") {
+  if (ctx.modelRegistry.getProviderAuthStatus(provider).source === "runtime") {
     throw new Error(
-      `Subagent model provider ${provider} uses a process-local runtime API key. Configure stored or environment credentials that child processes can read.`
+      `Subagent model provider ${displayProvider} uses a process-local runtime API key. Configure stored or environment credentials that child processes can read.`
     );
   }
-  return `${model.provider}/${model.id}`;
+  return {
+    provider,
+    model,
+    modelOverrides: {
+      ...provider !== parent?.provider ? { provider } : {},
+      ...model !== parent?.id ? { model } : {}
+    }
+  };
+}
+function validateModelIdentifier(value, field) {
+  if (typeof value === "string" && (value.length > MAX_BOOTSTRAP_BYTES || Buffer.byteLength(value, "utf8") > MAX_BOOTSTRAP_BYTES)) {
+    throw new Error(`Subagent ${field} exceeds the ${MAX_BOOTSTRAP_BYTES}-byte child bootstrap size limit.`);
+  }
+  if (typeof value !== "string" || !value.trim() || [...value].some((character) => {
+    const codePoint = character.codePointAt(0) ?? 0;
+    return codePoint <= 31 || codePoint >= 127 && codePoint <= 159;
+  }) || sanitizeTerminalText(value) !== value) {
+    throw new Error(`Subagent ${field} must be a non-empty exact ID without control characters.`);
+  }
+  return value;
 }
 function resolveThinkingLevel(value) {
   if (typeof value !== "string" || !THINKING_LEVEL_SET.has(value)) {
@@ -2608,23 +2621,10 @@ function resolveMainSendArguments(params) {
   }
   return recipient !== void 0 ? { kind: "request", recipient, message: params.message } : { kind: "response", requestId: requestId ?? "", message: params.message };
 }
-function optionalIdentifier(value, field) {
-  return value === void 0 ? void 0 : requiredIdentifier(value, field);
-}
 function requiredString(value, field) {
   if (typeof value !== "string" || !value.trim()) throw new Error(`Subagent ${field} is required.`);
   return value.trim();
 }
-function requiredIdentifier(value, field) {
-  const identifier = requiredString(value, field);
-  if (identifier.length > MAX_IDENTIFIER_LENGTH || [...identifier].some((character) => {
-    const codePoint = character.codePointAt(0) ?? 0;
-    return codePoint <= 31 || codePoint >= 127 && codePoint <= 159;
-  })) {
-    throw new Error(`Subagent ${field} is invalid.`);
-  }
-  return identifier;
-}
 function assertNotNested() {
   if ((Number.parseInt(process.env.PI_SUBAGENT_DEPTH ?? "0", 10) || 0) > 0) {
     throw new Error("Nested subagents are not supported by pi-subagents.");
@@ -2646,86 +2646,45 @@ function toolResult(value) {
 }
 
 // src/widget.ts
+import {
+  createEditorStatusCollection
+} from "@narumitw/pi-tui-kit/editor-status-collection";
+import { createEditorStatusPublisher } from "@narumitw/pi-tui-kit/editor-status-publisher";
+import {
+  createEditorStatusView
+} from "@narumitw/pi-tui-kit/editor-status-view";
+
+// src/widget-renderer.ts
 import { stripTerminalSequences, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { EditorStatusWidget } from "@narumitw/pi-tui-kit/editor-status-widget";
-var SUBAGENT_WIDGET_KEY = "subagents";
-var SUBAGENT_WIDGET_REFRESH_INTERVAL_MS = 1e3;
-var WIDGET_OPTIONS = { placement: "aboveEditor" };
 var TASK_PREVIEW_WIDTH = 40;
-function createSubagentWidgetController(runtime) {
-  let activeSession;
-  let refreshTimer;
-  let unsubscribeJobs;
-  let publishedValue;
-  let settings = { ...DEFAULT_SUBAGENT_SETTINGS };
-  let clearWidget;
-  const ownsSession = (ctx) => ctx.sessionManager === activeSession;
-  const stop = () => {
-    if (refreshTimer) clearInterval(refreshTimer);
-    refreshTimer = void 0;
-    unsubscribeJobs?.();
-    unsubscribeJobs = void 0;
-  };
-  const publish = (ctx) => {
-    if (ctx.mode !== "tui" || !ownsSession(ctx)) return;
-    const jobs = settings.showWidget ? runtime.activeJobsForDisplay() : [];
-    const value = `${JSON.stringify(settings)}
-${widgetValue(jobs)}`;
-    if (value === publishedValue) return;
-    if (jobs.length === 0) {
-      ctx.ui.setWidget(SUBAGENT_WIDGET_KEY, void 0);
-    } else {
-      const snapshot = jobs.map(cloneDisplayJob);
-      const preferences = { ...settings };
-      ctx.ui.setWidget(
-        SUBAGENT_WIDGET_KEY,
-        (_tui, theme) => createSubagentWidget(snapshot, theme, preferences),
-        WIDGET_OPTIONS
-      );
-    }
-    publishedValue = value;
-  };
-  return {
-    start(ctx, preferences = DEFAULT_SUBAGENT_SETTINGS) {
-      stop();
-      clearWidget?.();
-      clearWidget = void 0;
-      settings = { ...preferences };
-      activeSession = ctx.sessionManager;
-      publishedValue = void 0;
-      if (ctx.mode !== "tui") return;
-      clearWidget = () => ctx.ui.setWidget(SUBAGENT_WIDGET_KEY, void 0);
-      clearWidget();
-      unsubscribeJobs = runtime.subscribeJobs(() => publish(ctx));
-      refreshTimer = setInterval(() => publish(ctx), SUBAGENT_WIDGET_REFRESH_INTERVAL_MS);
-      refreshTimer.unref();
-      publish(ctx);
-    },
-    update(ctx, preferences) {
-      if (!ownsSession(ctx)) return;
-      settings = { ...preferences };
-      publish(ctx);
-    },
-    shutdown(ctx) {
-      if (!ownsSession(ctx)) return;
-      stop();
-      clearWidget?.();
-      clearWidget = void 0;
-      publishedValue = void 0;
-      activeSession = void 0;
-    }
-  };
-}
-function createSubagentWidget(jobs, theme, settings) {
-  return new EditorStatusWidget({
-    theme,
-    renderBody: () => [
-      theme.fg("muted", `Subagents \xB7 ${jobs.length} active`),
-      ...jobs.map((job) => renderJob(job, theme, settings))
-    ]
-  });
-}
-function renderJob(job, theme, settings) {
+var SUBAGENT_WIDGET_RESERVED_ROWS = 8;
+var SUBAGENT_WIDGET_MAX_ROWS = 10;
+function subagentWidgetRowBudget(rows) {
+  return Number.isFinite(rows) ? Math.min(SUBAGENT_WIDGET_MAX_ROWS, Math.max(0, Math.floor(rows) - SUBAGENT_WIDGET_RESERVED_ROWS)) : 0;
+}
+function renderSubagentWidgetSnapshot(snapshot, theme, width, maxRows) {
+  const { jobs, items, settings, mode } = snapshot;
+  const budget = Number.isFinite(maxRows) ? Math.max(0, Math.floor(maxRows)) : 0;
+  if (!settings.showWidget || mode === "hidden" || jobs.length === 0 || items.length === 0 || budget < 2) return [];
+  const running = jobs.filter((job) => job.state === "running").length;
+  const counts = `Subagents \xB7 ${jobs.length} active \xB7 ${running} running \xB7 ${jobs.length - running} queued`;
+  const removed = jobs.length - items.length;
+  const summary = (shown) => `${counts}${jobs.length > shown ? ` \xB7 ${jobs.length - shown} not shown${removed ? ` (${removed} removed)` : ""}` : ""}`;
+  const bodyRows = budget - 1;
+  let body;
+  if (mode === "compact" || bodyRows === 1) {
+    body = [theme.fg("muted", summary(0))];
+  } else {
+    const shown = items.slice(0, bodyRows - 1);
+    body = [
+      theme.fg("muted", shown.length === jobs.length ? `Subagents \xB7 ${jobs.length} active` : summary(shown.length)),
+      ...shown.map(({ value, mode: itemMode }) => renderJob(value, theme, settings, itemMode === "compact"))
+    ];
+  }
+  return new EditorStatusWidget({ theme, renderBody: () => body }).render(width);
+}
+function renderJob(job, theme, settings, compact) {
   const running = job.state === "running";
   const symbol = theme.fg(running ? "accent" : "dim", running ? "\u25B6 " : "\u25CB ");
   const state = theme.fg(running ? "accent" : "muted", job.state);
@@ -2733,27 +2692,25 @@ function renderJob(job, theme, settings) {
   const taskText = sanitizeSubagentDisplayText(job.task);
   const task = stripTerminalSequences(truncateToWidth(taskText, TASK_PREVIEW_WIDTH, "\u2026"));
   const labels = [
-    ...settings.showJobId ? [theme.fg("text", jobId)] : [],
-    ...visibleWidth(task) > 0 ? [theme.fg("text", task)] : [],
-    state
+    ...settings.showJobId && visibleWidth(jobId) > 0 ? [theme.fg("text", jobId)] : [],
+    ...visibleWidth(task) > 0 ? [theme.fg("text", task)] : []
   ];
+  const hasLabel = labels.length > 0;
+  if (!hasLabel) labels.push(state);
+  if (compact) return `${symbol}${labels.join(" \xB7 ")}${!running && hasLabel ? ` \xB7 ${state}` : ""}`;
   const tools = job.tools.length > 0 ? job.tools.map(sanitizeSubagentDisplayText).join(", ") : "none";
-  const timeout = job.timeout === void 0 ? "no timeout" : formatSeconds(job.timeout);
+  const timeout = job.timeout === void 0 ? void 0 : formatSeconds(job.timeout);
+  const elapsed = formatSeconds(Math.floor(job.elapsedMs / 1e3));
+  const timing = running ? `${elapsed}${timeout === void 0 ? "" : ` / ${timeout}`}` : timeout === void 0 ? void 0 : `timeout: ${timeout}`;
   const details = [
-    `thinking: ${sanitizeSubagentDisplayText(job.thinkingLevel)}`,
-    ...settings.showTiming ? [`${formatSeconds(Math.floor(job.elapsedMs / 1e3))} / ${timeout}`] : [],
+    ...job.provider !== void 0 ? [`provider: ${sanitizeSubagentDisplayText(job.provider)}`] : [],
+    ...job.model !== void 0 ? [`model: ${sanitizeSubagentDisplayText(job.model)}`] : [],
+    ...job.thinkingLevel !== job.defaultThinkingLevel ? [`thinking: ${sanitizeSubagentDisplayText(job.thinkingLevel)}`] : [],
+    ...!running && hasLabel ? ["queued"] : [],
+    ...settings.showTiming && timing !== void 0 ? [timing] : [],
     ...settings.showTools ? [`tools: ${tools}`] : []
   ];
-  const detail = details.length > 0 ? theme.fg("muted", ` \xB7 ${details.join(" \xB7 ")}`) : "";
-  return `${symbol}${labels.join(" \xB7 ")}${detail}`;
-}
-function widgetValue(jobs) {
-  return jobs.map(
-    (job) => `${job.jobId}\0${job.task}\0${job.state}\0${job.thinkingLevel}\0${Math.floor(job.elapsedMs / 1e3)}\0${job.timeout ?? ""}\0${job.tools.join(",")}`
-  ).join("\n");
-}
-function cloneDisplayJob(job) {
-  return { ...job, tools: [...job.tools] };
+  return `${symbol}${labels.join(" \xB7 ")}${details.length > 0 ? theme.fg("muted", ` \xB7 ${details.join(" \xB7 ")}`) : ""}`;
 }
 function formatSeconds(value) {
   if (value < 60) return `${formatNumber(value)}s`;
@@ -2768,6 +2725,225 @@ function formatNumber(value) {
   return Number.isInteger(value) ? String(value) : value.toFixed(3).replace(/0+$/u, "").replace(/\.$/u, "");
 }
 
+// src/widget.ts
+var SUBAGENT_WIDGET_KEY = "subagents";
+var SUBAGENT_WIDGET_REFRESH_INTERVAL_MS = 1e3;
+function createCollection() {
+  return createEditorStatusCollection({
+    maxItems: 8,
+    // Runtime accepts at most eight active jobs.
+    // 50 KiB task + 64 tool names (128 UTF-16 units each) + 16 KiB model selection, plus metadata.
+    maxContentSize: 128 * 1024,
+    measure: (job) => Buffer.byteLength(
+      [job.jobId, job.task, job.provider ?? "", job.model ?? "", job.thinkingLevel, ...job.tools].join("\0"),
+      "utf8"
+    ) + 128
+  });
+}
+function createSubagentWidgetController(runtime) {
+  let activeSession;
+  let generation = 0;
+  let refreshTimer;
+  let unsubscribeJobs;
+  let publisher;
+  let collection;
+  let view;
+  let controls;
+  let jobs = [];
+  let publishedValue;
+  let cyclePhase = "idle";
+  let lastOutcome;
+  let settings = { ...DEFAULT_SUBAGENT_SETTINGS };
+  const ownsSession = (ctx) => activeSession !== void 0 && ctx.sessionManager === activeSession;
+  const stop = (errors = []) => {
+    try {
+      for (const release of [
+        () => {
+          if (refreshTimer) clearInterval(refreshTimer);
+        },
+        () => unsubscribeJobs?.(),
+        () => view?.dispose(),
+        () => collection?.dispose(),
+        // The publisher must still own its key when it attempts to clear it.
+        () => publisher?.dispose()
+      ]) {
+        try {
+          release();
+        } catch (error) {
+          errors.push(error);
+        }
+      }
+    } finally {
+      generation++;
+      activeSession = void 0;
+      refreshTimer = void 0;
+      unsubscribeJobs = void 0;
+      view = void 0;
+      collection = void 0;
+      publisher = void 0;
+      controls = void 0;
+      jobs = [];
+      publishedValue = void 0;
+      cyclePhase = "idle";
+      lastOutcome = void 0;
+    }
+    if (errors.length === 1) throw errors[0];
+    if (errors.length > 1) throw new AggregateError(errors, "Subagent widget cleanup failed");
+  };
+  const publish = () => {
+    if (!view || !collection || !publisher) return;
+    const items = collection.snapshot();
+    const value = JSON.stringify([settings, view.mode, jobs, items]);
+    if (value === publishedValue) return;
+    publisher.publish(
+      settings.showWidget && view.mode !== "hidden" && items.length > 0 ? { jobs, items, settings: { ...settings }, mode: view.mode } : void 0
+    );
+    publishedValue = value;
+  };
+  const refresh = () => {
+    if (!view || !collection) return;
+    const next = runtime.activeJobsForDisplay().map((job) => ({ ...job, tools: [...job.tools] }));
+    const entries = next.map((job) => ({ id: job.jobId, value: job, revision: semanticRevision(job) }));
+    collection.replace(entries);
+    jobs = next;
+    view.revision(JSON.stringify(entries.map(({ id, revision }) => [id, revision])));
+    publish();
+  };
+  const finishCycle = (eligible) => {
+    try {
+      view?.settled(eligible);
+    } finally {
+      cyclePhase = "idle";
+      lastOutcome = void 0;
+    }
+  };
+  const startCycle = (phase) => {
+    if (cyclePhase === "idle" || cyclePhase === "maintenance") lastOutcome = void 0;
+    cyclePhase = phase;
+    view?.agentStarted();
+  };
+  const syncActiveCycle = (ctx) => {
+    if (ctx.isIdle()) {
+      if (cyclePhase !== "idle" && cyclePhase !== "running") finishCycle(false);
+    } else if (cyclePhase === "idle" || cyclePhase === "maintenance") {
+      startCycle(ctx.signal === void 0 ? "unconfirmed" : "running");
+    }
+  };
+  return {
+    start(ctx, preferences = DEFAULT_SUBAGENT_SETTINGS, phase = "idle") {
+      stop();
+      const token = generation;
+      const isCurrent = () => token === generation && ownsSession(ctx);
+      try {
+        activeSession = ctx.sessionManager;
+        settings = { ...preferences };
+        if (ctx.mode !== "tui" || !ctx.hasUI) return;
+        collection = createCollection();
+        view = createEditorStatusView({ onChange: publish, canCompact: () => settings.showWidget && jobs.length > 0 });
+        publisher = createEditorStatusPublisher({
+          key: SUBAGENT_WIDGET_KEY,
+          context: ctx,
+          isCurrent,
+          render: (snapshot, theme, width, rows) => renderSubagentWidgetSnapshot(snapshot, theme, width, subagentWidgetRowBudget(rows))
+        });
+        if (phase === "maintenance") cyclePhase = phase;
+        else if (phase !== "idle") startCycle(phase);
+        syncActiveCycle(ctx);
+        const ownedView = view;
+        controls = {
+          state: () => ({ mode: ownedView.mode, pinned: ownedView.pinned, trigger: ownedView.trigger }),
+          setMode: (mode) => {
+            if (isCurrent()) ownedView.setMode(mode);
+          },
+          setPinned: (pinned) => {
+            if (isCurrent()) ownedView.setPinned(pinned);
+          },
+          setTrigger: (trigger) => {
+            if (!isCurrent()) return;
+            syncActiveCycle(ctx);
+            ownedView.setTrigger(trigger);
+          },
+          resetItems() {
+            if (!isCurrent()) return;
+            collection?.dispose();
+            collection = createCollection();
+            refresh();
+          },
+          item(jobId) {
+            if (!isCurrent()) return void 0;
+            const handle = collection?.item(jobId);
+            if (!handle) return void 0;
+            const apply = (action) => {
+              if (!isCurrent() || !handle[action]()) return false;
+              publish();
+              return true;
+            };
+            return { compact: () => apply("compact"), expand: () => apply("expand"), remove: () => apply("remove") };
+          }
+        };
+        unsubscribeJobs = runtime.subscribeJobs(() => {
+          if (isCurrent()) refresh();
+        });
+        refreshTimer = setInterval(() => {
+          if (isCurrent()) refresh();
+        }, SUBAGENT_WIDGET_REFRESH_INTERVAL_MS);
+        refreshTimer.unref();
+        refresh();
+      } catch (error) {
+        stop([error]);
+      }
+    },
+    update(ctx, preferences) {
+      if (!ownsSession(ctx)) return;
+      settings = { ...preferences };
+      if (ctx.mode === "tui") refresh();
+    },
+    shutdown(ctx) {
+      if (!ownsSession(ctx)) return;
+      stop();
+    },
+    controls(ctx) {
+      return ownsSession(ctx) && ctx.mode === "tui" ? controls : void 0;
+    },
+    preparing(ctx) {
+      if (!ownsSession(ctx) || !view) return;
+      if (cyclePhase !== "auto-preparing" && cyclePhase !== "unconfirmed") finishCycle(false);
+      startCycle("preparing");
+    },
+    automaticCompaction(ctx) {
+      if (!ownsSession(ctx) || !view) return;
+      if (cyclePhase === "preparing" || cyclePhase === "maintenance") finishCycle(false);
+      if (cyclePhase === "idle" || cyclePhase === "unconfirmed") startCycle("auto-preparing");
+    },
+    clearCycle(ctx) {
+      if (ownsSession(ctx)) finishCycle(false);
+    },
+    maintenance(ctx) {
+      if (!ownsSession(ctx)) return;
+      finishCycle(false);
+      cyclePhase = "maintenance";
+    },
+    agentStarted(ctx) {
+      if (ownsSession(ctx) && view) startCycle("running");
+    },
+    userMessage(ctx) {
+      if (ownsSession(ctx)) view?.userMessage();
+    },
+    turnEnded(ctx, stopReason) {
+      if (ownsSession(ctx) && cyclePhase !== "idle" && cyclePhase !== "maintenance") lastOutcome = stopReason;
+    },
+    settled(ctx, aborted) {
+      if (!ownsSession(ctx) || !view) return;
+      const eligible = !aborted && lastOutcome !== void 0 && lastOutcome !== "error" && lastOutcome !== "aborted";
+      finishCycle(eligible);
+    }
+  };
+}
+function semanticRevision(job) {
+  const { elapsedMs: _elapsedMs, ...semantic } = job;
+  return JSON.stringify(semantic);
+}
+
 // src/subagents.ts
 function subagents(pi, dependencies = {}) {
   registerMessageRenderers(pi);
@@ -2779,9 +2955,18 @@ function subagents(pi, dependencies = {}) {
   let owner = new AbortController();
   let ready = false;
   let menuOpen = false;
+  let cyclePhase = "idle";
   let settings = { ...DEFAULT_SUBAGENT_SETTINGS };
   const menuTasks = /* @__PURE__ */ new Set();
-  const ownsSession = (ctx) => ctx.sessionManager === activeContext?.sessionManager;
+  const ownsSession = (ctx) => activeContext !== void 0 && ctx.sessionManager === activeContext.sessionManager;
+  const joinCleanup = async (steps, errors = []) => {
+    const results = await Promise.allSettled(steps.map(async (step) => step()));
+    for (const result of results) {
+      if (result.status === "rejected") errors.push(result.reason);
+    }
+    if (errors.length === 1) throw errors[0];
+    if (errors.length > 1) throw new AggregateError(errors, "Subagents session cleanup failed");
+  };
   const openSettings = async (ctx, signal, isCurrent) => {
     if (signal.aborted || !isCurrent()) return "stale";
     if (ctx.mode !== "tui") {
@@ -2825,13 +3010,13 @@ function subagents(pi, dependencies = {}) {
       menuOpen = true;
       const generation = sessionGeneration;
       const signal = owner.signal;
-      const isCurrent = () => generation === sessionGeneration && ownsSession(ctx) && !signal.aborted;
+      const isCurrent = () => generation === sessionGeneration && !signal.aborted && ownsSession(ctx);
       const task = (async () => {
         if (route === "settings") {
           await openSettings(ctx, signal, isCurrent);
           return;
         }
-        const { showSubagentsMenu } = await import("./chunks/menu-KAIUEWL7.ts");
+        const { showSubagentsMenu } = await import("./chunks/menu-2UH4ICLL.ts");
         if (!isCurrent()) return;
         await showSubagentsMenu(ctx, {
           signal,
@@ -2846,7 +3031,8 @@ function subagents(pi, dependencies = {}) {
             if (!isCurrent()) throw new Error("The subagents session changed.");
             await tools.runtime.cancel(jobId);
           },
-          showSettings: (actionSignal) => openSettings(ctx, actionSignal, isCurrent)
+          showSettings: (actionSignal) => openSettings(ctx, actionSignal, isCurrent),
+          widget: widget.controls(ctx)
         });
       })();
       menuTasks.add(task);
@@ -2863,40 +3049,115 @@ function subagents(pi, dependencies = {}) {
     }
   });
   pi.on("session_start", async (_event, ctx) => {
+    const previousContext = activeContext;
+    const generation = ++sessionGeneration;
+    ready = false;
+    menuOpen = false;
     owner.abort();
-    if (activeContext) widget.shutdown(activeContext);
     owner = new AbortController();
+    const signal = owner.signal;
     activeContext = ctx;
-    ready = false;
-    menuOpen = false;
-    const generation = ++sessionGeneration;
-    const isCurrent = () => generation === sessionGeneration && ownsSession(ctx) && !owner.signal.aborted;
-    await tools.startSession();
-    if (!isCurrent()) return;
-    await Promise.allSettled([...menuTasks]);
+    cyclePhase = ctx.signal === void 0 ? "idle" : "running";
+    const isCurrent = () => generation === sessionGeneration && !signal.aborted && ownsSession(ctx);
+    const errors = [];
+    try {
+      if (previousContext) widget.shutdown(previousContext);
+    } catch (error) {
+      errors.push(error);
+    }
+    const failedHandoff = errors.length > 0;
+    await joinCleanup(
+      [
+        () => failedHandoff ? tools.shutdown() : tools.startSession(),
+        ...[...menuTasks].map((task) => () => task),
+        ...failedHandoff ? [() => store.flush()] : []
+      ],
+      errors
+    );
     if (!isCurrent()) return;
     const loaded = await store.load();
     if (!isCurrent()) return;
     settings = { ...loaded.settings };
+    widget.start(ctx, settings, cyclePhase);
     ready = true;
-    widget.start(ctx, settings);
     if (loaded.diagnostics.length > 0) {
       const message = sanitizeSubagentDisplayText(`Subagent settings: ${loaded.diagnostics.join(" ")}`);
       if (ctx.hasUI) ctx.ui.notify(message, "warning");
       else throw new Error(message);
     }
   });
-  pi.on("session_shutdown", async (_event, ctx) => {
+  pi.on("before_agent_start", (_event, ctx) => {
+    if (!ownsSession(ctx)) return;
+    cyclePhase = "preparing";
+    if (ready) widget.preparing(ctx);
+  });
+  pi.on("session_before_compact", (event, ctx) => {
+    if (!ownsSession(ctx)) return;
+    if (event.reason === "manual") {
+      cyclePhase = "maintenance";
+      if (ready) widget.maintenance(ctx);
+    } else {
+      if (cyclePhase !== "running") cyclePhase = "auto-preparing";
+      if (ready) widget.automaticCompaction(ctx);
+    }
+  });
+  pi.on("session_before_tree", (_event, ctx) => {
+    if (!ownsSession(ctx)) return;
+    cyclePhase = "maintenance";
+    if (ready) widget.maintenance(ctx);
+  });
+  pi.on("input", (_event, ctx) => {
+    if (!ownsSession(ctx) || !ctx.isIdle()) return;
+    cyclePhase = "idle";
+    if (ready) widget.clearCycle(ctx);
+  });
+  pi.on("agent_start", (_event, ctx) => {
+    if (!ownsSession(ctx)) return;
+    cyclePhase = "running";
+    if (ready) widget.agentStarted(ctx);
+  });
+  pi.on("message_start", (event, ctx) => {
+    if (ready && ownsSession(ctx) && event.message.role === "user") widget.userMessage(ctx);
+  });
+  pi.on("turn_end", (event, ctx) => {
+    if (ready && ownsSession(ctx) && event.message.role === "assistant")
+      widget.turnEnded(ctx, event.message.stopReason);
+  });
+  pi.on("agent_settled", (event, ctx) => {
+    if (!ownsSession(ctx)) return;
+    cyclePhase = "idle";
+    if (ready) widget.settled(ctx, event.aborted);
+  });
+  pi.on("session_tree", (_event, ctx) => {
     if (!ownsSession(ctx)) return;
+    cyclePhase = "maintenance";
+    if (!ready) return;
     sessionGeneration++;
+    ready = false;
+    menuOpen = false;
     owner.abort();
+    owner = new AbortController();
+    widget.start(ctx, settings, cyclePhase);
+    ready = true;
+  });
+  pi.on("session_shutdown", async (_event, ctx) => {
+    if (!ownsSession(ctx)) return;
+    sessionGeneration++;
     ready = false;
     menuOpen = false;
     activeContext = void 0;
-    widget.shutdown(ctx);
-    const results = await Promise.allSettled([tools.shutdown(), ...menuTasks, store.flush()]);
-    const failed = results.find((result) => result.status === "rejected");
-    if (failed?.status === "rejected") throw failed.reason;
+    cyclePhase = "idle";
+    owner.abort();
+    const errors = [];
+    try {
+      widget.shutdown(ctx);
+    } catch (error) {
+      errors.push(error);
+    }
+    await joinCleanup(
+      [() => tools.shutdown(), ...[...menuTasks].map((task) => () => task), () => store.flush()],
+      errors
+    );
   });
 }
 export {