pi-agent-flow 1.7.2 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-agent-flow",
-  "version": "1.7.2",
+  "version": "1.8.0",
   "description": "Flow-state delegation extension for Pi coding agent.",
   "type": "module",
   "main": "src/index.ts",

package/src/batch/batch-bash.ts

@@ -0,0 +1,443 @@
+/**
+ * batch bash -- parallel bash execution and polling.
+ *
+ * Runs multiple shell commands concurrently with a soft timeout,
+ * tracks running/pending processes, and exposes a polling interface
+ * so the agent can retrieve results of long-running commands later.
+ *
+ * The soft timeout (default 20s) does NOT kill commands. It sets the maximum
+ * wait time before the batch tool returns partial results. Commands that
+ * haven't finished continue running in the background and can be polled
+ * via the `batch_bash_poll` tool.
+ */
+
+import { spawn, type ChildProcess } from "node:child_process";
+import { Type } from "@sinclair/typebox";
+import {
+	type BashOpResult,
+	type PendingBashResult,
+	BASH_SOFT_TIMEOUT_MS,
+	BASH_POLL_TAIL_LINES,
+} from "./constants.js";
+import { classifyDuration } from "../timed-bash.js";
+
+// ---------------------------------------------------------------------------
+// Process tracker -- shared between batch and batch_bash_poll tools
+// ---------------------------------------------------------------------------
+
+interface RunningProcess {
+	proc: ChildProcess;
+	command: string;
+	startedAt: number;
+	stdoutChunks: string[];
+	stderrChunks: string[];
+	abortController: AbortController;
+}
+
+export interface TrackedBashResult {
+	id: string;
+	command: string;
+	status: "ok" | "error" | "aborted";
+	exitCode?: number;
+	stdout: string;
+	stderr: string;
+	duration: number;
+	timingTier: string;
+}
+
+/**
+ * Process tracker for batch bash operations.
+ * Both the `batch` tool (launch side) and `batch_bash_poll` tool (read side)
+ * share the same instance.
+ */
+export class BashProcessTracker {
+	private running = new Map<string, RunningProcess>();
+	private completed = new Map<string, TrackedBashResult>();
+
+	/** Launch a bash command. Returns immediately; the process runs in the background. */
+	launch(
+		id: string,
+		command: string,
+		cwd: string,
+		signal?: AbortSignal,
+	): void {
+		// Abort any existing process with the same id
+		this.abortById(id);
+		this.completed.delete(id);
+
+		const ac = new AbortController();
+		const child = spawn(command, [], {
+			cwd,
+			shell: true,
+			stdio: ["ignore", "pipe", "pipe"],
+			signal: ac.signal,
+		});
+
+		const rp: RunningProcess = {
+			proc: child,
+			command,
+			startedAt: Date.now(),
+			stdoutChunks: [],
+			stderrChunks: [],
+			abortController: ac,
+		};
+
+		child.stdout?.on("data", (chunk: Buffer) => {
+			rp.stdoutChunks.push(chunk.toString());
+		});
+
+		child.stderr?.on("data", (chunk: Buffer) => {
+			rp.stderrChunks.push(chunk.toString());
+		});
+
+		// Wire parent signal
+		if (signal) {
+			const onParentAbort = () => this.abortById(id);
+			if (signal.aborted) {
+				this.abortById(id);
+			} else {
+				signal.addEventListener("abort", onParentAbort, { once: true });
+				child.on("close", () => signal.removeEventListener("abort", onParentAbort));
+			}
+		}
+
+		child.on("close", (code) => {
+			this.running.delete(id);
+
+			const stdout = rp.stdoutChunks.join("");
+			const stderr = rp.stderrChunks.join("");
+			const duration = Date.now() - rp.startedAt;
+			const report = classifyDuration(duration);
+
+			this.completed.set(id, {
+				id,
+				command,
+				status: code === 0 ? "ok" : "error",
+				exitCode: code ?? undefined,
+				stdout,
+				stderr,
+				duration,
+				timingTier: report.label,
+			});
+		});
+
+		child.on("error", (err) => {
+			this.running.delete(id);
+
+			const duration = Date.now() - rp.startedAt;
+			const report = classifyDuration(duration);
+			const stdout = rp.stdoutChunks.join("");
+			const stderr = rp.stderrChunks.join("") || err.message;
+
+			this.completed.set(id, {
+				id,
+				command,
+				status: "aborted",
+				exitCode: undefined,
+				stdout,
+				stderr,
+				duration,
+				timingTier: report.label,
+			});
+		});
+
+		this.running.set(id, rp);
+	}
+
+	/** Check if a command is still running. */
+	isRunning(id: string): boolean {
+		return this.running.has(id);
+	}
+
+	/** Get the last N lines of a running process's stdout. */
+	getRunningTail(id: string): string {
+		const rp = this.running.get(id);
+		if (!rp) return "";
+		const stdout = rp.stdoutChunks.join("");
+		return tailLines(stdout, BASH_POLL_TAIL_LINES);
+	}
+
+	/** Get the result of a completed/aborted command. Does NOT remove from cache. */
+	peekCompleted(id: string): TrackedBashResult | undefined {
+		return this.completed.get(id);
+	}
+
+	/** Get the result of a completed/aborted command. Removes from completed cache. */
+	popCompleted(id: string): TrackedBashResult | undefined {
+		const result = this.completed.get(id);
+		if (result) this.completed.delete(id);
+		return result;
+	}
+
+	/** Get the start time of a running process. */
+	getStartedAt(id: string): number | undefined {
+		return this.running.get(id)?.startedAt;
+	}
+
+	/** Check if a command has completed. */
+	hasCompleted(id: string): boolean {
+		return this.completed.has(id);
+	}
+
+	/** Abort a running process by id. */
+	private abortById(id: string): void {
+		const rp = this.running.get(id);
+		if (!rp) return;
+		try {
+			rp.abortController.abort();
+			rp.proc.kill("SIGTERM");
+		} catch {
+			/* already dead */
+		}
+	}
+
+	/** Abort all running processes (cleanup). */
+	abortAll(): void {
+		for (const [id] of this.running) {
+			this.abortById(id);
+		}
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function tailLines(text: string, n: number): string {
+	const lines = text.split("\n");
+	return lines.slice(-n).join("\n");
+}
+
+/** Generate a short random ID for bash ops that don't provide one. */
+export function generateBashId(): string {
+	return Math.random().toString(36).slice(2, 10);
+}
+
+/** Normalize a bash op from prepareArguments into a canonical form. */
+export function normalizeBashOp(raw: Record<string, unknown>): Record<string, unknown> {
+	return {
+		o: "bash",
+		c: raw.c ?? raw.command,
+		i: raw.i ?? raw.id ?? generateBashId(),
+		t: raw.t ?? raw.timeout,
+		h: raw.h ?? raw.cwdPath ?? raw.cwd,
+		p: raw.p ?? "bash",
+	};
+}
+
+/**
+ * Execute a batch of bash ops concurrently.
+ *
+ * Launches all commands in parallel, then waits until all finish or the
+ * soft timeout expires. The soft timeout is the max of per-op `t` values
+ * (if any), or the global default. Commands that haven't finished within
+ * the timeout are returned as "pending" with the last N lines of output.
+ * They continue running in the background and can be polled via batch_bash_poll.
+ */
+export async function executeBatchBash(
+	ops: Array<{ i: string; c: string; t?: number; h?: string }>,
+	defaultCwd: string,
+	tracker: BashProcessTracker,
+	signal?: AbortSignal,
+	softTimeoutMs: number = BASH_SOFT_TIMEOUT_MS,
+): Promise<BashOpResult[]> {
+	if (ops.length === 0) return [];
+
+	// Compute the effective batch soft timeout: if per-op timeouts are specified,
+	// use the minimum of those; otherwise fall back to the global default.
+	const perOpTimeouts = ops.filter((op) => typeof op.t === "number" && op.t! > 0).map((op) => op.t!);
+	const effectiveTimeout = perOpTimeouts.length > 0
+		? Math.min(...perOpTimeouts)
+		: softTimeoutMs;
+
+	// Launch all commands in parallel
+	for (const op of ops) {
+		const cwd = op.h ? op.h : defaultCwd;
+		tracker.launch(op.i, op.c, cwd, signal);
+	}
+
+	// Wait up to effectiveTimeout for all to finish
+	await waitForSettle(ops, tracker, effectiveTimeout, signal);
+
+	// Collect results
+	const results: BashOpResult[] = [];
+	for (const op of ops) {
+		const completed = tracker.popCompleted(op.i);
+		if (completed) {
+			results.push({
+				op: "bash",
+				path: op.i,
+				id: op.i,
+				command: op.c,
+				status: completed.status === "ok" ? "ok" : "error",
+				exitCode: completed.exitCode,
+				stdout: completed.stdout,
+				stderr: completed.stderr,
+				duration: completed.duration,
+				timingTier: completed.timingTier,
+			});
+		} else {
+			// Still running -- return pending with tail
+			const tail = tracker.getRunningTail(op.i);
+			results.push({
+				op: "bash",
+				path: op.i,
+				id: op.i,
+				command: op.c,
+				status: "pending",
+				stdout: tail,
+				stderr: "",
+				duration: Date.now() - getStartTime(tracker, op.i),
+			});
+		}
+	}
+
+	return results;
+}
+
+/** Get the start time of a running process, or Date.now() if not found. */
+function getStartTime(tracker: BashProcessTracker, id: string): number {
+	return tracker.getStartedAt(id) ?? Date.now();
+}
+
+/**
+ * Wait until all ops have completed or the soft timeout expires.
+ * Uses a polling check every 100ms.
+ */
+function waitForSettle(
+	ops: Array<{ i: string }>,
+	tracker: BashProcessTracker,
+	timeoutMs: number,
+	signal?: AbortSignal,
+): Promise<void> {
+	return new Promise<void>((resolve) => {
+		const deadline = Date.now() + timeoutMs;
+
+		const check = () => {
+			if (signal?.aborted) {
+				resolve();
+				return;
+			}
+			const allDone = ops.every((op) => !tracker.isRunning(op.i));
+			if (allDone || Date.now() >= deadline) {
+				resolve();
+				return;
+			}
+			setTimeout(check, 100);
+		};
+		check();
+	});
+}
+
+/** Poll for completed bash results. */
+export function pollBatchBashResults(
+	ids: string[],
+	tracker: BashProcessTracker,
+): PendingBashResult[] {
+	const results: PendingBashResult[] = [];
+	for (const id of ids) {
+		if (tracker.hasCompleted(id)) {
+			const r = tracker.popCompleted(id)!;
+			results.push({
+				id,
+				command: r.command,
+				status: "completed",
+				exitCode: r.exitCode,
+				stdout: r.stdout,
+				stderr: r.stderr,
+				duration: r.duration,
+				timingTier: r.timingTier,
+			});
+		} else if (tracker.isRunning(id)) {
+			results.push({
+				id,
+				command: "",
+				status: "pending",
+				stdout: tracker.getRunningTail(id),
+			});
+		} else {
+			results.push({
+				id,
+				command: "",
+				status: "pending",
+				stdout: "",
+			});
+		}
+	}
+	return results;
+}
+
+// ---------------------------------------------------------------------------
+// Poll tool schema & factory
+// ---------------------------------------------------------------------------
+
+export const BatchBashPollParams = Type.Object({
+	i: Type.Array(Type.String(), {
+		description: "Array of bash operation IDs to poll for results.",
+		minItems: 1,
+	}),
+});
+
+export function createBatchBashPollTool(tracker: BashProcessTracker) {
+	return {
+		name: "batch_bash_poll",
+		label: "batch_bash_poll",
+		description: [
+			"Poll for results of pending bash commands from a previous batch call.",
+			"Pass the IDs of pending commands to check their status.",
+			"Returns completed results with full stdout/stderr, or indicates still-pending with last output lines.",
+		].join("\n"),
+		promptSnippet: "Poll pending bash commands for results",
+		promptGuidelines: [
+			"Use batch_bash_poll to check on bash commands that returned pending from a batch call.",
+			"Pass the `i` (id) values from the pending results.",
+		],
+		parameters: BatchBashPollParams,
+
+		prepareArguments(input: unknown): unknown {
+			if (!input || typeof input !== "object") return { i: [] };
+			const args = input as Record<string, unknown>;
+			const ids = args.i ?? args.ids;
+			if (!Array.isArray(ids)) return { i: [] };
+			return { i: ids };
+		},
+
+		async execute(
+			_toolCallId: string,
+			input: unknown,
+			_signal?: AbortSignal,
+			_onUpdate?: unknown,
+		) {
+			const args = (input ?? {}) as Record<string, unknown>;
+			const ids = Array.isArray(args.i) ? (args.i as string[]) : Array.isArray(args.ids) ? (args.ids as string[]) : [];
+
+			if (ids.length === 0) {
+				return {
+					content: [{ type: "text", text: "Error: i (ids) array is required and must not be empty." }],
+					isError: true,
+				};
+			}
+
+			const results = pollBatchBashResults(ids, tracker);
+
+			const lines: string[] = [];
+			for (const r of results) {
+				if (r.status === "completed") {
+					const exitInfo = r.exitCode !== undefined ? `exit ${r.exitCode}` : "interrupted";
+					lines.push(`--- [${r.id}] ${exitInfo} (${r.timingTier ?? "unknown"}) ---`);
+					if (r.stdout?.trim()) lines.push(r.stdout.trimEnd());
+					if (r.stderr?.trim()) lines.push(`[stderr]\n${r.stderr.trimEnd()}`);
+				} else {
+					lines.push(`--- [${r.id}] still running ---`);
+					if (r.stdout?.trim()) lines.push(`[output so far]\n${r.stdout.trimEnd()}`);
+				}
+				lines.push("");
+			}
+
+			return {
+				content: [{ type: "text", text: lines.join("\n").trimEnd() }],
+				details: { results },
+			};
+		},
+	};
+}

package/src/batch/constants.ts

@@ -12,6 +12,8 @@ export const SAFE_FULL_READ_LIMIT = 300;
 export const TARGETED_READ_LINE_LIMIT = 1000;
 export const MAX_CONTEXT_MAP_ENTRIES = 100;
 export const MAX_TOTAL_RESULT_LINES = 1500;
+export const BASH_SOFT_TIMEOUT_MS = 20_000;
+export const BASH_POLL_TAIL_LINES = 50;
 
 // ---------------------------------------------------------------------------
 // Types
@@ -23,12 +25,15 @@ export interface EditReplacement {
 }
 
 export interface FileOpInput {
-	o: "read" | "write" | "edit" | "delete";
+	o: "read" | "write" | "edit" | "delete" | "bash";
 	p: string;
 	c?: string;
 	e?: EditReplacement[];
 	s?: number;
 	l?: number;
+	i?: string;
+	t?: number;
+	h?: string;
 }
 
 export interface ContextMapEntry {
@@ -40,9 +45,9 @@ export interface ContextMapEntry {
 }
 
 export interface OpResult {
-	op: "read" | "write" | "edit" | "delete";
+	op: "read" | "write" | "edit" | "delete" | "bash";
 	path: string;
-	status: "ok" | "error" | "skipped";
+	status: "ok" | "error" | "skipped" | "pending";
 	content?: string;
 	bytes?: number;
 	blocksChanged?: number;
@@ -56,6 +61,13 @@ export interface OpResult {
 	nextOffset?: number;
 	error?: string;
 	hint?: string;
+	id?: string;
+	command?: string;
+	exitCode?: number;
+	stdout?: string;
+	stderr?: string;
+	duration?: number;
+	timingTier?: string;
 }
 
 export interface ReadTruncationResult {
@@ -101,3 +113,16 @@ export type BatchTheme = {
 	bold: (s: string) => string;
 	bg: (color: string, text: string) => string;
 };
+
+export interface PendingBashResult {
+	id: string;
+	command: string;
+	status: "pending" | "completed";
+	exitCode?: number;
+	stdout?: string;
+	stderr?: string;
+	duration?: number;
+	timingTier?: string;
+}
+
+export type BashOpResult = OpResult;

package/src/batch/index.ts

@@ -7,7 +7,7 @@
 
 import { Type } from "@sinclair/typebox";
 import type { BatchTheme, FileOpInput } from "./constants.js";
-import { SAFE_FULL_READ_LIMIT, TARGETED_READ_LINE_LIMIT } from "./constants.js";
+import { SAFE_FULL_READ_LIMIT, TARGETED_READ_LINE_LIMIT, BASH_SOFT_TIMEOUT_MS } from "./constants.js";
 import { executeOperations, suggestSimilarFiles } from "./execute.js";
 import { expandTilde, isWithinDirectory } from "./fuzzy-edit.js";
 import {
@@ -15,6 +15,15 @@ import {
 	renderBatchReadCall,
 	renderBatchResult,
 } from "./render.js";
+import {
+	type BashProcessTracker,
+	generateBashId,
+	normalizeBashOp,
+	executeBatchBash,
+} from "./batch-bash.js";
+
+// Re-export polling tool factory and tracker from batch-bash
+export { BashProcessTracker, createBatchBashPollTool, pollBatchBashResults } from "./batch-bash.js";
 
 // ---------------------------------------------------------------------------
 // Schema
@@ -34,12 +43,13 @@ const FileOp = Type.Object({
 		Type.Literal("write"),
 		Type.Literal("edit"),
 		Type.Literal("delete"),
+		Type.Literal("bash"),
 	]),
-	p: Type.String({ description: "Path to the file (relative or absolute)" }),
+	p: Type.String({ description: "Path to the file (relative or absolute). Use 'bash' or any string for o: 'bash'." }),
 	c: Type.Optional(
 		Type.String({
 			description:
-				"Full file content. Creates if new, overwrites if exists. Auto-creates parent dirs. Used with o: 'write'.",
+				"File content for o: 'write'. Shell command for o: 'bash'.",
 		}),
 	),
 	e: Type.Optional(
@@ -62,12 +72,28 @@ const FileOp = Type.Object({
 				"Maximum number of lines to read (limit). Used with o: 'read'.",
 		}),
 	),
+	i: Type.Optional(
+		Type.String({
+			description: "Unique ID for this bash operation. Auto-generated if omitted. Used with o: 'bash'.",
+		}),
+	),
+	t: Type.Optional(
+		Type.Number({
+			minimum: 1,
+			description: `Soft timeout in ms. Default: ${BASH_SOFT_TIMEOUT_MS}. Command keeps running after timeout; returns partial output with pending status. Used with o: 'bash'.`,
+		}),
+	),
+	h: Type.Optional(
+		Type.String({
+			description: "Working directory override for this command. Used with o: 'bash'.",
+		}),
+	),
 });
 
 export const WeavePatchParams = Type.Object({
 	o: Type.Array(FileOp, {
 		description:
-			"Ordered list of file operations. Executed sequentially. On failure, remaining operations are skipped.",
+			"Ordered list of operations. File ops (read/write/edit/delete) execute sequentially — on failure, remaining file ops are skipped. Bash ops (bash) run in parallel after file ops complete and do not skip each other on failure.",
 	}),
 });
 
@@ -108,6 +134,11 @@ function normalizeOp(raw: Record<string, unknown>): Record<string, unknown> {
 	// Map operation type
 	op.o = raw.o ?? raw.op ?? (raw.c != null || raw.content != null ? "write" : (raw.e != null || raw.edits != null ? "edit" : "read"));
 
+	// Bash ops use a separate normalizer
+	if (op.o === "bash") {
+		return normalizeBashOp(raw);
+	}
+
 	// Map path
 	op.p = raw.p ?? raw.path;
 
@@ -298,22 +329,32 @@ export function createBatchReadTool() {
 	};
 }
 
-export function createBatchTool() {
+/**
+ * Create the batch tool.
+ *
+ * @param bashTracker Optional BashProcessTracker for executing bash operations.
+ *   When omitted, bash ops return an error. Both the batch tool and the
+ *   batch_bash_poll tool must share the same tracker instance.
+ */
+export function createBatchTool(bashTracker?: BashProcessTracker) {
 	return {
 		name: "batch",
 		label: "batch",
 		description: [
-			"Batch file operations — run multiple read, write, edit, or delete ops in a single call.",
-			"Each operation is independent: edits are matched against the current on-disk file, not against prior operations in the same call.",
-			"Operations execute sequentially in array order; on failure, remaining operations are skipped.",
+			"Batch operations — run multiple file ops (read/write/edit/delete) and bash commands in a single call.",
+			"Each file operation is independent: edits are matched against the current on-disk file, not against prior operations in the same call.",
+			"File operations execute sequentially in array order; on failure, remaining file operations are skipped.",
+			"Bash operations (o: 'bash') run in parallel after all file ops complete. Bash ops do NOT skip each other on failure.",
+			`Bash ops use c (command), i (id), t (timeout, default ${BASH_SOFT_TIMEOUT_MS}ms), h (cwd). Commands exceeding the soft timeout return "pending" status with last 50 lines of output; poll with batch_bash_poll.`,
 			"Use `o: \"read\"` with `s` (offset) and `l` (limit) for targeted reading. Prefer this over bash sed/head/tail.",
 			"Best for cross-cutting changes, multi-file refactors, or mixing reads with writes across several files.",
 		].join("\n"),
-		promptSnippet: "Batch file operations — run multiple read/write/edit/delete ops in one call",
+		promptSnippet: "Batch operations — run multiple file ops and bash commands in one call",
 		promptGuidelines: [
-			"Use batch to perform multiple file operations in a single call rather than separate tool calls.",
-			"Prefer batch when touching 2+ files or mixing creates, edits, reads, and deletes.",
-			"Each operation is independent — edits match the on-disk file, not prior ops in the same call.",
+			"Use batch to perform multiple file operations and bash commands in a single call.",
+			"Prefer batch when touching 2+ files, mixing creates/edits/reads/deletes, or running shell commands.",
+			"Each file operation is independent — edits match the on-disk file, not prior ops in the same call.",
+			"Bash ops run in parallel. Use i (id) to track them. Use batch_bash_poll to check on pending commands.",
 			"For single-file edits, the edit tool is fine; batch shines for cross-cutting and multi-file work.",
 		],
 		parameters: WeavePatchParams,
@@ -349,11 +390,100 @@ export function createBatchTool() {
 				};
 			}
 
-			const { contentText, results } = await executeOperations(ops, ctx.cwd, signal);
+			// Split ops into file ops and bash ops
+			const fileOps: FileOpInput[] = [];
+			const bashOps: FileOpInput[] = [];
+			for (const op of ops) {
+				if (op.o === "bash") {
+					bashOps.push(op);
+				} else {
+					fileOps.push(op);
+				}
+			}
+
+			// Execute file ops first (sequential, skip-on-failure)
+			let fileContentText = "";
+			let fileResults: import("./constants.js").OpResult[] = [];
+			let fileFailed = false;
+
+			if (fileOps.length > 0) {
+				const fileOutput = await executeOperations(fileOps, ctx.cwd, signal);
+				fileContentText = fileOutput.contentText;
+				fileResults = fileOutput.results;
+				fileFailed = fileOutput.results.some((r) => r.status === "error");
+			}
+
+			// Execute bash ops in parallel (independent of file failures,
+			// unless ALL ops are file+bash and a file op failed before any bash op)
+			// Per spec: file op failure skips bash ops
+			let bashResults: import("./constants.js").OpResult[] = [];
+			let bashContentText = "";
+
+			if (bashOps.length > 0 && !fileFailed && bashTracker) {
+				const normalizedBashOps = bashOps.map((op) => ({
+					i: op.i ?? generateBashId(),
+					c: op.c ?? "",
+					t: op.t,
+					h: op.h,
+				}));
+
+				const bashOutput = await executeBatchBash(
+					normalizedBashOps,
+					ctx.cwd,
+					bashTracker,
+					signal,
+				);
+
+				bashResults = bashOutput;
+
+				// Format bash results into content text
+				const bashLines: string[] = [];
+				for (const r of bashOutput) {
+					const timingInfo = r.timingTier ? ` (${r.timingTier})` : "";
+					if (r.status === "ok") {
+						bashLines.push(`\n--- bash [${r.id}] exit ${r.exitCode}${timingInfo} ---`);
+						if (r.stdout?.trim()) bashLines.push(r.stdout.trimEnd());
+					} else if (r.status === "pending") {
+						bashLines.push(`\n--- bash [${r.id}] pending${timingInfo} ---`);
+						if (r.stdout?.trim()) bashLines.push(`[partial output]\n${r.stdout.trimEnd()}`);
+						bashLines.push(`[Use batch_bash_poll with i: ["${r.id}"] to check results]`);
+					} else {
+						bashLines.push(`\n--- bash [${r.id}] error${timingInfo} ---`);
+						if (r.stdout?.trim()) bashLines.push(r.stdout.trimEnd());
+						if (r.stderr?.trim()) bashLines.push(`[stderr]\n${r.stderr.trimEnd()}`);
+					}
+				}
+				bashContentText = bashLines.join("\n");
+			} else if (bashOps.length > 0 && fileFailed) {
+				// File ops failed — mark bash ops as skipped
+				bashResults = bashOps.map((op) => ({
+					op: "bash" as const,
+					path: op.p,
+					status: "skipped" as const,
+					id: op.i,
+					command: op.c,
+					error: "Skipped: a file operation failed.",
+				}));
+				bashContentText = `\n--- bash: ${bashOps.length} command(s) skipped (file op failed) ---`;
+			} else if (bashOps.length > 0 && !bashTracker) {
+				bashResults = bashOps.map((op) => ({
+					op: "bash" as const,
+					path: op.p,
+					status: "error" as const,
+					id: op.i,
+					command: op.c,
+					error: "Bash tracker not available.",
+				}));
+				bashContentText = "\n--- bash: tracker not available ---";
+			}
+
+			// Combine results
+			const allResults = [...fileResults, ...bashResults];
+			const contentText = [fileContentText, bashContentText].filter(Boolean).join("\n");
 
 			return {
 				content: [{ type: "text", text: contentText }],
-				details: { results },
+				details: { results: allResults },
 			};
 		},
 

package/src/batch/render.ts

@@ -11,7 +11,7 @@ function shortenPath(p: string): string {
 	return p.startsWith(home) ? `~${p.slice(home.length)}` : p;
 }
 
-function extractBatchOps(args: Record<string, unknown>): Array<{ o: string; p: string; e?: unknown[] }> {
+function extractBatchOps(args: Record<string, unknown>): Array<{ o: string; p: string; e?: unknown[]; c?: string }> {
 	let rawOps: unknown[];
 	if (Array.isArray(args.o)) rawOps = args.o;
 	else if (Array.isArray(args.op)) rawOps = args.op;
@@ -25,7 +25,8 @@ function extractBatchOps(args: Record<string, unknown>): Array<{ o: string; p: s
 			const opName = String(op.o ?? op.op ?? "?");
 			const opPath = String(op.p ?? op.path ?? "?");
 			const edits = Array.isArray(op.e) ? op.e : Array.isArray(op.edits) ? op.edits : undefined;
-			return { o: opName, p: opPath, e: edits };
+			const cmd = typeof op.c === "string" ? op.c : typeof op.command === "string" ? op.command : undefined;
+			return { o: opName, p: opPath, e: edits, c: cmd };
 		});
 }
 
@@ -35,11 +36,17 @@ function formatBatchCall(args: Record<string, unknown>): string {
 
 	const parts: string[] = [];
 	for (const op of ops) {
-		const shortPath = shortenPath(op.p);
-		if (op.o === "edit" && op.e && op.e.length > 1) {
-			parts.push(`edit ${shortPath} (${op.e.length} blocks)`);
+		if (op.o === "bash") {
+			const cmd = op.c ?? "?";
+			const display = cmd.length > 40 ? cmd.slice(0, 37) + "..." : cmd;
+			parts.push(`bash: ${display}`);
 		} else {
-			parts.push(`${op.o} ${shortPath}`);
+			const shortPath = shortenPath(op.p);
+			if (op.o === "edit" && op.e && op.e.length > 1) {
+				parts.push(`edit ${shortPath} (${op.e.length} blocks)`);
+			} else {
+				parts.push(`${op.o} ${shortPath}`);
+			}
 		}
 	}
 

package/src/batch.ts

@@ -11,5 +11,18 @@ export {
 	createBatchReadTool,
 } from "./batch/index.js";
 
+export {
+	BashProcessTracker,
+	createBatchBashPollTool,
+	pollBatchBashResults,
+} from "./batch/index.js";
+
 export { suggestSimilarFiles } from "./batch/execute.js";
 export { isWithinDirectory } from "./batch/fuzzy-edit.js";
+
+export type {
+	BashOpResult,
+	PendingBashResult,
+	OpResult,
+	FileOpInput,
+} from "./batch/constants.js";

package/src/index.ts

@@ -41,7 +41,7 @@ import {
 	getFlowOutput,
 } from "./types.js";
 import { extractStructuredOutput } from "./structured-output.js";
-import { createBatchTool, createBatchReadTool } from "./batch.js";
+import { createBatchTool, createBatchReadTool, BashProcessTracker, createBatchBashPollTool } from "./batch.js";
 import {
 	createWebTool,
 	looksLikeUrlPrompt,
@@ -634,7 +634,7 @@ function sanitizeForkSnapshot(snapshot: string | null, cache: Map<string, Compre
 
 function computeActiveTools(optimize: boolean): string[] {
 	return optimize
-		? ["batch_read", "flow"]
+		? ["batch_read", "batch", "batch_bash_poll", "flow"]
 		: ["read", "write", "edit", "batch", "bash", "flow", "web"];
 }
 
@@ -842,9 +842,13 @@ export default function (pi: ExtensionAPI) {
 		}
 
 		// Register batch and batch_read so they are available for main agent and child flows.
+		// The bashProcessTracker is shared between the batch tool (launches bash ops)
+		// and the batch_bash_poll tool (checks on pending bash ops).
 		if (toolOptimize) {
+			const bashTracker = new BashProcessTracker();
 			pi.registerTool(createBatchReadTool());
-			pi.registerTool(createBatchTool());
+			pi.registerTool(createBatchTool(bashTracker));
+			pi.registerTool(createBatchBashPollTool(bashTracker));
 		}
 
 		// Override built-in bash with timed wrapper so the LLM sees execution-time classification.