@gajae-code/coding-agent 0.2.5 → 0.3.1

package/src/tools/subagent.ts

@@ -1,7 +1,8 @@
+import * as path from "node:path";
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@gajae-code/agent-core";
 import { prompt } from "@gajae-code/utils";
 import * as z from "zod/v4";
-import { type AsyncJob, AsyncJobManager } from "../async";
+import { type AsyncJob, AsyncJobManager, type SubagentRecord } from "../async";
 import subagentDescription from "../prompts/tools/subagent.md" with { type: "text" };
 import type { AgentSource } from "../task/types";
 import { Ellipsis, truncateToWidth } from "../tui";
@@ -13,17 +14,38 @@ const DEFAULT_AWAIT_TIMEOUT_MS = 30_000;
 const MAX_AWAIT_TIMEOUT_MS = 60 * 60 * 1000;
 const DEFAULT_LIST_LIMIT = 10;
 const MAX_LIST_LIMIT = 50;
-const TEXT_PREVIEW_WIDTH = 12_000;
+const RECEIPT_PREVIEW_WIDTH = 280;
+const PREVIEW_WIDTH = 2_000;
+const FULL_PREVIEW_WIDTH = 12_000;
 
 const subagentSchema = z.object({
-	action: z.enum(["list", "inspect", "await", "cancel"]).describe("subagent control action"),
+	action: z
+		.enum(["list", "inspect", "await", "cancel", "pause", "resume", "steer"])
+		.describe("subagent control action"),
 	ids: z.array(z.string()).optional().describe("subagent ids or backing job ids"),
+	id: z.string().optional().describe("single subagent id or backing job id for resume/steer"),
+	message: z.string().optional().describe("message to deliver when resuming or steering a subagent"),
+	pause: z.boolean().optional().describe("pause after steering a currently running subagent"),
 	timeout_ms: z.number().min(0).max(MAX_AWAIT_TIMEOUT_MS).optional().describe("await timeout in milliseconds"),
 	limit: z.number().min(1).max(MAX_LIST_LIMIT).optional().describe("maximum subagents to return"),
+	verbosity: z
+		.enum(["receipt", "preview", "full"])
+		.optional()
+		.describe(
+			"output verbosity: receipt (default, <=280-char receipt preview), preview (<=2000 chars), or full (<=12000 chars; requires explicit ids)",
+		),
 });
 
 type SubagentParams = z.infer<typeof subagentSchema>;
-type SubagentStatus = "running" | "completed" | "failed" | "cancelled" | "not_found" | "already_completed";
+type SubagentStatus =
+	| "running"
+	| "paused"
+	| "queued"
+	| "completed"
+	| "failed"
+	| "cancelled"
+	| "not_found"
+	| "already_completed";
 
 export interface SubagentSnapshot {
 	id: string;
@@ -37,6 +59,9 @@ export interface SubagentSnapshot {
 	durationMs: number;
 	resultText?: string;
 	errorText?: string;
+	resultPreview?: string;
+	outputRef?: string;
+	truncated?: boolean;
 	guidance?: string;
 }
 
@@ -75,19 +100,26 @@ export class SubagentTool implements AgentTool<typeof subagentSchema, SubagentTo
 		const ownerId = this.session.getAgentId?.() ?? undefined;
 		const ownerFilter = ownerId ? { ownerId } : undefined;
 		const limit = Math.min(MAX_LIST_LIMIT, Math.max(1, Math.floor(params.limit ?? DEFAULT_LIST_LIMIT)));
+		const verbosity = params.verbosity ?? "receipt";
+		if (verbosity === "full" && (params.action === "list" || !params.ids?.length)) {
+			throw new ToolError(
+				"`verbosity=full` cannot be used with `list` and requires explicit `ids` so broad inspection cannot inline retained subagent output.",
+			);
+		}
 
 		if (params.action === "list") {
-			const jobs = this.#listSubagentJobs(manager, ownerFilter, limit);
-			return this.#buildResult(manager, jobs, { title: "Subagents" });
+			const records = this.#listSubagentRecords(manager, ownerFilter, limit);
+			return await this.#buildRecordResult(manager, records, { title: "Subagents", verbosity });
 		}
 
 		if (params.action === "inspect") {
-			const jobs = params.ids?.length
-				? this.#visibleJobsByIds(manager, params.ids, ownerId)
-				: manager.getRunningJobs(ownerFilter).filter(isSubagentJob);
-			return this.#buildResult(manager, jobs, {
+			const records = params.ids?.length
+				? this.#visibleRecordsByIds(manager, params.ids, ownerFilter)
+				: this.#runningRecords(manager, ownerFilter);
+			return await this.#buildRecordResult(manager, records, {
 				title: "Subagent inspection",
-				notFoundIds: this.#notFoundIds(manager, params.ids ?? [], ownerId),
+				notFoundIds: this.#notFoundRecordIds(manager, params.ids ?? [], ownerFilter),
+				verbosity,
 			});
 		}
 
