@gajae-code/coding-agent 0.15.5 → 0.16.0

package/src/tools/bash.ts

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import * as path from "node:path";
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@gajae-code/agent-core";
 import type { Component } from "@gajae-code/tui";
 import { getKeybindings, ImageProtocol, TERMINAL, Text, visibleWidth } from "@gajae-code/tui";
@@ -17,8 +18,13 @@ import { InternalUrlRouter } from "../internal-urls";
 import { truncateToVisualLines } from "../modes/components/visual-truncate";
 import { highlightCode, type Theme } from "../modes/theme/theme";
 import bashDescription from "../prompts/tools/bash.md" with { type: "text" };
+import { renderSpawnTable, runSdkSpawn, type SdkSpawnArgs } from "../sdk/cli/master-cli";
 import type { ArtifactManager } from "../session/artifacts";
-import type { ClientBridgeTerminalExitStatus, ClientBridgeTerminalOutput } from "../session/client-bridge";
+import type {
+	ClientBridgeTerminalExitStatus,
+	ClientBridgeTerminalHandle,
+	ClientBridgeTerminalOutput,
+} from "../session/client-bridge";
 import {
 	DEFAULT_ARTIFACT_MAX_BYTES,
 	OutputSink,
@@ -62,6 +68,20 @@ import { formatToolWorkingDirectory, replaceTabs } from "./render-utils";
 import { checkTmuxSelfInjection } from "./tmux-self-injection-guard";
 import { ToolAbortError, ToolError } from "./tool-errors";
 import { toolResult } from "./tool-result";
+
+function sliceTextAfterUtf8ByteOffset(text: string, offsetBytes: number): string {
+	if (offsetBytes <= 0) return text;
+	let consumed = 0;
+	let index = 0;
+	while (index < text.length && consumed < offsetBytes) {
+		const codePoint = text.codePointAt(index);
+		if (codePoint === undefined) break;
+		consumed += Buffer.byteLength(String.fromCodePoint(codePoint), "utf8");
+		index += codePoint > 0xffff ? 2 : 1;
+	}
+	return text.slice(index);
+}
+
 import { clampTimeout, TOOL_TIMEOUTS } from "./tool-timeouts";
 
 export const BASH_DEFAULT_PREVIEW_LINES = 10;
@@ -69,7 +89,9 @@ export const BASH_DEFAULT_PREVIEW_LINES = 10;
 const BASH_ERROR_MAX_BYTES = 4096;
 const ARTIFACT_SAVE_DIAGNOSTIC_MAX_BYTES = 256;
 const BASH_ENV_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const MASTER_CAPABILITY_ENV = "GJC_MASTER_CAPABILITY";
 const DEFAULT_AUTO_BACKGROUND_THRESHOLD_MS = 60_000;
+const ACP_RELEASE_TIMEOUT_MS = 1_000;
 const READ_ONLY_BASH_ENV: Record<string, string> = {
 	GREP_OPTIONS: "",
 	GREP_COLOR: "",
@@ -151,6 +173,27 @@ function artifactReferenceIsReachable(text: string, result: BashResult | BashInt
 	);
 }
 
+function suffixPrefixOverlap(source: string, target: string): number {
+	if (source.length === 0 || target.length === 0) return 0;
+	const prefix = new Uint32Array(target.length);
+	for (let index = 1; index < target.length; index += 1) {
+		let length = prefix[index - 1] ?? 0;
+		const code = target.charCodeAt(index);
+		while (length > 0 && code !== target.charCodeAt(length)) length = prefix[length - 1] ?? 0;
+		if (code === target.charCodeAt(length)) length += 1;
+		prefix[index] = length;
+	}
+
+	let overlap = 0;
+	for (let index = 0; index < source.length; index += 1) {
+		const code = source.charCodeAt(index);
+		while (overlap > 0 && code !== target.charCodeAt(overlap)) overlap = prefix[overlap - 1] ?? 0;
+		if (code === target.charCodeAt(overlap)) overlap += 1;
+		if (overlap === target.length && index < source.length - 1) overlap = prefix[overlap - 1] ?? 0;
+	}
+	return overlap;
+}
+
 function artifactFailureDiagnosticForResult(result: BashResult | BashInteractiveResult): string | undefined {
 	const diagnostic = (result as OutputSummary).artifactFailureDiagnostic;
 	return typeof diagnostic === "string" && diagnostic.length > 0 ? diagnostic : undefined;
@@ -291,6 +334,48 @@ function formatClientTerminalAbortFailure(
 	return formatBashFailureMessage(result, outputText, "Command aborted");
 }
 
+function formatClientTerminalReadFailure(
+	prepared: PreparedClientTerminalOutput,
+	readDiagnostic: string,
+	pendingNotices: readonly string[] = [],
+): string {
+	const notices = [
+		...pendingNotices,
+		...(prepared.current.truncated || prepared.locallyTruncated ? ["(output truncated)"] : []),
+		...(prepared.artifactSaveNotice ? [prepared.artifactSaveNotice] : []),
+		`Terminal output recovery failed: ${readDiagnostic}`,
+	];
+	const outputText = [prepared.summary.output || "(no output)", ...notices].filter(Boolean).join("\n");
+	const result: BashResult = {
+		...prepared.summary,
+		exitCode: undefined,
+		cancelled: false,
+	};
+	return formatBashFailureMessage(result, outputText, "Terminal output read failed");
+}
+
+function formatClientTerminalWaitFailure(
+	prepared: PreparedClientTerminalOutput,
+	waitDiagnostic: string,
+	readDiagnostic?: string,
+	pendingNotices: readonly string[] = [],
+): string {
+	const notices = [
+		...pendingNotices,
+		...(prepared.current.truncated || prepared.locallyTruncated ? ["(output truncated)"] : []),
+		...(prepared.artifactSaveNotice ? [prepared.artifactSaveNotice] : []),
+		`Terminal wait failed: ${waitDiagnostic}`,
+		...(readDiagnostic ? [`Terminal output recovery failed: ${readDiagnostic}`] : []),
+	];
+	const outputText = [prepared.summary.output || "(no output)", ...notices].filter(Boolean).join("\n");
+	const result: BashResult = {
+		...prepared.summary,
+		exitCode: undefined,
+		cancelled: false,
+	};
+	return formatBashFailureMessage(result, outputText, "Terminal wait failed");
+}
+
 function appendArtifactDetails(text: string, result: BashResult | BashInteractiveResult): string {
 	const suffixParts: string[] = [];
 	const reference = artifactReferenceForResult(result);
@@ -468,6 +553,21 @@ interface ManagedBashJobHandle {
 	setBackgrounded: (backgrounded: boolean) => void;
 }
 
+/** The placeholder a folded PTY hands back to its (now finished) foreground call. */
+function interactiveResultFromText(text: string): BashInteractiveResult {
+	return {
+		exitCode: undefined,
+		cancelled: false,
+		timedOut: false,
+		output: text,
+		outputBytes: 0,
+		outputLines: 0,
+		totalBytes: 0,
+		totalLines: 0,
+		truncated: false,
+	};
+}
+
 function normalizeResultOutput(result: BashResult | BashInteractiveResult): string {
 	return result.output || "";
 }
@@ -504,6 +604,107 @@ function normalizeBashEnv(env: Record<string, string> | undefined): Record<strin
 	return normalized;
 }
 
+/**
+ * Return true only for a direct, shell-syntax-free `gjc sdk spawn` command.
+ *
+ * Master authority is process-local and must not become ambient state for an
+ * arbitrary shell pipeline. Keep a tiny lexer here instead of a prefix check:
+ * shell quoting is allowed for ordinary argument values, while operators,
+ * expansions, escapes, globbing, and line breaks all refuse the privileged
+ * environment injection path.
+ */
+function strictDirectSdkSpawnTokens(command: string): string[] | undefined {
+	if (command.length === 0) return undefined;
+	const tokens: string[] = [];
+	let token = "";
+	let tokenStarted = false;
+	let quote: "'" | '"' | undefined;
+	for (const character of command) {
+		if (quote !== undefined) {
+			if (character === quote) {
+				quote = undefined;
+				tokenStarted = true;
+			} else {
+				token += character;
+				tokenStarted = true;
+			}
+			continue;
+		}
+		if (";&|<>()$`\\*?[]{}#!\n\r".includes(character)) return undefined;
+		if (character === "'" || character === '"') {
+			quote = character;
+			tokenStarted = true;
+			continue;
+		}
+		if (/\s/u.test(character)) {
+			if (tokenStarted) {
+				tokens.push(token);
+				token = "";
+				tokenStarted = false;
+			}
+			continue;
+		}
+		token += character;
+		tokenStarted = true;
+	}
+	if (quote !== undefined) return undefined;
+	if (tokenStarted) tokens.push(token);
+	return tokens.length >= 3 && tokens[0] === "gjc" && tokens[1] === "sdk" && tokens[2] === "spawn"
+		? tokens
+		: undefined;
+}
+
+export function isStrictDirectSdkSpawnCommand(command: string): boolean {
+	return strictDirectSdkSpawnTokens(command) !== undefined;
+}
+
+export function parseDirectSdkSpawnArgs(command: string): SdkSpawnArgs {
+	const tokens = strictDirectSdkSpawnTokens(command);
+	if (tokens === undefined) throw new ToolError("Master spawn command is not a direct shell-safe invocation.");
+	const args: SdkSpawnArgs = {};
+	for (let index = 3; index < tokens.length; index++) {
+		const token = tokens[index]!;
+		if (token === "--json") {
+			args.json = true;
+			continue;
+		}
+		const equals = token.indexOf("=");
+		const name = equals < 0 ? token : token.slice(0, equals);
+		const value = equals < 0 ? tokens[++index] : token.slice(equals + 1);
+		if (value === undefined || value.length === 0) throw new ToolError(`Master spawn flag ${name} requires a value.`);
+		switch (name) {
+			case "--cwd":
+				args.cwd = value;
+				break;
+			case "--prompt":
+				args.prompt = value;
+				break;
+			case "--model":
+				args.model = value;
+				break;
+			case "--profile":
+				args.profile = value;
+				break;
+			case "--idempotency-key":
+				args.idempotencyKey = value;
+				break;
+			case "--agent-dir":
+				throw new ToolError("Master spawn cannot override the session agent directory.");
+			default:
+				throw new ToolError(`Unsupported master spawn flag: ${name}`);
+		}
+	}
+	return args;
+}
+
+export function masterCommandEnvOverrides(
+	env: Record<string, string> | undefined,
+	directMasterSpawn: boolean,
+): Record<string, string> {
+	if (directMasterSpawn) return {};
+	return Object.fromEntries(Object.entries(env ?? {}).filter(([key]) => key !== MASTER_CAPABILITY_ENV));
+}
+
 function escapeBashEnvValueForDisplay(value: string): string {
 	return value
 		.replaceAll("\\", "\\\\")
@@ -648,6 +849,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		this.description = prompt.render(bashDescription, {
 			asyncEnabled: this.#asyncEnabled,
 			autoBackgroundEnabled: this.#autoBackgroundEnabled,
+			foregroundFoldEnabled: this.session.registerForegroundFoldParticipant !== undefined,
 			autoBackgroundThresholdSeconds: Math.max(0, Math.floor(this.#autoBackgroundThresholdMs / 1000)),
 			hasAstGrep: this.session.settings.get("astGrep.enabled"),
 			hasAstEdit: this.session.settings.get("astEdit.enabled"),
@@ -732,12 +934,15 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		label: string,
 		previewText: string,
 		timeoutSec: number,
-		options: { requestedTimeoutSec?: number; notices?: readonly string[] } = {},
+		options: { requestedTimeoutSec?: number; notices?: readonly string[]; terminalId?: string } = {},
 	): AgentToolResult<BashToolDetails> {
 		const details: BashToolDetails = {
 			timeoutSeconds: timeoutSec,
 			async: { state: "running", jobId, type: "bash" },
 		};
+		// A folded client terminal keeps its remote handle, so the editor's live
+		// terminal card stays bound to the same id after the fold.
+		if (options.terminalId !== undefined) details.terminalId = options.terminalId;
 		if (options.requestedTimeoutSec !== undefined && options.requestedTimeoutSec !== timeoutSec) {
 			details.requestedTimeoutSeconds = options.requestedTimeoutSec;
 		}
@@ -773,8 +978,10 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		notices?: readonly string[];
 
 		resolvedEnv?: Record<string, string>;
+		directMasterSpawn: boolean;
 		onUpdate?: AgentToolUpdateCallback<BashToolDetails>;
 		startBackgrounded: boolean;
+		onCompletion?: () => void;
 		/** Immutable attempt-scoped tool call id, when executed via a tool call. */
 		toolCallId?: string;
 	}): ManagedBashJobHandle {
@@ -783,7 +990,11 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			throw new ToolError("Background job manager unavailable for this session.");
 		}
 
-		const label = options.command.length > 120 ? `${options.command.slice(0, 117)}...` : options.command;
+		const label = options.directMasterSpawn
+			? "gjc sdk spawn"
+			: options.command.length > 120
+				? `${options.command.slice(0, 117)}...`
+				: options.command;
 		let latestText = "";
 		let backgrounded = options.startBackgrounded;
 		const runningDetails = (jobId: string): Record<string, unknown> | undefined =>
@@ -806,37 +1017,37 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 
 				let executionResult: BashResult | BashInteractiveResult | undefined;
 				try {
-					const result = await executeBash(options.command, {
-						cwd: options.commandCwd,
-						settings: this.session.settings,
-						sessionKey: `${this.session.getSessionId?.() ?? ""}:async:${jobId}`,
-						timeout: options.timeoutMs,
-						signal: runSignal,
-						env: options.resolvedEnv,
-						artifactPath,
-						artifactId,
-						artifactPublisher,
-						spillThreshold,
-						headBytes,
-						oneShot: true,
-						ignoreShellPrefix: this.session.bashRestrictionProfile === "read-only",
-						disableShellSnapshot: this.session.bashRestrictionProfile === "read-only",
-						onChunk: chunk => {
-							tailBuffer.append(chunk);
-							latestText = tailBuffer.text();
-							void reportProgress(latestText, runningDetails(jobId));
-						},
-						onRawChunk: chunk => {
-							// Forward the unthrottled sanitized chunk to the async-job
-							// substrate so the Monitor tool can read the complete process
-							// stream by byte offset, independent of the throttled preview
-							// path above.
-							manager.appendOutput(jobId, chunk);
-						},
-						onMinimizedSave: async originalText => {
-							return saveBashOriginalArtifact(this.session, originalText);
-						},
-					});
+					const result = options.directMasterSpawn
+						? await this.#runDirectMasterSpawn(
+								options.command,
+								options.commandCwd,
+								options.timeoutMs,
+								runSignal,
+								options.resolvedEnv,
+							)
+						: await executeBash(options.command, {
+								cwd: options.commandCwd,
+								settings: this.session.settings,
+								sessionKey: `${this.session.getSessionId?.() ?? ""}:async:${jobId}`,
+								timeout: options.timeoutMs,
+								signal: runSignal,
+								env: options.resolvedEnv,
+								artifactPath,
+								artifactId,
+								artifactPublisher,
+								spillThreshold,
+								headBytes,
+								oneShot: true,
+								ignoreShellPrefix: this.session.bashRestrictionProfile === "read-only",
+								disableShellSnapshot: this.session.bashRestrictionProfile === "read-only",
+								onChunk: chunk => {
+									tailBuffer.append(chunk);
+									latestText = tailBuffer.text();
+									void reportProgress(latestText, runningDetails(jobId));
+								},
+								onRawChunk: chunk => manager.appendOutput(jobId, chunk),
+								onMinimizedSave: async originalText => saveBashOriginalArtifact(this.session, originalText),
+							});
 					executionResult = result;
 					const finalResult = this.#buildCompletedResult(result, options.timeoutSec, {
 						requestedTimeoutSec: options.requestedTimeoutSec,
@@ -845,12 +1056,14 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 					});
 					const finalText = this.#extractTextResult(finalResult);
 					latestText = finalText;
+					options.onCompletion?.();
 					completion.resolve({ kind: "completed", result: finalResult });
 					await reportProgress(finalText, completedDetails(jobId));
 					return finalText;
 				} catch (error) {
 					const message = error instanceof Error ? error.message : String(error);
 					latestText = message;
+					options.onCompletion?.();
 					completion.resolve({ kind: "failed", error, result: executionResult });
 					await reportProgress(message, failedDetails(jobId));
 					throw error;
@@ -867,6 +1080,11 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 				},
 			},
 		);
