@nklisch/pi-enhanced 0.2.7 → 0.3.1

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/tools/result-renderer.ts

@@ -1,130 +1,46 @@
-/**
- * result-renderer.ts — Pure per-status rendering functions for Agent tool results.
- *
- * All functions are stateless: they receive AgentDetails and a Theme, returning
- * formatted strings. No SDK types, no timers, no side effects.
- * Consumed by the renderResult hook in agent-tool.ts.
- */
+/** Pure presentation for the joined/detached launch result. */
 
 import type { AgentDetails, Theme } from "#src/ui/display";
 import { formatModelThinking, formatMs, formatTurns, SPINNER } from "#src/ui/display";
 
-// ---- Dispatcher ----
-
-/** Dispatch to the per-status renderer based on details.status and isPartial. */
-export function renderAgentResult(
-	details: AgentDetails,
-	resultText: string,
-	expanded: boolean,
-	isPartial: boolean,
-	theme: Theme,
-): string {
-	if (isPartial || details.status === "running") return renderRunning(details, theme);
-	if (details.status === "background") return renderBackground(details, theme);
-	if (details.status === "completed" || details.status === "steered")
-		return renderCompleted(details, resultText, expanded, theme);
-	if (details.status === "stopped") return renderStopped(details, theme);
-	return renderFailed(details, theme);
+export function renderAgentResult(details: AgentDetails, resultText: string, expanded: boolean, isPartial: boolean, theme: Theme): string {
+  if (isPartial || details.status === "running" || details.status === "queued") return renderRunning(details, theme);
+  if (details.status === "completed") return renderCompleted(details, resultText, expanded, theme);
+  if (details.status === "stopped") return renderStopped(details, theme);
+  return renderFailed(details, theme);
 }
 
-// ---- Per-status renderers ----
-
-/** Render running/partial status: spinner + stats + activity line. */
 export function renderRunning(details: AgentDetails, theme: Theme): string {
-	const frame = SPINNER[details.spinnerFrame ?? 0];
-	const s = renderStats(details, theme);
-	const duration = theme.fg("dim", formatMs(details.durationMs));
-	let line = theme.fg("accent", frame) + (s ? " " + s : "");
-	line += `${s ? " " + theme.fg("dim", "·") + " " : " "}${duration}`;
-	line += "\n" + theme.fg("dim", `  ⎿  ${details.activity ?? "thinking\u2026"}`);
-	return line;
+  const frame = SPINNER[details.spinnerFrame ?? 0];
+  const stats = renderStats(details, theme);
+  const duration = theme.fg("dim", formatMs(details.durationMs));
+  return theme.fg("accent", frame) + (stats ? " " + stats : "") + " " + duration + "\n" + theme.fg("dim", `  ⎿  ${details.activity ?? "thinking…"}`);
 }
 
-/** Render background launch status. */
-export function renderBackground(details: AgentDetails, theme: Theme): string {
-	const identity = [
-		formatModelThinking(details.modelName ?? "unknown model", details.thinkingLevel),
-		formatMs(details.durationMs),
-	].join(" · ");
-	return theme.fg("dim", `  \u23BF  Running in background (ID: ${details.agentId}) · ${identity}`);
+export function renderCompleted(details: AgentDetails, resultText: string, expanded: boolean, theme: Theme): string {
+  let line = theme.fg("success", "✓") + " " + renderStats(details, theme) + " " + theme.fg("dim", "·") + " " + theme.fg("dim", formatMs(details.durationMs));
+  if (expanded) {
+    for (const item of resultText.split("\n").slice(0, 50)) line += "\n" + theme.fg("dim", `  ${item}`);
+    if (resultText.split("\n").length > 50) line += "\n" + theme.fg("muted", "  ... (output truncated; use get_subagent_result for the bounded final output)");
+  } else {
+    line += "\n" + theme.fg("dim", `  ⎿  ${details.terminalReason === "turn_limit_graceful" ? "Completed (turn limit)" : "Done"}`);
+  }
+  return line;
 }
 
-/** Render completed or steered status with optional expanded result text. */
-export function renderCompleted(
-	details: AgentDetails,
-	resultText: string,
-	expanded: boolean,
-	theme: Theme,
-): string {
-	const duration = formatMs(details.durationMs);
-	const isSteered = details.status === "steered";
-	const icon = isSteered ? theme.fg("warning", "\u2713") : theme.fg("success", "\u2713");
-	const s = renderStats(details, theme);
-	let line = icon + (s ? " " + s : "");
-	line += " " + theme.fg("dim", "\u00B7") + " " + theme.fg("dim", duration);
-
-	if (expanded) {
-		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",
-						"  ... (use get_subagent_result with verbose for full output)",
-					);
-			}
-		}
-	} else {
-		const doneText = isSteered ? "Wrapped up (turn limit)" : "Done";
-		line += "\n" + theme.fg("dim", `  \u23BF  ${doneText}`);
-	}
-	return line;
-}
-
-/** Render stopped status: dim stop icon + stats + "Stopped". */
 export function renderStopped(details: AgentDetails, theme: Theme): string {
-	const s = renderStats(details, theme);
-	let line = theme.fg("dim", "\u25A0") + (s ? " " + s : "");
-	line += ` ${theme.fg("dim", "·")} ${theme.fg("dim", formatMs(details.durationMs))}`;
-	line += "\n" + theme.fg("dim", "  \u23BF  Stopped");
-	return line;
+  return theme.fg("dim", "■") + " " + renderStats(details, theme) + " " + theme.fg("dim", "·") + " " + theme.fg("dim", formatMs(details.durationMs)) + "\n" + theme.fg("dim", `  ⎿  Stopped${details.terminalReason ? ` (${details.terminalReason.replaceAll("_", " ")})` : ""}`);
 }
 