@@ -96,48 +128,190 @@ export class SubagentTool implements AgentTool<typeof subagentSchema, SubagentTo
 			if (ids.length === 0) {
 				throw new ToolError("`cancel` requires at least one subagent id.");
 			}
-			const snapshots: SubagentSnapshot[] = [];
+			const records: SubagentRecord[] = [];
+			const missing: SubagentSnapshot[] = [];
+			for (const id of ids) {
+				const record = this.#findVisibleRecord(manager, id, ownerFilter);
+				if (!record) {
+					missing.push(this.#missingSnapshot(id, "not_found", "No visible detached subagent matches this id."));
+					continue;
+				}
+				const cancelled = manager.cancelSubagent(record.subagentId, ownerFilter);
+				if (!cancelled && record.currentJobId) manager.cancel(record.currentJobId, ownerFilter);
+				records.push(this.#findVisibleRecord(manager, id, ownerFilter) ?? record);
+			}
+			const verifiedOutputIds = await this.#verifiedOutputIds(records);
+			return this.#buildSnapshotResult(
+				[
+					...records.map(record => this.#recordSnapshot(manager, record, false, verbosity, verifiedOutputIds)),
+					...missing,
+				],
+				"Subagent cancellation",
+			);
+		}
+
+		if (params.action === "pause") {
+			const ids = params.ids ?? [];
+			if (ids.length === 0) {
+				throw new ToolError("`pause` requires at least one subagent id.");
+			}
+			const records: SubagentRecord[] = [];
+			const missing: SubagentSnapshot[] = [];
 			for (const id of ids) {
-				const job = this.#findVisibleJob(manager, id, ownerId);
-				if (!job) {
-					snapshots.push(this.#missingSnapshot(id, "not_found", "No visible detached subagent matches this id."));
+				const record = this.#findVisibleRecord(manager, id, ownerFilter);
+				if (!record) {
+					missing.push(this.#missingSnapshot(id, "not_found", "No visible detached subagent matches this id."));
 					continue;
 				}
-				if (job.status !== "running") {
-					snapshots.push({ ...this.#snapshot(job), status: "already_completed" });
+				const result = manager.pauseSubagent(record.subagentId, ownerFilter);
+				if (!result.ok && result.reason === "not_found") {
+					missing.push(this.#missingSnapshot(id, "not_found", "No visible detached subagent matches this id."));
 					continue;
 				}
-				manager.cancel(job.id, ownerFilter);
-				snapshots.push(this.#snapshot(manager.getJob(job.id) ?? job));
+				records.push(manager.getSubagentRecord(record.subagentId, ownerFilter) ?? record);
+			}
+			const verifiedOutputIds = await this.#verifiedOutputIds(records);
+			return this.#buildSnapshotResult(
+				[
+					...records.map(record => this.#recordSnapshot(manager, record, false, verbosity, verifiedOutputIds)),
+					...missing,
+				],
+				"Subagent pause",
+			);
+		}
+
+		if (params.action === "resume") {
+			const id = this.#singleTargetId(params, "resume");
+			const records: SubagentRecord[] = [];
+			const missing: SubagentSnapshot[] = [];
+			const terminalGuidanceIds = new Set<string>();
+			const record = this.#findVisibleRecord(manager, id, ownerFilter);
+			const verifiedOutputIds = await this.#verifiedOutputIds(record ? [record] : []);
+			if (!record) {
+				missing.push(this.#missingSnapshot(id, "not_found", "No visible detached subagent matches this id."));
+			} else if (record.status === "running") {
+				records.push(record);
+			} else if (params.message === undefined && isTerminalStatus(record.status)) {
+				records.push(record);
+				terminalGuidanceIds.add(record.subagentId);
+			} else {
+				const result = manager.resumeSubagent(record.subagentId, ownerFilter, params.message);
+				if (!result.ok && result.reason === "context_unavailable") throw new ToolError("context unavailable");
+				if (!result.ok && result.reason === "not_found") {
+					missing.push(this.#missingSnapshot(id, "not_found", "No visible detached subagent matches this id."));
+				} else {
+					records.push(manager.getSubagentRecord(record.subagentId, ownerFilter) ?? record);
+				}
+			}
+
+			return this.#buildSnapshotResult(
+				[
+					...records.map(record => {
+						const snapshot = this.#recordSnapshot(manager, record, false, verbosity, verifiedOutputIds);
+						return terminalGuidanceIds.has(record.subagentId)
+							? {
+									...snapshot,
+									guidance:
+										"This subagent is terminal. Provide `message` to start a follow-up resume run from its saved context.",
+								}
+							: snapshot;
+					}),
+					...missing,
+				],
+				"Subagent resume",
+			);
+		}
+
+		if (params.action === "steer") {
+			const id = this.#singleTargetId(params, "steer");
+			const message = params.message;
+			if (message === undefined || message.trim() === "") {
+				throw new ToolError("`steer` requires a non-empty message.");
+			}
+			const records: SubagentRecord[] = [];
+			const missing: SubagentSnapshot[] = [];
+			const record = this.#findVisibleRecord(manager, id, ownerFilter);
+			const verifiedOutputIds = await this.#verifiedOutputIds(record ? [record] : []);
+			if (!record) {
+				missing.push(this.#missingSnapshot(id, "not_found", "No visible detached subagent matches this id."));
+			} else {
+				if (!record.sessionFile) throw new ToolError(`Subagent ${record.subagentId} has no session file.`);
+				if (record.status === "running") {
+					const handle = manager.getLiveHandle(record.subagentId);
+					if (!handle) throw new ToolError(`Subagent ${record.subagentId} has no live handle.`);
+					await handle.injectMessage(message, "steer");
+					if (params.pause === true) manager.pauseSubagent(record.subagentId, ownerFilter);
+				} else {
+					const result = manager.resumeSubagent(record.subagentId, ownerFilter, message);
+					if (!result.ok && result.reason === "context_unavailable") throw new ToolError("context unavailable");
+					if (!result.ok && result.reason === "not_found") {
+						missing.push(this.#missingSnapshot(id, "not_found", "No visible detached subagent matches this id."));
+					} else {
+						records.push(manager.getSubagentRecord(record.subagentId, ownerFilter) ?? record);
+					}
+				}
+				if (record.status === "running")
+					records.push(manager.getSubagentRecord(record.subagentId, ownerFilter) ?? record);
 			}
-			return this.#buildSnapshotResult(snapshots, "Subagent cancellation");
+			return this.#buildSnapshotResult(
+				[
+					...records.map(record => this.#recordSnapshot(manager, record, false, verbosity, verifiedOutputIds)),
+					...missing,
+				],
+				"Subagent steer",
+			);
 		}
 
-		return this.#awaitSubagents(manager, params, ownerId, ownerFilter, signal, onUpdate);
+		return this.#awaitSubagents(manager, params, ownerFilter, signal, onUpdate);
+	}
+
+	#singleTargetId(params: SubagentParams, action: "resume" | "steer"): string {
+		const id = params.id?.trim();
+		const ids = (params.ids ?? []).map(value => value.trim()).filter(value => value.length > 0);
+		if (id && ids.length > 0) {
+			if (ids.length === 1 && ids[0] === id) return id;
+			throw new ToolError(
+				`\`${action}\` accepts exactly one target; provide \`id\` or a single-item \`ids\`, not both.`,
+			);
+		}
+		if (id) return id;
+		if (ids.length === 1) return ids[0]!;
+		if (ids.length > 1) {
+			throw new ToolError(
+				`\`${action}\` accepts exactly one target because \`message\` is delivered to one subagent.`,
+			);
+		}
+		throw new ToolError(`\`${action}\` requires a single subagent id via \`id\`.`);
 	}
 
 	async #awaitSubagents(
 		manager: AsyncJobManager,
 		params: SubagentParams,
-		ownerId: string | undefined,
 		ownerFilter: { ownerId: string } | undefined,
 		signal: AbortSignal | undefined,
 		onUpdate: AgentToolUpdateCallback<SubagentToolDetails> | undefined,
 	): Promise<AgentToolResult<SubagentToolDetails>> {
-		const jobs = params.ids?.length
-			? this.#visibleJobsByIds(manager, params.ids, ownerId)
-			: manager.getRunningJobs(ownerFilter).filter(isSubagentJob);
-		const notFoundIds = this.#notFoundIds(manager, params.ids ?? [], ownerId);
-		if (jobs.length === 0) {
+		const records = params.ids?.length
+			? this.#visibleRecordsByIds(manager, params.ids, ownerFilter)
+			: this.#runningRecords(manager, ownerFilter);
+		const notFoundIds = this.#notFoundRecordIds(manager, params.ids ?? [], ownerFilter);
+		if (records.length === 0) {
 			const missing = notFoundIds.map(id =>
 				this.#missingSnapshot(id, "not_found", "No visible detached subagent matches this id."),
 			);
 			return this.#buildSnapshotResult(missing, "Subagent await");
 		}
 
-		const runningJobs = jobs.filter(job => job.status === "running");
+		const runningJobs = records
+			.filter(record => record.status === "running" && record.currentJobId)
+			.map(record => manager.getJob(record.currentJobId!))
+			.filter((job): job is AsyncJob => job !== undefined);
 		if (runningJobs.length === 0) {
-			return this.#buildResult(manager, jobs, { title: "Subagent await", notFoundIds });
+			return await this.#buildRecordResult(manager, records, {
+				title: "Subagent await",
+				notFoundIds,
+				verbosity: params.verbosity ?? "receipt",
+			});
 		}
 
 		const timeoutMs = Math.min(
@@ -148,10 +322,10 @@ export class SubagentTool implements AgentTool<typeof subagentSchema, SubagentTo
 		manager.watchJobs(watchedJobIds);
 		const progressTimer = onUpdate
 			? setInterval(() => {
-					onUpdate(this.#progressResult(manager, jobs));
+					onUpdate(this.#progressResult(manager, records));
 				}, 500)
 			: undefined;
-		onUpdate?.(this.#progressResult(manager, jobs));
+		onUpdate?.(this.#progressResult(manager, records));
 
 		let timedOut = false;
 		try {
@@ -176,70 +350,136 @@ export class SubagentTool implements AgentTool<typeof subagentSchema, SubagentTo
 			if (progressTimer) clearInterval(progressTimer);
 		}
 
-		return this.#buildResult(manager, jobs, { title: "Subagent await", notFoundIds, timedOut });
+		return await this.#buildRecordResult(manager, records, {
+			title: "Subagent await",
+			notFoundIds,
+			timedOut,
+			verbosity: params.verbosity ?? "receipt",
+		});
 	}
 
-	#listSubagentJobs(
+	#mergedRecords(
 		manager: AsyncJobManager,
 		ownerFilter: { ownerId: string } | undefined,
 		limit: number,
-	): AsyncJob[] {
-		const running = manager.getRunningJobs(ownerFilter).filter(isSubagentJob);
-		const recent = manager.getRecentJobs(limit, ownerFilter).filter(isSubagentJob);
-		const jobs = [...running, ...recent];
-		return this.#dedupeJobs(jobs).slice(0, limit);
+	): SubagentRecord[] {
+		const merged = [...manager.getSubagentRecords(ownerFilter)];
+		const known = new Set(merged.map(record => record.subagentId));
+		const jobs = [...manager.getRunningJobs(ownerFilter), ...manager.getRecentJobs(limit, ownerFilter)].filter(
+			isSubagentJob,
+		);
+		for (const job of jobs) {
+			const subagentId = job.metadata?.subagent?.id ?? job.id;
+			if (known.has(subagentId)) continue;
+			known.add(subagentId);
+			merged.push(this.#jobToRecord(job));
+		}
+		merged.sort((a, b) => {
+			const aJob = a.currentJobId ? manager.getJob(a.currentJobId) : undefined;
+			const bJob = b.currentJobId ? manager.getJob(b.currentJobId) : undefined;
+			return (bJob?.startTime ?? 0) - (aJob?.startTime ?? 0);
+		});
+		return merged.slice(0, limit);
 	}
 
-	#visibleJobsByIds(manager: AsyncJobManager, ids: string[], ownerId: string | undefined): AsyncJob[] {
-		const jobs: AsyncJob[] = [];
-		for (const id of ids) {
-			const job = this.#findVisibleJob(manager, id, ownerId);
-			if (job) jobs.push(job);
-		}
-		return this.#dedupeJobs(jobs);
+	#listSubagentRecords(
+		manager: AsyncJobManager,
+		ownerFilter: { ownerId: string } | undefined,
+		limit: number,
+	): SubagentRecord[] {
+		return this.#mergedRecords(manager, ownerFilter, limit);
 	}
 
-	#findVisibleJob(manager: AsyncJobManager, id: string, ownerId: string | undefined): AsyncJob | undefined {
-		const trimmedId = id.trim();
-		if (!trimmedId) return undefined;
-		const direct = manager.getJob(trimmedId);
+	#runningRecords(manager: AsyncJobManager, ownerFilter: { ownerId: string } | undefined): SubagentRecord[] {
+		return this.#mergedRecords(manager, ownerFilter, MAX_LIST_LIMIT).filter(record => record.status === "running");
+	}
+
+	/** Synthesize a record from a subagent job that has no registered SubagentRecord (backward compat). */
+	#jobToRecord(job: AsyncJob): SubagentRecord {
+		return {
+			subagentId: job.metadata?.subagent?.id ?? job.id,
+			ownerId: job.ownerId,
+			currentJobId: job.id,
+			historicalJobIds: [],
+			status: job.status,
+			sessionFile: null,
+			resumable: false,
+		};
+	}
+
+	#findSubagentJob(manager: AsyncJobManager, id: string, ownerId: string | undefined): AsyncJob | undefined {
+		const direct = manager.getJob(id);
 		if (direct && isSubagentJob(direct) && (!ownerId || direct.ownerId === ownerId)) return direct;
 		return manager
 			.getAllJobs(ownerId ? { ownerId } : undefined)
-			.find(job => isSubagentJob(job) && job.metadata?.subagent?.id === trimmedId);
+			.find(job => isSubagentJob(job) && job.metadata?.subagent?.id === id);
 	}
 
-	#notFoundIds(manager: AsyncJobManager, ids: string[], ownerId: string | undefined): string[] {
-		return ids.filter(id => !this.#findVisibleJob(manager, id, ownerId));
+	#visibleRecordsByIds(
+		manager: AsyncJobManager,
+		ids: string[],
+		ownerFilter: { ownerId: string } | undefined,
+	): SubagentRecord[] {
+		const records: SubagentRecord[] = [];
+		const seen = new Set<string>();
+		for (const id of ids) {
+			const record = this.#findVisibleRecord(manager, id, ownerFilter);
+			if (!record || seen.has(record.subagentId)) continue;
+			seen.add(record.subagentId);
+			records.push(record);
+		}
+		return records;
 	}
 
-	#dedupeJobs(jobs: AsyncJob[]): AsyncJob[] {
-		const seen = new Set<string>();
-		return jobs.filter(job => {
-			if (seen.has(job.id)) return false;
-			seen.add(job.id);
-			return true;
-		});
+	#findVisibleRecord(
+		manager: AsyncJobManager,
+		id: string,
+		ownerFilter: { ownerId: string } | undefined,
+	): SubagentRecord | undefined {
+		const trimmedId = id.trim();
+		if (!trimmedId) return undefined;
+		const direct = manager.getSubagentRecord(trimmedId, ownerFilter);
+		if (direct) return direct;
+		const byJobId = manager.getSubagentRecords(ownerFilter).find(record => record.currentJobId === trimmedId);
+		if (byJobId) return byJobId;
+		const job = this.#findSubagentJob(manager, trimmedId, ownerFilter?.ownerId);
+		return job ? this.#jobToRecord(job) : undefined;
 	}
 
-	#progressResult(manager: AsyncJobManager, jobs: AsyncJob[]): AgentToolResult<SubagentToolDetails> {
+	#notFoundRecordIds(manager: AsyncJobManager, ids: string[], ownerFilter: { ownerId: string } | undefined): string[] {
+		return ids.filter(id => !this.#findVisibleRecord(manager, id, ownerFilter));
+	}
+
+	#progressResult(manager: AsyncJobManager, records: SubagentRecord[]): AgentToolResult<SubagentToolDetails> {
 		return {
 			content: [{ type: "text", text: "" }],
-			details: { subagents: this.#snapshots(manager, jobs) },
+			details: { subagents: this.#recordSnapshots(manager, records, false, "receipt", new Set()) },
 		};
 	}
 
-	#buildResult(
+	async #buildRecordResult(
 		manager: AsyncJobManager,
-		jobs: AsyncJob[],
-		options: { title: string; notFoundIds?: string[]; timedOut?: boolean },
-	): AgentToolResult<SubagentToolDetails> {
-		const snapshots = this.#snapshots(manager, jobs, options.timedOut);
+		records: SubagentRecord[],
+		options: { title: string; notFoundIds?: string[]; timedOut?: boolean; verbosity?: SubagentParams["verbosity"] },
+	): Promise<AgentToolResult<SubagentToolDetails>> {
+		const verifiedOutputIds = await this.#verifiedOutputIds(records);
+		const snapshots = this.#recordSnapshots(
+			manager,
+			records,
+			options.timedOut,
+			options.verbosity ?? "receipt",
+			verifiedOutputIds,
+		);
 		for (const id of options.notFoundIds ?? []) {
 			snapshots.push(this.#missingSnapshot(id, "not_found", "No visible detached subagent matches this id."));
 		}
 		manager.acknowledgeDeliveries(
-			snapshots.filter(s => s.status !== "running" && s.status !== "not_found").map(s => s.jobId),
+			snapshots
+				.filter(
+					s =>
+						s.status !== "running" && s.status !== "paused" && s.status !== "queued" && s.status !== "not_found",
+				)
+				.map(s => s.jobId),
 		);
 		return this.#buildSnapshotResult(snapshots, options.title);
 	}
@@ -251,9 +491,13 @@ export class SubagentTool implements AgentTool<typeof subagentSchema, SubagentTo
 			if (snapshot.jobId !== snapshot.id) lines.push(`Job: ${snapshot.jobId}`);
 			if (snapshot.agent) lines.push(`Agent: ${snapshot.agent} (${snapshot.agentSource})`);
 			if (snapshot.description) lines.push(`Description: ${snapshot.description}`);
+			if (snapshot.outputRef) lines.push(`Output: ${snapshot.outputRef}`);
 			if (snapshot.assignment) lines.push("Assignment:", "```", snapshot.assignment, "```");
-			if (snapshot.resultText) lines.push("Result:", "```", snapshot.resultText, "```");
-			if (snapshot.errorText) lines.push("Error:", "```", snapshot.errorText, "```");
+			if (snapshot.resultPreview) {
+				lines.push(snapshot.errorText ? "Error preview:" : "Result preview:", "```", snapshot.resultPreview, "```");
+				if (snapshot.truncated)
+					lines.push("Preview truncated; use the output ref or explicit ids with `verbosity=full` for more.");
+			}
 			if (snapshot.guidance) lines.push(`Guidance: ${snapshot.guidance}`);
 			lines.push("");
 		}
@@ -263,32 +507,111 @@ export class SubagentTool implements AgentTool<typeof subagentSchema, SubagentTo
 		};
 	}
 
-	#snapshots(manager: AsyncJobManager, jobs: AsyncJob[], timedOut = false): SubagentSnapshot[] {
-		return jobs.map(job => this.#snapshot(manager.getJob(job.id) ?? job, timedOut));
+	#recordSnapshots(
+		manager: AsyncJobManager,
+		records: SubagentRecord[],
+		timedOut = false,
+		verbosity: SubagentParams["verbosity"] = "receipt",
+		verifiedOutputIds: ReadonlySet<string>,
+	): SubagentSnapshot[] {
+		return records.map(record => this.#recordSnapshot(manager, record, timedOut, verbosity, verifiedOutputIds));
+	}
+
+	#recordSnapshot(
+		manager: AsyncJobManager,
+		record: SubagentRecord,
+		timedOut = false,
+		verbosity: SubagentParams["verbosity"] = "receipt",
+		verifiedOutputIds: ReadonlySet<string>,
+	): SubagentSnapshot {
+		const job = record.currentJobId ? manager.getJob(record.currentJobId) : undefined;
+		if (job) {
+			return {
+				...this.#snapshot(job, timedOut, verbosity, verifiedOutputIds, record),
+				id: record.subagentId,
+				jobId: record.currentJobId ?? job.id,
+				status: record.status,
+			};
+		}
+		return {
+			id: record.subagentId,
+			jobId: record.currentJobId ?? record.subagentId,
+			status: record.status,
+			label: "subagent",
+			agent: "unknown",
+			agentSource: "bundled",
+			durationMs: 0,
+			...(verifiedOutputIds.has(record.subagentId) ? { outputRef: `agent://${record.subagentId}` } : {}),
+		};
 	}
 
-	#snapshot(job: AsyncJob, timedOut = false): SubagentSnapshot {
+	#snapshot(
+		job: AsyncJob,
+		timedOut = false,
+		verbosity: SubagentParams["verbosity"] = "receipt",
+		verifiedOutputIds: ReadonlySet<string>,
+		record?: SubagentRecord,
+	): SubagentSnapshot {
 		const subagent = job.metadata?.subagent;
 		const runningTimeoutGuidance =
 			timedOut && job.status === "running"
 				? "Still running after the await timeout; timeout only bounded this wait and is not a failure. Inspect progress, continue independent work, and never cancel just because an await timed out; cancel only if the subagent has actually failed, gone off-track, or become unrecoverably wrong."
 				: undefined;
+		const output = previewJobOutput(job, verbosity);
+		const outputRef = record && verifiedOutputIds.has(record.subagentId) ? `agent://${record.subagentId}` : undefined;
 		return {
 			id: subagent?.id ?? job.id,
 			jobId: job.id,
 			status: job.status,
-			label: sanitizeText(job.label),
+			label: sanitizeText(job.label, RECEIPT_PREVIEW_WIDTH),
 			agent: subagent?.agent ?? "unknown",
 			agentSource: subagent?.agentSource ?? "bundled",
 			durationMs: Math.max(0, Date.now() - job.startTime),
-			...(subagent?.description ? { description: sanitizeText(subagent.description) } : {}),
-			...(subagent?.assignment ? { assignment: sanitizeText(subagent.assignment) } : {}),
-			...(job.resultText ? { resultText: sanitizeText(job.resultText) } : {}),
-			...(job.errorText ? { errorText: sanitizeText(job.errorText) } : {}),
+			...(subagent?.description ? { description: sanitizeText(subagent.description, RECEIPT_PREVIEW_WIDTH) } : {}),
+			...(verbosity === "full" && subagent?.assignment
+				? { assignment: sanitizeText(subagent.assignment, FULL_PREVIEW_WIDTH) }
+				: {}),
+			...(output
+				? {
+						...(output.type === "error" ? { errorText: output.preview } : { resultText: output.preview }),
+						resultPreview: output.preview,
+						truncated: output.truncated,
+					}
+				: {}),
+			...(outputRef ? { outputRef } : {}),
 			...(runningTimeoutGuidance ? { guidance: runningTimeoutGuidance } : {}),
 		};
 	}
 
+	async #verifiedOutputIds(records: SubagentRecord[]): Promise<Set<string>> {
+		const ids = new Set(records.map(record => record.subagentId));
+		const dirs = this.#artifactDirsForRecords(records);
+		const verified = new Set<string>();
+		await Promise.all(
+			[...ids].map(async id => {
+				for (const dir of dirs) {
+					if (await Bun.file(path.join(dir, `${id}.md.meta.json`)).exists()) {
+						verified.add(id);
+						return;
+					}
+				}
+			}),
+		);
+		return verified;
+	}
+
+	#artifactDirsForRecords(records: SubagentRecord[]): string[] {
+		const dirs: string[] = [];
+		for (const record of records) {
+			if (!record.sessionFile) continue;
+			const dir = path.dirname(record.sessionFile);
+			if (!dirs.includes(dir)) dirs.push(dir);
+		}
+		const sessionDir = this.session.getArtifactsDir?.();
+		if (sessionDir && !dirs.includes(sessionDir)) dirs.push(sessionDir);
+		return dirs;
+	}
+
 	#missingSnapshot(id: string, status: "not_found", guidance: string): SubagentSnapshot {
 		return {
 			id,
@@ -303,10 +626,31 @@ export class SubagentTool implements AgentTool<typeof subagentSchema, SubagentTo
 	}
 }
 