+		const jobGeneration = manager.getJob(jobId)?.generation ?? jobId;
+		const unregisterOwnerCleanup = manager.registerOwnerCleanup(this.session.getAgentId?.() ?? "0-Main", () => {
+			manager.failNow(jobId, jobGeneration, "Bash job owner was torn down.");
+		});
+		void completion.promise.finally(unregisterOwnerCleanup);
 		registerOwnedIfLineaged(manager, options.toolCallId, jobId, this.session.getSessionId?.() ?? undefined);
 
 		return {
@@ -893,9 +1111,8 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 	 */
 	#resolveOwnedJobManager(): AsyncJobManager | undefined {
 		const endpointId = this.session.getSessionId?.() ?? undefined;
-		return (
-			this.session.getAsyncJobManager?.() ?? AsyncJobManager.forEndpoint(endpointId) ?? AsyncJobManager.instance()
-		);
+		if (this.session.getAsyncJobManager) return this.session.getAsyncJobManager();
+		return AsyncJobManager.forEndpoint(endpointId) ?? AsyncJobManager.instance();
 	}
 
 	async #waitForManagedBashJob(
@@ -953,6 +1170,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		command: string;
 		commandCwd: string;
 		resolvedEnv: Record<string, string>;
+		directMasterSpawn: boolean;
 		requestedTimeoutSec: number;
 		timeoutSec: number;
 		timeoutMs: number;
