@nklisch/pi-enhanced 0.2.7 → 0.3.0

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

@@ -1,4 +1,5 @@
-/* eslint-disable @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-base-to-string, @typescript-eslint/restrict-template-expressions -- Pi SDK types are not fully exported; see upstream Pi SDK for type improvements */
+/* eslint-disable @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-base-to-string, @typescript-eslint/restrict-template-expressions -- Pi SDK render types are intentionally narrow at this boundary */
+
 import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
@@ -6,266 +7,187 @@ import { Type } from "@sinclair/typebox";
 import { AgentTypeRegistry } from "#src/config/agent-types";
 import { THINKING_LEVELS_DESCRIPTION } from "#src/config/thinking-levels";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
-import type { AgentSpawnConfig } from "#src/lifecycle/subagent-manager";
-import { SubagentBusyError } from "#src/lifecycle/subagent";
-import { spawnBackground } from "#src/tools/background-spawner";
-import { runForeground } from "#src/tools/foreground-runner";
-import { buildAgentGuidelines, buildDetails, buildTypeListText, textResult } from "#src/tools/helpers";
+import type { AgentSpawnConfig, DeliveryOutcome } from "#src/lifecycle/subagent-manager";
+import type { Subagent } from "#src/lifecycle/subagent";
+import { buildAgentGuidelines, buildDetails, buildTypeListText, formatLifetimeTokens, textResult } from "#src/tools/helpers";
 import { renderAgentResult } from "#src/tools/result-renderer";
 import { type ModelInfo, resolveSpawnConfig } from "#src/tools/spawn-config";
-import type { ParentSessionInfo, Subagent } from "#src/types";
-import { type AgentDetails, formatDuration, formatModelThinking, getDisplayName } from "#src/ui/display";
-
-// ---- Deps interfaces ----
+import type { ParentSessionInfo } from "#src/types";
+import { describeActivity, type AgentDetails, formatModelThinking, formatMs, getDisplayName } from "#src/ui/display";
 
-/** Narrow manager interface — only the methods the Agent tool calls. */
 export interface AgentToolManager {
-	spawn: (snapshot: ParentSnapshot, type: string, prompt: string, opts: AgentSpawnConfig) => string;
-	spawnAndWait: (snapshot: ParentSnapshot, type: string, prompt: string, opts: Omit<AgentSpawnConfig, "isBackground">) => Promise<Subagent>;
-	resume: (id: string, prompt: string, signal: AbortSignal) => Promise<Subagent | undefined>;
-	getRecord: (id: string) => Subagent | undefined;
+  launch(snapshot: ParentSnapshot, type: string, prompt: string, opts: AgentSpawnConfig): Promise<DeliveryOutcome>;
+  getRecord(id: string): Subagent | undefined;
 }
 
-/** Narrow runtime interface — the Agent tool's slice of SubagentRuntime. */
 export interface AgentToolRuntime {
-	buildSnapshot(inheritContext: boolean): ParentSnapshot;
-	getModelInfo(): ModelInfo;
-	getSessionInfo(): { parentSessionFile: string; parentSessionId: string };
+  buildSnapshot(inheritContext: boolean): ParentSnapshot;
+  getModelInfo(): ModelInfo;
+  getSessionInfo(): { parentSessionFile: string; parentSessionId: string };
 }
 
-/** Narrow settings accessor — only the fields the Agent tool reads. */
 export type AgentToolSettings = {
-	readonly defaultMaxTurns: number | undefined;
-	readonly maxConcurrent: number;
-	readonly fallbackSubagent?: string | false;
+  readonly defaultMaxTurns: number | undefined;
+  readonly fallbackSubagent?: string | false;
 };
 
