@gajae-code/coding-agent 0.2.4 → 0.3.0

package/src/tools/index.ts

@@ -31,6 +31,7 @@ import { BashTool } from "./bash";
 import { BrowserTool } from "./browser";
 import { CalculatorTool } from "./calculator";
 import { type CheckpointState, CheckpointTool, RewindTool } from "./checkpoint";
+import { CronCreateTool, CronDeleteTool, CronListTool } from "./cron";
 import { DebugTool } from "./debug";
 import { EvalTool } from "./eval";
 import { FindTool } from "./find";
@@ -41,6 +42,7 @@ import { HindsightRetainTool } from "./hindsight-retain";
 import { InspectImageTool } from "./inspect-image";
 import { IrcTool } from "./irc";
 import { JobTool } from "./job";
+import { MonitorTool } from "./monitor";
 import { wrapToolWithMetaNotice } from "./output-meta";
 import { ReadTool } from "./read";
 import { RecipeTool } from "./recipe";
@@ -69,6 +71,7 @@ export * from "./bash";
 export * from "./browser";
 export * from "./calculator";
 export * from "./checkpoint";
+export * from "./cron";
 export * from "./debug";
 export * from "./eval";
 export * from "./find";
@@ -80,6 +83,7 @@ export * from "./image-gen";
 export * from "./inspect-image";
 export * from "./irc";
 export * from "./job";
+export * from "./monitor";
 export * from "./read";
 export * from "./recipe";
 export * from "./render-mermaid";
