@gajae-code/coding-agent 0.15.6 → 0.16.1

package/src/tools/bash.ts

@@ -1,10 +1,11 @@
 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";
 import { getProjectDir, isEnoent, logger, prompt } from "@gajae-code/utils";
 import * as z from "zod/v4";
-import { AsyncJobManager } from "../async";
+import { AsyncJobManager, type FoldReason } from "../async";
 import { type BashArtifactSaveResult, type BashResult, executeBash } from "../exec/bash-executor";
 
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
@@ -17,12 +18,14 @@ 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,
 	ClientBridgeTerminalHandle,
 	ClientBridgeTerminalOutput,
 } from "../session/client-bridge";
+import type { FoldAdapter } from "../session/fold-coordinator";
 import {
 	DEFAULT_ARTIFACT_MAX_BYTES,
 	OutputSink,
@@ -83,10 +86,23 @@ function sliceTextAfterUtf8ByteOffset(text: string, offsetBytes: number): string
 import { clampTimeout, TOOL_TIMEOUTS } from "./tool-timeouts";
 
 export const BASH_DEFAULT_PREVIEW_LINES = 10;
+/**
+ * A user steer folds a running foreground bash call only after it has been
+ * running at least this long. Shorter commands finish normally and the steer is
+ * consumed at the ordinary tool boundary, so a quick `git status` never turns
+ * into a background job plus a wake-up turn.
+ */
+export const STEER_FOLD_GRACE_MS = 2_000;
+
+/** Model-facing line appended to a steer-folded background-start result. */
+export function steerFoldReasonLine(jobId: string): string {
+	return `Folded into background job ${jobId} because a user steer arrived; the command keeps running with its original timeout and its result will wake a later turn.`;
+}
 
 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> = {
@@ -485,6 +501,8 @@ export interface BashToolDetails {
 	timeoutSeconds?: number;
 	requestedTimeoutSeconds?: number;
 	terminalId?: string;
+	/** Why the foreground wait was folded, when this result is a background-start after a fold. */
+	foldReason?: FoldReason;
 	async?: {
 		state: "running" | "completed" | "failed";
 		jobId: string;
@@ -601,6 +619,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("\\", "\\\\")
@@ -830,7 +949,12 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		label: string,
 		previewText: string,
 		timeoutSec: number,
-		options: { requestedTimeoutSec?: number; notices?: readonly string[]; terminalId?: string } = {},
+		options: {
+			requestedTimeoutSec?: number;
+			notices?: readonly string[];
+			terminalId?: string;
+			foldReason?: FoldReason;
+		} = {},
 	): AgentToolResult<BashToolDetails> {
 		const details: BashToolDetails = {
 			timeoutSeconds: timeoutSec,
@@ -842,6 +966,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		if (options.requestedTimeoutSec !== undefined && options.requestedTimeoutSec !== timeoutSec) {
 			details.requestedTimeoutSeconds = options.requestedTimeoutSec;
 		}
+		if (options.foldReason !== undefined) details.foldReason = options.foldReason;
 		const lines: string[] = [];
 		const trimmedPreview = previewText.trimEnd();
 		if (trimmedPreview.length > 0) {
@@ -851,6 +976,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			lines.push(...options.notices, "");
 		}
 		lines.push(`Background job ${jobId} started: ${label}`);
+		if (options.foldReason === "steer") lines.push(steerFoldReasonLine(jobId));
 		lines.push("Result will be delivered automatically when complete.");
 		lines.push(
 			`You can use \`job\` to poll until complete, but prefer to continue with another task in the meanwhile if it's not blocking.`,
@@ -874,6 +1000,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		notices?: readonly string[];
 
 		resolvedEnv?: Record<string, string>;
+		directMasterSpawn: boolean;
 		onUpdate?: AgentToolUpdateCallback<BashToolDetails>;
 		startBackgrounded: boolean;
 		onCompletion?: () => void;
@@ -885,7 +1012,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 =>
@@ -908,37 +1039,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,
@@ -1006,24 +1137,107 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		return AsyncJobManager.forEndpoint(endpointId) ?? AsyncJobManager.instance();
 	}
 
+	/**
+	 * Whether a queued user steer may fold the running foreground wait. Mirrors
+	 * the loop's own steer admission: `busyPromptMode=queue` never admits a
+	 * steer into the busy run, and `toolInterruptPolicy=finish_tools` explicitly
+	 * lets the tool finish, so neither may fold. The
+	 * auto-background setting is deliberately not consulted: like the chord,
+	 * a steer fold is a user action.
+	 *
+	 * Fails closed: a session that cannot prove its tool interrupt policy or
+	 * report newly admitted steering is not steer-foldable.
+	 */
+	#steerFoldEnabled(): boolean {
+		const { waitForUserSteering, getToolInterruptPolicy, requestForegroundBashBackground } = this.session;
+		if (!waitForUserSteering || !getToolInterruptPolicy || !requestForegroundBashBackground) return false;
+		if (this.session.settings.get("busyPromptMode") !== "steer") return false;
+		return getToolInterruptPolicy() === "abort_tools";
+	}
+
+	/**
+	 * Fold `adapter` on the first user steer that ARRIVES after the wait has run
+	 * for {@link STEER_FOLD_GRACE_MS} since `startedAt`. A steer already queued
+	 * when the wait starts, or one that arrives inside the grace window, never
+	 * folds: the command finishes normally and that steer is consumed at the
+	 * ordinary tool boundary. The watcher keeps observing so a later qualifying
+	 * steer still folds, and re-checks the gates at that moment so a
+	 * `busyPromptMode`/`toolInterruptPolicy` change during the command is honored.
+	 * Returns a stop function; call it when the wait settles. No-op when steer
+	 * folding is gated off at start.
+	 */
+	#watchSteerForFold(adapter: FoldAdapter, startedAt: number): () => void {
+		if (!this.#steerFoldEnabled()) return () => {};
+		const waitForSteer = this.session.waitForUserSteering;
+		const requestFold = this.session.requestForegroundBashBackground;
+		if (!waitForSteer || !requestFold) return () => {};
+		const watch = new AbortController();
+		const observe = async (): Promise<void> => {
+			while (!watch.signal.aborted) {
+				await waitForSteer(watch.signal);
+				if (watch.signal.aborted) return;
+				if (Date.now() - startedAt < STEER_FOLD_GRACE_MS) continue;
+				if (!this.#steerFoldEnabled()) continue;
+				await requestFold("steer", adapter);
+				return;
+			}
+		};
+		observe().catch((error: unknown) => {
+			logger.warn("Steer-triggered fold failed", {
+				jobId: adapter.jobId,
+				error: error instanceof Error ? error.message : String(error),
+			});
+		});
+		return () => watch.abort();
+	}
+
+	/**
+	 * Race a managed job against the auto-background threshold, an explicit fold
+	 * (chord / SDK control / steer), and abort. A steer that arrives once the
+	 * command has run for {@link STEER_FOLD_GRACE_MS} requests a `steer` fold,
+	 * which settles this wait through the same `backgroundRequest` path as the
+	 * chord; a steer inside the grace window is ignored here and consumed at the
+	 * ordinary tool boundary once the command finishes.
+	 */
 	async #waitForManagedBashJob(
 		job: ManagedBashJobHandle,
 		thresholdMs: number,
 		signal?: AbortSignal,
-		backgroundRequest?: Promise<void>,
-	): Promise<ManagedBashJobCompletion | { kind: "running" } | { kind: "aborted" }> {
+		backgroundRequest?: Promise<FoldReason>,
+		foldAdapter?: FoldAdapter,
+	): Promise<ManagedBashJobCompletion | { kind: "running"; reason: FoldReason } | { kind: "aborted" }> {
 		if (signal?.aborted) {
 			return { kind: "aborted" };
 		}
 
-		const threshold = Promise.withResolvers<{ kind: "running" }>();
-		const thresholdTimer = setTimeout(() => threshold.resolve({ kind: "running" }), Math.max(0, thresholdMs));
-		const waiters: Array<Promise<ManagedBashJobCompletion | { kind: "running" } | { kind: "aborted" }>> = [
-			job.completion,
-			threshold.promise,
-		];
+		const startedAt = Date.now();
+		const threshold = Promise.withResolvers<{ kind: "running"; reason: FoldReason }>();
+		const thresholdTimer = setTimeout(
+			() => {
+				const requestFold = this.session.requestForegroundBashBackground;
+				if (!foldAdapter || !requestFold) {
+					threshold.resolve({ kind: "running", reason: "timer" });
+					return;
+				}
+				void requestFold("timer", foldAdapter)
+					.then(folded => {
+						if (!folded) threshold.resolve({ kind: "running", reason: "timer" });
+					})
+					.catch(error => {
+						logger.warn("Timer-triggered fold failed", {
+							jobId: foldAdapter.jobId,
+							error: error instanceof Error ? error.message : String(error),
+						});
+						threshold.resolve({ kind: "running", reason: "timer" });
+					});
+			},
+			Math.max(0, thresholdMs),
+		);
+		const waiters: Array<
+			Promise<ManagedBashJobCompletion | { kind: "running"; reason: FoldReason } | { kind: "aborted" }>
+		> = [job.completion, threshold.promise];
 		if (backgroundRequest) {
-			waiters.push(backgroundRequest.then(() => ({ kind: "running" as const })));
+			waiters.push(backgroundRequest.then(reason => ({ kind: "running" as const, reason })));
 		}
 
 		let onAbort: (() => void) | undefined;
@@ -1033,9 +1247,13 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			signal.addEventListener("abort", onAbort, { once: true });
 			waiters.push(aborted.promise);
 		}
+
+		const stopSteerWatch =
+			backgroundRequest && foldAdapter ? this.#watchSteerForFold(foldAdapter, startedAt) : () => {};
 		try {
 			return await Promise.race(waiters);
 		} finally {
+			stopSteerWatch();
 			clearTimeout(thresholdTimer);
 			if (signal && onAbort) signal.removeEventListener("abort", onAbort);
 		}
@@ -1061,6 +1279,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		command: string;
 		commandCwd: string;
 		resolvedEnv: Record<string, string>;
+		directMasterSpawn: boolean;
 		requestedTimeoutSec: number;
 		timeoutSec: number;
 		timeoutMs: number;
@@ -1206,14 +1425,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" } : {}),
 		};
@@ -1245,7 +1476,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 });
 	}
 
 	/**
@@ -1343,8 +1647,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(), {
@@ -1416,11 +1721,25 @@ 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
@@ -1440,13 +1759,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);
+			asyncManager.markStartedInBackground(job.jobId, jobGeneration);
 			return this.#buildBackgroundStartResult(job.jobId, job.label, "", timeoutSec, {
 				requestedTimeoutSec,
 				notices: pendingNotices,
@@ -1457,7 +1777,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
@@ -1487,6 +1809,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 				notices: pendingNotices,
 
 				resolvedEnv,
+				directMasterSpawn,
 				onUpdate,
 				startBackgrounded,
 				onCompletion: () => {
@@ -1497,13 +1820,13 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			const jobGeneration = ownedManager.getJob(job.jobId)?.generation ?? job.jobId;
 			if (startBackgrounded) {
 				job.setBackgrounded(true);
-				ownedManager.markBackgrounded(job.jobId, jobGeneration);
+				ownedManager.markStartedInBackground(job.jobId, jobGeneration);
 				return this.#buildBackgroundStartResult(job.jobId, job.label, "", timeoutSec, {
 					requestedTimeoutSec,
 					notices: pendingNotices,
 				});
 			}
-			const backgroundRequest = Promise.withResolvers<void>();
+			const backgroundRequest = Promise.withResolvers<FoldReason>();
 			// 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.
@@ -1513,7 +1836,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 				foregroundSettled = true;
 				return "resolved";
 			};
-			const unregisterBackgroundRequest = this.session.registerForegroundFoldParticipant?.({
+			const managedFoldAdapter: FoldAdapter = {
 				kind: "bash-managed",
 				jobId: job.jobId,
 				jobGeneration,
@@ -1532,24 +1855,26 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 					const current = ownedManager.getJob(job.jobId);
 					return current?.generation === jobGeneration ? current : undefined;
 				},
-				detachObserver: () => {
+				detachObserver: receipt => {
 					const outcome = settleForeground();
 					if (outcome === "resolved") {
 						job.setBackgrounded(true);
-						ownedManager.markBackgrounded(job.jobId, jobGeneration);
-						backgroundRequest.resolve();
+						ownedManager.markBackgrounded(job.jobId, jobGeneration, receipt.reason);
+						backgroundRequest.resolve(receipt.reason);
 					}
 					return outcome;
 				},
 				resolveForegroundObserver: () => settleForeground(),
-			});
-			let waitResult: ManagedBashJobCompletion | { kind: "running" } | { kind: "aborted" };
+			};
+			const unregisterBackgroundRequest = this.session.registerForegroundFoldParticipant?.(managedFoldAdapter);
+			let waitResult: ManagedBashJobCompletion | { kind: "running"; reason: FoldReason } | { kind: "aborted" };
 			try {
 				waitResult = await this.#waitForManagedBashJob(
 					job,
 					autoBackgroundWaitMs,
 					signal,
 					backgroundRequest.promise,
+					managedFoldAdapter,
 				);
 			} finally {
 				unregisterBackgroundRequest?.();
@@ -1577,10 +1902,11 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 				throw new ToolAbortError(formatManagedAbortFailure(undefined, undefined, job.getLatestText()));
 			}
 			job.setBackgrounded(true);
-			ownedManager.markBackgrounded(job.jobId, jobGeneration);
+			ownedManager.markBackgrounded(job.jobId, jobGeneration, waitResult.reason);
 			return this.#buildBackgroundStartResult(job.jobId, job.label, job.getLatestText(), timeoutSec, {
 				requestedTimeoutSec,
 				notices: pendingNotices,
+				foldReason: waitResult.reason,
 			});
 		}
 
@@ -2109,9 +2435,9 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			void bridgeHandle.completion.finally(unregisterOwnerCleanup);
 			registerOwnedIfLineaged(bridgeManager, toolCallId, bridgeJobId, bridgeEndpointId);
 
-			const bridgeFoldRequest = Promise.withResolvers<void>();
+			const bridgeFoldRequest = Promise.withResolvers<FoldReason>();
 			const bridgeOriginatingTurn = ctx?.attemptScope !== undefined;
-			const unregisterBridgeFold = this.session.registerForegroundFoldParticipant?.({
+			const bridgeFoldAdapter: FoldAdapter = {
 				kind: "client-terminal",
 				jobId: bridgeJobId,
 				jobGeneration: bridgeGeneration,
@@ -2128,25 +2454,27 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 					const current = bridgeManager.getJob(bridgeJobId);
 					return current?.generation === bridgeGeneration ? current : undefined;
 				},
-				detachObserver: () => {
+				detachObserver: receipt => {
 					const outcome = settleBridgeForeground();
 					if (outcome === "resolved") {
 						bridgeHandle.setBackgrounded(true);
-						bridgeManager.markBackgrounded(bridgeJobId, bridgeGeneration);
-						bridgeFoldRequest.resolve();
+						bridgeManager.markBackgrounded(bridgeJobId, bridgeGeneration, receipt.reason);
+						bridgeFoldRequest.resolve(receipt.reason);
 					}
 					return outcome;
 				},
 				resolveForegroundObserver: () => settleBridgeForeground(),
-			});
+			};
+			const unregisterBridgeFold = this.session.registerForegroundFoldParticipant?.(bridgeFoldAdapter);
 
-			let bridgeWait: ManagedBashJobCompletion | { kind: "running" } | { kind: "aborted" };
+			let bridgeWait: ManagedBashJobCompletion | { kind: "running"; reason: FoldReason } | { kind: "aborted" };
 			try {
 				bridgeWait = await this.#waitForManagedBashJob(
 					bridgeHandle,
 					this.#autoBackgroundEnabled ? this.#resolveAutoBackgroundWaitMs(timeoutMs) : timeoutMs + 1_000,
 					signal,
 					bridgeFoldRequest.promise,
+					bridgeFoldAdapter,
 				);
 			} finally {
 				unregisterBridgeFold?.();
@@ -2181,11 +2509,12 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			// Folded (or auto-backgrounded): the remote terminal keeps running and its
 			// result arrives as a background completion.
 			bridgeHandle.setBackgrounded(true);
-			bridgeManager.markBackgrounded(bridgeJobId, bridgeGeneration);
+			bridgeManager.markBackgrounded(bridgeJobId, bridgeGeneration, bridgeWait.reason);
 			return this.#buildBackgroundStartResult(bridgeJobId, bridgeLabel, bridgeHandle.getLatestText(), timeoutSec, {
 				requestedTimeoutSec,
 				notices: pendingNotices,
 				terminalId: handle.terminalId,
+				foldReason: bridgeWait.reason,
 			});
 		}
 
@@ -2200,7 +2529,7 @@ 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
@@ -2307,7 +2636,8 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 							},
 						);
 						void controls.terminalCompletion.finally(unregisterPtyOwnerCleanup);
-						ptyFoldUnregister = this.session.registerForegroundFoldParticipant?.({
+						const ptyStartedAt = Date.now();
+						const ptyFoldAdapter: FoldAdapter = {
 							kind: "bash-pty",
 							jobId: ptyJobId,
 							jobGeneration: ptyGeneration,
@@ -2324,12 +2654,13 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 								const current = ptyManager.getJob(ptyJobId);
 								return current?.generation === ptyGeneration ? current : undefined;
 							},
-							detachObserver: () => {
+							detachObserver: receipt => {
 								// 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,
+									foldReason: receipt.reason,
 								});
 								const outcome = controls.detachObserver(
 									interactiveResultFromText(this.#extractTextResult(started)),
@@ -2337,13 +2668,19 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 								if (outcome === "resolved") {
 									controls.detachForegroundCancellation();
 									ptyBackgrounded = true;
-									ptyManager.markBackgrounded(ptyJobId, ptyGeneration);
+									ptyManager.markBackgrounded(ptyJobId, ptyGeneration, receipt.reason);
 									ptyFoldResult = started;
 								}
 								return outcome;
 							},
 							resolveForegroundObserver: () => "already-settled",
-						});
+						};
+						const unregisterPtyFold = this.session.registerForegroundFoldParticipant?.(ptyFoldAdapter);
+						const stopPtySteerWatch = this.#watchSteerForFold(ptyFoldAdapter, ptyStartedAt);
+						ptyFoldUnregister = () => {
+							stopPtySteerWatch();
+							unregisterPtyFold?.();
+						};
 					},
 					onFoldKey: () => {
 						const now = Date.now();
@@ -2368,7 +2705,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 					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,
@@ -2379,8 +2716,8 @@ 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