@jopqior/pi-subagents 1.0.0

package/src/tools/agent-tool.ts

@@ -0,0 +1,305 @@
+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 "@sinclair/typebox";
+import { AgentTypeRegistry } from "#src/config/agent-types";
+import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
+import type {
+	AgentSpawnConfig,
+	ResumeCallOptions,
+	ResumeOutcome,
+	ResumeRefusalReason,
+} from "#src/lifecycle/subagent-manager";
+import {
+	renderOutcomeAddenda,
+	renderOutcomeBody,
+	renderStatusNote,
+} from "#src/observation/outcome-delivery";
+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, type SpawnPresentation } from "#src/tools/spawn-config";
+import type { ParentSessionInfo, Subagent } 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, "background">) => Promise<Subagent>;
+	resume: (id: string, prompt: string, options: ResumeCallOptions) => Promise<ResumeOutcome>;
+	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 defaultMaxTurns: number | undefined;
+	readonly maxConcurrent: number;
+};
+
+// ---- 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<AgentDetails>) => void) | undefined,
+		_ctx: ExtensionContext,
+	) {
+		// 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) {
+			return this.resumeExisting(
+				params.resume as string,
+				params.prompt as string,
+				signal,
+				config.presentation.detailBase,
+			);
+		}
+
+		// ---- 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,
+		);
+	}
+
+	/**
+	 * Continue an existing agent's session with a new prompt, returning its
+	 * resumed outcome directly to the parent.
+	 */
+	private async resumeExisting(
+		id: string,
+		prompt: string,
+		signal: AbortSignal | undefined,
+		detailBase: SpawnPresentation["detailBase"],
+	) {
+		// The manager owns whether a resume happens; this door owns only how the
+		// answer is worded. Resuming commits this call to delivering the outcome,
+		// so it claims it — nothing else announces what is already being returned.
+		const outcome = await this.manager.resume(id, prompt, {
+			signal: signal ?? new AbortController().signal,
+			claimOutcome: true,
+		});
+		if (outcome.kind === "refused") {
+			return textResult(resumeRefusalMessage(outcome.reason, id));
+		}
+		const record = outcome.record;
+		// Resume-return delivery edge: the resumed outcome is returned directly.
+		record.markConsumed();
+		return textResult(
+			`Agent ID: ${record.id}${renderStatusNote(record.status)}\n\n` +
+				renderOutcomeBody(record) +
+				renderOutcomeAddenda(record),
+			buildDetails(detailBase, record),
+		);
+	}
+
+	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.",
+			"- 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, or to answer an agent that ended its turn with a question.",
+			"- 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.",
+			"- When a spawn-selection provider is registered, the subagent tool still accepts model and thinking, but the operator's choice after the call overrides those arguments and any agent locks for those two fields.",
+			"- 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. An agent that locks this field keeps its own model and says so in the result.',
+					}),
+				),
+				thinking: Type.Optional(
+					Type.String({
+						description:
+							"Thinking level: off, minimal, low, medium, high, xhigh, max. Overrides the agent's default unless the agent locks this field.",
+					}),
+				),
+				max_turns: Type.Optional(
+					Type.Number({
+						description:
+							"Maximum number of agentic turns before stopping. Omit to use the agent's own limit, or unlimited when it declares none.",
+						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. Omit to use the agent's own default.",
+					}),
+				),
+				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. Omit to use the agent's own default, which is fresh context unless it declares otherwise.",
+					}),
+				),
+			}),
+
+			// ---- 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),
+		});
+	}
+}
+
+/**
+ * The operator-facing sentence for each reason a resume is refused.
+ *
+ * Exhaustive over `ResumeRefusalReason`, so a reason added later fails to
+ * compile here rather than falling through to an attempted resume.
+ */
+function resumeRefusalMessage(refusal: ResumeRefusalReason, id: string): string {
+	switch (refusal) {
+		case "unknown-agent":
+			return `Agent not found: "${id}". Records are cleared at session start/switch, so it may be from a previous session.`;
+		case "still-running":
+			return (
+				`Agent "${id}" is still running; wait for it to finish before resuming. ` +
+				"Use steer_subagent to send it a message while it runs."
+			);
+		case "session-released":
+			return `Agent "${id}" had its session released after its retention window; resume is unavailable, but its result is still retrievable via get_subagent_result.`;
+		case "no-session":
+			return `Agent "${id}" has no active session to resume.`;
+		case "workspace-disposed":
+			return (
+				`Agent "${id}" ran in an isolated workspace that no longer ` +
+				"exists; resume is unavailable because the agent would re-enter a directory that " +
+				"has been removed. Spawn a new agent instead — the agent's result records where " +
+				"any work was saved."
+			);
+	}
+}

package/src/tools/background-spawner.ts

