@yefengr/pi-subagents 0.0.0-stage → 0.1.0

package/src/tools/agent-tool.ts

@@ -0,0 +1,289 @@
+import type { AgentToolResult, ExtensionContext, ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { AgentTypeRegistry } from "#src/config/agent-types";
+import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
+import type { AgentSpawnConfig } from "#src/lifecycle/subagent-manager";
+import { spawnBackground } from "#src/tools/background-spawner";
+import { runForeground } from "#src/tools/foreground-runner";
+import { buildAgentGuidelines, buildDetails, buildTypeListText, 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, SubagentInvocationIdentity } from "#src/types";
+import { type AgentDetails, getDisplayName, type Theme } from "#src/ui/display";
+import { GLYPHS } from "#src/ui/glyphs";
+
+// ---- Deps interfaces ----
+
+/** 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,
+		invocation: SubagentInvocationIdentity,
+		limits?: { maxTurns?: number; wrapUpTurns?: number; maxDurationSeconds?: number },
+		signal?: AbortSignal,
+	) => Promise<Subagent | undefined>;
+	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 };
+}
+
+/** Narrow settings accessor — only the fields the Agent tool reads. */
+export type AgentToolSettings = {
+	readonly maxTurns: number;
+	readonly wrapUpTurns: number;
+	readonly maxDurationSeconds: number;
+	readonly maxQueueWaitSeconds: number;
+	readonly abortGraceSeconds: number;
+	readonly maxConcurrent: number;
+};
+
+// ---- Class ----
+
+export class AgentTool {
+	constructor(
+		private readonly manager: AgentToolManager,
+		private readonly runtime: AgentToolRuntime,
+		private readonly settings: AgentToolSettings,
+		private readonly registry: AgentTypeRegistry,
+		private readonly agentDir: string,
+	) {}
+
+	async execute(
+		toolCallId: string,
+		params: Record<string, unknown>,
+		signal: AbortSignal | undefined,
+		onUpdate: ((update: AgentToolResult<AgentDetails>) => void) | undefined,
+		_ctx: ExtensionContext,
+	) {
+		// Reload custom agents so new .pi/agents/*.md files are picked up without restart
+		this.registry.reload();
+
+		// 恢复按原任务的真实类型校验，不能用另一个已启用类型绕过禁用。
+		const existing = params.resume ? this.manager.getRecord(params.resume as string) : undefined;
+		if (params.resume && !existing) {
+			return textResult(
+				`Agent not found: "${params.resume as string}". Records are cleared at session start/switch, so it may be from a previous session.`,
+			);
+		}
+
+		// ---- Config resolution (pure) ----
+		const config = resolveSpawnConfig(
+			existing ? { ...params, subagent_type: existing.type } : 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 && existing) {
+			if (!existing.isSessionReady()) {
+				if (existing.sessionReleased) {
+					return textResult(
+						`Agent "${params.resume as string}" had its session released after its retention window; resume is unavailable, but its result is still retrievable via get_subagent_result.`,
+					);
+				}
+				return textResult(
+					`Agent "${params.resume as string}" has no active session to resume.`,
+				);
+			}
+			let record: Subagent | undefined;
+			try {
+				record = await this.manager.resume(
+					params.resume as string,
+					params.prompt as string,
+					{ kind: "resume", source: "tool", toolCallId },
+					{
+						maxTurns: config.execution.effectiveMaxTurns,
+						wrapUpTurns: config.execution.effectiveWrapUpTurns,
+						maxDurationSeconds: config.execution.effectiveMaxDurationSeconds,
+					},
+					signal,
+				);
+			} catch (err) {
+				return textResult(
+					`Failed to resume agent "${params.resume as string}": ${err instanceof Error ? err.message : String(err)}`,
+				);
+			}
+			if (!record) {
+				return textResult(`Failed to resume agent "${params.resume as string}".`);
+			}
+			// Resume-return delivery edge: the resumed outcome is returned directly.
+			record.markConsumed();
+			return textResult(
+				record.result?.trim() ?? record.error?.trim() ?? "No output.",
+				buildDetails(config.presentation.detailBase, 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 = buildTypeListText(this.registry, this.agentDir);
+		const availableTypesText = this.registry.getAvailableTypes().join(", ");
+		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.",
+			...buildAgentGuidelines(this.registry),
+			"- Provide clear, detailed prompts so the agent can work autonomously.",
+			"- Subagent results are returned as text — summarize them for the user.",
+			"- Use run_in_background for work you don't need immediately. You will be notified when it completes.",
+			"- Use resume with an agent ID to continue a previous agent's work.",
+			"- Use steer_subagent to send mid-run messages to a running background agent.",
+			'- 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: "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: off, minimal, low, medium, high, xhigh. Overrides agent default.",
+					}),
+				),
+				max_turns: Type.Optional(
+					Type.Integer({
+						description:
+							"Maximum number of agentic turns before the hard stop. Caps the configured default; cannot raise it.",
+						minimum: 1,
+					}),
+				),
+				wrap_up_turns: Type.Optional(
+					Type.Integer({
+						description:
+							"Turns reserved for wrap-up before the hard stop. Overrides the configured wrap-up budget but stays below max_turns. Omit to use the agent/global value.",
+						minimum: 0,
+					}),
+				),
+				max_duration_seconds: Type.Optional(
+					Type.Integer({
+						description:
+							"Maximum agent runtime in seconds. Caps the configured default; cannot raise it.",
+						minimum: 1,
+					}),
+				),
+				run_in_background: Type.Optional(
+					Type.Boolean({
+						description:
+							"Set to true to run in background. Returns agent ID immediately. You will be notified when it completes.",
+					}),
+				),
+				resume: Type.Optional(
+					Type.String({
+						description: "Optional agent ID to resume from. Continues from previous 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: Theme) {
+				const displayName = args.subagent_type
+					? getDisplayName(args.subagent_type as string, registry)
+					: "Subagent";
+				const desc = (args.description as string | undefined) ?? "";
+				return new Text(
+					`${GLYPHS.toolCall} ` +
+						theme.fg("toolTitle", theme.bold(displayName)) +
+						(desc ? "  " + theme.fg("muted", desc) : ""),
+					0,
+					0,
+				);
+			},
+
+			renderResult(
+				result: AgentToolResult<AgentDetails | undefined>,
+				{ expanded, isPartial }: ToolRenderResultOptions,
+				theme: Theme,
+			) {
+				const details = result.details;
+				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,
+				);
+			},
+
+			execute: (
+				toolCallId: string,
+				params: Record<string, unknown>,
+				signal: AbortSignal | undefined,
+				onUpdate: ((update: AgentToolResult<AgentDetails>) => void) | undefined,
+				ctx: ExtensionContext,
+			) => this.execute(toolCallId, params, signal, onUpdate, ctx),
+		});
+	}
+}

