@nklisch/pi-enhanced 0.2.6 → 0.3.0

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/tools/resume-tool.ts

@@ -0,0 +1,105 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import type { SubagentMode } from "#src/types";
+import type { ResumeOutcome } from "#src/lifecycle/subagent-manager";
+import type { Subagent } from "#src/lifecycle/subagent";
+import { buildDetails, formatLifetimeTokens, textResult } from "#src/tools/helpers";
+import { formatModelThinking, formatMs } from "#src/ui/display";
+
+export interface ResumeToolManager {
+  resume(id: string, prompt: string, mode: SubagentMode, timeoutSeconds: number | undefined, signal?: AbortSignal, onReserved?: (record: Subagent) => void): Promise<ResumeOutcome>;
+  getRecord(id: string): Subagent | undefined;
+}
+
+export class ResumeTool {
+  constructor(private readonly manager: ResumeToolManager) {}
+
+  async execute(_toolCallId: string, params: { agent_id: string; prompt: string; mode?: SubagentMode; timeout_seconds?: number }, signal: AbortSignal | undefined, onUpdate: ((update: unknown) => void) | undefined, _ctx: unknown) {
+    if (params.timeout_seconds != null && (!Number.isInteger(params.timeout_seconds) || params.timeout_seconds <= 0)) {
+      return textResult("timeout_seconds must be a positive integer");
+    }
+    const mode = params.mode ?? "detached";
+    let spinnerFrame = 0;
+    const timer = setInterval(() => {
+      if (!onUpdate || mode !== "joined") return;
+      const record = this.manager.getRecord(params.agent_id);
+      if (!record) return;
+      onUpdate({ content: [{ type: "text", text: `${record.toolUses} tool uses...` }], details: buildDetails({
+        displayName: record.type, description: record.description, subagentType: record.type,
+        modelName: record.modelLabel, thinkingLevel: record.effectiveThinkingLevel, tags: [`mode: ${record.mode}`],
+      }, record, {
+        status: record.status,
+        terminalReason: record.stateTerminalReason,
+        durationMs: record.activeRuntimeMs,
+        spinnerFrame: spinnerFrame++,
+      }) });
+    }, 500);
+    let outcome: ResumeOutcome;
+    try {
+      outcome = await this.manager.resume(params.agent_id, params.prompt, mode, params.timeout_seconds, signal, (record) => {
+        if (onUpdate && mode === "joined") onUpdate({ content: [{ type: "text", text: "Resuming..." }], details: buildDetails({
+          displayName: record.type, description: record.description, subagentType: record.type,
+          modelName: record.modelLabel, thinkingLevel: record.effectiveThinkingLevel, tags: [`mode: ${record.mode}`],
+        }, record, {
+          status: record.status,
+          terminalReason: record.stateTerminalReason,
+          durationMs: record.activeRuntimeMs,
+        }) });
+      });
+    } finally {
+      clearInterval(timer);
+    }
+    if (outcome.kind === "not_found") return textResult(`Agent not found: "${outcome.agentId}". It may have been cleaned up.`);
+    if (outcome.kind === "wrong_state") return textResult(`Agent "${outcome.agentId}" cannot be resumed (status: ${outcome.status}). It must have a retained settled session.`);
+
+    const record = outcome.kind === "joined" ? outcome.record : this.manager.getRecord(outcome.agentId);
+    if (!record) return textResult(`Agent not found after resume: "${params.agent_id}".`);
+    if (outcome.kind === "detached") {
+      return textResult(`Resume detached for agent ${record.id}.\nRun ID: ${record.runId}\nMode: detached\nCompletion will send one notification.`, buildDetails({
+        displayName: record.type,
+        description: record.description,
+        subagentType: record.type,
+        modelName: record.modelLabel,
+        thinkingLevel: record.effectiveThinkingLevel,
+        tags: [`mode: ${record.mode}`],
+      }, record, {
+        status: record.status,
+        terminalReason: record.stateTerminalReason,
+        durationMs: record.activeRuntimeMs,
+      }));
+    }
+    record.markConsumed();
+    return textResult(`Agent ${record.id} ${record.status}.\nRun ID: ${record.runId}\nModel: ${formatModelThinking(record.modelLabel, record.effectiveThinkingLevel)}\nRuntime: ${formatMs(record.activeRuntimeMs)}\nReason: ${record.stateTerminalReason ?? "unknown"}\n\n${boundResult(record.result, record.outputFile)}`, buildDetails({
+      displayName: record.type,
+      description: record.description,
+      subagentType: record.type,
+      modelName: record.modelLabel,
+      thinkingLevel: record.effectiveThinkingLevel,
+      tags: [`mode: ${record.mode}`],
+    }, record, { tokens: formatLifetimeTokens(record), durationMs: record.activeRuntimeMs, terminalReason: record.stateTerminalReason }));
+  }
+
+  toToolDefinition() {
+    return defineTool({
+      name: "resume_subagent" as const,
+      label: "Resume Subagent",
+      promptSnippet: "resume_subagent: Continue a retained subagent session.",
+      description: "Continue a retained settled subagent session. Delivery defaults to detached; joined waits for the resumed run to settle.",
+      parameters: Type.Object({
+        agent_id: Type.String({ description: "The retained subagent ID to resume." }),
+        prompt: Type.String({ description: "The next task or instruction." }),
+        mode: Type.Optional(Type.Union([Type.Literal("joined"), Type.Literal("detached")], { description: "Result delivery mode. Defaults to detached." })),
+        timeout_seconds: Type.Optional(Type.Integer({ description: "Active runtime deadline in seconds; queued time is excluded.", minimum: 1 })),
+      }),
+      execute: (toolCallId: string, params: { agent_id: string; prompt: string; mode?: SubagentMode; timeout_seconds?: number }, signal: AbortSignal | undefined, onUpdate: unknown, ctx: unknown) => this.execute(toolCallId, params, signal, onUpdate as ((update: unknown) => void) | undefined, ctx),
+    });
+  }
+}
+
+const MAX_RESULT_OUTPUT = 12_000;
+function boundResult(result: string | undefined, outputFile: string | undefined): string {
+  const output = result?.trim() || "No output.";
+  return output.length > MAX_RESULT_OUTPUT
+    ? output.slice(0, MAX_RESULT_OUTPUT) + `\n\nOutput truncated. Full transcript: ${outputFile ?? "unavailable"}`
+    : output;
+}

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/tools/spawn-config.ts