-/** Render error or aborted status: error icon + stats + status message. */
 export function renderFailed(details: AgentDetails, theme: Theme): string {
-	const s = renderStats(details, theme);
-	let line = theme.fg("error", "\u2717") + (s ? " " + s : "");
-	line += ` ${theme.fg("dim", "·")} ${theme.fg("dim", formatMs(details.durationMs))}`;
-
-	if (details.status === "error") {
-		line += "\n" + theme.fg("error", `  \u23BF  Error: ${details.error ?? "unknown"}`);
-	} else {
-		line += "\n" + theme.fg("warning", "  \u23BF  Aborted (max turns exceeded)");
-	}
-	return line;
+  return theme.fg("error", "✗") + " " + renderStats(details, theme) + " " + theme.fg("dim", "·") + " " + theme.fg("dim", formatMs(details.durationMs)) + "\n" + theme.fg("error", `  ⎿  Error: ${details.error ?? "unknown"}`);
 }
 
-// ---- Shared helper ----
-
-/**
- * Build the stats string: "haiku · thinking: high · ⟳5≤30 · 3 tool uses · 33.8k token".
- * Returns an empty string when all fields are absent or zero.
- */
 export function renderStats(details: AgentDetails, theme: Theme): string {
-	const parts: string[] = [];
-	parts.push(formatModelThinking(details.modelName ?? "unknown model", details.thinkingLevel));
-	if (details.tags) parts.push(...details.tags.filter((tag) => !tag.startsWith("thinking: ")));
-	if (details.turnCount != null && details.turnCount > 0) {
-		parts.push(formatTurns(details.turnCount, details.maxTurns));
-	}
-	if (details.toolUses > 0)
-		parts.push(`${details.toolUses} tool use${details.toolUses === 1 ? "" : "s"}`);
-	if (details.tokens) parts.push(details.tokens);
-	return parts
-		.map((p) => theme.fg("dim", p))
-		.join(" " + theme.fg("dim", "\u00B7") + " ");
+  const parts: string[] = [formatModelThinking(details.modelName ?? "unknown model", details.thinkingLevel)];
+  if (details.tags) parts.push(...details.tags.filter((tag) => !tag.startsWith("thinking: ")));
+  if (details.turnCount != null && details.turnCount > 0) parts.push(formatTurns(details.turnCount, details.maxTurns));
+  if (details.toolUses > 0) parts.push(`${details.toolUses} tool use${details.toolUses === 1 ? "" : "s"}`);
+  if (details.tokens) parts.push(details.tokens);
+  return parts.map((p) => theme.fg("dim", p)).join(" " + theme.fg("dim", "·") + " ");
 }

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;
 }