package/src/tools/background-spawner.ts

@@ -0,0 +1,73 @@
+import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
+import type { AgentSpawnConfig } from "#src/lifecycle/subagent-manager";
+import { textResult } from "#src/tools/helpers";
+import type { ResolvedSpawnConfig } from "#src/tools/spawn-config";
+import type { ParentSessionInfo, Subagent } from "#src/types";
+
+/** Narrow manager interface for the background spawner. */
+export interface BackgroundManagerDeps {
+  spawn(snapshot: ParentSnapshot, type: string, prompt: string, opts: AgentSpawnConfig): string;
+  getRecord(id: string): Subagent | undefined;
+}
+
+/** All values the background spawner needs beyond the resolved config. */
+export interface BackgroundParams {
+  config: ResolvedSpawnConfig;
+  snapshot: ParentSnapshot;
+  parentSession: ParentSessionInfo;
+  settings: { readonly maxConcurrent: number };
+}
+
+/**
+ * Spawn a background agent and return the tool result immediately.
+ * Owns: launch message formatting.
+ */
+export function spawnBackground(
+  manager: BackgroundManagerDeps,
+  params: BackgroundParams,
+) {
+  const { identity, execution, presentation } = params.config;
+
+  let id: string;
+  try {
+    id = manager.spawn(params.snapshot, identity.subagentType, execution.prompt, {
+      parentSession: params.parentSession,
+      description: execution.description,
+      model: execution.model,
+      maxTurns: execution.effectiveMaxTurns,
+      wrapUpTurns: execution.effectiveWrapUpTurns,
+      maxDurationSeconds: execution.effectiveMaxDurationSeconds,
+      inheritContext: execution.inheritContext,
+      thinkingLevel: execution.thinking,
+      isBackground: true,
+      invocation: execution.agentInvocation,
+    });
+  } catch (err) {
+    return textResult(err instanceof Error ? err.message : String(err));
+  }
+
+  const record = manager.getRecord(id);
+
+  const isQueued = record?.phase === "queued";
+  return textResult(
+    `Agent ${isQueued ? "queued" : "started"} in background.\n` +
+      `Agent ID: ${id}\n` +
+      `Type: ${identity.displayName}\n` +
+      `Description: ${execution.description}\n` +
+      (record?.outputFile ? `Output file: ${record.outputFile}\n` : "") +
+      (isQueued
+        ? `Position: queued (max ${params.settings.maxConcurrent} concurrent)\n`
+        : "") +
+      `\nYou will be notified when this agent completes.\n` +
+      `Use get_subagent_result to retrieve full results, or steer_subagent to send it messages.\n` +
+      `Do not duplicate this agent's work.`,
+    {
+      ...presentation.detailBase,
+      toolUses: 0,
+      tokens: "",
+      durationMs: 0,
+      phase: "background" as const,
+      agentId: id,
+    },
+  );
+}