@@ -15,7 +15,7 @@ import type { ModelRegistry } from "#src/session/model-resolver";
 import { formatModelLabel } from "#src/session/model-label";
 import { resolveInvocationModel } from "#src/session/model-resolver";
 import { resolveEffectiveThinkingLevel } from "#src/session/thinking-level";
-import type { AgentInvocation, SubagentType, ThinkingLevel } from "#src/types";
+import type { AgentInvocation, SubagentMode, SubagentType, ThinkingLevel } from "#src/types";
 import {
   type AgentDetails,
   buildInvocationTags,
@@ -50,7 +50,8 @@ export interface SpawnExecution {
   /** Exact level passed to the child session after model-capability clamping. */
   effectiveThinkingLevel: ThinkingLevel;
   inheritContext: boolean;
-  runInBackground: boolean;
+  mode: SubagentMode;
+  timeoutSeconds?: number;
   agentInvocation: AgentInvocation;
 }
 
@@ -88,6 +89,13 @@ export function resolveSpawnConfig(
     readonly fallbackSubagent?: string | false;
   },
 ): ResolvedSpawnConfig | SpawnConfigError {
+  const removedField = ["run_in_background", "foreground", "resume"].find((field) =>
+    Object.prototype.hasOwnProperty.call(params, field),
+  );
+  if (removedField) {
+    return { error: `Removed field "${removedField}"; use mode: joined|detached${removedField === "resume" ? " and resume_subagent" : ""}.` };
+  }
+
   const rawType = params.subagent_type as SubagentType;
   const typeResolution = resolveDispatchAgentType(
     rawType,
@@ -122,21 +130,30 @@ export function resolveSpawnConfig(
     modelInfo.parentThinkingLevel,
   );
   const inheritContext = resolvedConfig.inheritContext;
-  const runInBackground = resolvedConfig.runInBackground;
+  const mode = resolvedConfig.mode;
+  if (mode !== "joined" && mode !== "detached") {
+    return { error: "mode must be joined or detached" };
+  }
+  const maxTurns = resolvedConfig.maxTurns ?? settings.defaultMaxTurns;
+  if (maxTurns != null && (!Number.isInteger(maxTurns) || maxTurns < 0)) {
+    return { error: "max_turns must be a non-negative integer" };
+  }
+  if (resolvedConfig.timeoutSeconds != null && (!Number.isInteger(resolvedConfig.timeoutSeconds) || resolvedConfig.timeoutSeconds <= 0)) {
+    return { error: "timeout_seconds must be a positive integer" };
+  }
 
   // Every status surface shows the exact effective model, including inheritance.
   const modelName = formatModelLabel(model);
 
-  const effectiveMaxTurns = normalizeMaxTurns(
-    resolvedConfig.maxTurns ?? settings.defaultMaxTurns,
-  );
+  const effectiveMaxTurns = normalizeMaxTurns(maxTurns);
 
   const agentInvocation: AgentInvocation = {
     modelName,
     thinking,
     maxTurns: normalizeMaxTurns(resolvedConfig.maxTurns),
     inheritContext,
-    runInBackground,
+    mode,
+    timeoutSeconds: resolvedConfig.timeoutSeconds,
   };
 
   const modeLabel = getPromptModeLabel(subagentType, registry);
@@ -162,7 +179,8 @@ export function resolveSpawnConfig(
       thinking,
       effectiveThinkingLevel,
       inheritContext,
-      runInBackground,
+      mode,
+      timeoutSeconds: resolvedConfig.timeoutSeconds,
       agentInvocation,
     },
     presentation: { modelName, agentTags, detailBase },

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/tools/steer-tool.ts

@@ -1,117 +1,33 @@
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
-import { formatLifetimeTokens, textResult } from "#src/tools/helpers";
-import type { SteerOutcome, Subagent } from "#src/types";
-import { formatDuration, formatModelThinking } from "#src/ui/display";
+import type { ManagerSteerOutcome } from "#src/lifecycle/subagent-manager";
+import { textResult } from "#src/tools/helpers";
 
-// ---- Deps interfaces ----
-
-export interface SteerToolManager {
-	getRecord(id: string): Subagent | undefined;
-}
-
-export interface SteerToolEvents {
-	emit(name: string, data: unknown): void;
-}
-
-// ---- Class ----
+export interface SteerToolManager { steer(id: string, message: string): Promise<ManagerSteerOutcome>; }
+export interface SteerToolEvents { emit(name: string, data: unknown): void; }
 
 export class SteerTool {
-	constructor(
-		private readonly manager: SteerToolManager,
-		private readonly events: SteerToolEvents,
-	) {}
-
-	async execute(
-		_toolCallId: string,
-		params: { agent_id: string; message: string },
-		_signal: AbortSignal,
-		_onUpdate: unknown,
-		_ctx: unknown,
-	) {
-		const record = this.manager.getRecord(params.agent_id);
-		if (!record) {
-			return textResult(
-				`Agent not found: "${params.agent_id}". It may have been cleaned up.`,
-			);
-		}
-
-		let outcome: SteerOutcome;
-		try {
-			outcome = await record.steer(params.message);
-		} catch (err) {
-			return textResult(
-				`Failed to steer agent: ${err instanceof Error ? err.message : String(err)}\n`
-					+ this.renderRunIdentity(record),
-			);
-		}
-
-		switch (outcome.kind) {
-			case "rejected":
-				return textResult(
-					`Agent "${params.agent_id}" is not running (status: ${outcome.status}). Cannot steer a non-running agent.\n`
-						+ this.renderRunIdentity(record),
-				);
-			case "buffered":
-				this.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.\n`
-						+ this.renderRunIdentity(record),
-				);
-			case "delivered":
-				this.events.emit("subagents:steered", { id: record.id, message: params.message });
-				return this.renderDelivered(record);
-		}
-	}
-
-	/** Render the success message with live state for a delivered steer. */
-	private renderDelivered(record: Subagent) {
-		const tokens = formatLifetimeTokens(record);
-		const contextPercent = record.getContextPercent();
-		const stateParts: string[] = [formatModelThinking(record.modelLabel, record.effectiveThinkingLevel), formatDuration(record.startedAt, record.completedAt)];
-		if (tokens) stateParts.push(tokens);
-		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(
-			`Steering message sent to agent ${record.id}. The agent will process it after its current tool execution.\n` +
-				`Current state: ${stateParts.join(" · ")}`,
-		);
-	}
-
-	private renderRunIdentity(record: Subagent): string {
-		return `Model: ${formatModelThinking(record.modelLabel, record.effectiveThinkingLevel)}\nRuntime: ${formatDuration(record.startedAt, record.completedAt)}`;
-	}
-
-	toToolDefinition() {
-		return defineTool({
-			name: "steer_subagent" as const,
-			label: "Steer Agent",
-			promptSnippet:
-				"steer_subagent: Send a mid-run message to redirect a running background 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.",
-			parameters: Type.Object({
-				agent_id: Type.String({
-					description: "The agent ID to steer (must be currently running).",
-				}),
-				message: Type.String({
-					description:
-						"The steering message to send. This will appear as a user message in the agent's conversation.",
-				}),
-			}),
-			execute: (
-				toolCallId: string,
-				params: { agent_id: string; message: string },
-				signal: AbortSignal,
-				onUpdate: unknown,
-				ctx: unknown,
-			) => this.execute(toolCallId, params, signal, onUpdate, ctx),
-		});
-	}
+  constructor(private readonly manager: SteerToolManager, private readonly events: SteerToolEvents) {}
+
+  async execute(_toolCallId: string, params: { agent_id: string; message: string }, _signal: AbortSignal, _onUpdate: unknown, _ctx: unknown) {
+    const outcome = await this.manager.steer(params.agent_id, params.message);
+    if (outcome.kind === "not_found") return textResult(`Agent not found: "${outcome.agentId}". It may have been cleaned up.`, outcome);
+    if (outcome.kind === "rejected") return textResult(`Agent "${params.agent_id}" cannot be steered (status: ${outcome.status}).`, { ...outcome, agentId: params.agent_id });
+    this.events.emit("subagents:steered", { id: params.agent_id, runId: outcome.runId, outcome: outcome.kind, message: params.message });
+    return textResult(`Steering message ${outcome.kind} for agent ${params.agent_id}.\nRun ID: ${outcome.runId}.`, { ...outcome, agentId: params.agent_id });
+  }
+
+  toToolDefinition() {
+    return defineTool({
+      name: "steer_subagent" as const,
+      label: "Steer Subagent",
+      promptSnippet: "steer_subagent: Send a message to a running subagent.",
+      description: "Send a steering message to a running subagent. The structured outcome distinguishes delivered, buffered, rejected, and not-found cases.",
+      parameters: Type.Object({
+        agent_id: Type.String({ description: "The running subagent ID." }),
+        message: Type.String({ description: "The message to add to the subagent's conversation." }),
+      }),
+      execute: (toolCallId: string, params: { agent_id: string; message: string }, signal: AbortSignal, onUpdate: unknown, ctx: unknown) => this.execute(toolCallId, params, signal, onUpdate, ctx),
+    });
+  }
 }

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/tools/stop-tool.ts

@@ -0,0 +1,53 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import type { StopOutcome } from "#src/lifecycle/subagent-manager";
+import type { Subagent } from "#src/lifecycle/subagent";
+import { buildDetails, formatLifetimeTokens, textResult } from "#src/tools/helpers";
+import { formatModelThinking, formatMs } from "#src/ui/display";
+
+export interface StopToolManager {
+  stop(id: string, settlementTimeoutSeconds?: number, waitSignal?: AbortSignal): Promise<StopOutcome>;
+}
+
+export class StopTool {
+  constructor(private readonly manager: StopToolManager) {}
+
+  async execute(_toolCallId: string, params: { agent_id: string; settlement_timeout_seconds?: number }, signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) {
+    const timeout = params.settlement_timeout_seconds ?? 5;
+    if (!Number.isInteger(timeout) || timeout < 1 || timeout > 30) return textResult("settlement_timeout_seconds must be an integer from 1 to 30");
+    const outcome = await this.manager.stop(params.agent_id, timeout, signal);
+    if (outcome.kind === "not_found") return textResult(`Agent not found: "${outcome.agentId}". It may have been cleaned up.`, { kind: outcome.kind, agentId: outcome.agentId });
+    if (outcome.kind === "already_terminal") return textResult(`Agent ${outcome.agentId} is already terminal (${outcome.record.status}, ${outcome.record.stateTerminalReason ?? "unknown"}).`, renderDetails(outcome.record));
+    if (outcome.kind === "stop_pending") return textResult(`Stop requested for agent ${outcome.agentId}, but its run has not settled within ${timeout}s. It remains active; no hard kill was attempted.\nRun ID: ${outcome.runId}\nReason: ${outcome.reason}`, renderDetails(outcome.record));
+    return textResult(`Agent ${outcome.agentId} stopped.\nRun ID: ${outcome.runId}\nReason: ${outcome.reason}\nRuntime: ${formatMs(outcome.record.activeRuntimeMs)}`, renderDetails(outcome.record));
+  }
+
+  toToolDefinition() {
+    return defineTool({
+      name: "stop_subagent" as const,
+      label: "Stop Subagent",
+      promptSnippet: "stop_subagent: Request cooperative cancellation of a subagent.",
+      description: "Stop queued work immediately or request cooperative cancellation of a live subagent. The result distinguishes settled, already-terminal, not-found, and stop-pending outcomes; it never hard-kills JavaScript.",
+      parameters: Type.Object({
+        agent_id: Type.String({ description: "The subagent ID to stop." }),
+        settlement_timeout_seconds: Type.Optional(Type.Integer({ description: "How long to wait for cooperative settlement (1-30 seconds, default 5).", minimum: 1, maximum: 30 })),
+      }),
+      execute: (toolCallId: string, params: { agent_id: string; settlement_timeout_seconds?: number }, signal: AbortSignal | undefined, onUpdate: unknown, ctx: unknown) => this.execute(toolCallId, params, signal, onUpdate, ctx),
+    });
+  }
+}
+
+function renderDetails(record: Subagent) {
+  return buildDetails({
+    displayName: record.type,
+    description: record.description,
+    subagentType: record.type,
+    modelName: record.modelLabel,
+    thinkingLevel: record.effectiveThinkingLevel,
+    tags: [`mode: ${record.mode}`],
+  }, record, {
+    terminalReason: record.stateTerminalReason,
+    tokens: formatLifetimeTokens(record),
+    durationMs: record.activeRuntimeMs,
+  });
+}

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/types.ts

@@ -33,6 +33,9 @@ export interface SubscribableSession {
 /** Agent type: any string name (built-in defaults or user-defined). */
 export type SubagentType = string;
 
+/** Delivery mode for one initial or resumed run. */
+export type SubagentMode = "joined" | "detached";
+
 /** UI display and agent listing — name, display name, description, prompt mode. */
 export interface AgentIdentity {
   name: string;
@@ -54,10 +57,12 @@ export interface AgentConfig extends AgentIdentity, AgentPromptConfig {
   model?: string;
   thinking?: ThinkingLevel;
   maxTurns?: number;
-  /** Default for spawn: fork parent conversation. undefined = caller decides. */
+  /** Active runtime deadline in seconds for launch/resume. */
+  timeoutSeconds?: number;
+  /** Default for launch/resume: fork parent conversation. undefined = caller decides. */
   inheritContext?: boolean;
-  /** Default for spawn: run in background. undefined = caller decides. */
-  runInBackground?: boolean;
+  /** Default delivery mode for launch/resume. */
+  mode?: SubagentMode;
   /** One-line usage guideline for the subagent tool's Guidelines: block. Omitted — no guideline line. */
   toolGuideline?: string;
   /** true = this is an embedded default agent (informational) */
@@ -74,7 +79,8 @@ export interface AgentInvocation {
   thinking?: ThinkingLevel;
   maxTurns?: number;
   inheritContext?: boolean;
-  runInBackground?: boolean;
+  mode?: SubagentMode;
+  timeoutSeconds?: number;
 }
 
 /**
@@ -115,7 +121,7 @@ export interface ParentSessionInfo {
 	parentSessionFile?: string;
 	/** Session ID of the parent agent (stored in the child session's parentSession header). */
 	parentSessionId?: string;
-	/** Tool call ID for background notification wiring. Exposed on the record via Subagent.toolCallId. */
+	/** Tool call ID for detached completion notification wiring. Exposed on the record via Subagent.toolCallId. */
 	toolCallId?: string;
 }
 

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/ui/agent-widget.ts

@@ -87,14 +87,14 @@ export class AgentWidget implements SubagentManagerObserver {
   private widgetFrame = 0;
   private widgetInterval: ReturnType<typeof setInterval> | undefined;
   /**
-   * Bounded reactive read model: lifecycle callbacks add active background
+   * Bounded reactive read model: lifecycle callbacks add active detached
    * records and the small terminal linger set; render ticks never ask the
    * manager to clone or sort its retained history.
    */
-  private readonly backgroundAgents = new Map<string, Subagent>();
+  private readonly detachedAgents = new Map<string, Subagent>();
   /** Tracks how many turns each finished agent has survived. */
   private finishedTurnAge = new Map<string, number>();
-  /** How many extra turns errors/aborted agents linger (completed agents clear after 1 turn). */
+  /** How many extra turns errors/stopped agents linger (completed agents clear after 1 turn). */
   private static readonly ERROR_LINGER_TURNS = 2;
   /** Pi renders the whole component tree for each requestRender call. */
   private static readonly STATUS_REFRESH_INTERVAL_MS = 500;
@@ -122,7 +122,7 @@ export class AgentWidget implements SubagentManagerObserver {
     // Lifecycle events can arrive before the first tool gives us a UI context.
     // Refresh when that context becomes available, but let update() decide
     // whether any active record actually needs an animation timer.
-    if (contextChanged && this.uiCtx && this.backgroundAgents.size > 0) this.refresh();
+    if (contextChanged && this.uiCtx && this.detachedAgents.size > 0) this.refresh();
   }
 
   /**
@@ -131,13 +131,13 @@ export class AgentWidget implements SubagentManagerObserver {
    */
   onTurnStart() {
     // Age terminal records and remove them before the next render. Completed
-    // records linger for one turn; errors and aborted records linger for two.
+    // records linger for one turn; errors and stopped records linger for two.
     for (const [id, age] of this.finishedTurnAge) {
-      const record = this.backgroundAgents.get(id);
+      const record = this.detachedAgents.get(id);
       const nextAge = age + 1;
       if (!record || nextAge >= this.maxFinishedAge(record.status)) {
         this.finishedTurnAge.delete(id);
-        this.backgroundAgents.delete(id);
+        this.detachedAgents.delete(id);
       } else {
         this.finishedTurnAge.set(id, nextAge);
       }
@@ -149,47 +149,47 @@ export class AgentWidget implements SubagentManagerObserver {
 
   /** A subagent started running — ensure the update loop is live and render. */
   onSubagentStarted(record: Subagent) {
-    if (!this.trackBackground(record)) return;
+    if (!this.trackDetached(record)) return;
     this.finishedTurnAge.delete(record.id);
     this.startLoop();
   }
 
-  /** A background subagent was created (queued) — ensure the loop is live and render. */
+  /** A detached subagent was created (queued) — ensure the loop is live and render. */
   onSubagentCreated(record: Subagent) {
-    if (!this.trackBackground(record)) return;
+    if (!this.trackDetached(record)) return;
     this.finishedTurnAge.delete(record.id);
     this.startLoop();
   }
 
   /** A subagent completed — seed its bounded linger entry and render. */
   onSubagentCompleted(record: Subagent) {
-    if (!this.trackBackground(record)) return;
+    if (!this.trackDetached(record)) return;
     this.finishedTurnAge.set(record.id, 0);
     this.refresh();
   }
 
   /** A resumed subagent started — ensure the update loop is live and render. */
   onSubagentResumedStarted(record: Subagent) {
-    if (!this.trackBackground(record)) return;
+    if (!this.trackDetached(record)) return;
     this.finishedTurnAge.delete(record.id);
     this.startLoop();
   }
 
   /** A resumed subagent settled — seed its terminal linger entry. */
   onSubagentResumed(record: Subagent) {
-    if (!this.trackBackground(record)) return;
+    if (!this.trackDetached(record)) return;
     this.finishedTurnAge.set(record.id, 0);
     this.refresh();
   }
 
   /** A subagent's session compacted — render to refresh the compaction count. */
   onSubagentCompacted(record: Subagent, _info: CompactionInfo) {
-    if (this.trackBackground(record)) this.refresh();
+    if (this.trackDetached(record)) this.refresh();
   }
 
   /** Remove terminal state when the manager clears a parent session. */
   onSubagentCleared(record: Subagent) {
-    if (!this.backgroundAgents.delete(record.id)) return;
+    if (!this.detachedAgents.delete(record.id)) return;
     this.finishedTurnAge.delete(record.id);
     this.refresh();
   }
@@ -226,19 +226,23 @@ export class AgentWidget implements SubagentManagerObserver {
     return ERROR_STATUSES.has(status) ? AgentWidget.ERROR_LINGER_TURNS : 1;
   }
 
-  /** Add a record only when its immutable invocation snapshot marks it background. */
-  private trackBackground(record: Subagent): boolean {
-    if (record.invocation?.runInBackground !== true) return false;
-    this.backgroundAgents.set(record.id, record);
+  /** Add a record only when its current run mode is detached. */
+  private trackDetached(record: Subagent): boolean {
+    if (record.mode !== "detached") {
+      this.detachedAgents.delete(record.id);
+      this.finishedTurnAge.delete(record.id);
+      return false;
+    }
+    this.detachedAgents.set(record.id, record);
     return true;
   }
 
   /** Drop terminal entries whose turn-based linger window has already elapsed. */
   private pruneExpiredFinished(): void {
-    for (const [id, record] of this.backgroundAgents) {
+    for (const [id, record] of this.detachedAgents) {
       if (record.isActive()) continue;
       if (record.completedAt == null || !this.shouldShowFinished(id, record.status)) {
-        this.backgroundAgents.delete(id);
+        this.detachedAgents.delete(id);
         this.finishedTurnAge.delete(id);
       }
     }
@@ -250,12 +254,14 @@ export class AgentWidget implements SubagentManagerObserver {
       id: record.id,
       type: record.type,
       status: record.status,
+      terminalReason: record.stateTerminalReason,
       description: record.description,
       modelLabel: record.modelLabel,
       thinkingLevel: record.effectiveThinkingLevel,
       toolUses: record.toolUses,
       startedAt: record.startedAt,
       completedAt: record.completedAt,
+      activeRuntimeMs: record.activeRuntimeMs,
       error: record.error,
       lifetimeUsage: record.lifetimeUsage,
       compactionCount: record.compactionCount,
@@ -270,7 +276,7 @@ export class AgentWidget implements SubagentManagerObserver {
   /** Delegate rendering to the pure widget-renderer module. */
   private renderWidget(tui: any, theme: Theme): string[] {
     return renderWidgetLines({
-      agents: [...this.backgroundAgents.values()].map(r => this.toWidgetAgent(r)),
+      agents: [...this.detachedAgents.values()].map(r => this.toWidgetAgent(r)),
       registry: this.registry,
       spinnerFrame: this.widgetFrame,
       terminalWidth: tui.terminal.columns,
@@ -295,7 +301,7 @@ export class AgentWidget implements SubagentManagerObserver {
       this.lastStatusText = undefined;
     }
     this.stopTimer();
-    this.backgroundAgents.clear();
+    this.detachedAgents.clear();
     this.finishedTurnAge.clear();
   }
 
@@ -316,8 +322,8 @@ export class AgentWidget implements SubagentManagerObserver {
     if (!this.uiCtx) return;
 
     this.pruneExpiredFinished();
-    const backgroundAgents = [...this.backgroundAgents.values()];
-    const state = assembleWidgetState(backgroundAgents, (id, status) => this.shouldShowFinished(id, status));
+    const detachedAgents = [...this.detachedAgents.values()];
+    const state = assembleWidgetState(detachedAgents, (id, status) => this.shouldShowFinished(id, status));
 
     if (!state.hasActive && !state.hasFinished) {
       this.clearWidget();
@@ -329,7 +335,7 @@ export class AgentWidget implements SubagentManagerObserver {
     // static completion widget remains registered.
     if (state.hasActive) this.ensureTimer();
     else this.stopTimer();
-    this.updateStatusBar(state, backgroundAgents);
+    this.updateStatusBar(state, detachedAgents);
     this.widgetFrame++;
 
     // Register widget callback once; subsequent updates use requestRender()
@@ -387,7 +393,7 @@ export class AgentWidget implements SubagentManagerObserver {
     this.widgetRegistered = false;
     this.tui = undefined;
     this.lastStatusText = undefined;
-    this.backgroundAgents.clear();
+    this.detachedAgents.clear();
     this.finishedTurnAge.clear();
   }
 }

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/ui/display.ts

@@ -7,6 +7,7 @@
 
 import type { AgentConfigLookup } from "#src/config/agent-types";
 import { GLYPHS } from "#src/ui/glyphs";
+import type { SubagentTerminalReason } from "#src/lifecycle/subagent-state";
 import type { AgentInvocation, SubagentType, ThinkingLevel } from "#src/types";
 
 // ---- Types ----
@@ -24,7 +25,8 @@ export interface AgentDetails {
   toolUses: number;
   tokens: string;
   durationMs: number;
-  status: "queued" | "running" | "completed" | "steered" | "aborted" | "stopped" | "error" | "background";
+  status: "queued" | "running" | "completed" | "stopped" | "error";
+  terminalReason?: SubagentTerminalReason;
   /** Human-readable description of what the agent is currently doing. */
   activity?: string;
   /** Current spinner frame index (for animated running indicator). */
@@ -49,7 +51,7 @@ export interface AgentDetails {
 export const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 
 /** Statuses that indicate an error/non-success outcome (used for linger behavior and icon rendering). */
-export const ERROR_STATUSES = new Set(["error", "aborted", "steered", "stopped"]);
+export const ERROR_STATUSES = new Set(["error", "stopped"]);
 
 /** Tool name → human-readable action for activity descriptions. */
 const TOOL_DISPLAY: Record<string, string> = {
@@ -146,8 +148,9 @@ export function buildInvocationTags(
   if (!invocation) return { tags };
   if (invocation.thinking) tags.push(`thinking: ${invocation.thinking}`);
   if (invocation.inheritContext) tags.push("inherit context");
-  if (invocation.runInBackground) tags.push("background");
+  if (invocation.mode) tags.push(`mode: ${invocation.mode}`);
   if (invocation.maxTurns != null) tags.push(`max turns: ${invocation.maxTurns}`);
+  if (invocation.timeoutSeconds != null) tags.push(`timeout: ${invocation.timeoutSeconds}s`);
   return { modelName: invocation.modelName, tags };
 }