@@ -164,6 +168,8 @@ export interface ToolSession {
 	getToolByName?: (name: string) => AgentTool | undefined;
 	/** Agent registry for IRC routing across live sessions. */
 	agentRegistry?: AgentRegistry;
+	/** Optional restricted bash command prefixes for read-only role agents. */
+	bashAllowedPrefixes?: string[];
 	/** Get artifacts directory for artifact:// URLs */
 	getArtifactsDir?: () => string | null;
 	/** Get the ArtifactManager backing this session (shared across parent + subagents). */
@@ -319,6 +325,10 @@ export const BUILTIN_TOOLS: Record<string, ToolFactory> = {
 	task: s => TaskTool.create(s),
 	subagent: s => new SubagentTool(s),
 	job: JobTool.createIf,
+	monitor: MonitorTool.createIf,
+	CronCreate: CronCreateTool.createIf,
+	CronList: CronListTool.createIf,
+	CronDelete: CronDeleteTool.createIf,
 	recipe: RecipeTool.createIf,
 	irc: IrcTool.createIf,
 	todo_write: s => new TodoWriteTool(s),
@@ -466,6 +476,11 @@ export async function createTools(session: ToolSession, toolNames?: string[]): P
 	const discoveryActive = effectiveDiscoveryMode !== "off";
 
 	const allTools: Record<string, ToolFactory> = { ...BUILTIN_TOOLS, ...HIDDEN_TOOLS };
+	const allToolFactoryEntries = Object.entries(allTools) as Array<[string, ToolFactory]>;
+	const allToolsByRequestName = new Map<string, [string, ToolFactory]>();
+	for (const [name, factory] of allToolFactoryEntries) {
+		allToolsByRequestName.set(name.toLowerCase(), [name, factory]);
+	}
 	const isToolAllowed = (name: string) => {
 		if (name === "goal") return goalEnabled && session.getGoalRuntime !== undefined;
 		if (goalStateToolNames.includes(name as (typeof GOAL_MODE_TOOL_NAMES)[number])) return goalEnabled;
@@ -509,10 +524,13 @@ export async function createTools(session: ToolSession, toolNames?: string[]): P
 		requestedTools.push("yield");
 	}
 
-	const filteredRequestedTools = requestedTools?.filter(name => name in allTools && isToolAllowed(name));
+	const filteredRequestedTools = requestedTools
+		?.map(name => allToolsByRequestName.get(name))
+		.filter((entry): entry is [string, ToolFactory] => entry !== undefined)
+		.filter(([name]) => isToolAllowed(name));
 	const baseEntries =
 		filteredRequestedTools !== undefined
-			? filteredRequestedTools.filter(name => name !== "resolve").map(name => [name, allTools[name]] as const)
+			? filteredRequestedTools.filter(([name]) => name !== "resolve")
 			: [
 					...Object.entries(BUILTIN_TOOLS)
 						.filter(([name]) => isToolAllowed(name))

package/src/tools/monitor.ts

@@ -0,0 +1,136 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@gajae-code/agent-core";
+import { logger, prompt } from "@gajae-code/utils";
+import * as z from "zod/v4";
+import { AsyncJobManager, isBackgroundJobSupportEnabled } from "../async";
+import monitorDescription from "../prompts/tools/monitor.md" with { type: "text" };
+import { BashTool } from "./bash";
+import type { ToolSession } from "./index";
+import { ToolError } from "./tool-errors";
+
+const monitorKindEnum = z.enum(["log", "poll", "watch", "other"]);
+
+const monitorSchema = z.object({
+	command: z
+		.string()
+		.describe(
+			"Shell command to run as a background monitor. Each stdout line is delivered as a separate task-notification event.",
+		),
+	kind: monitorKindEnum.describe(
+		"Category of monitor. 'log' tails a log file, 'poll' polls a status endpoint, 'watch' watches a directory, 'other' for arbitrary streams.",
+	),
+	description: z
+		.string()
+		.describe("Short human-readable description of what is being monitored. Appears in task listings."),
+	timeout: z
+		.number()
+		.min(1)
+		.optional()
+		.describe(
+			"Optional maximum wall-clock seconds the monitor may run before automatic shutdown. Omit for indefinite (subject to session lifetime).",
+		),
+	persistent: z
+		.boolean()
+		.optional()
+		.describe(
+			"Whether to keep the monitor running past the originating turn. Persistent monitors survive until session end or explicit kill via the background-task stop tool.",
+		),
+});
+
+export type MonitorParams = z.infer<typeof monitorSchema>;
+
+export interface MonitorToolDetails {
+	taskId: string;
+	kind: z.infer<typeof monitorKindEnum>;
+	description: string;
+	command: string;
+	persistent: boolean;
+}
+
+const MONITOR_LABEL_MAX = 120;
+
+function buildMonitorLabel(params: MonitorParams): string {
+	const base = `[monitor:${params.kind}] ${params.description}`;
+	if (base.length <= MONITOR_LABEL_MAX) return base;
+	return `${base.slice(0, MONITOR_LABEL_MAX - 3)}...`;
+}
+
+export class MonitorTool implements AgentTool<typeof monitorSchema, MonitorToolDetails> {
+	readonly name = "monitor";
+	readonly label = "Monitor";
+	readonly summary = "Start a background monitor that streams stdout lines as task notifications";
+	readonly description: string;
+	readonly parameters = monitorSchema;
+	readonly strict = true;
+	readonly loadMode = "discoverable";
+
+	constructor(private readonly session: ToolSession) {
+		this.description = prompt.render(monitorDescription);
+	}
+
+	static createIf(session: ToolSession): MonitorTool | null {
+		if (!isBackgroundJobSupportEnabled(session.settings)) return null;
+		return new MonitorTool(session);
+	}
+
+	async execute(
+		_toolCallId: string,
+		params: MonitorParams,
+		_signal?: AbortSignal,
+		_onUpdate?: AgentToolUpdateCallback<MonitorToolDetails>,
+		context?: AgentToolContext,
+	): Promise<AgentToolResult<MonitorToolDetails>> {
+		const manager = AsyncJobManager.instance();
+		if (!manager) {
+			throw new ToolError("Async execution is disabled; the monitor tool is unavailable in this session.");
+		}
+
+		const persistent = params.persistent ?? false;
+		const label = buildMonitorLabel(params);
+		const ownerId = this.session.getAgentId?.() ?? undefined;
+		const bash = new BashTool(this.session);
+		let deliveredFirstLine = false;
+		const monitorJob = await bash.startMonitorJob(
+			{ command: params.command, timeout: params.timeout },
+			{
+				ownerId,
+				label,
+				ctx: context,
+				onRawLine: (line, jobId) => {
+					if (!persistent && deliveredFirstLine) return;
+					deliveredFirstLine = true;
+					const content = `<task-notification>\nMonitor task ${jobId} (${params.kind}: ${params.description}) emitted:\n${line}\n</task-notification>`;
+					const details = { taskId: jobId, kind: params.kind, description: params.description };
+					const sendPromise = this.session.sendCustomMessage?.(
+						{ customType: "task-notification", content, display: false, attribution: "agent", details },
+						{ triggerTurn: true, deliverAs: "followUp" },
+					);
+					if (sendPromise) {
+						void sendPromise.catch(error => {
+							logger.warn("Monitor task-notification delivery failed", {
+								error: error instanceof Error ? error.message : String(error),
+							});
+						});
+					} else {
+						this.session.steer?.({ customType: "task-notification", content, details });
+					}
+					if (!persistent) {
+						manager.cancel(jobId, ownerId ? { ownerId } : undefined);
+					}
+				},
+			},
+		);
+
+		const startedText = `Monitor started · task ${monitorJob.jobId} · persistent: ${persistent}`;
+
+		return {
+			content: [{ type: "text", text: startedText }],
+			details: {
+				taskId: monitorJob.jobId,
+				kind: params.kind,
+				description: params.description,
+				command: params.command,
+				persistent,
+			},
+		};
+	}
+}

package/src/tools/subagent.ts

@@ -1,7 +1,7 @@
 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";
@@ -16,14 +16,26 @@ const MAX_LIST_LIMIT = 50;
 const TEXT_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"),
+	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"),
 });
 
 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;
@@ -77,17 +89,17 @@ export class SubagentTool implements AgentTool<typeof subagentSchema, SubagentTo
 		const limit = Math.min(MAX_LIST_LIMIT, Math.max(1, Math.floor(params.limit ?? DEFAULT_LIST_LIMIT)));
 
 		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 this.#buildRecordResult(manager, records, { title: "Subagents" });
 		}
 
 		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 this.#buildRecordResult(manager, records, {
 				title: "Subagent inspection",