@@ -1098,14 +1316,26 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		// silently ignore the caller's override.
 		const explicitAgentDirOverride =
 			expandedEnv?.GJC_CODING_AGENT_DIR !== undefined || expandedEnv?.PI_CODING_AGENT_DIR !== undefined;
+		// The master capability is a one-shot authority for the direct spawn CLI,
+		// never ambient state for ordinary Bash or a chained/pipelined descendant.
+		// Check both spellings so cwd normalization or URL expansion cannot turn a
+		// command that contained shell syntax into a privileged one.
+		const directMasterSpawn = isStrictDirectSdkSpawnCommand(rawCommand) && isStrictDirectSdkSpawnCommand(command);
+		const masterCapability = directMasterSpawn ? this.session.getMasterBashCapability?.() : undefined;
+		const masterOwnerSessionId = directMasterSpawn ? this.session.getMasterOwnerSessionId?.() : undefined;
+		const commandEnvOverrides = masterCommandEnvOverrides(expandedEnv, directMasterSpawn);
 		const resolvedEnv = {
 			...buildGjcRuntimeSessionEnv({
 				sessionFile: null,
 				sessionId: this.session.getSessionId?.(),
 				cwd: this.session.cwd,
 			}),
-			...(sessionAgentDir && !explicitAgentDirOverride ? { GJC_CODING_AGENT_DIR: sessionAgentDir } : {}),
-			...expandedEnv,
+			...(sessionAgentDir && (!explicitAgentDirOverride || directMasterSpawn)
+				? { GJC_CODING_AGENT_DIR: sessionAgentDir }
+				: {}),
+			...commandEnvOverrides,
+			...(masterCapability ? { [MASTER_CAPABILITY_ENV]: masterCapability } : {}),
+			...(masterOwnerSessionId ? { GJC_MASTER_OWNER_SESSION_ID: masterOwnerSessionId } : {}),
 			...(this.session.bashRestrictionProfile === "read-only" ? READ_ONLY_BASH_ENV : {}),
 			...(allowedPrefixes && allowedPrefixes.length > 0 ? { [GJC_RESTRICTED_ROLE_AGENT_BASH_ENV]: "1" } : {}),
 		};
@@ -1137,7 +1367,80 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		const sleepAdvisory = longSleepAdvisory(command, timeoutSec);
 		if (sleepAdvisory) notices.push(sleepAdvisory);
 