+function isTerminalStatus(status: SubagentStatus): boolean {
+	return status === "completed" || status === "failed" || status === "cancelled";
+}
+
 function isSubagentJob(job: AsyncJob): boolean {
 	return job.type === "task" && job.metadata?.subagent !== undefined;
 }
 
-function sanitizeText(text: string): string {
-	return truncateToWidth(replaceTabs(text), TEXT_PREVIEW_WIDTH, Ellipsis.Unicode);
+function sanitizeText(text: string, width: number): string {
+	return truncateToWidth(replaceTabs(text), width, Ellipsis.Unicode);
+}
+
+function previewJobOutput(
+	job: AsyncJob,
+	verbosity: SubagentParams["verbosity"] = "receipt",
+): { type: "result" | "error"; preview: string; truncated: boolean } | undefined {
+	const source = job.errorText
+		? { type: "error" as const, text: job.errorText }
+		: job.resultText
+			? { type: "result" as const, text: job.resultText }
+			: undefined;
+	if (!source) return undefined;
+	const width =
+		verbosity === "full" ? FULL_PREVIEW_WIDTH : verbosity === "preview" ? PREVIEW_WIDTH : RECEIPT_PREVIEW_WIDTH;
+	const normalized = replaceTabs(source.text);
+	const preview = truncateToWidth(normalized, width, Ellipsis.Unicode);
+	return { type: source.type, preview, truncated: preview !== normalized };
 }