-				notFoundIds: this.#notFoundIds(manager, params.ids ?? [], ownerId),
+				notFoundIds: this.#notFoundRecordIds(manager, params.ids ?? [], ownerFilter),
 			});
 		}
 
@@ -98,46 +110,146 @@ export class SubagentTool implements AgentTool<typeof subagentSchema, SubagentTo
 			}
 			const snapshots: SubagentSnapshot[] = [];
 			for (const id of ids) {
-				const job = this.#findVisibleJob(manager, id, ownerId);
-				if (!job) {
+				const record = this.#findVisibleRecord(manager, id, ownerFilter);
+				if (!record) {
 					snapshots.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 cancelled = manager.cancelSubagent(record.subagentId, ownerFilter);
+				if (!cancelled && record.currentJobId) manager.cancel(record.currentJobId, ownerFilter);
+				const updated = this.#findVisibleRecord(manager, id, ownerFilter) ?? record;
+				snapshots.push(this.#recordSnapshot(manager, updated));
+			}
+			return this.#buildSnapshotResult(snapshots, "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 snapshots: SubagentSnapshot[] = [];
+			for (const id of ids) {
+				const record = this.#findVisibleRecord(manager, id, ownerFilter);
+				if (!record) {
+					snapshots.push(this.#missingSnapshot(id, "not_found", "No visible detached subagent matches this id."));
+					continue;
+				}
+				const result = manager.pauseSubagent(record.subagentId, ownerFilter);
+				if (!result.ok && result.reason === "not_found") {
+					snapshots.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));
+				snapshots.push(
+					this.#recordSnapshot(manager, manager.getSubagentRecord(record.subagentId, ownerFilter) ?? record),
+				);
 			}
-			return this.#buildSnapshotResult(snapshots, "Subagent cancellation");
+			return this.#buildSnapshotResult(snapshots, "Subagent pause");
+		}
+
+		if (params.action === "resume") {
+			const ids = params.ids ?? [];
+			if (ids.length === 0) {
+				throw new ToolError("`resume` requires at least one subagent id.");
+			}
+			const snapshots: SubagentSnapshot[] = [];
+			for (const id of ids) {
+				const record = this.#findVisibleRecord(manager, id, ownerFilter);
+				if (!record) {
+					snapshots.push(this.#missingSnapshot(id, "not_found", "No visible detached subagent matches this id."));
+					continue;
+				}
+				if (record.status === "running") {
+					snapshots.push(this.#recordSnapshot(manager, record));
+					continue;
+				}
+				if (params.message === undefined && isTerminalStatus(record.status)) {
+					snapshots.push({
+						...this.#recordSnapshot(manager, record),
+						guidance:
+							"This subagent is terminal. Provide `message` to start a follow-up resume run from its saved context.",
+					});
+					continue;
+				}
+				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") {
+					snapshots.push(this.#missingSnapshot(id, "not_found", "No visible detached subagent matches this id."));
+					continue;
+				}
+				snapshots.push(
+					this.#recordSnapshot(manager, manager.getSubagentRecord(record.subagentId, ownerFilter) ?? record),
+				);
+			}
+			return this.#buildSnapshotResult(snapshots, "Subagent resume");
 		}
 
-		return this.#awaitSubagents(manager, params, ownerId, ownerFilter, signal, onUpdate);
+		if (params.action === "steer") {
+			const ids = params.ids ?? [];
+			const message = params.message;
+			if (ids.length === 0) {
+				throw new ToolError("`steer` requires at least one subagent id.");
+			}
+			if (message === undefined || message.trim() === "") {
+				throw new ToolError("`steer` requires a non-empty message.");
+			}
+			const snapshots: SubagentSnapshot[] = [];
+			for (const id of ids) {
+				const record = this.#findVisibleRecord(manager, id, ownerFilter);
+				if (!record) {
+					snapshots.push(this.#missingSnapshot(id, "not_found", "No visible detached subagent matches this id."));
+					continue;
+				}
+				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") {
+						snapshots.push(
+							this.#missingSnapshot(id, "not_found", "No visible detached subagent matches this id."),
+						);
+						continue;
+					}
+				}
+				snapshots.push(
+					this.#recordSnapshot(manager, manager.getSubagentRecord(record.subagentId, ownerFilter) ?? record),
+				);
+			}
+			return this.#buildSnapshotResult(snapshots, "Subagent steer");
+		}
+
+		return this.#awaitSubagents(manager, params, ownerFilter, signal, onUpdate);
 	}
 
 	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 this.#buildRecordResult(manager, records, { title: "Subagent await", notFoundIds });
 		}
 
 		const timeoutMs = Math.min(
@@ -148,10 +260,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 +288,124 @@ export class SubagentTool implements AgentTool<typeof subagentSchema, SubagentTo
 			if (progressTimer) clearInterval(progressTimer);
 		}
 
-		return this.#buildResult(manager, jobs, { title: "Subagent await", notFoundIds, timedOut });
+		return this.#buildRecordResult(manager, records, { title: "Subagent await", notFoundIds, timedOut });
 	}
 