-		return { command, commandCwd, resolvedEnv, requestedTimeoutSec, timeoutSec, timeoutMs, notices };
+		return {
+			command,
+			commandCwd,
+			resolvedEnv,
+			directMasterSpawn,
+			requestedTimeoutSec,
+			timeoutSec,
+			timeoutMs,
+			notices,
+		};
+	}
+
+	async #runDirectMasterSpawn(
+		command: string,
+		commandCwd: string,
+		timeoutMs: number,
+		signal: AbortSignal | undefined,
+		resolvedEnv: Record<string, string> | undefined,
+	): Promise<BashResult> {
+		const masterCapability = resolvedEnv?.[MASTER_CAPABILITY_ENV];
+		const sessionAgentDir = resolvedEnv?.GJC_CODING_AGENT_DIR;
+		if (masterCapability === undefined || sessionAgentDir === undefined)
+			throw new ToolError("Master spawn authority context is unavailable.");
+		const args = parseDirectSdkSpawnArgs(command);
+		args.agentDir = sessionAgentDir;
+		if (args.cwd !== undefined && !path.isAbsolute(args.cwd)) args.cwd = path.resolve(commandCwd, args.cwd);
+		const request = runSdkSpawn(args, {
+			env: {
+				...process.env,
+				GJC_MASTER_CAPABILITY: masterCapability,
+				GJC_SESSION_ID: resolvedEnv?.GJC_MASTER_OWNER_SESSION_ID ?? this.session.getSessionId?.() ?? undefined,
+				GJC_CODING_AGENT_DIR: sessionAgentDir,
+			},
+		});
+		const timeout = Bun.sleep(timeoutMs).then(() => {
+			throw new ToolError(`Command timed out after ${Math.ceil(timeoutMs / 1000)} seconds`);
+		});
+		const aborted = Promise.withResolvers<never>();
+		const onAbort = (): void => aborted.reject(new ToolAbortError("Command aborted"));
+		if (signal?.aborted) onAbort();
+		else signal?.addEventListener("abort", onAbort, { once: true });
+		let result: Awaited<typeof request>;
+		try {
+			result = await Promise.race([request, timeout, aborted.promise]);
+		} finally {
+			signal?.removeEventListener("abort", onAbort);
+		}
+		const output = args.json ? JSON.stringify(result.rendered) : renderSpawnTable(result.rendered);
+		const outputBytes = Buffer.byteLength(output, "utf8");
+		const outputLines = output.split("\n").length;
+		return {
+			output,
+			exitCode: result.exitCode,
+			cancelled: false,
+			truncated: false,
+			totalLines: outputLines,
+			totalBytes: outputBytes,
+			outputLines,
+			outputBytes,
+		};
+	}
+
+	async #executeDirectMasterSpawn(
+		command: string,
+		commandCwd: string,
+		timeoutSec: number,
+		timeoutMs: number,
+		requestedTimeoutSec: number,
+		notices: readonly string[],
+		signal: AbortSignal | undefined,
+		resolvedEnv: Record<string, string>,
+	): Promise<AgentToolResult<BashToolDetails>> {
+		const result = await this.#runDirectMasterSpawn(command, commandCwd, timeoutMs, signal, resolvedEnv);
+		return this.#buildCompletedResult(result, timeoutSec, { requestedTimeoutSec, notices });
 	}
 
 	/**
@@ -1165,6 +1468,9 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		if (!manager) {
 			throw new ToolError("Async job manager unavailable for this session.");
 		}
+		if (!manager.hasCapacity()) {
+			throw new ToolError("Background job limit reached. Wait for running jobs to finish or cancel one.");
+		}
 		const prepared = await this.#prepareBashExecution(input, opts.ctx);
 		const label =
 			opts.label ?? (prepared.command.length > 120 ? `${prepared.command.slice(0, 117)}...` : prepared.command);
@@ -1232,8 +1538,9 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 						spillThreshold,
 						headBytes,
 						oneShot: true,
-						ignoreShellPrefix: this.session.bashRestrictionProfile === "read-only",
-						disableShellSnapshot: this.session.bashRestrictionProfile === "read-only",
+						ignoreShellPrefix: this.session.bashRestrictionProfile === "read-only" || prepared.directMasterSpawn,
+						disableShellSnapshot:
+							this.session.bashRestrictionProfile === "read-only" || prepared.directMasterSpawn,
 						onChunk: chunk => {
 							tailBuffer.append(chunk);
 							void reportProgress(tailBuffer.text(), {
@@ -1289,6 +1596,13 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		if (this.session.bashRestrictionProfile === "read-only" && pty) {
 			throw new ToolError("Read-only bash does not allow PTY mode.");
 		}
+		const admissionManager = this.#resolveOwnedJobManager();
+		if (asyncRequested && !admissionManager) {
+			throw new ToolError("Async job manager unavailable for this session.");
+		}
+		if (admissionManager && !admissionManager.hasCapacity()) {
+			throw new ToolError("Background job limit reached. Wait for running jobs to finish or cancel one.");
+		}
 
 		const prepared = await this.#prepareBashExecution(
 			{ command: rawCommand, env: rawEnv, timeout: rawTimeout, cwd },
@@ -1298,18 +1612,33 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			command,
 			commandCwd,
 			resolvedEnv,
+			directMasterSpawn,
 			requestedTimeoutSec,
 			timeoutSec,
 			timeoutMs,
 			notices: pendingNotices,
 		} = prepared;
+		const masterCapability = directMasterSpawn ? resolvedEnv[MASTER_CAPABILITY_ENV] : undefined;
+		if (directMasterSpawn && masterCapability !== undefined && !asyncRequested) {
+			return await this.#executeDirectMasterSpawn(
+				command,
+				commandCwd,
+				timeoutSec,
+				timeoutMs,
+				requestedTimeoutSec,
+				pendingNotices,
+				signal,
+				resolvedEnv,
+			);
+		}
 
 		if (asyncRequested) {
 			// Availability is endpoint-first: a concurrent top-level session
 			// that was the process-global instance may have been disposed,
 			// clearing instance() while THIS session's manager stays
 			// registered by endpoint (review thread P1).
-			if (!this.#resolveOwnedJobManager()) {
+			const asyncManager = admissionManager ?? this.#resolveOwnedJobManager();
+			if (!asyncManager) {
 				throw new ToolError("Async job manager unavailable for this session.");
 			}
 			const job = this.#startManagedBashJob({
@@ -1321,10 +1650,14 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 				notices: pendingNotices,
 
 				resolvedEnv,
+				directMasterSpawn,
 				onUpdate,
 				startBackgrounded: true,
 				toolCallId,
 			});
+			const jobGeneration = asyncManager.getJob(job.jobId)?.generation ?? job.jobId;
+			job.setBackgrounded(true);
+			asyncManager.markBackgrounded(job.jobId, jobGeneration);
 			return this.#buildBackgroundStartResult(job.jobId, job.label, "", timeoutSec, {
 				requestedTimeoutSec,
 				notices: pendingNotices,
@@ -1335,7 +1668,9 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		// Skip when pty=true (PTY needs the local terminal UI).
 		const clientBridge =
 			this.session.bashRestrictionProfile === "read-only" ? undefined : this.session.getClientBridge?.();
-		const clientTerminalActive = Boolean(clientBridge?.capabilities.terminal && clientBridge.createTerminal && !pty);
+		const clientTerminalActive = Boolean(
+			!directMasterSpawn && clientBridge?.capabilities.terminal && clientBridge.createTerminal && !pty,
+		);
 
 		// Run non-PTY bash through the managed job path so Ctrl+B-twice fold-on-demand works
 		// even when auto-background is disabled. When a client terminal will handle the
@@ -1345,13 +1680,17 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		// and unregistering — the process-global instance may belong to a different
 		// concurrent top-level session (review thread P1).
 		const ownedManager = this.#resolveOwnedJobManager();
-		if (!pty && ownedManager && (this.#autoBackgroundEnabled || !clientTerminalActive)) {
+		// The client-terminal path is now itself manager-backed and foldable, so it no
+		// longer has to be bypassed to make folding work. A capable ACP session keeps
+		// its terminal contract and still folds.
+		if (!pty && ownedManager && !clientTerminalActive) {
 			// With auto-background off, wait past the command's own timeout so the job only
 			// leaves the foreground on an explicit Ctrl+B fold, never on an auto-background timer.
 			const autoBackgroundWaitMs = this.#autoBackgroundEnabled
 				? this.#resolveAutoBackgroundWaitMs(timeoutMs)
 				: timeoutMs + 1_000;
 			const startBackgrounded = autoBackgroundWaitMs === 0;
+			let managedForegroundSettled = false;
 			const job = this.#startManagedBashJob({
 				command,
 				commandCwd,
@@ -1361,20 +1700,62 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 				notices: pendingNotices,
 
 				resolvedEnv,
+				directMasterSpawn,
 				onUpdate,
 				startBackgrounded,
+				onCompletion: () => {
+					managedForegroundSettled = true;
+				},
 				toolCallId,
 			});
+			const jobGeneration = ownedManager.getJob(job.jobId)?.generation ?? job.jobId;
 			if (startBackgrounded) {
+				job.setBackgrounded(true);
+				ownedManager.markBackgrounded(job.jobId, jobGeneration);
 				return this.#buildBackgroundStartResult(job.jobId, job.label, "", timeoutSec, {
 					requestedTimeoutSec,
 					notices: pendingNotices,
 				});
 			}
 			const backgroundRequest = Promise.withResolvers<void>();
-			const unregisterBackgroundRequest = this.session.registerForegroundBashBackgroundRequestHandler?.(() => {
-				job.setBackgrounded(true);
-				backgroundRequest.resolve();
+			// Exactly one party may settle the foreground caller. detachObserver (the
+			// fold won) and resolveForegroundObserver (a completion was handed back
+			// after a failed fold) share this flag, so a race cannot double-settle.
+			let foregroundSettled = false;
+			const settleForeground = (): "resolved" | "already-settled" => {
+				if (foregroundSettled || managedForegroundSettled) return "already-settled";
+				foregroundSettled = true;
+				return "resolved";
+			};
+			const unregisterBackgroundRequest = this.session.registerForegroundFoldParticipant?.({
+				kind: "bash-managed",
+				jobId: job.jobId,
+				jobGeneration,
+				label: job.label,
+				cwdSensitive: true,
+				signal,
+				originatingTurn: ctx?.attemptScope !== undefined,
+				outputRef: {
+					jobId: job.jobId,
+					generation: jobGeneration,
+					instruction: `Use the job tool's tail operation for ${job.jobId} to read this command's output.`,
+				},
+				// Bound at registration over the manager that registered THIS job, so
+				// identity can never resolve to another manager's identically-named job.
+				getJob: () => {
+					const current = ownedManager.getJob(job.jobId);
+					return current?.generation === jobGeneration ? current : undefined;
+				},
+				detachObserver: () => {
+					const outcome = settleForeground();
+					if (outcome === "resolved") {
+						job.setBackgrounded(true);
+						ownedManager.markBackgrounded(job.jobId, jobGeneration);
+						backgroundRequest.resolve();
+					}
+					return outcome;
+				},
+				resolveForegroundObserver: () => settleForeground(),
 			});
 			let waitResult: ManagedBashJobCompletion | { kind: "running" } | { kind: "aborted" };
 			try {
@@ -1410,6 +1791,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 				throw new ToolAbortError(formatManagedAbortFailure(undefined, undefined, job.getLatestText()));
 			}
 			job.setBackgrounded(true);
+			ownedManager.markBackgrounded(job.jobId, jobGeneration);
 			return this.#buildBackgroundStartResult(job.jobId, job.label, job.getLatestText(), timeoutSec, {
 				requestedTimeoutSec,
 				notices: pendingNotices,
@@ -1417,63 +1799,200 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		}
 
 		if (clientBridge?.capabilities.terminal && clientBridge.createTerminal && !pty) {
+			const clientAdmission = ownedManager?.reserveCapacity();
 			const clientHeadBytes = resolveBashOutputSinkHeadBytes(this.session.settings);
 			const clientTailBytes = resolveBashOutputSinkTailBytes(this.session.settings);
-			const handle = await clientBridge.createTerminal({
-				command,
-				cwd: commandCwd,
-				env: resolvedEnv
-					? Object.entries(resolvedEnv).map(([name, value]) => ({ name, value: value as string }))
-					: undefined,
-				outputByteLimit: clientHeadBytes > 0 ? undefined : clientTailBytes,
-			});
-
-			// Emit partial update so the editor can embed the live terminal card.
-			onUpdate?.({ content: [], details: { terminalId: handle.terminalId } });
-
-			const exitPromise = handle.waitForExit();
-			let exitStatus!: ClientBridgeTerminalExitStatus;
-
-			type BridgeRaceResult =
-				| { kind: "exit"; status: ClientBridgeTerminalExitStatus }
-				| { kind: "poll" }
+			const runBoundedCleanup = async (
+				terminal: ClientBridgeTerminalHandle,
+				operation: () => Promise<void>,
+				label: "kill" | "release",
+			): Promise<void> => {
+				const attempt = Promise.resolve()
+					.then(operation)
+					.catch((error: unknown) => {
+						logger.warn(`ACP terminal ${label} failed`, { terminalId: terminal.terminalId, error });
+					});
+				const completed = await Promise.race([
+					attempt.then(() => true),
+					Bun.sleep(ACP_RELEASE_TIMEOUT_MS).then(() => false),
+				]);
+				if (!completed) logger.warn(`ACP terminal ${label} timed out`, { terminalId: terminal.terminalId });
+			};
+			const createPromise = Promise.resolve().then(() =>
+				clientBridge.createTerminal!({
+					command,
+					cwd: commandCwd,
+					env: resolvedEnv
+						? Object.entries(resolvedEnv).map(([name, value]) => ({ name, value: value as string }))
+						: undefined,
+					outputByteLimit: clientHeadBytes > 0 ? undefined : clientTailBytes,
+				}),
+			);
+			const timeout = Promise.withResolvers<{ kind: "timeout" }>();
+			const abort = Promise.withResolvers<{ kind: "aborted" }>();
+			const onCreateAbort = (): void => abort.resolve({ kind: "aborted" });
+			if (signal?.aborted) onCreateAbort();
+			else signal?.addEventListener("abort", onCreateAbort, { once: true });
+			const createTimer = setTimeout(() => timeout.resolve({ kind: "timeout" }), timeoutMs);
+			let createOutcome:
+				| { kind: "created"; handle: ClientBridgeTerminalHandle }
 				| { kind: "timeout" }
 				| { kind: "aborted" };
+			try {
+				createOutcome = await Promise.race([
+					createPromise.then(handle => ({ kind: "created" as const, handle })),
+					timeout.promise,
+					abort.promise,
+				]);
+			} catch (error) {
+				if (clientAdmission) ownedManager?.releaseCapacity(clientAdmission);
+				throw error;
+			} finally {
+				clearTimeout(createTimer);
+				signal?.removeEventListener("abort", onCreateAbort);
+			}
+
+			if (createOutcome.kind !== "created") {
+				void createPromise
+					.then(async lateHandle => {
+						await runBoundedCleanup(lateHandle, () => lateHandle.kill(), "kill");
+						await runBoundedCleanup(lateHandle, () => lateHandle.release(), "release");
+					})
+					.catch((error: unknown) => {
+						logger.warn("ACP terminal late create cleanup failed", { error });
+					});
+				if (clientAdmission) ownedManager?.releaseCapacity(clientAdmission);
+				if (createOutcome.kind === "aborted") throw new ToolAbortError("Command aborted");
+				throw new ToolError(`Command timed out after ${timeoutSec} seconds`);
+			}
+
+			let handle: ClientBridgeTerminalHandle;
+			handle = createOutcome.handle;
 
-			// Set up abort listener before entering the poll loop. The listener
-			// kicks off `handle.kill()` synchronously so a `session/cancel`
-			// arriving mid-poll terminates the remote command immediately,
-			// instead of waiting for the next `currentOutput()` to return.
-			const { promise: abortedP, resolve: resolveAborted } = Promise.withResolvers<void>();
+			// The remote terminal is released exactly once, by whichever path settles
+			// it: a foreground return, a folded background completion, or a failure.
+			let released = false;
+			const releaseTerminalOnce = async (): Promise<void> => {
+				if (released) return;
+				released = true;
+				await runBoundedCleanup(handle, () => handle.release(), "release");
+			};
 			let killPromise: Promise<void> | undefined;
 			const fireKill = (): Promise<void> => {
 				if (killPromise) return killPromise;
-				killPromise = handle.kill().catch((error: unknown) => {
+				try {
+					killPromise = Promise.resolve(handle.kill()).catch((error: unknown) => {
+						logger.warn("ACP terminal kill failed", { terminalId: handle.terminalId, error });
+					});
+				} catch (error) {
 					logger.warn("ACP terminal kill failed", { terminalId: handle.terminalId, error });
-				});
+					killPromise = Promise.resolve();
+				}
 				return killPromise;
 			};
-			const onAbortSignal = () => {
-				resolveAborted();
-				void fireKill();
+			const boundedKill = async (): Promise<void> => {
+				await runBoundedCleanup(handle, fireKill, "kill");
 			};
-			signal?.addEventListener("abort", onAbortSignal, { once: true });
 
+			// Emit partial update so the editor can embed the live terminal card.
 			try {
+				onUpdate?.({ content: [], details: { terminalId: handle.terminalId } });
+			} catch (error) {
+				await boundedKill();
+				await releaseTerminalOnce();
+				if (clientAdmission) ownedManager?.releaseCapacity(clientAdmission);
+				throw error;
+			}
+			let latestText = "";
+			let bridgeJobId!: string;
+			let bridgeBackgrounded = false;
+			let retainedAcpSnapshot = "";
+			let retainedAcpTruncated = false;
+			const ACP_RAW_OVERLAP_BYTES = 512 * 1024;
+			const appendAcpSnapshot = (snapshot: string, upstreamTruncated = false): void => {
+				retainedAcpTruncated ||= upstreamTruncated;
+				if (!snapshot) return;
+				const snapshotBytes = Buffer.byteLength(snapshot, "utf8");
+				const retainedBytes = Buffer.byteLength(retainedAcpSnapshot, "utf8");
+				const boundedSnapshot =
+					snapshotBytes > ACP_RAW_OVERLAP_BYTES
+						? sliceTextAfterUtf8ByteOffset(snapshot, snapshotBytes - ACP_RAW_OVERLAP_BYTES)
+						: snapshot;
+				const boundedRetained =
+					retainedBytes > ACP_RAW_OVERLAP_BYTES
+						? sliceTextAfterUtf8ByteOffset(retainedAcpSnapshot, retainedBytes - ACP_RAW_OVERLAP_BYTES)
+						: retainedAcpSnapshot;
+				const overlap = suffixPrefixOverlap(boundedRetained, boundedSnapshot);
+				const delta = boundedSnapshot.slice(overlap);
+				if (bridgeJobId && delta) ownedManager?.appendOutput(bridgeJobId, delta);
+				retainedAcpSnapshot = boundedSnapshot;
+				retainedAcpTruncated ||= snapshotBytes > ACP_RAW_OVERLAP_BYTES;
+			};
+			const retainedAcpOutput = (): ClientBridgeTerminalOutput => ({
+				output: retainedAcpSnapshot,
+				truncated: retainedAcpTruncated,
+			});
+
+			const runToCompletion = async (
+				runSignal: AbortSignal | undefined,
+			): Promise<AgentToolResult<BashToolDetails>> => {
+				type BridgeRaceResult =
+					| { kind: "exit"; status: ClientBridgeTerminalExitStatus }
+					| { kind: "wait-failed"; error: unknown }
+					| { kind: "poll" }
+					| { kind: "timeout" }
+					| { kind: "aborted" };
+				const exitPromise = Promise.resolve().then(() => handle.waitForExit());
+				const exitRacePromise: Promise<BridgeRaceResult> = exitPromise.then(
+					status => ({ kind: "exit" as const, status }),
+					error => ({ kind: "wait-failed" as const, error }),
+				);
+				let exitStatus!: ClientBridgeTerminalExitStatus;
+
+				// Set up abort listener before entering the poll loop. The listener
+				// kicks off `handle.kill()` synchronously so a `session/cancel`
+				// arriving mid-poll terminates the remote command immediately,
+				// instead of waiting for the next `currentOutput()` to return.
+				const { promise: abortedP, resolve: resolveAborted } = Promise.withResolvers<void>();
+				const deadlineAt = Date.now() + timeoutMs;
+				const readOutput = async (
+					limitMs: number,
+					includeAbort = true,
+					includeExit = false,
+				): Promise<ClientBridgeTerminalOutput | undefined> => {
+					const timeout = Promise.withResolvers<undefined>();
+					const timer = setTimeout(() => timeout.resolve(undefined), Math.max(1, limitMs));
+					return Promise.race([
+						handle.currentOutput(),
+						...(includeAbort ? [abortedP.then(() => undefined as ClientBridgeTerminalOutput | undefined)] : []),
+						...(includeExit
+							? [exitRacePromise.then(() => undefined as ClientBridgeTerminalOutput | undefined)]
+							: []),
+						timeout.promise,
+					]).finally(() => clearTimeout(timer));
+				};
+				const onAbortSignal = () => {
+					resolveAborted();
+					void fireKill();
+				};
+				runSignal?.addEventListener("abort", onAbortSignal, { once: true });
+
 				try {
-					if (signal?.aborted) {
-						await fireKill();
+					if (runSignal?.aborted) {
+						await boundedKill();
 						let current: ClientBridgeTerminalOutput = { output: "", truncated: false };
 						let readDiagnostic: string | undefined;
 						try {
-							current = await handle.currentOutput();
+							current = (await readOutput(1_000, false)) ?? retainedAcpOutput();
 						} catch (error) {
+							current = retainedAcpOutput();
 							readDiagnostic = boundArtifactSaveDiagnostic(error);
 							logger.warn("ACP terminal aborted output read failed", {
 								terminalId: handle.terminalId,
 								error,
 							});
 						}
+						appendAcpSnapshot(current.output, current.truncated);
 						const prepared = await prepareClientTerminalOutput(this.session, current);
 						throw new ToolAbortError(formatClientTerminalAbortFailure(prepared, readDiagnostic, pendingNotices));
 					}
@@ -1482,51 +2001,81 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 					// Poll until the process exits, times out, or the caller aborts.
 					for (;;) {
 						const racers: Array<Promise<BridgeRaceResult>> = [
-							exitPromise.then(s => ({ kind: "exit" as const, status: s })),
+							exitRacePromise,
 							timeoutPromise,
 							Bun.sleep(250).then(() => ({ kind: "poll" as const })),
 						];
-						if (signal) {
+						if (runSignal) {
 							racers.push(abortedP.then(() => ({ kind: "aborted" as const })));
 						}
 						const raced = await Promise.race(racers);
 
-						if (raced.kind === "aborted" || signal?.aborted) {
-							await fireKill();
+						if (raced.kind === "aborted" || runSignal?.aborted) {
+							await boundedKill();
 							let current: ClientBridgeTerminalOutput = { output: "", truncated: false };
 							let readDiagnostic: string | undefined;
 							try {
-								current = await handle.currentOutput();
+								current = (await readOutput(1_000, false)) ?? retainedAcpOutput();
 							} catch (error) {
+								current = retainedAcpOutput();
 								readDiagnostic = boundArtifactSaveDiagnostic(error);
 								logger.warn("ACP terminal aborted output read failed", {
 									terminalId: handle.terminalId,
 									error,
 								});
 							}
+							appendAcpSnapshot(current.output, current.truncated);
 							const prepared = await prepareClientTerminalOutput(this.session, current);
 							throw new ToolAbortError(
 								formatClientTerminalAbortFailure(prepared, readDiagnostic, pendingNotices),
 							);
 						}
 
+						if (raced.kind === "wait-failed") {
+							await boundedKill();
+							let current: ClientBridgeTerminalOutput = { output: "", truncated: false };
+							let readDiagnostic: string | undefined;
+							try {
+								current = (await readOutput(1_000, false)) ?? retainedAcpOutput();
+							} catch (error) {
+								current = retainedAcpOutput();
+								readDiagnostic = boundArtifactSaveDiagnostic(error);
+								logger.warn("ACP terminal output recovery after wait failure failed", {
+									terminalId: handle.terminalId,
+									error,
+								});
+							}
+							appendAcpSnapshot(current.output, current.truncated);
+							const prepared = await prepareClientTerminalOutput(this.session, current);
+							throw new ToolError(
+								formatClientTerminalWaitFailure(
+									prepared,
+									boundArtifactSaveDiagnostic(raced.error),
+									readDiagnostic,
+									pendingNotices,
+								),
+							);
+						}
+
 						if (raced.kind === "timeout") {
 							// Kill before reading final output so a slow `terminal/output`
 							// RPC cannot let a timed-out command keep running past the
 							// enforced timeout. The handle stays valid post-kill so the
 							// buffered output is still readable.
-							await fireKill();
+							await boundedKill();
 							let current: ClientBridgeTerminalOutput = { output: "", truncated: false };
 							let readDiagnostic: string | undefined;
 							try {
-								current = await handle.currentOutput();
+								current = (await readOutput(1_000, false)) ?? retainedAcpOutput();
 							} catch (error) {
+								current = retainedAcpOutput();
 								readDiagnostic = boundArtifactSaveDiagnostic(error);
 								logger.warn("ACP terminal final output read failed", {
 									terminalId: handle.terminalId,
 									error,
 								});
 							}
+							appendAcpSnapshot(current.output, current.truncated);
 							const prepared = await prepareClientTerminalOutput(this.session, current);
 							const timeoutNotices = [
 								...pendingNotices,
@@ -1555,13 +2104,24 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 						// Poll tick: push current output so agent-loop transcript stays consistent.
 						// Race the read against abort so a stuck `terminal/output` RPC does not
 						// delay cancellation.
-						const pollOutput = await Promise.race([
-							handle.currentOutput(),
-							abortedP.then(() => undefined as ClientBridgeTerminalOutput | undefined),
-						]);
+						let pollOutput: ClientBridgeTerminalOutput | undefined;
+						try {
+							pollOutput = await readOutput(Math.max(1, deadlineAt - Date.now()), true, true);
+						} catch (error) {
+							await boundedKill();
+							const diagnostic = boundArtifactSaveDiagnostic(error);
+							const recoveredOutput = retainedAcpOutput();
+							appendAcpSnapshot(recoveredOutput.output, recoveredOutput.truncated);
+							const prepared = await prepareClientTerminalOutput(this.session, recoveredOutput);
+							logger.warn("ACP terminal poll output read failed", {
+								terminalId: handle.terminalId,
+								error,
+							});
+							throw new ToolError(formatClientTerminalReadFailure(prepared, diagnostic, pendingNotices));
+						}
 						if (pollOutput === undefined) {
 							// Abort fired during the poll-tick read; let the next loop iteration
-							// observe `signal?.aborted` and exit via the abort branch.
+							// observe `runSignal?.aborted` and exit via the abort branch.
 							continue;
 						}
 						const { summary, locallyTruncated } = await boundClientTerminalOutput(
@@ -1573,40 +2133,80 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 							pollOutput.truncated || locallyTruncated
 								? `${summary.output}${summary.output.endsWith("\n") ? "" : "\n"}(output truncated)`
 								: summary.output;
-						onUpdate?.({
-							content: [{ type: "text", text: pollText }],
-							details: { terminalId: handle.terminalId },
-						});
+						latestText = pollText;
+						appendAcpSnapshot(pollOutput.output, pollOutput.truncated);
+						if (!bridgeBackgrounded) {
+							try {
+								onUpdate?.({
+									content: [{ type: "text", text: pollText }],
+									details: { terminalId: handle.terminalId },
+								});
+							} catch (error) {
+								await boundedKill();
+								const diagnostic = boundArtifactSaveDiagnostic(error);
+								const recoveredOutput = retainedAcpOutput();
+								const prepared = await prepareClientTerminalOutput(this.session, recoveredOutput);
+								throw new ToolError(formatClientTerminalReadFailure(prepared, diagnostic, pendingNotices));
+							}
+						}
 					}
 				} finally {
-					signal?.removeEventListener("abort", onAbortSignal);
+					runSignal?.removeEventListener("abort", onAbortSignal);
 				}
 
-				if (signal?.aborted) {
-					await fireKill();
+				if (runSignal?.aborted) {
+					await boundedKill();
 					let current: ClientBridgeTerminalOutput = { output: "", truncated: false };
 					let readDiagnostic: string | undefined;
 					try {
-						current = await handle.currentOutput();
+						current = (await readOutput(1_000, false)) ?? retainedAcpOutput();
 					} catch (error) {
+						current = retainedAcpOutput();
 						readDiagnostic = boundArtifactSaveDiagnostic(error);
 						logger.warn("ACP terminal aborted output read failed", {
 							terminalId: handle.terminalId,
 							error,
 						});
 					}
+					appendAcpSnapshot(current.output, current.truncated);
 					const prepared = await prepareClientTerminalOutput(this.session, current);
 					throw new ToolAbortError(formatClientTerminalAbortFailure(prepared, readDiagnostic, pendingNotices));
 				}
 
 				// Fetch final output; the terminal is released in the outer finally.
-				const finalOutput = await handle.currentOutput();
+				let finalReadDiagnostic: string | undefined;
+				let finalOutput: ClientBridgeTerminalOutput;
+				try {
+					const recovered = await readOutput(1_000, false);
+					if (recovered === undefined) {
+						finalOutput = retainedAcpOutput();
+						finalReadDiagnostic = "terminal/output read timed out";
+					} else {
+						finalOutput = recovered;
+					}
+				} catch (error) {
+					finalOutput = retainedAcpOutput();
+					finalReadDiagnostic = boundArtifactSaveDiagnostic(error);
+					logger.warn("ACP terminal final output read failed", {
+						terminalId: handle.terminalId,
+						error,
+					});
+				}
+				if (runSignal?.aborted) {
+					await boundedKill();
+					appendAcpSnapshot(finalOutput.output, finalOutput.truncated);
+					const prepared = await prepareClientTerminalOutput(this.session, finalOutput);
+					throw new ToolAbortError(
+						formatClientTerminalAbortFailure(prepared, finalReadDiagnostic, pendingNotices),
+					);
+				}
 
 				// Map exit status: null exitCode with a signal → treat as signal kill (137).
 				const rawExitCode = exitStatus.exitCode;
 				const exitCode: number | undefined =
 					rawExitCode != null ? rawExitCode : exitStatus.signal ? 137 : undefined;
 
+				appendAcpSnapshot(finalOutput.output, finalOutput.truncated);
 				const prepared = await prepareClientTerminalOutput(this.session, finalOutput);
 
 				const bridgeResult: BashResult = {
@@ -1619,19 +2219,188 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 				if (finalOutput.truncated || prepared.locallyTruncated) bridgeNotices.push("(output truncated)");
 				for (const notice of pendingNotices) bridgeNotices.push(notice);
 				if (prepared.artifactSaveNotice) bridgeNotices.push(prepared.artifactSaveNotice);
+				if (finalReadDiagnostic) bridgeNotices.push(`Terminal output recovery failed: ${finalReadDiagnostic}`);
 
 				return this.#buildCompletedResult(bridgeResult, timeoutSec, {
 					requestedTimeoutSec,
 					notices: bridgeNotices,
 					terminalId: handle.terminalId,
 				});
-			} finally {
+			};
+
+			// Without a job manager nothing can fold this, so ownership never leaves the
+			// foreground call.
+			if (!ownedManager) {
 				try {
-					await handle.release();
-				} catch (error) {
-					logger.warn("ACP terminal release failed", { terminalId: handle.terminalId, error });
+					return await runToCompletion(signal);
+				} finally {
+					await releaseTerminalOnce();
 				}
 			}
+
+			// Manager-backed runner: the remote command keeps running after a fold and
+			// its completion is delivered like any other background job. createTerminal
+			// already ran above, so exactly ONE remote handle exists and is retained
+			// across the fold.
+			const bridgeManager = ownedManager;
+			const bridgeEndpointId = this.session.getSessionId?.() ?? "local";
+			const bridgeLabel = command.length > 120 ? `${command.slice(0, 117)}...` : command;
+			const bridgeCompletion = Promise.withResolvers<ManagedBashJobCompletion>();
+			let bridgeForegroundSettled = false;
+			const settleBridgeForeground = (): "resolved" | "already-settled" => {
+				if (bridgeForegroundSettled) return "already-settled";
+				bridgeForegroundSettled = true;
+				return "resolved";
+			};
+
+			try {
+				bridgeJobId = bridgeManager.register(
+					"bash",
+					bridgeLabel,
+					async ({ jobId, signal: runSignal, reportProgress }) => {
+						try {
+							const result = await runToCompletion(runSignal);
+							const finalText = this.#extractTextResult(result);
+							latestText = finalText;
+							if (!bridgeBackgrounded) settleBridgeForeground();
+							bridgeCompletion.resolve({ kind: "completed", result });
+							await reportProgress(
+								finalText,
+								bridgeBackgrounded ? { async: { state: "completed", jobId, type: "bash" } } : undefined,
+							);
+							return finalText;
+						} catch (error) {
+							const message = error instanceof Error ? error.message : String(error);
+							latestText = message;
+							if (!bridgeBackgrounded) settleBridgeForeground();
+							bridgeCompletion.resolve({ kind: "failed", error });
+							await reportProgress(
+								message,
+								bridgeBackgrounded ? { async: { state: "failed", jobId, type: "bash" } } : undefined,
+							);
+							throw error;
+						} finally {
+							await releaseTerminalOnce();
+						}
+					},
+					{
+						ownerId: this.session.getAgentId?.() ?? undefined,
+						admissionToken: clientAdmission,
+						onProgress: async (text: string) => {
+							latestText = text;
+						},
+					},
+				);
+			} catch (error) {
+				await boundedKill();
+				await releaseTerminalOnce();
+				if (clientAdmission) ownedManager?.releaseCapacity(clientAdmission);
+				throw error;
+			}
+
+			const bridgeGeneration = bridgeManager.getJob(bridgeJobId)?.generation ?? bridgeJobId;
+			// Owner teardown must not swallow a live remote command. failNow is the one
+			// transition that both fails the job AND enqueues its delivery, so the
+			// failure stays visible instead of becoming a cancelled job that delivers
+			// nothing.
+			const unregisterOwnerCleanup = bridgeManager.registerOwnerCleanup(
+				this.session.getAgentId?.() ?? "0-Main",
+				() => {
+					void boundedKill().then(() => releaseTerminalOnce());
+					bridgeManager.failNow(bridgeJobId, bridgeGeneration, "Client terminal owner was torn down.");
+				},
+			);
+
+			const bridgeHandle: ManagedBashJobHandle = {
+				jobId: bridgeJobId,
+				label: bridgeLabel,
+				completion: bridgeCompletion.promise,
+				getLatestText: () => latestText,
+				setBackgrounded: (next: boolean) => {
+					bridgeBackgrounded = next;
+				},
+			};
+			void bridgeHandle.completion.finally(unregisterOwnerCleanup);
+			registerOwnedIfLineaged(bridgeManager, toolCallId, bridgeJobId, bridgeEndpointId);
+
+			const bridgeFoldRequest = Promise.withResolvers<void>();
+			const bridgeOriginatingTurn = ctx?.attemptScope !== undefined;
+			const unregisterBridgeFold = this.session.registerForegroundFoldParticipant?.({
+				kind: "client-terminal",
+				jobId: bridgeJobId,
+				jobGeneration: bridgeGeneration,
+				label: bridgeLabel,
+				cwdSensitive: true,
+				signal,
+				originatingTurn: bridgeOriginatingTurn,
+				outputRef: {
+					jobId: bridgeJobId,
+					generation: bridgeGeneration,
+					instruction: `Use the job tool's tail operation for ${bridgeJobId} to read this command's output.`,
+				},
+				getJob: () => {
+					const current = bridgeManager.getJob(bridgeJobId);
+					return current?.generation === bridgeGeneration ? current : undefined;
+				},
+				detachObserver: () => {
+					const outcome = settleBridgeForeground();
+					if (outcome === "resolved") {
+						bridgeHandle.setBackgrounded(true);
+						bridgeManager.markBackgrounded(bridgeJobId, bridgeGeneration);
+						bridgeFoldRequest.resolve();
+					}
+					return outcome;
+				},
+				resolveForegroundObserver: () => settleBridgeForeground(),
+			});
+
+			let bridgeWait: ManagedBashJobCompletion | { kind: "running" } | { kind: "aborted" };
+			try {
+				bridgeWait = await this.#waitForManagedBashJob(
+					bridgeHandle,
+					this.#autoBackgroundEnabled ? this.#resolveAutoBackgroundWaitMs(timeoutMs) : timeoutMs + 1_000,
+					signal,
+					bridgeFoldRequest.promise,
+				);
+			} finally {
+				unregisterBridgeFold?.();
+			}
+
+			if (bridgeWait.kind === "completed") {
+				unregisterOwnerCleanup();
+				bridgeManager.acknowledgeDeliveries([bridgeJobId]);
+				unregisterForegroundOwnedBash(bridgeManager, bridgeJobId, bridgeEndpointId);
+				return bridgeWait.result;
+			}
+			if (bridgeWait.kind === "failed") {
+				unregisterOwnerCleanup();
+				bridgeManager.acknowledgeDeliveries([bridgeJobId]);
+				unregisterForegroundOwnedBash(bridgeManager, bridgeJobId, bridgeEndpointId);
+				throw bridgeWait.error;
+			}
+			if (bridgeWait.kind === "aborted") {
+				unregisterOwnerCleanup();
+				bridgeManager.cancel(bridgeJobId);
+				const terminal = await bridgeHandle.completion;
+				bridgeManager.acknowledgeDeliveries([bridgeJobId]);
+				unregisterForegroundOwnedBash(bridgeManager, bridgeJobId, bridgeEndpointId);
+				if (terminal.kind === "failed") {
+					throw new ToolAbortError(
+						formatManagedAbortFailure(terminal.error, undefined, bridgeHandle.getLatestText()),
+					);
+				}
+				throw new ToolAbortError(formatManagedAbortFailure(undefined, undefined, bridgeHandle.getLatestText()));
+			}
+
+			// Folded (or auto-backgrounded): the remote terminal keeps running and its
+			// result arrives as a background completion.
+			bridgeHandle.setBackgrounded(true);
+			bridgeManager.markBackgrounded(bridgeJobId, bridgeGeneration);
+			return this.#buildBackgroundStartResult(bridgeJobId, bridgeLabel, bridgeHandle.getLatestText(), timeoutSec, {
+				requestedTimeoutSec,
+				notices: pendingNotices,
+				terminalId: handle.terminalId,
+			});
 		}
 
 		const spillThreshold = resolveBashOutputSinkTailBytes(this.session.settings);
@@ -1645,11 +2414,22 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		const artifactPublisher = createBashArtifactPublisher(this.session);
 
 		const interactiveUi =
-			this.session.bashRestrictionProfile === "read-only"
+			this.session.bashRestrictionProfile === "read-only" || directMasterSpawn
 				? undefined
 				: canUseInteractiveBashPty(pty, ctx)
 					? ctx?.ui
 					: undefined;
+		const ptyAdmission = interactiveUi && ownedManager ? ownedManager.reserveCapacity() : undefined;
+		// A PTY command is foldable too: the runner owns the session, so the fold
+		// registers a job that delivers the run's real outcome after the foreground
+		// has already returned.
+		let ptyFoldUnregister: (() => void) | undefined;
+		let ptyFoldResult: AgentToolResult<BashToolDetails> | undefined;
+		let ptyBackgrounded = false;
+		let lastPtyFoldKeyTime = 0;
+		let ptyJobId!: string;
+		let ptyOutputSeen = false;
+		let ptyOutcome: BashInteractiveResult | undefined;
 		const result: BashResult | BashInteractiveResult = interactiveUi
 			? await runInteractiveBashPty(interactiveUi, {
 					command,
@@ -1663,12 +2443,146 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 					artifactPublisher,
 					spillThreshold,
 					headBytes,
+					onControls: controls => {
+						if (!ownedManager) return;
+						const ptyManager = ownedManager;
+						const ptyLabel = command.length > 120 ? `${command.slice(0, 117)}...` : command;
+						const ptyOwnerId = this.session.getAgentId?.() ?? "0-Main";
+						let ptyKillStarted = false;
+						const killPtyOnce = (): void => {
+							if (ptyKillStarted) return;
+							ptyKillStarted = true;
+							try {
+								controls.kill();
+							} catch (error) {
+								logger.warn("PTY kill failed", {
+									jobId: ptyJobId,
+									error: error instanceof Error ? error.message : String(error),
+								});
+							}
+						};
+						const ownerTeardownText = (): string => {
+							const retained = ptyManager.readOutputSince(ptyJobId, 0, { ownerId: ptyOwnerId });
+							const output = ptyOutcome?.output || retained?.text || "";
+							if (!output && !ptyOutcome) return "PTY job owner was torn down.";
+							const summary = ptyOutcome ? { ...ptyOutcome, output } : interactiveResultFromText(output);
+							const body = [
+								output || "(no output)",
+								...(retained?.truncated && !ptyOutcome?.truncated ? ["(output truncated)"] : []),
+							].join("\n");
+							return formatBashFailureMessage(summary, body, "PTY job owner was torn down.");
+						};
+						// The job's runner simply awaits the run that is ALREADY executing,
+						// so registering never re-executes the command.
+						try {
+							ptyJobId = ptyManager.register(
+								"bash",
+								ptyLabel,
+								async () => {
+									let outcome: BashInteractiveResult | undefined;
+									try {
+										outcome = await controls.terminalCompletion;
+										const completed = this.#buildCompletedResult(outcome, timeoutSec, {
+											requestedTimeoutSec,
+										});
+										return this.#extractTextResult(completed);
+									} finally {
+										if (!ptyOutputSeen && outcome)
+											ptyManager.appendOutput(ptyJobId, this.#formatResultOutput(outcome));
+										if (!ptyBackgrounded) ptyManager.cancel(ptyJobId);
+									}
+								},
+								{
+									ownerId: this.session.getAgentId?.() ?? undefined,
+									admissionToken: ptyAdmission,
+									lifecycle: { onCancel: killPtyOnce },
+								},
+							);
+						} catch (error) {
+							killPtyOnce();
+							if (ptyAdmission) ptyManager.releaseCapacity(ptyAdmission);
+							throw error;
+						}
+						const ptyGeneration = ptyManager.getJob(ptyJobId)?.generation ?? ptyJobId;
+						registerOwnedIfLineaged(ptyManager, toolCallId, ptyJobId, this.session.getSessionId?.() ?? undefined);
+						const unregisterPtyOwnerCleanup = ptyManager.registerOwnerCleanup(ptyOwnerId, () => {
+							killPtyOnce();
+							ptyManager.failNow(ptyJobId, ptyGeneration, ownerTeardownText());
+						});
+						void controls.terminalCompletion.then(
+							outcome => {
+								ptyOutcome = outcome;
+							},
+							(error: unknown) => {
+								logger.warn("PTY terminal completion failed", {
+									jobId: ptyJobId,
+									error: error instanceof Error ? error.message : String(error),
+								});
+							},
+						);
+						void controls.terminalCompletion.finally(unregisterPtyOwnerCleanup);
+						ptyFoldUnregister = this.session.registerForegroundFoldParticipant?.({
+							kind: "bash-pty",
+							jobId: ptyJobId,
+							jobGeneration: ptyGeneration,
+							label: ptyLabel,
+							cwdSensitive: true,
+							signal,
+							originatingTurn: ctx?.attemptScope !== undefined,
+							outputRef: {
+								jobId: ptyJobId,
+								generation: ptyGeneration,
+								instruction: `Use the job tool's tail operation for ${ptyJobId} to read this command's output.`,
+							},
+							getJob: () => {
+								const current = ptyManager.getJob(ptyJobId);
+								return current?.generation === ptyGeneration ? current : undefined;
+							},
+							detachObserver: () => {
+								// Output-only continuation: stdin forwarding ends here and the
+								// process is never killed or restarted by folding.
+								const started = this.#buildBackgroundStartResult(ptyJobId, ptyLabel, "", timeoutSec, {
+									requestedTimeoutSec,
+									notices: pendingNotices,
+								});
+								const outcome = controls.detachObserver(
+									interactiveResultFromText(this.#extractTextResult(started)),
+								);
+								if (outcome === "resolved") {
+									controls.detachForegroundCancellation();
+									ptyBackgrounded = true;
+									ptyManager.markBackgrounded(ptyJobId, ptyGeneration);
+									ptyFoldResult = started;
+								}
+								return outcome;
+							},
+							resolveForegroundObserver: () => "already-settled",
+						});
+					},
+					onFoldKey: () => {
+						const now = Date.now();
+						if (now - lastPtyFoldKeyTime > 750) {
+							lastPtyFoldKeyTime = now;
+							return true;
+						}
+						lastPtyFoldKeyTime = 0;
+						if (!this.session.hasForegroundBashBackgroundRequestHandler?.()) return false;
+						void this.session.requestForegroundBashBackground?.();
+						return true;
+					},
+					onOutput: chunk => {
+						ptyOutputSeen = true;
+						if (ptyJobId) ownedManager?.appendOutput(ptyJobId, chunk);
+					},
+				}).catch(error => {
+					if (ptyAdmission) ownedManager?.releaseCapacity(ptyAdmission);
+					throw error;
 				})
 			: await executeBash(command, {
 					cwd: commandCwd,
 					settings: this.session.settings,
 					sessionKey: this.session.getSessionId?.() ?? undefined,
-					oneShot: this.session.bashRestrictionProfile === "read-only",
+					oneShot: this.session.bashRestrictionProfile === "read-only" || directMasterSpawn,
 					timeout: timeoutMs,
 					signal,
 					env: resolvedEnv,
@@ -1679,9 +2593,14 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 					headBytes,
 					onChunk: streamTailUpdates(tailBuffer, onUpdate),
 					onMinimizedSave: async originalText => saveBashOriginalArtifact(this.session, originalText),
-					ignoreShellPrefix: this.session.bashRestrictionProfile === "read-only",
-					disableShellSnapshot: this.session.bashRestrictionProfile === "read-only",
+					ignoreShellPrefix: this.session.bashRestrictionProfile === "read-only" || directMasterSpawn,
+					disableShellSnapshot: this.session.bashRestrictionProfile === "read-only" || directMasterSpawn,
 				});
+		ptyFoldUnregister?.();
+		// Folded: the foreground was settled by the fold, so return the background
+		// -start result verbatim instead of presenting a half-finished command.
+		if (ptyFoldResult) return ptyFoldResult;
+
 		if (result.cancelled) {
 			const noticeSuffix = pendingNotices.length > 0 ? `\n\n${pendingNotices.join("\n")}` : "";
 			const baseCancelledText = normalizeResultOutput(result) || "Command aborted";