package/src/tools/foreground-runner.ts

@@ -0,0 +1,135 @@
+import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
+import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
+import type { AgentSpawnConfig } from "#src/lifecycle/subagent-manager";
+import {
+  buildDetails,
+  formatLifetimeTokens,
+  getOutcomeNote,
+  textResult,
+} from "#src/tools/helpers";
+import type { ResolvedSpawnConfig } from "#src/tools/spawn-config";
+import type { ParentSessionInfo, Subagent } from "#src/types";
+import { type AgentDetails, describeActivity, formatMs } from "#src/ui/display";
+import { SPINNER } from "#src/ui/glyphs";
+
+/** Narrow manager interface for the foreground runner. */
+export interface ForegroundManagerDeps {
+  spawnAndWait(
+    snapshot: ParentSnapshot,
+    type: string,
+    prompt: string,
+    opts: Omit<AgentSpawnConfig, "isBackground">,
+  ): Promise<Subagent>;
+}
+
+/** All values the foreground runner needs beyond the resolved config. */
+export interface ForegroundParams {
+  config: ResolvedSpawnConfig;
+  snapshot: ParentSnapshot;
+  parentSession: ParentSessionInfo;
+}
+
+/**
+ * Run an agent synchronously in the foreground, streaming spinner updates.
+ * Owns: spinner interval, streaming onUpdate callbacks, cleanup, and result formatting.
+ */
+export async function runForeground(
+  manager: ForegroundManagerDeps,
+  params: ForegroundParams,
+  signal: AbortSignal | undefined,
+  onUpdate: ((update: AgentToolResult<AgentDetails>) => void) | undefined,
+) {
+  const { identity, execution, presentation } = params.config;
+  let spinnerFrame = 0;
+  const startedAt = Date.now();
+
+  let recordRef: Subagent | undefined;
+
+  const streamUpdate = () => {
+    const toolUses = recordRef?.toolUses ?? 0;
+    const details: AgentDetails = {
+      ...presentation.detailBase,
+      toolUses,
+      tokens: recordRef ? formatLifetimeTokens(recordRef) : "",
+      // Read activity off the record; fall back to safe defaults before onSessionCreated fires
+      invocationTurnCount: recordRef?.invocationTurnCount ?? 0,
+      lifetimeTurnCount: recordRef?.lifetimeTurnCount ?? 0,
+      maxTurns: recordRef?.maxTurns ?? execution.effectiveMaxTurns,
+      durationMs: Date.now() - startedAt,
+      phase: "running",
+      activity: describeActivity(
+        recordRef?.activeTools ?? new Map(),
+        recordRef?.responseText ?? "",
+      ),
+      spinnerFrame: spinnerFrame % SPINNER.length,
+    };
+    onUpdate?.({
+      content: [{ type: "text", text: `${toolUses} tool uses...` }],
+      details,
+    });
+  };
+
+  // Animate spinner at ~80ms (smooth rotation through 10 braille frames)
+  const spinnerInterval = setInterval(() => {
+    spinnerFrame++;
+    streamUpdate();
+  }, 80);
+
+  streamUpdate();
+
+  let record: Subagent;
+  try {
+    record = await manager.spawnAndWait(
+      params.snapshot,
+      identity.subagentType,
+      execution.prompt,
+      {
+        description: execution.description,
+        model: execution.model,
+        maxTurns: execution.effectiveMaxTurns,
+        wrapUpTurns: execution.effectiveWrapUpTurns,
+        maxDurationSeconds: execution.effectiveMaxDurationSeconds,
+        inheritContext: execution.inheritContext,
+        thinkingLevel: execution.thinking,
+        invocation: execution.agentInvocation,
+        signal,
+        parentSession: params.parentSession,
+        observer: {
+          onSessionCreated: (agent) => {
+            recordRef = agent;
+          },
+        },
+      },
+    );
+  } catch (err) {
+    clearInterval(spinnerInterval);
+    return textResult(err instanceof Error ? err.message : String(err));
+  }
+
+  clearInterval(spinnerInterval);
+
+  // Foreground-return delivery edge: the result is handed back in this tool
+  // result, so the outcome is collected. Mark it consumed.
+  record.markConsumed();
+
+  const tokenText = formatLifetimeTokens(record);
+  const details = buildDetails(presentation.detailBase, record, { tokens: tokenText });
+
+  const fallbackNote = identity.fellBack
+    ? `Note: Unknown agent type "${identity.rawType}" — using general-purpose.\n\n`
+    : "";
+  const agentIdentity = `Agent ID: ${record.id}\n`;
+
+  if (record.outcome === "error") {
+    return textResult(`${fallbackNote}${agentIdentity}Agent failed: ${record.error}`, details);
+  }
+
+  const durationMs = (record.completedAt ?? Date.now()) - record.startedAt;
+  const statsParts = [`${record.toolUses} tool uses`];
+  if (tokenText) statsParts.push(tokenText);
+  return textResult(
+    `${fallbackNote}${agentIdentity}Agent completed in ${formatMs(durationMs)} (${statsParts.join(", ")})${getOutcomeNote(record.outcome, record.stoppedWhileQueued)}.\n\n` +
+      (record.result?.trim() ?? "No output."),
+    details,
+  );
+}

