feat(coding-agent): added auto-backgrounding for long bash jobs to avoid blocking

- Added bash.autoBackground.enabled and bash.autoBackground.thresholdMs settings with defaults for background job behavior.
- Added auto-backgrounding support for long foreground bash commands with managed job state and timeout threshold.
- Updated bash prompts, job-protocol messages, and tool activation checks to use async and auto-background support.
- Added background bash completion integration with AsyncJobManager and end-to-end tests for short/long auto-background scenarios.

packages/coding-agent/src/async/index.ts

@@ -1 +1,2 @@
 export * from "./job-manager";
+export * from "./support";

packages/coding-agent/src/async/support.ts

@@ -0,0 +1,5 @@
+import type { Settings } from "../config/settings";
+
+export function isBackgroundJobSupportEnabled(settings: Pick<Settings, "get">): boolean {
+	return settings.get("async.enabled") || settings.get("bash.autoBackground.enabled");
+}

packages/coding-agent/src/config/settings-schema.ts

@@ -1385,6 +1385,27 @@ export const SETTINGS_SCHEMA = {
 		},
 	},
 
+	"bash.autoBackground.enabled": {
+		type: "boolean",
+		default: false,
+		ui: {
+			tab: "tools",
+			label: "Bash Auto-Background",
+			description: "Automatically background long-running bash commands and deliver the result later",
+		},
+	},
+
+	"bash.autoBackground.thresholdMs": {
+		type: "number",
+		default: 60_000,
+		ui: {
+			tab: "tools",
+			label: "Bash Auto-Background Delay",
+			description: "Milliseconds to wait before a bash command is moved to the background (0 = immediately)",
+			submenu: true,
+		},
+	},
+
 	// MCP
 	"mcp.enableProjectConfig": {
 		type: "boolean",

packages/coding-agent/src/internal-urls/jobs-protocol.ts

@@ -30,7 +30,8 @@ export class JobsProtocolHandler implements ProtocolHandler {
 	async resolve(url: InternalUrl): Promise<InternalResource> {
 		const manager = this.options.getAsyncJobManager();
 		if (!manager) {
-			const content = "# Jobs\n\nAsync execution is disabled. Enable `async.enabled` to use jobs://.";
+			const content =
+				"# Jobs\n\nBackground job support is disabled. Enable `async.enabled` or `bash.autoBackground.enabled` to use jobs://.";
 			return {
 				url: url.href,
 				content,

packages/coding-agent/src/main.ts

@@ -79,6 +79,8 @@ const RPC_DEFAULTED_SETTING_PATHS: SettingPath[] = [
 	"todo.eager",
 	"async.enabled",
 	"async.maxJobs",
+	"bash.autoBackground.enabled",
+	"bash.autoBackground.thresholdMs",
 	"task.isolation.mode",
 	"task.isolation.merge",
 	"task.isolation.commits",

packages/coding-agent/src/prompts/tools/bash.md

@@ -12,8 +12,23 @@ Executes bash command in shell session for terminal operations like git, bun, ca
 - Internal URLs are also auto-resolved to filesystem paths before execution.
 {{#if asyncEnabled}}
 - Use `async: true` for long-running commands when you don't need immediate output; the call returns a background job ID and the result is delivered automatically as a follow-up.
+{{/if}}
+{{#if autoBackgroundEnabled}}
+- Long-running non-PTY bash commands may auto-background after about {{autoBackgroundThresholdSeconds}}s and continue as background jobs automatically.
+{{/if}}
+{{#if asyncEnabled}}
+{{else}}
+{{#if autoBackgroundEnabled}}
+- Auto-backgrounded jobs use the same background-job pipeline as explicit async execution.
+{{/if}}
+{{/if}}
+{{#if asyncEnabled}}
 - Use `read jobs://` to inspect all background jobs and `read jobs://<job-id>` for detailed status/output when needed.
 - When you need to wait for async results before continuing, call `await` — it blocks until jobs complete. Do NOT poll `read jobs://` in a loop or yield and hope for delivery.
+{{else}}
+{{#if autoBackgroundEnabled}}
+- If a command auto-backgrounds, use `read jobs://` to inspect jobs and `await` when you need to wait for completion instead of polling in a loop.
+{{/if}}
 {{/if}}
 </instruction>
 

packages/coding-agent/src/prompts/tools/cancel-job.md

@@ -1,4 +1,4 @@
-Cancels a running background job started via async tool execution.
+Cancels a running background job started via async tool execution or bash auto-backgrounding.
 
 You **SHOULD** use this when a background `bash` or `task` job is no longer needed or is stuck.
 

packages/coding-agent/src/sdk.ts

@@ -25,7 +25,7 @@ import {
 	prompt,
 } from "@oh-my-pi/pi-utils";
 import chalk from "chalk";
-import { AsyncJobManager } from "./async";
+import { AsyncJobManager, isBackgroundJobSupportEnabled } from "./async";
 import { createAutoresearchExtension } from "./autoresearch";
 import { loadCapability } from "./capability";
 import { type Rule, ruleCapability } from "./capability/rule";
@@ -838,7 +838,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	let session: AgentSession;
 
 	const enableLsp = options.enableLsp ?? true;
-	const asyncEnabled = settings.get("async.enabled");
+	const backgroundJobsEnabled = isBackgroundJobSupportEnabled(settings);
 	const asyncMaxJobs = Math.min(100, Math.max(1, settings.get("async.maxJobs") ?? 100));
 	const ASYNC_INLINE_RESULT_MAX_CHARS = 12_000;
 	const ASYNC_PREVIEW_MAX_CHARS = 4_000;
@@ -862,7 +862,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 
 		return preview;
 	};
-	const asyncJobManager = asyncEnabled
+	const asyncJobManager = backgroundJobsEnabled
 		? new AsyncJobManager({
 				maxRunningJobs: asyncMaxJobs,
 				onJobComplete: async (jobId, result, job) => {

packages/coding-agent/src/task/executor.ts

@@ -435,7 +435,11 @@ function createSubagentSettings(baseSettings: Settings): Settings {
 	for (const key of Object.keys(SETTINGS_SCHEMA) as SettingPath[]) {
 		snapshot[key] = baseSettings.get(key);
 	}
-	return Settings.isolated({ ...snapshot, "async.enabled": false });
+	return Settings.isolated({
+		...snapshot,
+		"async.enabled": false,
+		"bash.autoBackground.enabled": false,
+	});
 }
 
 /**

packages/coding-agent/src/tools/await-tool.ts

@@ -1,6 +1,7 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
 import { prompt } from "@oh-my-pi/pi-utils";
 import { type Static, Type } from "@sinclair/typebox";
+import { isBackgroundJobSupportEnabled } from "../async";
 import awaitDescription from "../prompts/tools/await.md" with { type: "text" };
 import type { ToolSession } from "./index";
 
@@ -40,7 +41,7 @@ export class AwaitTool implements AgentTool<typeof awaitSchema, AwaitToolDetails
 	}
 
 	static createIf(session: ToolSession): AwaitTool | null {
-		if (!session.settings.get("async.enabled")) return null;
+		if (!isBackgroundJobSupportEnabled(session.settings)) return null;
 		return new AwaitTool(session);
 	}
 

packages/coding-agent/src/tools/bash.ts

@@ -28,6 +28,7 @@ import { clampTimeout } from "./tool-timeouts";
 export const BASH_DEFAULT_PREVIEW_LINES = 10;
 
 const BASH_ENV_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const DEFAULT_AUTO_BACKGROUND_THRESHOLD_MS = 60_000;
 
 const bashSchemaBase = Type.Object({
 	command: Type.String({ description: "Command to execute" }),
@@ -81,6 +82,24 @@ export interface BashToolDetails {
 
 export interface BashToolOptions {}
 
+type ManagedBashJobCompletion =
+	| {
+			kind: "completed";
+			result: AgentToolResult<BashToolDetails>;
+	  }
+	| {
+			kind: "failed";
+			error: unknown;
+	  };
+
+interface ManagedBashJobHandle {
+	jobId: string;
+	label: string;
+	completion: Promise<ManagedBashJobCompletion>;
+	getLatestText: () => string;
+	setBackgrounded: (backgrounded: boolean) => void;
+}
+
 function normalizeResultOutput(result: BashResult | BashInteractiveResult): string {
 	return result.output || "";
 }
@@ -212,12 +231,23 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 	readonly concurrency = "exclusive";
 	readonly strict = true;
 	readonly #asyncEnabled: boolean;
+	readonly #autoBackgroundEnabled: boolean;
+	readonly #autoBackgroundThresholdMs: number;
 
 	constructor(private readonly session: ToolSession) {
 		this.#asyncEnabled = this.session.settings.get("async.enabled");
+		this.#autoBackgroundEnabled = this.session.settings.get("bash.autoBackground.enabled");
+		this.#autoBackgroundThresholdMs = Math.max(
+			0,
+			Math.floor(
+				this.session.settings.get("bash.autoBackground.thresholdMs") ?? DEFAULT_AUTO_BACKGROUND_THRESHOLD_MS,
+			),
+		);
 		this.parameters = this.#asyncEnabled ? bashSchemaWithAsync : bashSchemaBase;
 		this.description = prompt.render(bashDescription, {
 			asyncEnabled: this.#asyncEnabled,
+			autoBackgroundEnabled: this.#autoBackgroundEnabled,
+			autoBackgroundThresholdSeconds: Math.max(0, Math.floor(this.#autoBackgroundThresholdMs / 1000)),
 			hasAstGrep: this.session.settings.get("astGrep.enabled"),
 			hasAstEdit: this.session.settings.get("astEdit.enabled"),
 			hasGrep: this.session.settings.get("grep.enabled"),
@@ -253,6 +283,153 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		return outputText;
 	}
 
+	#buildCompletedResult(
+		result: BashResult | BashInteractiveResult,
+		timeoutSec: number,
+		headLines?: number,
+		tailLines?: number,
+	): AgentToolResult<BashToolDetails> {
+		const outputText = this.#formatResultOutput(result, headLines, tailLines);
+		const details: BashToolDetails = {};
+		const resultBuilder = toolResult(details).text(outputText).truncationFromSummary(result, { direction: "tail" });
+		this.#buildResultText(result, timeoutSec, outputText);
+		return resultBuilder.done();
+	}
+
+	#buildBackgroundStartResult(jobId: string, label: string, previewText: string): AgentToolResult<BashToolDetails> {
+		const details: BashToolDetails = {
+			async: { state: "running", jobId, type: "bash" },
+		};
+		const lines: string[] = [];
+		const trimmedPreview = previewText.trimEnd();
+		if (trimmedPreview.length > 0) {
+			lines.push(trimmedPreview, "");
+		}
+		lines.push(`Background job ${jobId} started: ${label}`);
+		lines.push("Result will be delivered automatically when complete.");
+		lines.push(`Use \`await\`, \`read jobs://${jobId}\`, or \`cancel_job\` if needed.`);
+		return {
+			content: [{ type: "text", text: lines.join("\n") }],
+			details,
+		};
+	}
+
+	#extractTextResult(result: AgentToolResult<BashToolDetails>): string {
+		return result.content.find(block => block.type === "text")?.text ?? "";
+	}
+
+	#startManagedBashJob(options: {
+		command: string;
+		commandCwd: string;
+		timeoutMs: number;
+		timeoutSec: number;
+		headLines?: number;
+		tailLines?: number;
+		resolvedEnv?: Record<string, string>;
+		onUpdate?: AgentToolUpdateCallback<BashToolDetails>;
+		startBackgrounded: boolean;
+	}): ManagedBashJobHandle {
+		const manager = this.session.asyncJobManager;
+		if (!manager) {
+			throw new ToolError("Background job manager unavailable for this session.");
+		}
+
+		const label = options.command.length > 120 ? `${options.command.slice(0, 117)}...` : options.command;
+		let latestText = "";
+		let backgrounded = options.startBackgrounded;
+		const completion = Promise.withResolvers<ManagedBashJobCompletion>();
+
+		const jobId = manager.register(
+			"bash",
+			label,
+			async ({ jobId, signal: runSignal, reportProgress }) => {
+				const { path: artifactPath, id: artifactId } = (await this.session.allocateOutputArtifact?.("bash")) ?? {};
+				const tailBuffer = new TailBuffer(DEFAULT_MAX_BYTES);
+				try {
+					const result = await executeBash(options.command, {
+						cwd: options.commandCwd,
+						sessionKey: `${this.session.getSessionId?.() ?? ""}:async:${jobId}`,
+						timeout: options.timeoutMs,
+						signal: runSignal,
+						env: options.resolvedEnv,
+						artifactPath,
+						artifactId,
+						onChunk: chunk => {
+							tailBuffer.append(chunk);
+							latestText = tailBuffer.text();
+							void reportProgress(latestText, { async: { state: "running", jobId, type: "bash" } });
+						},
+					});
+					const finalResult = this.#buildCompletedResult(
+						result,
+						options.timeoutSec,
+						options.headLines,
+						options.tailLines,
+					);
+					const finalText = this.#extractTextResult(finalResult);
+					latestText = finalText;
+					completion.resolve({ kind: "completed", result: finalResult });
+					await reportProgress(finalText, { async: { state: "completed", jobId, type: "bash" } });
+					return finalText;
+				} catch (error) {
+					const message = error instanceof Error ? error.message : String(error);
+					latestText = message;
+					completion.resolve({ kind: "failed", error });
+					await reportProgress(message, { async: { state: "failed", jobId, type: "bash" } });
+					throw error;
+				}
+			},
+			{
+				onProgress: async (text, details) => {
+					latestText = text;
+					await options.onUpdate?.({
+						content: [{ type: "text", text }],
+						details: backgrounded ? ((details ?? {}) as BashToolDetails) : {},
+					});
+				},
+			},
+		);
+
+		return {
+			jobId,
+			label,
+			completion: completion.promise,
+			getLatestText: () => latestText,
+			setBackgrounded: (nextBackgrounded: boolean) => {
+				backgrounded = nextBackgrounded;
+			},
+		};
+	}
+
+	async #waitForManagedBashJob(
+		job: ManagedBashJobHandle,
+		thresholdMs: number,
+		signal?: AbortSignal,
+	): Promise<ManagedBashJobCompletion | { kind: "running" } | { kind: "aborted" }> {
+		if (signal?.aborted) {
+			return { kind: "aborted" };
+		}
+
+		const waiters: Array<Promise<ManagedBashJobCompletion | { kind: "running" } | { kind: "aborted" }>> = [
+			job.completion,
+			Bun.sleep(thresholdMs).then(() => ({ kind: "running" as const })),
+		];
+
+		if (!signal) {
+			return await Promise.race(waiters);
+		}
+
+		const { promise: abortedPromise, resolve: resolveAborted } = Promise.withResolvers<{ kind: "aborted" }>();
+		const onAbort = () => resolveAborted({ kind: "aborted" });
+		signal.addEventListener("abort", onAbort, { once: true });
+		waiters.push(abortedPromise);
+		try {
+			return await Promise.race(waiters);
+		} finally {
+			signal.removeEventListener("abort", onAbort);
+		}
+	}
+
 	async execute(
 		_toolCallId: string,
 		{
@@ -345,52 +522,51 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		const timeoutMs = timeoutSec * 1000;
 
 		if (asyncRequested) {
-			const manager = this.session.asyncJobManager;
-			if (!manager) {
+			if (!this.session.asyncJobManager) {
 				throw new ToolError("Async job manager unavailable for this session.");
 			}
-			const label = command.length > 120 ? `${command.slice(0, 117)}...` : command;
-			const tailBuffer = new TailBuffer(DEFAULT_MAX_BYTES);
-			const jobId = manager.register(
-				"bash",
-				label,
-				async ({ jobId, signal: runSignal, reportProgress }) => {
-					const { path: artifactPath, id: artifactId } =
-						(await this.session.allocateOutputArtifact?.("bash")) ?? {};
-					try {
-						const result = await executeBash(command, {
-							cwd: commandCwd,
-							sessionKey: `${this.session.getSessionId?.() ?? ""}:async:${jobId}`,
-							timeout: timeoutMs,
-							signal: runSignal,
-							env: resolvedEnv,
-							artifactPath,
-							artifactId,
-							onChunk: chunk => {
-								tailBuffer.append(chunk);
-								void reportProgress(tailBuffer.text(), { async: { state: "running", jobId, type: "bash" } });
-							},
-						});
-						const outputText = this.#formatResultOutput(result, headLines, tailLines);
-						const finalText = this.#buildResultText(result, timeoutSec, outputText);
-						await reportProgress(finalText, { async: { state: "completed", jobId, type: "bash" } });
-						return finalText;
-					} catch (error) {
-						const message = error instanceof Error ? error.message : String(error);
-						await reportProgress(message, { async: { state: "failed", jobId, type: "bash" } });
-						throw error;
-					}
-				},
-				{
-					onProgress: (text, details) => {
-						onUpdate?.({ content: [{ type: "text", text }], details: details ?? {} });
-					},
-				},
-			);
-			return {
-				content: [{ type: "text", text: `Background job ${jobId} started: ${label}` }],
-				details: { async: { state: "running", jobId, type: "bash" } },
-			};
+			const job = this.#startManagedBashJob({
+				command,
+				commandCwd,
+				timeoutMs,
+				timeoutSec,
+				headLines,
+				tailLines,
+				resolvedEnv,
+				onUpdate,
+				startBackgrounded: true,
+			});
+			return this.#buildBackgroundStartResult(job.jobId, job.label, "");
+		}
+
+		if (this.#autoBackgroundEnabled && !pty && this.session.asyncJobManager) {
+			const job = this.#startManagedBashJob({
+				command,
+				commandCwd,
+				timeoutMs,
+				timeoutSec,
+				headLines,
+				tailLines,
+				resolvedEnv,
+				onUpdate,
+				startBackgrounded: false,
+			});
+			const waitResult = await this.#waitForManagedBashJob(job, this.#autoBackgroundThresholdMs, signal);
+			if (waitResult.kind === "completed") {
+				this.session.asyncJobManager.acknowledgeDeliveries([job.jobId]);
+				return waitResult.result;
+			}
+			if (waitResult.kind === "failed") {
+				this.session.asyncJobManager.acknowledgeDeliveries([job.jobId]);
+				throw waitResult.error;
+			}
+			if (waitResult.kind === "aborted") {
+				this.session.asyncJobManager.cancel(job.jobId);
+				this.session.asyncJobManager.acknowledgeDeliveries([job.jobId]);
+				throw new ToolAbortError(job.getLatestText() || "Command aborted");
+			}
+			job.setBackgrounded(true);
+			return this.#buildBackgroundStartResult(job.jobId, job.label, job.getLatestText());
 		}
 
 		// Track output for streaming updates (tail only)
@@ -437,18 +613,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		if (isInteractiveResult(result) && result.timedOut) {
 			throw new ToolError(normalizeResultOutput(result) || `Command timed out after ${timeoutSec} seconds`);
 		}
-
-		const outputText = this.#formatResultOutput(result, headLines, tailLines);
-		const details: BashToolDetails = {};
-		const resultBuilder = toolResult(details).text(outputText).truncationFromSummary(result, { direction: "tail" });
-		if (result.exitCode === undefined) {
-			throw new ToolError(`${outputText}\n\nCommand failed: missing exit status`);
-		}
-		if (result.exitCode !== 0 && result.exitCode !== undefined) {
-			throw new ToolError(`${outputText}\n\nCommand exited with code ${result.exitCode}`);
-		}
-
-		return resultBuilder.done();
+		return this.#buildCompletedResult(result, timeoutSec, headLines, tailLines);
 	}
 }
 

packages/coding-agent/src/tools/cancel-job.ts

@@ -1,6 +1,7 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
 import { prompt } from "@oh-my-pi/pi-utils";
 import { type Static, Type } from "@sinclair/typebox";
+import { isBackgroundJobSupportEnabled } from "../async";
 import cancelJobDescription from "../prompts/tools/cancel-job.md" with { type: "text" };
 import type { ToolSession } from "./index";
 
@@ -27,7 +28,7 @@ export class CancelJobTool implements AgentTool<typeof cancelJobSchema, CancelJo
 	}
 
 	static createIf(session: ToolSession): CancelJobTool | null {
-		if (!session.settings.get("async.enabled")) return null;
+		if (!isBackgroundJobSupportEnabled(session.settings)) return null;
 		return new CancelJobTool(session);
 	}