@@ -0,0 +1,83 @@
+import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
+import type { AgentSpawnConfig } from "#src/lifecycle/subagent-manager";
+import { renderSpawnNotes, textResult } from "#src/tools/helpers";
+import type { ResolvedSpawnConfig } from "#src/tools/spawn-config";
+import type { ParentSessionInfo, Subagent } from "#src/types";
+import type { AgentDetails } from "#src/ui/display";
+
+/** 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, notes } = 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,
+      inheritContext: execution.inheritContext,
+      thinkingLevel: execution.thinking,
+      // resolveSpawnConfig already merged the agent's frontmatter and AgentTool
+      // routed here on the result, so this door has committed.
+      background: { kind: "explicit", isBackground: true },
+    });
+  } catch (err) {
+    return textResult(err instanceof Error ? err.message : String(err));
+  }
+
+  const record = manager.getRecord(id);
+
+  const isQueued = record?.status === "queued";
+  const isAwaitingSelection = record?.awaitingSelection === true;
+  const launchVerb = isQueued ? "queued" : isAwaitingSelection ? "submitted" : "started";
+  // Annotated rather than inlined into the call: `textResult` is generic over its
+  // details, so an inline literal would define the type instead of being checked
+  // against it.
+  const details: AgentDetails = {
+    ...presentation.detailBase,
+    toolUses: 0,
+    tokens: "",
+    durationMs: 0,
+    status: "background",
+    agentId: id,
+  };
+  return textResult(
+    renderSpawnNotes(notes) +
+      `Agent ${launchVerb} 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`
+        : "") +
+      (isAwaitingSelection && !isQueued
+        ? `Awaiting model/thinking selection.\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.`,
+    details,
+  );
+}

package/src/tools/foreground-runner.ts

@@ -0,0 +1,159 @@
+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 {
+  renderOutcomeAddenda,
+  renderOutcomeBody,
+  renderRunUpdates,
+  renderStatusNote,
+  renderWorkspaceNotice,
+} from "#src/observation/outcome-delivery";
+import {
+  buildDetails,
+  formatLifetimeTokens,
+  renderSpawnNotes,
+  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, PENDING_SELECTION_ACTIVITY } 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, "background">,
+  ): 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 session creation.
+      // onStarted fires at admission, so pending selection is visible before onSessionCreated.
+      turnCount: recordRef?.turnCount ?? 1,
+      maxTurns: recordRef?.maxTurns ?? execution.effectiveMaxTurns,
+      durationMs: Date.now() - startedAt,
+      status: "running",
+      activity: recordRef?.awaitingSelection
+        ? PENDING_SELECTION_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,
+        inheritContext: execution.inheritContext,
+        thinkingLevel: execution.thinking,
+        signal,
+        parentSession: params.parentSession,
+        observer: {
+          onStarted: (agent) => {
+            recordRef = agent;
+          },
+          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 noteText = renderSpawnNotes(params.config.notes);
+
+  if (record.status === "error") {
+    // A failed run has no result text, so this return is the only carrier that
+    // can say where its workspace saved the work — or what the child flagged
+    // before the failure, which is the one place those findings survive.
+    // The transcript pointer rides here for the same reason: with no result to
+    // read, it is the parent's only route to what the child did before it died.
+    // The success branch omits it deliberately — that return carries the result.
+    // The ask-back affordance is not composed here: a failed run answers no
+    // question, so this is the addenda tail minus the one that cannot apply.
+    const transcriptLine = record.outputFile
+      ? `\nFull transcript available at: ${record.outputFile}`
+      : "";
+    return textResult(
+      `${noteText}Agent failed: ${record.error}\nAgent ID: ${record.id}${transcriptLine}` +
+        renderRunUpdates(record.runUpdates) +
+        renderWorkspaceNotice(record.workspaceNotice),
+      details,
+    );
+  }
+
+  const durationMs = (record.completedAt ?? Date.now()) - record.startedAt;
+  const statsParts = [`${record.toolUses} tool uses`];
+  if (tokenText) statsParts.push(tokenText);
+  return textResult(
+    `${noteText}Agent completed in ${formatMs(durationMs)} (${statsParts.join(", ")})${renderStatusNote(record.status)}.\n` +
+      `Agent ID: ${record.id}\n\n` +
+      renderOutcomeBody(record) +
+      renderOutcomeAddenda(record),
+    details,
+  );
+}

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

@@ -0,0 +1,119 @@
+/**
+ * get-result-renderer.ts — Pure line assembly for the get_subagent_result TUI view.
+ *
+ * All functions are stateless: they receive GetResultDetails, the report text,
+ * and a Theme, returning the pre-themed lines a BoundedLines component spends
+ * one terminal row on each. No SDK types, no timers, no side effects.
+ * Consumed by the renderResult hook in get-result-tool.ts. Mirrors the
+ * result-renderer.ts pattern used by the subagent tool's renderer.
+ */
+
+import type { SubagentStatus } from "#src/lifecycle/subagent-state";
+import { renderStatusIcon } from "#src/tools/result-renderer";
+import type { Theme } from "#src/ui/display";
+import { GLYPHS } from "#src/ui/glyphs";
+
+/** How many report lines the expanded view draws before it defers to the transcript. */
+export const MAX_EXPANDED_LINES = 50;
+
+/** How much of the result body the collapsed preview may carry into `details`. */
+export const PREVIEW_CHARS = 200;
+
+/**
+ * Compact presentation metadata for a get_subagent_result result.
+ *
+ * Deliberately excludes the result body and the conversation: `details` is
+ * serialized verbatim into the session JSONL and is never sent to the model, so
+ * carrying either would duplicate on disk what `content` already holds. The
+ * renderer reads the report text from the result's own content instead, and
+ * `preview` is bounded at `PREVIEW_CHARS` by its producer.
+ */
+export interface GetResultDetails {
+	agentId: string;
+	displayName: string;
+	status: SubagentStatus;
+	description: string;
+	toolUses: number;
+	/** Pre-formatted lifetime token total; "" when zero. */
+	tokens: string;
+	contextPercent: number | null;
+	compactionCount: number;
+	/** Pre-formatted duration string. */
+	duration: string;
+	/** First non-empty line of the result body, clipped. Never the whole result. */
+	preview?: string;
+	error?: string;
+	/** Whether the conversation was requested, so the expanded view can say where it went. */
+	verbose: boolean;
+	transcriptPath?: string;
+}
+
+/**
+ * The lines for one get_subagent_result row, in its current expansion state.
+ *
+ * Collapsed is a fixed summary built from `details` alone; expanded is the
+ * report text, capped. Neither grows with the size of the result.
+ */
+export function renderGetResultLines(
+	details: GetResultDetails,
+	reportText: string,
+	expanded: boolean,
+	theme: Theme,
+): string[] {
+	return expanded
+		? renderExpandedReport(details, reportText, theme)
+		: renderCollapsedSummary(details, theme);
+}
+
+/** Status glyph and stats, then the description and either the preview or the error. */
+function renderCollapsedSummary(details: GetResultDetails, theme: Theme): string[] {
+	const lines = [`${renderStatusIcon(details.status, theme)} ${renderStats(details, theme)}`];
+	if (details.description) lines.push(subLine(details.description, "dim", theme));
+	if (details.error) {
+		lines.push(subLine(details.error, "error", theme));
+	} else if (details.preview) {
+		lines.push(subLine(details.preview, "dim", theme));
+	}
+	return lines;
+}
+
+/** The report text capped at MAX_EXPANDED_LINES, with an indicator when lines were dropped. */
+function renderExpandedReport(
+	details: GetResultDetails,
+	reportText: string,
+	theme: Theme,
+): string[] {
+	const reportLines = reportText.split("\n");
+	const shown = reportLines.slice(0, MAX_EXPANDED_LINES);
+	const lines = shown.map((line) => theme.fg("dim", `  ${line}`));
+	const dropped = reportLines.length - shown.length;
+	if (dropped > 0) lines.push(theme.fg("muted", `  ${renderOverflowNotice(details, dropped)}`));
+	return lines;
+}
+
+/** Say how much was withheld and where the whole of it can still be read. */
+function renderOverflowNotice(details: GetResultDetails, dropped: number): string {
+	const withheld = details.verbose ? `${dropped} more lines, including the conversation` : `${dropped} more lines`;
+	const where = details.transcriptPath ? ` — full transcript at ${details.transcriptPath}` : "";
+	return `… (${withheld}${where})`;
+}
+
+/** The dim continuation line beneath the status line. */
+function subLine(text: string, color: string, theme: Theme): string {
+	return theme.fg(color, `  ${GLYPHS.subLine}  ${text}`);
+}
+
+/** Build the stats string: "Explore · 44 tool uses · 95.9k token · 9% · ⇊3 · 213.0s". */
+function renderStats(details: GetResultDetails, theme: Theme): string {
+	const parts = [details.displayName];
+	if (details.toolUses > 0) {
+		parts.push(`${details.toolUses} tool use${details.toolUses === 1 ? "" : "s"}`);
+	}
+	if (details.tokens) parts.push(details.tokens);
+	if (details.contextPercent !== null) parts.push(`${Math.round(details.contextPercent)}%`);
+	if (details.compactionCount > 0) parts.push(`${GLYPHS.compactions}${details.compactionCount}`);
+	parts.push(details.duration);
+	return parts
+		.map((part) => theme.fg("dim", part))
+		.join(" " + theme.fg("dim", "\u00B7") + " ");
+}