package/src/tools/get-result-report.ts

@@ -0,0 +1,73 @@
+/**
+ * get-result-report.ts — Pure report assembly for get_subagent_result.
+ *
+ * All functions are stateless: they receive an AgentReport, returning
+ * formatted strings. No SDK types, no timers, no side effects.
+ * Consumed by GetResultTool.execute in get-result-tool.ts. Mirrors the
+ * result-renderer.ts pattern used by the subagent tool's TUI renderer.
+ */
+
+import type { SubagentOutcome, SubagentPhase } from "#src/lifecycle/subagent";
+
+/** The data a get_subagent_result report renders from — only what the formatter reads. */
+export interface AgentReport {
+	id: string;
+	displayName: string;
+	phase: SubagentPhase;
+	outcome?: SubagentOutcome;
+	toolUses: number;
+	/** Pre-formatted lifetime token total; "" when zero. */
+	tokens: string;
+	contextPercent: number | null;
+	compactionCount: number;
+	/** Pre-formatted duration string. */
+	duration: string;
+	description: string;
+	result: string | undefined;
+	error: string | undefined;
+	/** Whether the agent was stopped before the limiter ever admitted it. */
+	stoppedWhileQueued: boolean;
+	/** Present only when verbose was requested and a conversation is available. */
+	conversation?: string;
+	/** Persisted transcript path; rendered as a pointer so the parent can read it directly. */
+	transcriptPath?: string;
+}
+
+/** Assemble the stats parts: Tool uses / tokens? / Context? / Compactions? / Duration. */
+export function renderStatsParts(report: AgentReport): string[] {
+	const parts = [`Tool uses: ${report.toolUses}`];
+	if (report.tokens) parts.push(report.tokens);
+	if (report.contextPercent !== null) parts.push(`Context: ${Math.round(report.contextPercent)}%`);
+	if (report.compactionCount) parts.push(`Compactions: ${report.compactionCount}`);
+	parts.push(`Duration: ${report.duration}`);
+	return parts;
+}
+
+/** Select the per-phase/outcome body: running note, error line, or trimmed result. */
+export function renderReportBody(report: AgentReport): string {
+	if (report.phase !== "terminal")
+		return "Agent is still running. Use wait: true or check back later.";
+	if (report.outcome === "error") return `Error: ${report.error}`;
+	if (
+		report.stoppedWhileQueued &&
+		(report.outcome === "cancelled" || report.outcome === "queue_timeout")
+	)
+		return "Agent was stopped while queued and never started. No work was performed.";
+	return report.result?.trim() ?? "No output.";
+}
+
+/** Assemble the full get_subagent_result report text. */
+export function formatAgentReport(report: AgentReport): string {
+	let output =
+		`Agent: ${report.id}\n` +
+		`Type: ${report.displayName} | Status: ${report.outcome ?? report.phase} | ${renderStatsParts(report).join(" | ")}\n` +
+		`Description: ${report.description}\n\n`;
+	output += renderReportBody(report);
+	if (report.conversation) {
+		output += `\n\n--- Agent Conversation ---\n${report.conversation}`;
+	}
+	if (report.transcriptPath) {
+		output += `\n\nFull transcript available at: ${report.transcriptPath}`;
+	}
+	return output;
+}