-// ---- Class ----
-
 export class AgentTool {
-	private readonly typeListText: string;
-	private readonly availableTypesText: string;
-	private readonly agentGuidelines: string[];
-
-	constructor(
-		private readonly manager: AgentToolManager,
-		private readonly runtime: AgentToolRuntime,
-		private readonly settings: AgentToolSettings,
-		private readonly registry: AgentTypeRegistry,
-		private readonly agentDir: string,
-	) {
-		this.typeListText = buildTypeListText(registry, agentDir);
-		this.availableTypesText = registry.getAvailableTypes().join(", ");
-		this.agentGuidelines = buildAgentGuidelines(registry);
-	}
-
-	async execute(
-		toolCallId: string,
-		params: Record<string, unknown>,
-		signal: AbortSignal | undefined,
-		onUpdate: ((update: AgentToolResult<any>) => void) | undefined,
-		_ctx: any,
-	) {
-		// Reload custom agents so new .pi/agents/*.md files are picked up without restart
-		this.registry.reload();
-
-		// ---- Config resolution (pure) ----
-		const config = resolveSpawnConfig(
-			params,
-			this.registry,
-			this.runtime.getModelInfo(),
-			this.settings,
-		);
-		if ("error" in config) return textResult(config.error);
-
-		// ---- Boundary extraction (after config so inheritContext is resolved) ----
-		const snapshot = this.runtime.buildSnapshot(config.execution.inheritContext);
-		const { parentSessionFile, parentSessionId } = this.runtime.getSessionInfo();
-		const parentSession: ParentSessionInfo = { parentSessionFile, parentSessionId, toolCallId };
-
-		// ---- Resume existing agent ----
-		if (params.resume) {
-			const existing = this.manager.getRecord(params.resume as string);
-			if (!existing) {
-				return textResult(
-					`Agent not found: "${params.resume}". It may have been cleaned up.`,
-				);
-			}
-			if (!existing.isSessionReady()) {
-				return textResult(
-					existing.sessionReleased
-						? `Agent "${params.resume}" retained its result and transcript, but its live session was released after the retention window. Start a new subagent for fresh context.`
-						: `Agent "${params.resume}" has no active session to resume.`,
-				);
-			}
-			let record: Subagent | undefined;
-			try {
-				record = await this.manager.resume(
-					params.resume as string,
-					params.prompt as string,
-					signal ?? new AbortController().signal,
-				);
-			} catch (error) {
-				if (error instanceof SubagentBusyError) return textResult(error.message);
-				throw error;
-			}
-			if (!record) {
-				return textResult(`Failed to resume agent "${params.resume}".`);
-			}
-			record.markConsumed();
-			const partial = record.result?.trim();
-			const resultText = record.status === "error"
-				? partial
-					? `Error: ${record.error}\n\nPartial output before the failure:\n${partial}`
-					: `Error: ${record.error}`
-				: partial ?? "No output.";
-			return textResult(
-				`Model: ${formatModelThinking(record.modelLabel, record.effectiveThinkingLevel)}\nRuntime: ${formatDuration(record.startedAt, record.completedAt)}\n\n${resultText}`,
-				buildDetails(
-					{ ...config.presentation.detailBase, modelName: record.modelLabel, thinkingLevel: record.effectiveThinkingLevel },
-					record,
-				),
-			);
-		}
-
-		// ---- Background execution ----
-		if (config.execution.runInBackground) {
-			return spawnBackground(
-				this.manager,
-				{ config, snapshot, parentSession, settings: this.settings },
-			);
-		}
-
-		// ---- Foreground execution — stream progress via onUpdate ----
-		return runForeground(
-			this.manager,
-			{ config, snapshot, parentSession },
-			signal,
-			onUpdate,
-		);
-	}
-
-	toToolDefinition() {
-		const typeListText = this.typeListText;
-		const availableTypesText = this.availableTypesText;
-		const agentDir = this.agentDir;
-		const registry = this.registry;
-
-		const guidelines = [
-			"- For parallel work, use run_in_background: true on each agent. Foreground calls run sequentially — only one executes at a time.",
-			...this.agentGuidelines,
-			"- Provide clear, detailed prompts so the agent can work autonomously.",
-			"- Subagent results are returned as text — summarize them for the user.",
-			"- Background completion automatically wakes you with a result preview. Continue other work instead of polling.",
-			"- Use get_subagent_result only for full output, verbose conversation, an explicit status check or synchronization point, or recovery after a missed notification.",
-			"- Use steer_subagent to redirect an agent that is still running.",
-			"- Use resume only after an agent finishes when it should continue with the same retained conversation history.",
-			"- Launch a new subagent without resume when prior conversation history is unnecessary.",
-			'- Use model to specify a different model (as "provider/modelId", or fuzzy e.g. "haiku", "sonnet").',
-			"- Use thinking to control extended thinking level.",
-			"- Use inherit_context if the agent needs the parent conversation history.",
-		].join("\n");
-
-		return defineTool({
-			name: "subagent" as const,
-			label: "Subagent",
-			promptSnippet: "subagent: Launch a specialized agent for complex, multi-step tasks.",
-			description: `Launch a new agent to handle complex, multi-step tasks autonomously.
-
-The subagent tool launches specialized agents that autonomously handle complex tasks. Each agent type has specific capabilities and tools available to it.
-
-Available agent types:
-${typeListText}
-
-Guidelines:
-${guidelines}
-`,
-			parameters: Type.Object({
-				prompt: Type.String({
-					description: "The task for the agent to perform.",
-				}),
-				description: Type.String({
-					description: "A short (3-5 word) description of the task (shown in UI).",
-				}),
-				subagent_type: Type.String({
-					description: `The type of specialized agent to use. Available types: ${availableTypesText}. Custom agents from .pi/agents/<name>.md (project) or ${agentDir}/agents/<name>.md (global) are also available.`,
-				}),
-				model: Type.Optional(
-					Type.String({
-						description:
-							'Optional model override. Accepts "provider/modelId" or fuzzy name (e.g. "haiku", "sonnet"). Omit to use the agent type\'s default.',
-					}),
-				),
-				thinking: Type.Optional(
-					Type.String({
-						description:
-							`Thinking level: ${THINKING_LEVELS_DESCRIPTION}. Overrides agent default. Availability depends on the selected model and host Pi version.`,
-					}),
-				),
-				max_turns: Type.Optional(
-					Type.Number({
-						description:
-							"Maximum number of agentic turns before stopping. Omit for unlimited (default).",
-						minimum: 1,
-					}),
-				),
-				run_in_background: Type.Optional(
-					Type.Boolean({
-						description:
-							"Set to true to run in background. Returns an agent ID immediately; completion automatically wakes you with a result preview.",
-					}),
-				),
-				resume: Type.Optional(
-					Type.String({
-						description:
-							"Agent ID of a retained, finished session to continue with the same conversation history. Omit to start a new context.",
-					}),
-				),
-				inherit_context: Type.Optional(
-					Type.Boolean({
-						description:
-							"If true, fork parent conversation into the agent. Default: false (fresh context).",
-					}),
-				),
-			}),
-
-			// ---- Custom rendering: inline subagent results ----
-
-			renderCall(args: Record<string, unknown>, theme: any) {
-				const displayName = args.subagent_type
-					? getDisplayName(args.subagent_type as string, registry)
-					: "Subagent";
-				const desc = (args.description as string | undefined) ?? "";
-				return new Text(
-					"▸ " +
-						theme.fg("toolTitle", theme.bold(displayName)) +
-						(desc ? "  " + theme.fg("muted", desc) : ""),
-					0,
-					0,
-				);
-			},
-
-			renderResult(result: any, { expanded, isPartial }: any, theme: any) {
-				const details = result.details as AgentDetails | undefined;
-				if (!details) {
-					const text = result.content[0]?.type === "text" ? result.content[0].text : "";
-					return new Text(text, 0, 0);
-				}
-				const resultText = result.content[0]?.type === "text" ? result.content[0].text : "";
-				return new Text(
-					renderAgentResult(details, resultText, expanded, isPartial, theme),
-					0,
-					0,
-				);
-			},
+  private readonly typeListText: string;
+  private readonly availableTypesText: string;
+  private readonly agentGuidelines: string[];
+
+  constructor(
+    private readonly manager: AgentToolManager,
+    private readonly runtime: AgentToolRuntime,
+    private readonly settings: AgentToolSettings,
+    private readonly registry: AgentTypeRegistry,
+    private readonly agentDir: string,
+  ) {
+    this.typeListText = buildTypeListText(registry, agentDir);
+    this.availableTypesText = registry.getAvailableTypes().join(", ");
+    this.agentGuidelines = buildAgentGuidelines(registry);
+  }
+
+  async execute(
+    toolCallId: string,
+    params: Record<string, unknown>,
+    signal: AbortSignal | undefined,
+    onUpdate: ((update: AgentToolResult<any>) => void) | undefined,
+    _ctx: any,
+  ) {
+    this.registry.reload();
+    const config = resolveSpawnConfig(params, this.registry, this.runtime.getModelInfo(), this.settings);
+    if ("error" in config) return textResult(config.error);
+
+    const snapshot = this.runtime.buildSnapshot(config.execution.inheritContext);
+    const sessionInfo = this.runtime.getSessionInfo();
+    const parentSession: ParentSessionInfo = { ...sessionInfo, toolCallId };
+    let currentId: string | undefined;
+    let spinnerFrame = 0;
+    const update = (): void => {
+      const record = currentId ? this.manager.getRecord(currentId) : undefined;
+      if (!record || !onUpdate || config.execution.mode !== "joined") return;
+      const details = buildDetails(config.presentation.detailBase, record, {
+        durationMs: record.activeRuntimeMs,
+        status: record.status,
+        terminalReason: record.stateTerminalReason,
+        tokens: formatLifetimeTokens(record),
+        activity: record.stateTerminalReason ? undefined : describeActivity(record.activeTools, record.responseText),
+        spinnerFrame: spinnerFrame++,
+      });
+      onUpdate({ content: [{ type: "text", text: `${record.toolUses} tool uses...` }], details: details as any });
+    };
+    const timer = setInterval(update, 500);
+
+    let outcome: DeliveryOutcome;
+    try {
+      outcome = await this.manager.launch(snapshot, config.identity.subagentType, config.execution.prompt, {
+        description: config.execution.description,
+        model: config.execution.model,
+        maxTurns: config.execution.effectiveMaxTurns,
+        inheritContext: config.execution.inheritContext,
+        thinkingLevel: config.execution.effectiveThinkingLevel,
+        mode: config.execution.mode,
+        timeoutSeconds: config.execution.timeoutSeconds,
+        origin: "tool",
+        invocation: config.execution.agentInvocation,
+        parentSession,
+        signal,
+        onCreated: (record) => { currentId = record.id; update(); },
+      });
+      currentId = outcome.kind === "joined" ? outcome.record.id : outcome.agentId;
+      update();
+    } catch (error) {
+      return textResult(error instanceof Error ? error.message : String(error));
+    } finally {
+      clearInterval(timer);
+    }
+
+    const record = this.manager.getRecord(currentId!);
+    if (!record) return textResult(`Agent not found after launch: "${currentId}".`);
+    if (outcome.kind === "detached") {
+      return textResult(
+        `Agent detached and ${record.status === "queued" ? "queued" : "started"}.\n` +
+        `Agent ID: ${record.id}\nRun ID: ${record.runId}\nType: ${config.identity.displayName}\n` +
+        `Mode: detached\nModel: ${formatModelThinking(record.modelLabel, record.effectiveThinkingLevel)}\n` +
+        `Description: ${record.description}\n` +
+        (record.status === "queued" ? "Admission: queued\n" : "") +
+        "Completion will send one notification. Use get_subagent_result for the bounded final result.",
+        buildDetails(config.presentation.detailBase, record, {
+          status: record.status,
+          terminalReason: record.stateTerminalReason,
+          durationMs: record.activeRuntimeMs,
+        }),
+      );
+    }
+
+    record.markConsumed();
+    const details = buildDetails(config.presentation.detailBase, record, {
+      status: record.status,
+      terminalReason: record.stateTerminalReason,
+      tokens: formatLifetimeTokens(record),
+      durationMs: record.activeRuntimeMs,
+    });
+    const fallback = config.identity.fellBack ? `Unknown agent type "${config.identity.rawType}" — using ${config.identity.subagentType}.\n\n` : "";
+    const boundedResult = boundResult(record.result, record.outputFile);
+    if (record.status === "error") {
+      return textResult(`${fallback}Model: ${formatModelThinking(record.modelLabel, record.effectiveThinkingLevel)}\nRuntime: ${formatMs(record.activeRuntimeMs)}\nAgent failed: ${record.error}${boundedResult ? `\n\nPartial output:\n${boundedResult}` : ""}`, details);
+    }
+    return textResult(`${fallback}Model: ${formatModelThinking(record.modelLabel, record.effectiveThinkingLevel)}\nRuntime: ${formatMs(record.activeRuntimeMs)}\nAgent ${record.status}${record.stateTerminalReason ? ` (${record.stateTerminalReason.replaceAll("_", " ")})` : ""}.\n\n${boundedResult}`, details);
+  }
+
+  toToolDefinition() {
+    const typeListText = this.typeListText;
+    const availableTypesText = this.availableTypesText;
+    const agentDir = this.agentDir;
+    const registry = this.registry;
+    const guidelines = [
+      "- Use mode: joined when the parent needs the result in this turn; use mode: detached for independent work (default).",
+      ...this.agentGuidelines,
+      "- Provide clear, detailed prompts so the agent can work autonomously.",
+      "- Detached completion automatically wakes you with one bounded result preview; do not poll.",
+      "- Use resume_subagent to continue a retained session and stop_subagent to request cooperative cancellation.",
+      '- Use model to specify a different model (as "provider/modelId", or fuzzy e.g. "haiku", "sonnet").',
+      "- Use thinking to control extended thinking level.",
+      "- Use inherit_context if the agent needs the parent conversation history.",
+    ].join("\n");
+
+    return defineTool({
+      name: "subagent" as const,
+      label: "Subagent",
+      promptSnippet: "subagent: Launch a specialized agent for complex, multi-step tasks.",
+      description: `Launch one specialized agent. Delivery defaults to detached; choose joined when this parent turn must receive the settled result.\n\nAvailable agent types:\n${typeListText}\n\nGuidelines:\n${guidelines}\n`,
+      parameters: Type.Object({
+        prompt: Type.String({ description: "The task for the agent to perform." }),
+        description: Type.String({ description: "A short (3-5 word) description of the task." }),
+        subagent_type: Type.String({ description: `The specialized agent type. Available types: ${availableTypesText}. Custom agents from .pi/agents/<name>.md or ${agentDir}/agents/<name>.md are also available.` }),
+        model: Type.Optional(Type.String({ description: 'Optional model override: "provider/modelId" or fuzzy name.' })),
+        thinking: Type.Optional(Type.String({ description: `Thinking level: ${THINKING_LEVELS_DESCRIPTION}.` })),
+        max_turns: Type.Optional(Type.Integer({ description: "Maximum agentic turns. Use 0 or omit for unlimited.", minimum: 0 })),
+        timeout_seconds: Type.Optional(Type.Integer({ description: "Active runtime deadline in seconds; queued time is excluded.", minimum: 1 })),
+        mode: Type.Optional(Type.Union([Type.Literal("joined"), Type.Literal("detached")], { description: "Result delivery mode. Defaults to detached." })),
+        inherit_context: Type.Optional(Type.Boolean({ description: "Fork parent conversation into the agent. Default: false." })),
+      }),
+      renderCall(args: Record<string, unknown>, theme: any) {
+        const displayName = args.subagent_type ? getDisplayName(args.subagent_type as string, registry) : "Subagent";
+        const desc = (args.description as string | undefined) ?? "";
+        return new Text("▸ " + theme.fg("toolTitle", theme.bold(displayName)) + (desc ? "  " + theme.fg("muted", desc) : ""), 0, 0);
+      },
+      renderResult(result: any, { expanded, isPartial }: any, theme: any) {
+        const details = result.details as AgentDetails | undefined;
+        if (!details) return new Text(result.content[0]?.type === "text" ? result.content[0].text : "", 0, 0);
+        const text = result.content[0]?.type === "text" ? result.content[0].text : "";
+        return new Text(renderAgentResult(details, text, expanded, isPartial, theme), 0, 0);
+      },
+      execute: (toolCallId: string, params: Record<string, unknown>, signal: AbortSignal | undefined, onUpdate: ((update: AgentToolResult<any>) => void) | undefined, ctx: any) => this.execute(toolCallId, params, signal, onUpdate, ctx),
+    });
+  }
+}
 
-			execute: (
-				toolCallId: string,
-				params: Record<string, unknown>,
-				signal: AbortSignal | undefined,
-				onUpdate: ((update: AgentToolResult<any>) => void) | undefined,
-				ctx: any,
-			) => this.execute(toolCallId, params, signal, onUpdate, 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/get-result-tool.ts

@@ -1,104 +1,61 @@
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 import type { AgentConfigLookup } from "#src/config/agent-types";
-import { type AgentReport, formatAgentReport } from "#src/tools/get-result-report";
+import type { Subagent } from "#src/lifecycle/subagent";
 import { formatLifetimeTokens, textResult } from "#src/tools/helpers";
-import type { Subagent } from "#src/types";
-import { formatDuration, getDisplayName } from "#src/ui/display";
+import type { AgentDetails } from "#src/ui/display";
+import { describeActivity, formatMs, formatModelThinking } from "#src/ui/display";
 
-// ---- Deps interfaces ----
+const MAX_RESULT_OUTPUT = 12_000;
 
-export interface GetResultToolManager {
-	getRecord(id: string): Subagent | undefined;
-}
-
-// ---- Class ----
+export interface GetResultToolManager { getRecord(id: string): Subagent | undefined; }
 
 export class GetResultTool {
-	constructor(
-		private readonly manager: GetResultToolManager,
-		private readonly registry: AgentConfigLookup,
-	) {}
-
-	async execute(
-		_toolCallId: string,
-		params: { agent_id: string; wait?: boolean; verbose?: boolean },
-		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.`);
-		}
-
-		// A queued record is awaitable from spawn, and a resumed record republishes
-		// its live promise. This claim is synchronous so completion cannot race the
-		// direct result with an asynchronous follow-up notification. Interrupting
-		// this tool stops only the wait.
-		if (params.wait) await record.waitForResult(signal);
-
-		// Pull delivery: only a terminal result was actually collected.
-		if (!record.isActive()) record.markConsumed();
-
-		return textResult(formatAgentReport(this.buildReport(record, params.verbose)));
-	}
-
-	private buildReport(record: Subagent, verbose?: boolean): AgentReport {
-		return {
-			id: record.id,
-			displayName: getDisplayName(record.type, this.registry),
-			modelLabel: record.modelLabel,
-			thinkingLevel: record.effectiveThinkingLevel,
-			status: record.status,
-			toolUses: record.toolUses,
-			tokens: formatLifetimeTokens(record),
-			contextPercent: record.getContextPercent(),
-			compactionCount: record.compactionCount,
-			duration: formatDuration(record.startedAt, record.completedAt),
-			description: record.description,
-			result: record.result,
-			error: record.error,
-			stoppedWhileQueued: record.stoppedWhileQueued,
-			conversation: verbose ? record.getConversation() : undefined,
-			transcriptPath: record.outputFile,
-		};
-	}
+  constructor(private readonly manager: GetResultToolManager, private readonly registry: AgentConfigLookup) {}
+
+  async execute(_toolCallId: string, params: { agent_id: string }, _signal: AbortSignal | undefined, _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.`);
+    if (!record.isActive()) record.markConsumed();
+
+    const activity = describeActivity(record.activeTools, record.responseText);
+    const text = record.isActive()
+      ? `Agent ${record.id} is ${record.status}.\nRun ID: ${record.runId}\nMode: ${record.mode}\nModel: ${formatModelThinking(record.modelLabel, record.effectiveThinkingLevel)}\nRuntime: ${formatMs(record.activeRuntimeMs)} (running)\nActivity: ${activity}`
+      : renderTerminalResult(record);
+    const details: AgentDetails = {
+      displayName: this.registry.resolveAgentConfig(record.type).displayName ?? record.type,
+      description: record.description,
+      subagentType: record.type,
+      toolUses: record.toolUses,
+      tokens: formatLifetimeTokens(record),
+      durationMs: record.activeRuntimeMs,
+      status: record.status,
+      terminalReason: record.stateTerminalReason,
+      modelName: record.modelLabel,
+      thinkingLevel: record.effectiveThinkingLevel,
+      turnCount: record.turnCount,
+      maxTurns: record.maxTurns,
+      activity,
+      agentId: record.id,
+      error: record.error,
+    };
+    return textResult(text, details);
+  }
+
+  toToolDefinition() {
+    return defineTool({
+      name: "get_subagent_result" as const,
+      label: "Get Subagent Result",
+      promptSnippet: "get_subagent_result: Read a bounded subagent result without waiting.",
+      description: "Read a subagent's current status or bounded terminal result. This tool never waits and never dumps the full conversation. Use the transcript path when output is truncated.",
+      parameters: Type.Object({ agent_id: Type.String({ description: "The subagent ID to inspect." }) }),
+      execute: (toolCallId: string, params: { agent_id: string }, signal: AbortSignal, onUpdate: unknown, ctx: unknown) => this.execute(toolCallId, params, signal, onUpdate, ctx),
+    });
+  }
+}
 
-	toToolDefinition() {
-		return defineTool({
-			name: "get_subagent_result" as const,
-			label: "Get Agent Result",
-			promptSnippet:
-				"get_subagent_result: Inspect status or retrieve full results from a background agent.",
-			description:
-				"Background completion automatically wakes you with a result preview, so do not poll. " +
-				"Use this tool only for full output, verbose conversation, an explicit status check or synchronization point, " +
-				"or recovery after a missed notification.",
-			parameters: Type.Object({
-				agent_id: Type.String({
-					description: "The agent ID to check.",
-				}),
-				wait: Type.Optional(
-					Type.Boolean({
-						description:
-							"If true, wait for the agent to complete before returning. Default: false.",
-					}),
-				),
-				verbose: Type.Optional(
-					Type.Boolean({
-						description:
-							"If true, include the agent's full conversation (messages + tool calls). Default: false.",
-					}),
-				),
-			}),
-			execute: (
-				toolCallId: string,
-				params: { agent_id: string; wait?: boolean; verbose?: boolean },
-				signal: AbortSignal,
-				onUpdate: unknown,
-				ctx: unknown,
-			) => this.execute(toolCallId, params, signal, onUpdate, ctx),
-		});
-	}
+function renderTerminalResult(record: Subagent): string {
+  const output = record.result?.trim() || "No output.";
+  const bounded = output.length > MAX_RESULT_OUTPUT ? output.slice(0, MAX_RESULT_OUTPUT) + `\n\nOutput truncated. Full transcript: ${record.outputFile ?? "unavailable"}` : output;
+  return `Agent ${record.id} ${record.status}.\nRun ID: ${record.runId}\nMode: ${record.mode}\nModel: ${formatModelThinking(record.modelLabel, record.effectiveThinkingLevel)}\nRuntime: ${formatMs(record.activeRuntimeMs)}\nReason: ${record.stateTerminalReason ?? "unknown"}\n\n${record.status === "error" ? `Error: ${record.error}\n\n` : ""}${bounded}`;
 }