-	#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;
+	}
+
+	#notFoundRecordIds(manager: AsyncJobManager, ids: string[], ownerFilter: { ownerId: string } | undefined): string[] {
+		return ids.filter(id => !this.#findVisibleRecord(manager, id, ownerFilter));
 	}
 
-	#progressResult(manager: AsyncJobManager, jobs: AsyncJob[]): AgentToolResult<SubagentToolDetails> {
+	#progressResult(manager: AsyncJobManager, records: SubagentRecord[]): AgentToolResult<SubagentToolDetails> {
 		return {
 			content: [{ type: "text", text: "" }],
-			details: { subagents: this.#snapshots(manager, jobs) },
+			details: { subagents: this.#recordSnapshots(manager, records) },
 		};
 	}
 
-	#buildResult(
+	#buildRecordResult(
 		manager: AsyncJobManager,
-		jobs: AsyncJob[],
+		records: SubagentRecord[],
 		options: { title: string; notFoundIds?: string[]; timedOut?: boolean },
 	): AgentToolResult<SubagentToolDetails> {
-		const snapshots = this.#snapshots(manager, jobs, options.timedOut);
+		const snapshots = this.#recordSnapshots(manager, records, options.timedOut);
 		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);
 	}
@@ -263,8 +429,29 @@ 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): SubagentSnapshot[] {
+		return records.map(record => this.#recordSnapshot(manager, record, timedOut));
+	}
+
+	#recordSnapshot(manager: AsyncJobManager, record: SubagentRecord, timedOut = false): SubagentSnapshot {
+		const job = record.currentJobId ? manager.getJob(record.currentJobId) : undefined;
+		if (job) {
+			return {
+				...this.#snapshot(job, timedOut),
+				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,
+		};
 	}
 
 	#snapshot(job: AsyncJob, timedOut = false): SubagentSnapshot {
@@ -303,6 +490,10 @@ 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;
 }