package/src/tools/get-result-tool.ts

@@ -0,0 +1,109 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { AgentConfigLookup } from "#src/config/agent-types";
+import { type AgentReport, formatAgentReport } from "#src/tools/get-result-report";
+import { formatLifetimeTokens, textResult } from "#src/tools/helpers";
+import type { Subagent } from "#src/types";
+import { formatDuration, getDisplayName } from "#src/ui/display";
+
+// ---- Deps interfaces ----
+
+export interface GetResultToolManager {
+	getRecord(id: string): Subagent | undefined;
+}
+
+// ---- Class ----
+
+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}". Records are cleared at session start/switch, so it may be from a previous session.`);
+		}
+
+		// Wait for completion if requested. The record owns the decision of whether
+		// it is still awaitable — a queued agent counts, because scheduleVia()
+		// captures its limiter promise at spawn. A parent interrupt ends the wait
+		// without cancelling the agent, leaving the outcome uncollected below.
+		if (params.wait) {
+			await record.waitUntilSettled(signal);
+		}
+
+		// Pull-delivery edge: the parent is collecting the settled outcome here, so
+		// mark it consumed. The completion nudge scheduled by onSubagentCompleted
+		// re-reads record.consumed at fire time and suppresses itself.
+		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),
+			phase: record.phase,
+			...(record.outcome ? { outcome: record.outcome } : {}),
+			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,
+			// Transcript pointer: lets the parent read the full session from disk,
+			// and covers verbose after the live session was released (no conversation).
+			transcriptPath: record.outputFile,
+		};
+	}
+
+	toToolDefinition() {
+		return defineTool({
+			name: "get_subagent_result" as const,
+			label: "Get Agent Result",
+			promptSnippet:
+				"Check status and retrieve results from a background agent.",
+			description:
+				"Check status and retrieve results from a background agent. Use the agent ID returned by Agent with run_in_background.",
+			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),
+		});
+	}
+}