@gajae-code/coding-agent 0.13.2 → 0.14.0

package/src/tools/index.ts

@@ -1,6 +1,7 @@
 import type { AgentTelemetryConfig, AgentTool } from "@gajae-code/agent-core";
 import type { Model, ServiceTier, ToolChoice } from "@gajae-code/ai/core";
 import { $env, logger } from "@gajae-code/utils";
+import type { AsyncJobManager } from "../async";
 import type { PromptTemplate } from "../config/prompt-templates";
 import type { Settings } from "../config/settings";
 import type { Skill } from "../extensibility/skills";
@@ -217,6 +218,8 @@ export interface ToolSession {
 	hasForegroundBashBackgroundRequestHandler?: () => boolean;
 	/** Request that the active managed foreground bash call fold into a background job, if supported. */
 	requestForegroundBashBackground?: () => boolean;
+	/** Get the session-owned or inherited async job manager. */
+	getAsyncJobManager?: () => AsyncJobManager | undefined;
 	/** Get session ID */
 	getSessionId?: () => string | null;
 	/** Get credential-selection session identity. */
@@ -279,6 +282,11 @@ export interface ToolSession {
 	agentOutputManager?: AgentOutputManager;
 	/** Settings instance for passing to subagents */
 	settings: Settings;
+	/**
+	 * The session's REQUESTED effective agent directory, independent of the
+	 * global Settings singleton (which can be reused across sessions).
+	 */
+	getSessionAgentDir?: () => string;
 	/** Live service-tier intent of the parent session, inherited by `inherit` subagents. */
 	serviceTier?: ServiceTier;
 	/** Whether the effective subagent tier grants fast mode for a resolved provider. */

package/src/tools/job.ts

@@ -7,6 +7,7 @@ import { type AsyncJob, AsyncJobManager, isBackgroundJobSupportEnabled, jobElaps
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { Theme } from "../modes/theme/theme";
 import jobDescription from "../prompts/tools/job.md" with { type: "text" };
+import { lookupOwnedRegistration, unregisterOwnedRegistration } from "../session/terminal-abort";
 import { Ellipsis, Hasher, type RenderCache, renderStatusLine, renderTreeList, truncateToWidth } from "../tui";
 import type { ToolSession } from "./index";
 import {
@@ -100,7 +101,10 @@ export class JobTool implements AgentTool<typeof jobSchema, JobToolDetails> {
 		onUpdate?: AgentToolUpdateCallback<JobToolDetails>,
 		_context?: AgentToolContext,
 	): Promise<AgentToolResult<JobToolDetails>> {
-		const manager = AsyncJobManager.instance();
+		const manager =
+			this.session.getAsyncJobManager?.() ??
+			AsyncJobManager.forEndpoint(this.session.getSessionId?.() ?? undefined) ??
+			AsyncJobManager.instance();
 		if (!manager) {
 			return {
 				content: [{ type: "text", text: "Async execution is disabled; no background jobs are available." }],
@@ -237,7 +241,7 @@ export class JobTool implements AgentTool<typeof jobSchema, JobToolDetails> {
 		const PROGRESS_INTERVAL_MS = 500;
 		const emitProgress = () => {
 			if (!onUpdate) return;
-			const snapshot = this.#snapshotJobs(allTrackedJobs);
+			const snapshot = this.#snapshotJobs(manager, allTrackedJobs);
 			onUpdate({
 				content: [{ type: "text", text: "" }],
 				details: {
@@ -318,6 +322,7 @@ export class JobTool implements AgentTool<typeof jobSchema, JobToolDetails> {
 	}
 
 	#snapshotJobs(
+		manager: AsyncJobManager,
 		jobs: {
 			id: string;
 			type: "bash" | "task";
@@ -331,7 +336,7 @@ export class JobTool implements AgentTool<typeof jobSchema, JobToolDetails> {
 	): JobSnapshot[] {
 		const now = Date.now();
 		return jobs.map(j => {
-			const current = AsyncJobManager.instance()?.getJob(j.id);
+			const current = manager.getJob(j.id);
 			const latest = current ?? j;
 			return {
 				id: latest.id,
@@ -366,9 +371,31 @@ export class JobTool implements AgentTool<typeof jobSchema, JobToolDetails> {
 			seen.add(j.id);
 			return true;
 		});
-		const jobResults = this.#snapshotJobs(uniqueJobs);
-
-		manager.acknowledgeDeliveries(jobResults.filter(j => j.status !== "running").map(j => j.id));
+		const jobResults = this.#snapshotJobs(manager, uniqueJobs);
+
+		// Only COMPLETED/FAILED/CANCELLED jobs are terminal for ownership
+		// retirement: a paused subagent is not quiescent (settleOwnedWork
+		// cancels paused jobs before it can claim stopped_owned), so its
+		// ownership tuple must stay registered until it is actually cancelled
+		// — otherwise a scope:"owned" abort could find an empty causal set and
+		// report stopped_owned while the job remains visibly paused (review
+		// thread P2).
+		const terminalJobs = jobResults.filter(
+			j => j.status === "completed" || j.status === "failed" || j.status === "cancelled",
+		);
+		manager.acknowledgeDeliveries(terminalJobs.map(j => j.id));
+		// A terminal job whose deliveries were just acknowledged is
+		// synchronously consumed: its owned registration is settled and must
+		// not occupy the registry, otherwise the retained-policy tombstone
+		// treats it as a live policy occupant forever and its FIFO fallback can
+		// evict a genuinely running job's policy (review thread P2).
+		for (const job of terminalJobs) {
+			const generation = manager.getJob?.(job.id)?.generation;
+			if (!generation) continue;
+			// The endpoint disambiguates concurrent sessions' same job ids (review P1).
+			const registration = lookupOwnedRegistration(job.id, generation, this.session.getSessionId?.() ?? "local");
+			if (registration) unregisterOwnedRegistration(registration);
+		}
 
 		const completed = jobResults.filter(j => j.status !== "running");
 		const running = jobResults.filter(j => j.status === "running");

package/src/tools/monitor.ts

@@ -4,6 +4,7 @@ import * as z from "zod/v4";
 import { AsyncJobManager, isBackgroundJobSupportEnabled } from "../async";
 import monitorDescription from "../prompts/tools/monitor.md" with { type: "text" };
 import { truncateTail } from "../session/streaming-output";
+import { lookupOwnedRegistration } from "../session/terminal-abort";
 import { BashTool } from "./bash";
 import type { ToolSession } from "./index";
 import { ToolError } from "./tool-errors";
@@ -106,13 +107,20 @@ export class MonitorTool implements AgentTool<typeof monitorSchema, MonitorToolD
 	}
 
 	async execute(
-		_toolCallId: string,
+		toolCallId: string,
 		params: MonitorParams,
 		_signal?: AbortSignal,
 		_onUpdate?: AgentToolUpdateCallback<MonitorToolDetails>,
 		context?: AgentToolContext,
 	): Promise<AgentToolResult<MonitorToolDetails>> {
-		const manager = AsyncJobManager.instance();
+		// The session's ENDPOINT-owned manager first: the monitor job is created
+		// in it, its generation is read from it, and non-persistent cancel must
+		// stop that exact job — the process-global instance may belong to a
+		// different concurrent top-level session (review thread P1).
+		const manager =
+			this.session.getAsyncJobManager?.() ??
+			AsyncJobManager.forEndpoint(this.session.getSessionId?.() ?? undefined) ??
+			AsyncJobManager.instance();
 		if (!manager) {
 			throw new ToolError("Async execution is disabled; the monitor tool is unavailable in this session.");
 		}
@@ -169,8 +177,38 @@ export class MonitorTool implements AgentTool<typeof monitorSchema, MonitorToolD
 			const suffix = count > 0 ? `\n(+${count} earlier lines)` : "";
 			const notificationLine = formatMonitorNotificationLine(line);
 			const content = `<task-notification>\nMonitor task ${jobId} (${params.kind}: ${params.description}) emitted latest state:\n${notificationLine.content}${suffix}\n</task-notification>`;
+			// Route the notification through the SAME owned-completion envelope
+			// and fresh-admission path as async results: a scope:"turn" abort
+			// that left this monitor running must resume the agent with a FRESH
+			// lineage (never the aborted attempt's), and scope:"owned" must drop
+			// it. The envelope is built from the tool-call lineage binding and
+			// the exact registered tuple; monitors without a registration stay
+			// ordinary. The standalone generation is NOT persisted — it lives in
+			// the envelope, which INTERNAL_DETAILS_FIELDS strips (review threads
+			// P1/P2).
+			const generation = manager.getJob(jobId)?.generation;
+			// Build the envelope from the RETAINED registration (which carries the
+			// complete lineage tuple), not the tool-call binding: the binding map
+			// is separately bounded and can evict a long-lived monitor's entry,
+			// but the registration keeps the lineage for owned classification
+			// (review thread P2).
+			// The lookup is ENDPOINT-scoped to THIS monitor's session: concurrent
+			// sessions have monitors with the same manager-local job id, and an
+			// endpoint-less fallback scan could attach a foreign session's
+			// registration (review thread P2).
+			const registration = generation
+				? lookupOwnedRegistration(jobId, generation, this.session.getSessionId?.() ?? "local")
+				: undefined;
+			const ownedCompletion = registration
+				? {
+						lineageIdHash: registration.lineageIdHash,
+						promptAttemptEpoch: registration.promptAttemptEpoch,
+						registration,
+					}
+				: undefined;
 			const details = {
 				taskId: jobId,
+				...(ownedCompletion ? { ownedCompletions: [ownedCompletion] } : {}),
 				kind: params.kind,
 				description: params.description,
 				monitor: true,
@@ -219,6 +257,7 @@ export class MonitorTool implements AgentTool<typeof monitorSchema, MonitorToolD
 				ownerId,
 				label,
 				ctx: context,
+				toolCallId,
 				shouldAcceptRawLine: () => !controller.closed,
 				lifecycle: {
 					onCancel: () => closeMonitor("purge"),

package/src/tools/skill-discovery.ts

@@ -1,7 +1,11 @@
 import type { AgentTool, AgentToolResult } from "@gajae-code/agent-core";
 import { prompt, untilAborted } from "@gajae-code/utils";
 import * as z from "zod/v4";
-import { discoverRuntimeSkills, type RuntimeSkillDiscoveryCandidate } from "../extensibility/runtime-skill-discovery";
+import {
+	describeDisabledSkillScopes,
+	discoverRuntimeSkills,
+	type RuntimeSkillDiscoveryCandidate,
+} from "../extensibility/runtime-skill-discovery";
 import skillDiscoveryDescription from "../prompts/tools/skill-discovery.md" with { type: "text" };
 import type { ToolSession } from ".";
 
@@ -23,11 +27,18 @@ export interface SkillDiscoveryToolDetails {
 	count: number;
 	/**
 	 * Present only when zero candidates were returned AND discovery config gates
-	 * (`skills.enabled` / `skills.enablePiProject` / `skills.enablePiUser`)
+	 * (`skills.enabled` / `skills.trustProjectSkills` / `skills.trustUserSkills`)
 	 * prevented some or all of the requested scope from being searched. Without
 	 * this, a disabled config is indistinguishable from "no skills exist".
 	 */
 	notice?: string;
+	/**
+	 * Human-readable diagnostics for skills that were scanned but not
+	 * advertised (protected-name collisions with bundled workflow skills,
+	 * include/ignore/disable policy filters, invalid frontmatter, shadowing,
+	 * scan failures). Bounded; empty when nothing was filtered.
+	 */
+	diagnostics?: string[];
 }
 
 export class SkillDiscoveryTool implements AgentTool<typeof skillDiscoverySchema, SkillDiscoveryToolDetails> {
@@ -65,16 +76,20 @@ export class SkillDiscoveryTool implements AgentTool<typeof skillDiscoverySchema
 	): Promise<AgentToolResult<SkillDiscoveryToolDetails>> {
 		return untilAborted(signal, async () => {
 			const source = input.source ?? "all";
-			const candidates = await discoverRuntimeSkills({
+			const result = await discoverRuntimeSkills({
 				cwd: this.#session.cwd,
 				query: input.query,
 				source,
 				limit: input.limit,
 				policy: this.#getRuntimeSkillPolicy(),
 			});
-			const details: SkillDiscoveryToolDetails = { candidates, count: candidates.length };
-			if (candidates.length === 0) {
-				const notice = this.#disabledPolicyNotice(source);
+			const details: SkillDiscoveryToolDetails = {
+				candidates: result.candidates,
+				count: result.candidates.length,
+			};
+			if (result.diagnostics.messages.length > 0) details.diagnostics = result.diagnostics.messages;
+			if (result.candidates.length === 0) {
+				const notice = describeDisabledSkillScopes(source, this.#getRuntimeSkillPolicy());
 				if (notice) details.notice = notice;
 			}
 			return {
@@ -83,27 +98,4 @@ export class SkillDiscoveryTool implements AgentTool<typeof skillDiscoverySchema
 			};
 		});
 	}
-
-	/**
-	 * Explain an empty result that is caused by disabled discovery config rather
-	 * than by an actually empty skill catalog.
-	 */
-	#disabledPolicyNotice(source: "all" | "project" | "user"): string | undefined {
-		const policy = this.#getRuntimeSkillPolicy();
-		if (policy.enabled !== true) {
-			return "Runtime skill discovery is disabled: `skills.enabled` is false, so no skill directories were searched. Enable it with `gjc config set skills.enabled true` (project and user scopes additionally require `skills.enablePiProject` / `skills.enablePiUser`).";
-		}
-		const skipped: string[] = [];
-		const commands: string[] = [];
-		if ((source === "all" || source === "project") && policy.enablePiProject !== true) {
-			skipped.push("project (`skills.enablePiProject` is false)");
-			commands.push("`gjc config set skills.enablePiProject true`");
-		}
-		if ((source === "all" || source === "user") && policy.enablePiUser !== true) {
-			skipped.push("user (`skills.enablePiUser` is false)");
-			commands.push("`gjc config set skills.enablePiUser true`");
-		}
-		if (skipped.length === 0) return undefined;
-		return `Skill discovery skipped disabled scope(s): ${skipped.join(", ")}. Enable them with ${commands.join(" and ")}.`;
-	}
 }

package/src/tools/subagent.ts

@@ -1,6 +1,6 @@
 import * as path from "node:path";
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@gajae-code/agent-core";
-import { prompt } from "@gajae-code/utils";
+import { formatDuration, logger, prompt } from "@gajae-code/utils";
 import * as z from "zod/v4";
 import { type AsyncJob, AsyncJobManager, jobElapsedMs, type SubagentRecord } from "../async";
 import subagentDescription from "../prompts/tools/subagent.md" with { type: "text" };
@@ -12,6 +12,15 @@ import { ToolError } from "./tool-errors";
 
 const DEFAULT_AWAIT_TIMEOUT_MS = 30_000;
 const MAX_AWAIT_TIMEOUT_MS = 60 * 60 * 1000;
+/**
+ * Bounded cadence for await liveness: even when the rendered-state signature is
+ * stable (a running subagent emitting no new progress), the await panel re-emits
+ * so a healthy wait never looks like a hung session (issue #4465). Derived from
+ * `heartbeat_ms` so callers keep one knob, floor-bounded so a small heartbeat
+ * cannot turn liveness into transcript spam, and injected for tests.
+ */
+const AWAIT_LIVENESS_MULTIPLIER = 30;
+const AWAIT_LIVENESS_MIN_INTERVAL_MS = 15_000;
 const DEFAULT_LIST_LIMIT = 10;
 const MAX_LIST_LIMIT = 50;
 const RECEIPT_PREVIEW_WIDTH = 280;
@@ -123,6 +132,22 @@ export class SubagentTool implements AgentTool<typeof subagentSchema, SubagentTo
 	readonly parameters = subagentSchema;
 	readonly strict = true;
 	readonly loadMode = "discoverable";
+	/**
+	 * Injected monotonic clock for await-liveness tests. Production callers leave
+	 * this undefined and the await falls back to `Date.now`; tests substitute a
+	 * virtual clock so a 15s+ liveness interval is exercised without any real
+	 * multi-minute sleep (#4465).
+	 */
+	#livenessNowMs?: () => number;
+
+	/** Test-only seam: substitute the liveness clock. Returns a restore function. */
+	withLivenessClock(nowMs: () => number): () => void {
+		const prior = this.#livenessNowMs;
+		this.#livenessNowMs = nowMs;
+		return () => {
+			this.#livenessNowMs = prior;
+		};
+	}
 
 	constructor(private readonly session: ToolSession) {
 		this.description = prompt.render(subagentDescription);
@@ -135,7 +160,16 @@ export class SubagentTool implements AgentTool<typeof subagentSchema, SubagentTo
 		onUpdate?: AgentToolUpdateCallback<SubagentToolDetails>,
 		_context?: AgentToolContext,
 	): Promise<AgentToolResult<SubagentToolDetails>> {
-		const manager = AsyncJobManager.instance();
+		// The session's ENDPOINT-owned manager first: concurrent top-level
+		// sessions register their manager under their endpoint (sdk/session.ts),
+		// so list/pause/resume/message/cancel/await must inspect THIS session's
+		// manager — the process-global instance belongs to the last-created
+		// session, where this session's subagent records and jobs are absent
+		// or belong to a same-id subagent of another session (review thread P1).
+		const manager =
+			this.session.getAsyncJobManager?.() ??
+			AsyncJobManager.forEndpoint(this.session.getSessionId?.() ?? undefined) ??
+			AsyncJobManager.instance();
 		if (!manager) {
 			return {
 				content: [{ type: "text", text: "No subagent manager is available in this session." }],
@@ -241,7 +275,7 @@ export class SubagentTool implements AgentTool<typeof subagentSchema, SubagentTo
 				records.push(record);
 				terminalGuidanceIds.add(record.subagentId);
 			} else {
-				const result = manager.resumeSubagent(record.subagentId, ownerFilter, params.message);
+				const result = manager.resumeSubagent(record.subagentId, ownerFilter, params.message, _toolCallId);
 				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."));
@@ -293,7 +327,7 @@ export class SubagentTool implements AgentTool<typeof subagentSchema, SubagentTo
 					records.push(manager.getSubagentRecord(record.subagentId, ownerFilter) ?? record);
 					steerStates.set(record.subagentId, "queued");
 				} else {
-					const result = manager.resumeSubagent(record.subagentId, ownerFilter, message);
+					const result = manager.resumeSubagent(record.subagentId, ownerFilter, message, _toolCallId);
 					if (!result.ok && result.reason === "not_found") {
 						missing.push(this.#missingSnapshot(id, "not_found", "No visible detached subagent matches this id."));
 					} else if (!result.ok) {
@@ -402,23 +436,71 @@ export class SubagentTool implements AgentTool<typeof subagentSchema, SubagentTo
 			});
 		}
 		const watchedJobIds = targets.map(target => target.jobId).filter((jobId): jobId is string => jobId !== null);
-		manager.watchJobs(watchedJobIds);
+		const watchHandle = manager.watchJobGenerations(watchedJobIds);
 		const heartbeatMs = params.heartbeat_ms === undefined ? 500 : params.heartbeat_ms;
+		// Liveness interval: force a re-emit even when the rendered-state signature
+		// is stable so a healthy wait never looks like a hung session (#4465). The
+		// `#livenessNowMs` clock is injected for deterministic tests; `Date.now`
+		// is the production fallback. The interval is floor-bounded so a caller who
+		// sets a tiny `heartbeat_ms` cannot turn liveness into transcript spam.
+		const livenessIntervalMs = Math.max(AWAIT_LIVENESS_MIN_INTERVAL_MS, heartbeatMs * AWAIT_LIVENESS_MULTIPLIER);
+		const nowMs = this.#livenessNowMs ?? Date.now;
+		let lastEmitMs = nowMs();
 		let lastEmittedSignature: string | undefined;
+		let streamingDisabled = false;
+		let stopProgressTimer = (): void => {};
+		const disableStreaming = (error: unknown): void => {
+			if (streamingDisabled) return;
+			streamingDisabled = true;
+			stopProgressTimer();
+			try {
+				logger.warn("Subagent await progress update failed; streaming disabled for this wait", {
+					error: safeThrownValue(error),
+				});
+			} catch {
+				// Diagnostics must never turn a recoverable progress-channel failure
+				// into an await or process-lifecycle failure.
+			}
+		};
 		const emitIfChanged = (force: boolean): void => {
-			if (!onUpdate) return;
-			const result = this.#progressResult(manager, records, true);
-			const signature = subagentAwaitRenderedStateSignature(result.details?.subagents ?? []);
-			if (!force && signature === lastEmittedSignature) return;
-			lastEmittedSignature = signature;
-			onUpdate(result);
+			if (!onUpdate || streamingDisabled) return;
+			try {
+				const result = this.#progressResult(manager, records, true);
+				const signature = subagentAwaitRenderedStateSignature(result.details?.subagents ?? []);
+				const t = nowMs();
+				const livenessDue = force || t - lastEmitMs >= livenessIntervalMs;
+				if (!livenessDue && signature === lastEmittedSignature) return;
+				lastEmittedSignature = signature;
+				lastEmitMs = t;
+				// A TypeScript void-return callback may still be implemented by an
+				// async function. Observe its runtime result so a rejected promise or
+				// thenable cannot become an unhandled rejection outside this span.
+				const updateResult = (onUpdate as (update: AgentToolResult<SubagentToolDetails>) => unknown)(result);
+				if (isPromiseLike(updateResult)) void Promise.resolve(updateResult).catch(disableStreaming);
+			} catch (error) {
+				// The liveness timer fires outside this function's promise chain, so a
+				// throwing progress consumer would otherwise escape `setInterval` as an
+				// uncaught exception, leave the wait's cleanup unreached, and let the
+				// interval keep firing and rethrowing for the rest of the await. Retire
+				// the streaming channel instead and keep waiting: losing progress output
+				// is recoverable, losing the timer and the watch registration is not.
+				disableStreaming(error);
+			}
 		};
-		const progressTimer =
-			onUpdate && heartbeatMs > 0 ? setInterval(() => emitIfChanged(false), heartbeatMs) : undefined;
-		emitIfChanged(true);
+		// The initial emission and the timer own process-lifetime resources together
+		// with the watch registration and the terminal-wait handle, so they all live
+		// inside one guarded span rather than straddling it.
+		let progressTimer: Timer | undefined;
 		let waitOutcome: "completed" | "timed_out_wait" | "interrupted";
 		let onAbort: (() => void) | undefined;
+		let terminalJobIds: string[] | undefined;
 		try {
+			progressTimer = onUpdate && heartbeatMs > 0 ? setInterval(() => emitIfChanged(false), heartbeatMs) : undefined;
+			stopProgressTimer = () => {
+				if (progressTimer) clearInterval(progressTimer);
+				progressTimer = undefined;
+			};
+			emitIfChanged(true);
 			const abortPromise = new Promise<"interrupted">(resolve => {
 				onAbort = () => resolve("interrupted");
 				if (signal?.aborted) onAbort();
@@ -432,14 +514,16 @@ export class SubagentTool implements AgentTool<typeof subagentSchema, SubagentTo
 							Bun.sleep(timeoutMs).then(() => "timed_out_wait" as const),
 							abortPromise,
 						]);
+			if (waitOutcome === "completed") {
+				terminalJobIds = (await handle.result).terminalJobIds;
+				handle.acknowledge(terminalJobIds);
+			}
 		} finally {
 			if (signal && onAbort) signal.removeEventListener("abort", onAbort);
-			if (progressTimer) clearInterval(progressTimer);
+			stopProgressTimer();
+			watchHandle.close();
+			handle.close();
 		}
-		const waitResult = waitOutcome === "completed" ? await handle.result : undefined;
-		if (waitOutcome === "completed") handle.acknowledge(waitResult?.terminalJobIds);
-		manager.unwatchJobs(watchedJobIds);
-		handle.close();
 		const awaitOutcome: SubagentAwaitOutcome =
 			waitOutcome === "completed" ? "completed" : waitOutcome === "timed_out_wait" ? "timed_out" : "interrupted";
 		const finalRecords = this.#visibleRecordsByIds(
@@ -456,7 +540,7 @@ export class SubagentTool implements AgentTool<typeof subagentSchema, SubagentTo
 			awaitOutcome,
 			waitOutcome,
 			condition,
-			terminalIds: waitResult?.terminalJobIds,
+			terminalIds: terminalJobIds,
 		});
 	}
 
@@ -558,11 +642,10 @@ export class SubagentTool implements AgentTool<typeof subagentSchema, SubagentTo
 		records: SubagentRecord[],
 		attachLiveProgress = false,
 	): AgentToolResult<SubagentToolDetails> {
+		const subagents = this.#recordSnapshots(manager, records, false, "receipt", new Set(), attachLiveProgress);
 		return {
-			content: [{ type: "text", text: "" }],
-			details: {
-				subagents: this.#recordSnapshots(manager, records, false, "receipt", new Set(), attachLiveProgress),
-			},
+			content: [{ type: "text", text: awaitProgressSummary(subagents) }],
+			details: { subagents },
 		};
 	}
 
@@ -810,6 +893,41 @@ export class SubagentTool implements AgentTool<typeof subagentSchema, SubagentTo
 	}
 }
 
+/**
+ * Human-readable line for streamed `await` progress.
+ *
+ * Consumers that render structured content (ACP) previously received an empty
+ * text block here, which made `extractStructuredText` fail and the mapper fall
+ * back to serializing the whole result object as the human-readable content. A
+ * real sentence keeps the elapsed time legible there and in any log that only
+ * shows tool text.
+ */
+function awaitProgressSummary(subagents: readonly SubagentSnapshot[]): string {
+	const waiting = subagents.filter(snapshot => !isTerminalStatus(snapshot.status));
+	if (waiting.length === 0) return "";
+	// Accumulate rather than spreading into Math.max: explicit `ids` are not
+	// capped by MAX_LIST_LIMIT, so a large await would hit the argument limit.
+	let longestMs = 0;
+	for (const snapshot of waiting) if (snapshot.durationMs > longestMs) longestMs = snapshot.durationMs;
+	return `Awaiting ${waiting.length} subagent(s) for ${formatDuration(longestMs)}: ${waiting
+		.map(snapshot => snapshot.id)
+		.join(", ")}`;
+}
+
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+	if ((typeof value !== "object" || value === null) && typeof value !== "function") return false;
+	return typeof (value as { then?: unknown }).then === "function";
+}
+
+function safeThrownValue(error: unknown): string {
+	try {
+		if (error instanceof Error) return error.message;
+		return String(error);
+	} catch {
+		return "[unprintable thrown value]";
+	}
+}
+
 function isTerminalStatus(status: SubagentStatus): boolean {
 	return status === "completed" || status === "failed" || status === "cancelled";
 }

package/src/tools/todo-contract.ts

@@ -50,6 +50,8 @@ const TODO_OP_KEYS = new Set(["op", "list", "task", "phase", "items", "text"]);
 const TODO_INIT_ENTRY_KEYS = new Set(["phase", "items"]);
 /** `content` is accepted only as a synonym the schema rewrites to `task`. */
 const TODO_OP_KEYS_WITH_ALIASES = new Set([...TODO_OP_KEYS, "content"]);
+const MAX_REJECTED_KEYS = 8;
+const POSITIONAL_HANDLE_KEYS = new Set(["id", "ids", "index", "taskId", "task_id"]);
 
 /**
  * Exact key corrections. `note` is the one repeatable confusion: it is an `op`
@@ -60,11 +62,27 @@ const TODO_OP_KEYS_WITH_ALIASES = new Set([...TODO_OP_KEYS, "content"]);
  * an entry here when the replacement is unambiguous — never from fuzzy or
  * edit-distance matching, because a wrong suggestion costs more turns than no
  * suggestion.
+ *
+ * The positional-handle family (`id`, `index`, and spellings of them) is the
+ * other repeatable confusion: the tool result renders tasks as a list, so a
+ * caller assumes the list is addressable by ordinal. No op has ever taken a
+ * handle - a task is addressed by its verbatim content - and the executor
+ * already says so, but on the validated model-facing path this validator
+ * rejects the key first, so that message never gets its turn. One shared
+ * correction keeps both layers telling the same story.
  */
+const POSITIONAL_HANDLE_CORRECTION =
+	'tasks have no id or index; target a task with "task" set to its exact content, or a whole phase with "phase"';
+
 const TODO_KEY_CORRECTIONS = new Map<string, string>([
 	["note", 'note is an op, not a key; note operations require both "task" and "text"'],
 	["newTask", "there is no rename op; re-run init with the corrected list to rename a task"],
 	["tasks", 'tasks is not a key; append operations take "items"'],
+	["id", POSITIONAL_HANDLE_CORRECTION],
+	["ids", POSITIONAL_HANDLE_CORRECTION],
+	["index", POSITIONAL_HANDLE_CORRECTION],
+	["taskId", POSITIONAL_HANDLE_CORRECTION],
+	["task_id", POSITIONAL_HANDLE_CORRECTION],
 ]);
 
 function unknownKeys(value: object, allowed: Set<string>): string[] {
@@ -72,15 +90,42 @@ function unknownKeys(value: object, allowed: Set<string>): string[] {
 }
 
 function keyRejectionDetail(keys: readonly string[], location?: string): RawArgumentRejectionDetail {
-	const hints = keys.map(key => TODO_KEY_CORRECTIONS.get(key)).filter((hint): hint is string => hint !== undefined);
-	const parts = location === undefined ? hints : [location, ...hints];
-	return parts.length > 0 ? { rejectedKeys: keys, hint: parts.join("; ") } : { rejectedKeys: keys };
+	const rejectedKeys = keys.slice(0, MAX_REJECTED_KEYS);
+	// Distinct corrections only. A family that shares one correction (every
+	// positional handle) would otherwise repeat it once per rejected key and blow
+	// past the caller's hint clamp, which truncates the advice mid-sentence.
+	const hints = [
+		...new Set(
+			keys
+				.map(key => TODO_KEY_CORRECTIONS.get(key) ?? TODO_KEY_CORRECTIONS.get(key.split(".").at(-1) ?? ""))
+				.filter((hint): hint is string => hint !== undefined),
+		),
+	];
+	const omitted = keys.length - rejectedKeys.length;
+	const parts = [
+		...(location === undefined ? [] : [location]),
+		...hints,
+		...(omitted > 0 ? [`${omitted} additional rejected keys omitted`] : []),
+	];
+	return parts.length > 0 ? { rejectedKeys, hint: parts.join("; ") } : { rejectedKeys };
 }
 
 function isPlainRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+function nestedPositionalHandleKeys(entry: Record<string, unknown>): string[] {
+	const keys: string[] = [];
+	for (const alias of ["task", "content"] as const) {
+		const value = entry[alias];
+		if (!isPlainRecord(value)) continue;
+		for (const key of Object.keys(value)) {
+			if (POSITIONAL_HANDLE_KEYS.has(key)) keys.push(`${alias}.${key}`);
+		}
+	}
+	return keys;
+}
+
 /**
  * Single source of truth for todo_write pre-coercion validation. Every
  * rejection carries a code so the caller can surface an actionable correction
@@ -119,6 +164,13 @@ export function validateRawTodoArguments(arguments_: Record<string, unknown>): R
 				code: "todo-write-unknown-op-entry-key",
 				detail: keyRejectionDetail(unknownEntryKeys, location),
 			};
+		const nestedHandles = nestedPositionalHandleKeys(entry);
+		if (nestedHandles.length > 0)
+			return {
+				outcome: "reject",
+				code: "todo-write-unknown-op-entry-key",
+				detail: keyRejectionDetail(nestedHandles, location),
+			};
 		const target = entry.task ?? entry.content;
 		if ((op === "done" || op === "drop") && !target && !entry.phase) {
 			return { outcome: "reject", code: "todo-write-done-drop-requires-target", detail: { hint: location } };

package/src/tools/todo-write.ts

@@ -539,9 +539,10 @@ export class TodoWriteTool implements AgentTool<typeof todoWriteSchema, TodoWrit
 			entry => (entry.op === "done" || entry.op === "drop") && !entry.task && !entry.phase,
 		);
 		if (missingTarget) {
-			// Models reach for a positional handle here (`id: "1"`, `index: 2`). Those keys
-			// are stripped before this point, leaving a targetless op, so the message has to
-			// name the one thing that does work: the task's content, verbatim.
+			// Model-issued calls never arrive here with a positional handle (`id: "1"`,
+			// `index: 2`): raw validation rejects the key first and carries the same
+			// correction. Bridges that call execute directly (eval's callSessionTool)
+			// skip that validation, so this still has to name what actually works.
 			const errors = [
 				`Missing task or phase for ${missingTarget.op} operation. ` +
 					`Pass "task" with the task's exact content, or "phase" with the phase name; ` +