@oh-my-pi/pi-coding-agent 17.0.9 → 17.1.0

package/src/task/index.ts

@@ -187,7 +187,6 @@ function renderDescription(
 		agents: renderedAgents,
 		spawningDisabled,
 		defaultAgent: spawnPolicy.defaultAgent,
-		allowedAgentsText: spawnPolicy.allowedPromptText,
 		isolationEnabled,
 		applyIsolatedChanges,
 		batchEnabled,
@@ -531,19 +530,35 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 		if (typeof params.context === "string" && params.context.trim()) {
 			lines.push(`Context:\n${truncateForPrompt(params.context)}`);
 		}
-		const tasks = Array.isArray(params.tasks) ? params.tasks : [];
-		const firstTask = tasks[0];
-		if (firstTask) {
-			if (typeof firstTask.name === "string" && firstTask.name.trim()) {
-				lines.push(`Name: ${truncateForPrompt(firstTask.name)}`);
-			}
-			if (typeof firstTask.agent === "string" && firstTask.agent.trim()) {
-				lines.push(`Agent: ${truncateForPrompt(firstTask.agent)}`);
+		const tasks: unknown[] = Array.isArray(params.tasks) ? params.tasks : [];
+		if (tasks.length > 0) {
+			const defaultAgent = resolveSpawnPolicy(this.session.getSessionSpawns()).defaultAgent;
+			const effectiveAgent = (item: unknown): string => {
+				if (item && typeof item === "object" && "agent" in item) {
+					const agent = item.agent;
+					if (typeof agent === "string" && agent.trim()) return agent.trim();
+				}
+				return defaultAgent;
+			};
+			const agentCounts = new Map<string, number>();
+			for (const item of tasks) {
+				const agent = effectiveAgent(item);
+				agentCounts.set(agent, (agentCounts.get(agent) ?? 0) + 1);
 			}
-			const itemModel = formatModelForApproval(firstTask.model);
-			if (itemModel) lines.push(`Model: ${itemModel}`);
-			if (typeof firstTask.task === "string") {
-				lines.push(`Task:\n${truncateForPrompt(firstTask.task)}`);
+			const agentSummary = [...agentCounts].map(([agent, count]) => `${agent} ×${count}`).join(", ");
+			lines.push(`Batch agents: ${truncateForPrompt(agentSummary)}`);
+
+			const firstTask = tasks[0];
+			if (firstTask && typeof firstTask === "object") {
+				if ("name" in firstTask && typeof firstTask.name === "string" && firstTask.name.trim()) {
+					lines.push(`Name: ${truncateForPrompt(firstTask.name)}`);
+				}
+				lines.push(`Agent: ${truncateForPrompt(effectiveAgent(firstTask))}`);
+				const itemModel = formatModelForApproval("model" in firstTask ? firstTask.model : undefined);
+				if (itemModel) lines.push(`Model: ${itemModel}`);
+				if ("task" in firstTask && typeof firstTask.task === "string") {
+					lines.push(`Task:\n${truncateForPrompt(firstTask.task)}`);
+				}
 			}
 			if (tasks.length > 1) {
 				lines.push(`+${tasks.length - 1} more task${tasks.length === 2 ? "" : "s"}`);
@@ -687,27 +702,53 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 		const spawnItems = resolveSpawnItems(params);
 		const normalizedSpawnParams = spawnItems.map(item => spawnParamsFor(params, item, defaultAgent));
 		const resolvedAgents = normalizedSpawnParams.map(spawn => spawn.agent ?? defaultAgent);
+		// Resolve every item before choosing an execution path. No executor or
+		// job manager may observe a batch unless every effective policy is valid.
+		const preflights = await Promise.all(
+			normalizedSpawnParams.map(async spawn => {
+				try {
+					return { policy: await this.#resolveSpawnPreflight(spawn) };
+				} catch (error) {
+					return { error: error instanceof StructuredSubagentError ? error.message : String(error) };
+				}
+			}),
+		);
+		const preflightFailures = preflights
+			.map((preflight, index) => ("error" in preflight ? { index, error: preflight.error } : undefined))
+			.filter((failure): failure is { index: number; error: string } => failure !== undefined);
+		if (preflightFailures.length > 0) {
+			if (!batchEnabled) {
+				return createTaskModeError(`Task execution failed: ${preflightFailures[0]!.error}`);
+			}
+			return createTaskModeError(
+				preflightFailures
+					.map(({ index, error }) => {
+						const item = spawnItems[index]!;
+						return `Task ${item.name?.trim() || `#${index + 1}`} failed preflight: ${error}`;
+					})
+					.join("\n"),
+			);
+		}
+		const policies = preflights.map(preflight => preflight.policy!);
+		const itemBlocking = policies.map(policy => policy.effectiveAgent.blocking === true);
+
 		// Execution mode is per item: an item whose agent type declares
 		// `blocking: true` runs inline on this turn (the parent waits on its
 		// result); every other item becomes a background job when async
 		// execution is available.
-		const provisionalBlocking = resolvedAgents.map(
-			name => this.#discoveredAgents.find(agent => agent.name === name)?.blocking === true,
-		);
 		const asyncEnabled = this.session.settings.get("async.enabled");
 		const manager = asyncEnabled ? this.session.asyncJobManager : undefined;
-		const provisionalAsyncItems = manager ? spawnItems.filter((_, index) => !provisionalBlocking[index]) : [];
+		const asyncItems = manager ? spawnItems.filter((_, index) => !itemBlocking[index]) : [];
 		const depthCapacity = canSpawnAtDepth(
 			this.session.settings.get("task.maxRecursionDepth") ?? 2,
 			this.session.taskDepth ?? 0,
 		);
 		const ircEnabled = isIrcEnabled(this.session.settings, this.session.taskDepth ?? 0);
 
-		if (!manager || provisionalAsyncItems.length === 0) {
+		if (!manager || asyncItems.length === 0) {
 			// Sync fallback: async execution disabled, orphaned host that never
 			// wired a job manager, or every item's agent type declares
-			// `blocking: true`. `runStructuredSubagent` performs its own shared
-			// preflight before reserving an id in these inline paths.
+			// `blocking: true`.
 			if (asyncEnabled && !this.session.asyncJobManager) {
 				logger.warn("task: no AsyncJobManager registered; falling back to sync execution");
 			}
@@ -715,7 +756,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 				? undefined
 				: composeSpawnAdvisory({
 						agents: resolvedAgents,
-						items: provisionalAsyncItems,
+						items: asyncItems,
 						depthCapacity,
 						ircEnabled,
 						willRunAsync: false,
@@ -741,43 +782,13 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 			return { ...result, content };
 		}
 
-		// Async jobs are otherwise registered before their body can reach
-		// `runStructuredSubagent`. Resolve the shared policy first so policy
-		// failures remain synchronous and cannot leave a queued invalid job.
-		const preflights = await Promise.all(
-			normalizedSpawnParams.map(async spawn => {
-				try {
-					return { policy: await this.#resolveSpawnPreflight(spawn) };
-				} catch (error) {
-					return { error: error instanceof StructuredSubagentError ? error.message : String(error) };
-				}
-			}),
-		);
-		const preflightFailures = preflights
-			.map((preflight, index) => ("error" in preflight ? { index, error: preflight.error } : undefined))
-			.filter((failure): failure is { index: number; error: string } => failure !== undefined);
-		const renderPreflightFailures = () =>
-			preflightFailures
-				.map(({ index, error }) => {
-					const item = spawnItems[index]!;
-					return `Task ${item.name?.trim() || `#${index + 1}`} failed preflight: ${error}`;
-				})
-				.join("\n");
-		if (preflightFailures.length === spawnItems.length) {
-			return createTaskModeError(renderPreflightFailures());
-		}
-
-		const validIndices = preflights.flatMap((preflight, index) => (preflight.policy ? [index] : []));
-		const validSpawns = validIndices.map(index => ({ item: spawnItems[index]!, index }));
-		const itemBlocking = preflights.map(preflight => preflight.policy?.effectiveAgent.blocking === true);
-		const asyncItems = validIndices.filter(index => !itemBlocking[index]).map(index => spawnItems[index]!);
 		// Coordination only makes sense for spawns that keep running after this
 		// call returns (the async subset). Blocking items have already completed
 		// by then, so a "coordinate while they run" hint would misfire.
 		const advisory = this.session.suppressSpawnAdvisory
 			? undefined
 			: composeSpawnAdvisory({
-					agents: validIndices.map(index => resolvedAgents[index]!),
+					agents: resolvedAgents,
 					items: asyncItems,
 					depthCapacity,
 					ircEnabled,
@@ -799,24 +810,15 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 			if (!appended) content.push({ type: "text", text: advisory });
 			return { ...result, content };
 		};
-		const withPreflightFailures = (result: AgentToolResult<TaskToolDetails>): AgentToolResult<TaskToolDetails> => {
-			if (preflightFailures.length === 0) return result;
-			const failures = renderPreflightFailures();
-			let prepended = false;
-			const content = result.content.map(part => {
-				if (!prepended && part.type === "text" && typeof part.text === "string") {
-					prepended = true;
-					return { ...part, text: `${failures}\n\n${part.text}` };
-				}
-				return part;
-			});
-			if (!prepended) content.unshift({ type: "text", text: failures });
-			return { ...result, content };
-		};
 		if (asyncItems.length === 0) {
-			return withPreflightFailures(
-				withAdvisory(
-					await this.#executeSyncFanout(toolCallId, params, validSpawns, defaultAgent, signal, onUpdate),
+			return withAdvisory(
+				await this.#executeSyncFanout(
+					toolCallId,
+					params,
+					spawnItems.map((item, index) => ({ item, index })),
+					defaultAgent,
+					signal,
+					onUpdate,
 				),
 			);
 		}
@@ -836,12 +838,9 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 			blocking: boolean;
 			progress: AgentProgress;
 		}> = [];
-		for (const index of validIndices) {
-			const item = spawnItems[index]!;
+		for (const [index, item] of spawnItems.entries()) {
 			const agentType = resolvedAgents[index]!;
-			const preflight = preflights[index]!;
-			const policy = preflight.policy;
-			if (!policy) continue;
+			const policy = policies[index]!;
 			const agentSource = policy.agent.source;
 			const agentId = await outputManager.allocate(item.name?.trim() || generateTaskName());
 			const assignment = (item.task ?? "").trim();
@@ -878,7 +877,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 		// failed. Blocking spawns run inline below and land in `results` before
 		// the call returns, so post-return job updates never drop them.
 		let settledCount = 0;
-		let failedCount = preflightFailures.length;
+		let failedCount = 0;
 		let primaryJobId = asyncSpawns[0].agentId;
 		const syncResults: SingleResult[] = [];
 		let syncUsage: Usage | undefined;
@@ -928,7 +927,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 		}
 
 		if (started.length === 0 && syncSpawns.length === 0) {
-			return withPreflightFailures({
+			return {
 				content: [
 					{
 						type: "text",
@@ -936,7 +935,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 					},
 				],
 				details: { projectAgentsDir: null, results: [], totalDurationMs: 0 },
-			});
+			};
 		}
 
 		const scheduleFailureSummary =
@@ -961,34 +960,30 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 					content: [{ type: "text", text: `Spawned agent \`${agentId}\`...` }],
 					details: buildAsyncDetails(),
 				});
-				return withPreflightFailures(
-					withAdvisory({
-						content: [
-							{
-								type: "text",
-								text: `Spawned agent \`${agentId}\` (job \`${jobId}\`). Its result auto-delivers on yield unless a settled \`hub jobs\`/\`wait\` snapshot consumes it first. ${coordinationHint}`,
-							},
-						],
-						details: buildAsyncDetails(),
-					}),
-				);
-			}
-			const startedListing = started.map(({ agentId, jobId }) => `- \`${agentId}\` (job \`${jobId}\`)`).join("\n");
-			onUpdate?.({
-				content: [{ type: "text", text: `Spawned ${started.length} agents...` }],
-				details: buildAsyncDetails(),
-			});
-			return withPreflightFailures(
-				withAdvisory({
+				return withAdvisory({
 					content: [
 						{
 							type: "text",
-							text: `Spawned ${started.length} background agents using ${agentLabel}.${scheduleFailureSummary} Each result auto-delivers on yield unless a settled \`hub jobs\`/\`wait\` snapshot consumes it first.\n${startedListing}\n${coordinationHint}`,
+							text: `Spawned agent \`${agentId}\` (job \`${jobId}\`). Its result auto-delivers on yield unless a settled \`hub jobs\`/\`wait\` snapshot consumes it first. ${coordinationHint}`,
 						},
 					],
 					details: buildAsyncDetails(),
-				}),
-			);
+				});
+			}
+			const startedListing = started.map(({ agentId, jobId }) => `- \`${agentId}\` (job \`${jobId}\`)`).join("\n");
+			onUpdate?.({
+				content: [{ type: "text", text: `Spawned ${started.length} agents...` }],
+				details: buildAsyncDetails(),
+			});
+			return withAdvisory({
+				content: [
+					{
+						type: "text",
+						text: `Spawned ${started.length} background agents using ${agentLabel}.${scheduleFailureSummary} Each result auto-delivers on yield unless a settled \`hub jobs\`/\`wait\` snapshot consumes it first.\n${startedListing}\n${coordinationHint}`,
+					},
+				],
+				details: buildAsyncDetails(),
+			});
 		}
 
 		// Mixed call: the async jobs above already run detached; the blocking
@@ -1053,12 +1048,10 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 		const text = [merged.contentParts.join("\n\n"), spawnedSummary]
 			.filter(section => section.trim().length > 0)
 			.join("\n\n");
-		return withPreflightFailures(
-			withAdvisory({
-				content: [{ type: "text", text: text.length > 0 ? text : "No results." }],
-				details: buildAsyncDetails(),
-			}),
-		);
+		return withAdvisory({
+			content: [{ type: "text", text: text.length > 0 ? text : "No results." }],
+			details: buildAsyncDetails(),
+		});
 	}
 
 	/**

package/src/task/output-manager.ts

@@ -18,10 +18,11 @@ import { ADVISOR_TRANSCRIPT_STEM } from "../advisor/transcript-recorder";
  *
  * The first allocation of a given name keeps the name as-is; subsequent
  * allocations of the same name get a `-2`, `-3`, … suffix. On resume, scans
- * existing output files so previously written outputs are never overwritten.
+ * existing output and child-session files so prior state is never overwritten.
  */
 export class AgentOutputManager {
 	#initialized = false;
+	#initializing: Promise<void> | undefined;
 	/** Final ids already handed out, relative to this manager's scope. */
 	readonly #taken = new Set<string>();
 	readonly #getArtifactsDir: () => string | null;
@@ -42,8 +43,12 @@ export class AgentOutputManager {
 	 */
 	async #ensureInitialized(): Promise<void> {
 		if (this.#initialized) return;
+		this.#initializing ??= this.#seedFromDisk();
+		await this.#initializing;
 		this.#initialized = true;
+	}
 
+	async #seedFromDisk(): Promise<void> {
 		const dir = this.#getArtifactsDir();
 		if (!dir) return;
 
@@ -56,8 +61,9 @@ export class AgentOutputManager {
 
 		const prefix = this.#parentPrefix ? `${this.#parentPrefix}.` : "";
 		for (const file of files) {
-			if (!file.endsWith(".md")) continue;
-			let rest = file.slice(0, -3); // drop ".md"
+			const extension = file.endsWith(".jsonl") ? ".jsonl" : file.endsWith(".md") ? ".md" : undefined;
+			if (!extension) continue;
+			let rest = file.slice(0, -extension.length);
 			if (prefix) {
 				if (!rest.startsWith(prefix)) continue;
 				rest = rest.slice(prefix.length);
@@ -80,6 +86,22 @@ export class AgentOutputManager {
 		return this.#parentPrefix ? `${this.#parentPrefix}.${candidate}` : candidate;
 	}
 
+	/** Reserve final IDs discovered outside the output directory scan. */
+	async reserve(ids: Iterable<string>): Promise<void> {
+		await this.#ensureInitialized();
+		const prefix = this.#parentPrefix ? `${this.#parentPrefix}.` : "";
+		for (const id of ids) {
+			let rest = id;
+			if (prefix) {
+				if (!rest.startsWith(prefix)) continue;
+				rest = rest.slice(prefix.length);
+			}
+			const dot = rest.indexOf(".");
+			const segment = dot === -1 ? rest : rest.slice(0, dot);
+			if (segment) this.#taken.add(segment);
+		}
+	}
+
 	/**
 	 * Allocate a unique ID.
 	 *

package/src/task/persisted-revive.ts

@@ -71,7 +71,7 @@ export function createPersistedSubagentReviverFactory(
 			taskDepth++;
 			parentId = registry.get(parentId)?.parentId;
 		}
-		return async () => {
+		return async expectedRef => {
 			// Re-open fresh on every revive: park closes the writer, so this takes
 			// the single-writer lock cleanly and restores the full message history.
 			const reopened = await SessionManager.open(sessionFile, undefined, undefined, {
@@ -97,6 +97,7 @@ export function createPersistedSubagentReviverFactory(
 				agentDisplayName: ref.displayName,
 				parentTaskPrefix: ref.id,
 				parentAgentId: ref.parentId,
+				expectedAgentRef: expectedRef,
 				taskDepth,
 				toolNames: init.tools,
 				outputSchema: init.outputSchema,
@@ -131,8 +132,8 @@ export function createPersistedSubagentReviverFactory(
 			// Without it the idle-TTL timer never clears on a turn and the lifecycle
 			// could park the agent mid-run.
 			session.subscribe(event => {
-				if (event.type === "agent_start") registry.setStatus(ref.id, "running");
-				else if (event.type === "agent_end") registry.setStatus(ref.id, "idle");
+				if (event.type === "agent_start") registry.setStatus(ref.id, "running", session);
+				else if (event.type === "agent_end") registry.setStatus(ref.id, "idle", session);
 			});
 			return session;
 		};

package/src/task/structured-subagent.ts

@@ -373,6 +373,7 @@ function buildExecutorOptions(
 	const enableMCP = !policy.planMode && (session.enableMCP ?? true);
 	return {
 		cwd: session.cwd,
+		additionalDirectories: session.additionalDirectories,
 		agent: policy.effectiveAgent,
 		task: renderSubagentPrompt(request.assignment),
 		assignment: request.assignment.trim(),

package/src/tools/approval.ts

@@ -20,6 +20,7 @@ export interface ResolvedApproval {
 	tier: ToolTier;
 	reason?: string;
 	override: boolean;
+	source?: "tool" | "user" | "mode";
 }
 
 const POLICY_VALUES: ReadonlySet<ApprovalPolicy> = new Set(["allow", "deny", "prompt"]);
@@ -50,7 +51,7 @@ function isToolTier(value: unknown): value is ToolTier {
 	return typeof value === "string" && TIER_VALUES.has(value as ToolTier);
 }
 
-function normalizeDecision(value: unknown): Omit<ResolvedApproval, "policy"> {
+function normalizeDecision(value: unknown): Omit<ResolvedApproval, "policy"> & { policy?: ApprovalPolicy } {
 	if (isToolTier(value)) {
 		return { tier: value, override: false };
 	}
@@ -59,9 +60,11 @@ function normalizeDecision(value: unknown): Omit<ResolvedApproval, "policy"> {
 		const record = value as Record<string, unknown>;
 		const tier = isToolTier(record.tier) ? record.tier : "exec";
 		const reason = typeof record.reason === "string" && record.reason.length > 0 ? record.reason : undefined;
+		const policy = normalizePolicy(record.policy);
 		return {
 			tier,
 			override: record.override === true,
+			...(policy ? { policy } : {}),
 			...(reason ? { reason } : {}),
 		};
 	}
@@ -69,7 +72,10 @@ function normalizeDecision(value: unknown): Omit<ResolvedApproval, "policy"> {
 	return { tier: "exec", override: false };
 }
 
-function getToolDecision(tool: ApprovalSubject, args: unknown): Omit<ResolvedApproval, "policy"> {
+function getToolDecision(
+	tool: ApprovalSubject,
+	args: unknown,
+): Omit<ResolvedApproval, "policy"> & { policy?: ApprovalPolicy } {
 	const approval = tool.approval;
 	const decision: ToolApprovalDecision | undefined = typeof approval === "function" ? approval(args) : approval;
 	return normalizeDecision(decision);
@@ -110,34 +116,70 @@ export function resolveApproval(
 	const decision = getToolDecision(tool, args);
 	const userPolicy = Object.hasOwn(userConfig, tool.name) ? normalizePolicy(userConfig[tool.name]) : undefined;
 
+	if (decision.policy === "deny") {
+		return {
+			policy: "deny",
+			tier: decision.tier,
+			override: decision.override,
+			source: "tool",
+			...(decision.reason ? { reason: decision.reason } : {}),
+		};
+	}
+	if (userPolicy === "deny") {
+		return { policy: "deny", tier: decision.tier, override: decision.override, source: "user" };
+	}
+
 	if (mode === "yolo") {
-		return { policy: userPolicy ?? "allow", tier: decision.tier, override: false };
+		if (decision.policy) {
+			return {
+				policy: decision.policy,
+				tier: decision.tier,
+				override: false,
+				source: "tool",
+				...(decision.reason ? { reason: decision.reason } : {}),
+			};
+		}
+		return {
+			policy: userPolicy ?? "allow",
+			tier: decision.tier,
+			override: false,
+			source: userPolicy ? "user" : "mode",
+		};
 	}
 
 	if (decision.override) {
-		if (userPolicy === "deny") {
-			return { policy: "deny", tier: decision.tier, override: true };
-		}
 		return {
-			policy: "prompt",
+			policy: decision.policy === "allow" ? "allow" : "prompt",
 			tier: decision.tier,
 			override: true,
+			source: "tool",
+			...(decision.reason ? { reason: decision.reason } : {}),
+		};
+	}
+
+	if (decision.policy === "allow" || decision.policy === "prompt") {
+		return {
+			policy: decision.policy,
+			tier: decision.tier,
+			override: false,
+			source: "tool",
 			...(decision.reason ? { reason: decision.reason } : {}),
 		};
 	}
 
 	if (userPolicy) {
-		return { policy: userPolicy, tier: decision.tier, override: false };
+		return { policy: userPolicy, tier: decision.tier, override: false, source: "user" };
 	}
 
 	if (modeApprovesTier(mode, decision.tier)) {
-		return { policy: "allow", tier: decision.tier, override: false };
+		return { policy: "allow", tier: decision.tier, override: false, source: "mode" };
 	}
 
 	return {
 		policy: "prompt",
 		tier: decision.tier,
 		override: false,
+		source: "mode",
 		...(decision.reason ? { reason: decision.reason } : {}),
 	};
 }
@@ -154,9 +196,12 @@ export function requiresApproval(
 	mode: ApprovalMode,
 	userConfig: Record<string, unknown> = {},
 ): { required: boolean; reason?: string } {
-	const { policy, reason } = resolveApproval(tool, args, mode, userConfig);
+	const { policy, reason, source } = resolveApproval(tool, args, mode, userConfig);
 
 	if (policy === "deny") {
+		if (source === "tool") {
+			throw new Error(`Tool "${tool.name}" is blocked by tool policy.${reason ? `\nReason: ${reason}` : ""}`);
+		}
 		throw new Error(
 			`Tool "${tool.name}" is blocked by user policy.\n` +
 				`To allow: remove "tools.approval.${tool.name}: deny" from config.`,

package/src/tools/bash-interactive.ts

@@ -32,6 +32,10 @@ function normalizeCaptureChunk(chunk: string): string {
 	return sanitizeWithOptionalSixelPassthrough(normalized, sanitizeText);
 }
 
+// Caps only the live xterm display backlog; OutputSink remains the bounded
+// source of truth for the final captured output.
+const MAX_LIVE_WRITE_QUEUE_CHUNKS = 512;
+
 // @xterm/headless is only needed once an interactive PTY session actually starts,
 // so it is loaded lazily (and memoized) instead of weighing down CLI startup.
 let xtermTerminalCtor: typeof XtermModule.Terminal | undefined;
@@ -142,9 +146,31 @@ class BashInteractiveOverlayComponent implements Component {
 
 	appendOutput(chunk: string): void {
 		this.#writeQueue.push(chunk);
+		this.#trimWriteQueue();
 		this.#drainQueue();
 	}
 
+	#trimWriteQueue(): void {
+		// Compact the consumed prefix first: the queue only self-resets on a
+		// full drain, which never happens while a fast producer keeps a
+		// backlog alive, so already-written chunks must be released here to
+		// keep the retained array itself bounded.
+		if (this.#writeOffset > 0) {
+			this.#writeQueue.splice(0, this.#writeOffset);
+			this.#writeOffset = 0;
+		}
+		const firstPending = this.#writing ? 1 : 0;
+		const overflow = this.#writeQueue.length - firstPending - MAX_LIVE_WRITE_QUEUE_CHUNKS;
+		if (overflow > 0) {
+			this.#writeQueue.splice(firstPending, overflow);
+			// Dropped chunks can split an in-flight DCS/OSC/APC string (e.g. a
+			// sixel payload) across the gap; a stray string terminator is a
+			// no-op in the ground state but resynchronizes the parser if the
+			// terminator was dropped.
+			this.#writeQueue[firstPending] = `\u001b\\${this.#writeQueue[firstPending]}`;
+		}
+	}
+
 	#drainQueue(): void {
 		if (this.#writing) return;
 		if (this.#writeOffset >= this.#writeQueue.length) {

package/src/tools/bash-skill-urls.ts

@@ -144,6 +144,8 @@ function unquoteToken(token: string): string {
 function isInsideShellQuote(command: string, index: number): boolean {
 	type ShellQuote = "'" | '"' | undefined;
 	interface CommandSubstitution {
+		/** `$(` … `)` tracks paren depth; `` ` `` … `` ` `` is a plain toggle. */
+		kind: "dollar" | "backtick";
 		outerQuote: ShellQuote;
 		depth: number;
 	}
@@ -152,6 +154,19 @@ function isInsideShellQuote(command: string, index: number): boolean {
 	const substitutions: CommandSubstitution[] = [];
 	for (let i = 0; i < index; i++) {
 		const char = command[i];
+		// Inside a backtick substitution nested in double quotes, bash treats `\"`
+		// as a quote delimiter for the inner command, not as an escaped literal.
+		if (
+			char === "\\" &&
+			command[i + 1] === '"' &&
+			quote !== "'" &&
+			substitutions.at(-1)?.kind === "backtick" &&
+			substitutions.at(-1)?.outerQuote === '"'
+		) {
+			quote = quote === '"' ? undefined : '"';
+			i++;
+			continue;
+		}
 		if (char === "\\" && quote !== "'") {
 			i++;
 			continue;
@@ -165,15 +180,26 @@ function isInsideShellQuote(command: string, index: number): boolean {
 			continue;
 		}
 		if (char === "$" && command[i + 1] === "(" && quote !== "'") {
-			substitutions.push({ outerQuote: quote, depth: 1 });
+			substitutions.push({ kind: "dollar", outerQuote: quote, depth: 1 });
 			quote = undefined;
 			i++;
 			continue;
 		}
+		if (char === "`" && quote !== "'") {
+			const top = substitutions.at(-1);
+			if (top?.kind === "backtick") {
+				substitutions.pop();
+				quote = top.outerQuote;
+			} else {
+				substitutions.push({ kind: "backtick", outerQuote: quote, depth: 0 });
+				quote = undefined;
+			}
+			continue;
+		}
 		if (quote !== undefined) continue;
 
 		const substitution = substitutions.at(-1);
-		if (!substitution) continue;
+		if (substitution?.kind !== "dollar") continue;
 		if (char === "(") {
 			substitution.depth++;
 		} else if (char === ")") {