@toddzheng024/dscode-bundle 0.7.27 → 0.7.29

package/vendor/bash/index.js

@@ -1,33 +1,129 @@
 // dscode-named-shell-v1
 import z from "@deepseek-ai/schemastery";
-import { isAbsolute, resolve } from "node:path";
+import { isAbsolute, sep } from "node:path";
 import { TOOL_ABORTED, defineTool } from "@deepseek-ai/dsh-tools";
 import { HarnessError } from "@deepseek-ai/dsh-llm";
-import { ESCALATION_TARGETS, approveEscalation, canonicalPath, escalationHintMarker, sandboxDenialMarker, validateEscalationArgs } from "@deepseek-ai/dsh-sandbox";
+import { ESCALATION_TARGETS, approveEscalation, escalationHintMarker, sandboxDenialMarker, validateEscalationArgs } from "@deepseek-ai/dsh-sandbox";
 import { DSH_ENV_PREFIX, parseExitStatus } from "@deepseek-ai/dsh-shell";
 //#region lib/types/background.js
 /**
-* Generic-task adaptation for background bash process handles.
+* Generic-job adaptation for bash process handles: the terminal outcome the
+* registry records, the pull sources it pumps, and the ring read a foreground
+* call renders when it stops waiting.
 *
 * @module @deepseek-ai/dsh-tool-bash/background
 */
 /**
-* Map a settled background process onto the generic task-outcome vocabulary:
+* Sandbox facts worth the terminal detail: a runner that never ran the
+* command, or a denial (with the escalation hint this composition offers).
+* @param sandbox - settled sandbox facts, when this was a confined process.
+* @param escalationModes - escalation targets advertised by this composition.
+* @returns the markers to append, oldest first.
+*/
+function sandboxNotes(sandbox, escalationModes) {
+	if (sandbox?.runnerFailed) return [`[sandbox: the sandbox runner itself failed under ${sandbox.mode} mode — the command did not run; this is a sandbox problem, not a command failure]`];
+	if (sandbox?.denied) {
+		const notes = [sandboxDenialMarker(sandbox.mode)];
+		if (escalationModes.length > 0) notes.push(escalationHintMarker("command"));
+		return notes;
+	}
+	return [];
+}
+/**
+* Map a settled background process onto the generic job-outcome vocabulary:
 * `killed` stays `killed` (detail: the signal when one is known), everything
 * else is `completed` with the exit code as detail. A nonzero command exit is
-* reported, not failed, exactly like the foreground rendering.
+* reported, not failed, exactly like the foreground rendering. Sandbox facts
+* join the detail, since a job's terminal reason is the one line every
+* reader — the model's status line, the roster row — shows.
 * @param proc - the settled process handle.
+* @param escalationModes - escalation targets advertised by this composition.
 * @returns the outcome for the `ctx.jobs` registration.
 */
-function processOutcome(proc) {
-	if (proc.status === "killed") return {
+function processOutcome(proc, escalationModes = []) {
+	const base = proc.status === "killed" ? {
 		status: "killed",
 		detail: proc.signal !== null ? `signal: ${proc.signal}` : "killed before exit"
-	};
-	return {
+	} : {
 		status: "completed",
 		detail: `exit code: ${proc.exitCode ?? 0}`
 	};
+	const notes = sandboxNotes(proc.sandbox, escalationModes);
+	return notes.length === 0 ? base : {
+		...base,
+		detail: `${base.detail}; ${notes.join(" ")}`
+	};
+}
+/**
+* The process's non-consuming stream readers as registry pull sources. They
+* bind lazily because the process is spawned inside the starter, after the
+* registry admitted the job; a read before the spawn yields nothing, and the
+* pump keeps the model's consuming cursor untouched. A rejected spawn's
+* stderr reader carries the provider's `subprocess failed before reporting an
+* outcome: …` note.
+* @param proc - the started process's observed streams, once the starter has spawned it.
+* @returns one source per stream, stdout first.
+*/
+function processSources(proc) {
+	const source = (channel) => ({
+		channel,
+		read: (fromByte) => {
+			const live = proc();
+			return live === void 0 ? {
+				text: "",
+				nextOffset: fromByte,
+				lossy: false
+			} : live.observed[channel].readFrom(fromByte);
+		}
+	});
+	return [source("stdout"), source("stderr")];
+}
+/**
+* The ring chunks of one consuming registry read as the shell tools render a
+* process read: stdout chunks in order, then every stderr chunk in one
+* `[stderr]` section, so the output a foreground call hands over when it
+* stops waiting reads exactly like the `job_output` reads that follow it.
+* @param chunks - the chunks since the model cursor, in offset order.
+* @returns the delta text, possibly empty.
+*/
+function ringDelta(chunks) {
+	const out = chunks.filter((chunk) => chunk.channel !== "stderr").map((chunk) => chunk.text).join("");
+	const err = chunks.filter((chunk) => chunk.channel === "stderr").map((chunk) => chunk.text).join("");
+	const separator = out.length > 0 && !out.endsWith("\n") ? "\n" : "";
+	return out + (err.length > 0 ? `${separator}[stderr]\n${err}` : "");
+}
+/**
+* Adapt asynchronous shell preparation after job admission without exposing a partial process.
+* @param start - starts the process with job-owned cancellation.
+* @param outcome - projects the settled process into the job outcome.
+* @returns synchronous job hooks whose completion includes preparation and process settlement.
+*/
+function processJob(start, outcome) {
+	const controller = new AbortController();
+	let process;
+	return {
+		cancel: (reason) => {
+			if (controller.signal.aborted) return;
+			controller.abort(reason);
+			process?.kill();
+		},
+		done: (async () => {
+			try {
+				process = await start(controller.signal);
+				try {
+					if (controller.signal.aborted) process.kill();
+				} finally {
+					await process.done;
+				}
+				return outcome(process);
+			} catch (error) {
+				return {
+					status: controller.signal.aborted && process === void 0 ? "killed" : "failed",
+					detail: error instanceof Error ? error.message : String(error)
+				};
+			}
+		})()
+	};
 }
 //#endregion
 //#region lib/types/render.js
@@ -50,7 +146,7 @@ function streamText(output) {
 * @param escalationModes - the escalation targets this composition advertises;
 *   non-empty adds the same-turn escalation hint after a denial marker
 *   (default `[]`: no hint).
-* @returns the model-facing text: output body (or `(no output)`), then any timeout/signal/exit markers, each on its own line.
+* @returns the model-facing text: output body (or `(no output)`), then any timeout/stopped/signal/exit markers, each on its own line.
 */
 function renderResult(result, escalationModes = []) {
 	const out = streamText(result.stdout);
@@ -67,6 +163,7 @@ function renderResult(result, escalationModes = []) {
 		if (escalationModes.length > 0) markers.push(escalationHintMarker("command"));
 	}
 	if (result.timedOut) markers.push(`[timed out after ${result.timeoutMs}ms]`);
+	if (result.stopped !== void 0) markers.push(`[stopped: ${result.stopped}]`);
 	if (result.signal !== null) markers.push(`[killed by signal: ${result.signal}]`);
 	else if (result.exitCode !== 0) markers.push(`[exit code: ${result.exitCode}]`);
 	if (markers.length === 0) return body;
@@ -74,35 +171,50 @@ function renderResult(result, escalationModes = []) {
 	return body + markers.join("\n");
 }
 /**
-* Shape one background-process read into the `job_output` delta the model
-* sees: the incremental delta, plus the lossy-read notice (with full-stream
-* spill paths) when in-memory truncation dropped unread bytes. Empty-delta
-* rendering (`(no new output)`) is the generic job controller's job.
-* @param read - one incremental read from the process handle.
+* Shape a foreground call that stopped waiting into the text the model sees:
+* the output captured so far (one consuming registry read taken at that
+* point, so `job_output` continues exactly after it), then the still-running
+* marker and the job hand-off guidance.
+* @param promoted - the promoted result value: the job id, the wait that
+*   expired, and the output so far.
+* @returns the model-facing text for a promoted call.
+*/
+function renderPromoted(promoted) {
+	return `${promoted.output.length > 0 ? promoted.output.endsWith("\n") ? promoted.output : `${promoted.output}\n` : ""}[still running after ${promoted.timeoutMs}ms; moved to background job ${promoted.jobId}]\nThe command keeps running in the background. You will be notified when it finishes; read newer output with job_output, stop it with job_kill.`;
+}
+/**
+* Shape the one consuming registry read a foreground call embeds in its
+* result when it stops waiting: the output produced so far, plus the
+* dropped-output notice (naming the job's spill files) when the model cursor
+* fell behind the ring, and the sandbox notices. Later `job_output` reads
+* render the same ring through the job tools.
+* @param delta - the read's chunks as rendered text.
+* @param lossy - whether bytes before the delta were evicted unread.
+* @param spillPaths - the complete-stream files the job currently advertises.
 * @param sandbox - settled sandbox facts, when this was a confined process.
 * @param escalationModes - escalation targets advertised by this composition.
 * @returns the delta text with any loss or sandbox notice appended.
 */
-function renderProcessRead(read, sandbox, escalationModes = []) {
+function renderJobRead(delta, lossy, spillPaths, sandbox, escalationModes = []) {
 	const notices = [];
-	if (read.lossy) {
-		const paths = [read.stdoutSpillPath, read.stderrSpillPath].filter((path) => path !== void 0);
-		notices.push(`[some output was dropped from memory; full output: ${paths.length > 0 ? paths.join(", ") : "(unavailable)"}]`);
-	}
+	if (lossy) notices.push(`[some output was dropped from memory; full output: ${spillPaths.length > 0 ? spillPaths.join(", ") : "(unavailable)"}]`);
 	if (sandbox?.runnerFailed) notices.push(`[sandbox: the sandbox runner itself failed under ${sandbox.mode} mode — the command did not run; this is a sandbox problem, not a command failure]`);
 	else if (sandbox?.denied) {
 		notices.push(sandboxDenialMarker(sandbox.mode));
 		if (escalationModes.length > 0) notices.push(escalationHintMarker("command"));
 	}
-	if (notices.length === 0) return read.delta;
-	return `${read.delta}${read.delta.length > 0 && !read.delta.endsWith("\n") ? "\n" : ""}${notices.join("\n")}`;
+	if (notices.length === 0) return delta;
+	return `${delta}${delta.length > 0 && !delta.endsWith("\n") ? "\n" : ""}${notices.join("\n")}`;
 }
 //#endregion
 //#region lib/types/index.js
 /**
-* Model-facing Consumer of the `ctx.shell` capability seam. Background calls
-* register process handles with `ctx.jobs`; their work uses job cancellation
-* rather than the tool-call signal after an id is returned.
+* Model-facing Consumer of the `ctx.shell` capability seam. While a job
+* registry is composed, every call registers its process with `ctx.jobs` as
+* it starts: `run_in_background` returns the id at once, and a foreground call
+* waits on its job until the command finishes or the wait times out, at which
+* point it returns the same id. Without a registry the tool is foreground-only
+* and the executor's deadline kills the command.
 *
 * TODO(permissions): deployment policy belongs in `tools/pre-execute` and
 * sandboxing executors; see docs/architecture.md § Where new behavior goes.
@@ -116,15 +228,21 @@ const inject = [
 	"shellEnv"
 ];
 /** Runtime configuration schema for the bash tool plugin. */
-const Config = z.object({ toolName: z.string().default("bash"), enableRunInBackground: z.boolean().default(true) });
-function validateBashArgs(args) {
+const Config = z.object({
+	toolName: z.string().default("bash"),
+	enableRunInBackground: z.boolean().default(true),
+	promoteOnTimeout: z.boolean().default(true)
+});
+function validateBashArgs(args, effectiveMode) {
 	if (args.command.trim().length === 0) throw new Error("invalid command: expected a non-empty string");
 	if (args.description.trim().length === 0) throw new Error("invalid description: expected a non-empty string");
 	if (args.timeoutMs !== void 0 && (!Number.isFinite(args.timeoutMs) || args.timeoutMs <= 0)) throw new Error(`invalid timeoutMs: expected a positive number, got ${JSON.stringify(args.timeoutMs)}`);
-	validateEscalationArgs(args.sandbox_permissions, args.justification);
+	if (args.sandbox_permissions !== void 0 && args.sandbox_permissions === effectiveMode) return;
+	const justification = args.sandbox_permissions === void 0 && args.justification?.trim() === "" ? void 0 : args.justification;
+	validateEscalationArgs(args.sandbox_permissions, justification);
 }
-function bashDescription(backgroundEnabled, escalationModes) {
-	const background = backgroundEnabled ? "Set `run_in_background: true` for long-running commands: the call returns a job id immediately; read its output with `job_output` and stop it with `job_kill`." : "Background execution is not available; long-running commands must finish within the timeout.";
+function bashDescription(backgroundEnabled, escalationModes, promoteOnTimeout) {
+	const background = backgroundEnabled ? "Set `run_in_background: true` for long-running commands: the call returns a job id immediately; read its output with `job_output` and stop it with `job_kill`." + (promoteOnTimeout ? " A foreground command that reaches its timeout is not killed: it moves to the background the same way, returning its job id and the output so far." : "") : "Background execution is not available; long-running commands must finish within the timeout.";
 	const base = `Execute a bash command (\`bash -c\`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass \`workdir\` instead of using \`cd\`. Non-zero exits are reported as \`[exit code: N]\`. Current harness environment facts are exposed through managed \`$${DSH_ENV_PREFIX}*\` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as \`[sandbox: file access denied under <mode> mode]\` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. ` + background;
 	if (escalationModes.length === 0) return base;
 	return base + " Attempting a command the sandbox may deny is safe and expected: run it and read the marker rather than assuming the denial. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn — the one sanctioned exception to a denial: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Do not detour through chat to ask permission first — the approval prompt raised by that retry is how the user consents. If the session states approval prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. Never escalate speculatively: ground the request in a real denial — normally the one this command just hit; escalating up front is fine only when this session already denied the same access. A rejected escalation is final for that command — stop and explain, never work around it — but it does not forbid attempting or escalating other commands later.";
@@ -155,7 +273,9 @@ function presentBashResult(args, result) {
 	const block = result.content.length === 1 ? result.content[0] : void 0;
 	if (block === void 0 || block.type !== "text") return void 0;
 	const raw = block.text;
-	if (typeof args === "object" && args !== null && args.run_in_background === true || result.isError) return {
+	const isBackground = typeof args === "object" && args !== null && args.run_in_background === true;
+	const isPromoted = result.value?.kind === "promoted";
+	if (isBackground || isPromoted || result.isError) return {
 		card: "generic",
 		content: [{
 			type: "text",
@@ -177,9 +297,9 @@ function presentBashResult(args, result) {
 */
 function resolveWorkdir(modelWorkdir, exec, policyWorkspaceRoot) {
 	const headerCwd = exec.agent?.session.header.cwd;
-	const sessionCwd = policyWorkspaceRoot ?? (headerCwd === void 0 ? void 0 : canonicalPath(headerCwd));
+	const sessionCwd = policyWorkspaceRoot ?? headerCwd;
 	if (modelWorkdir === void 0) return sessionCwd;
-	if (sessionCwd !== void 0 && !isAbsolute(modelWorkdir)) return resolve(sessionCwd, modelWorkdir);
+	if (sessionCwd !== void 0 && !isAbsolute(modelWorkdir)) return `${sessionCwd}${sep}${modelWorkdir}`;
 	return modelWorkdir;
 }
 /** Detach the executor DTO from readonly Service Definition types into plain JSON data. */
@@ -205,6 +325,12 @@ function canonicalBashResult(result) {
 		} } : {}
 	};
 }
+/** The structured abort the foreground paths throw when the caller cancels the call. */
+function toolAborted() {
+	const error = new HarnessError("tool call aborted", TOOL_ABORTED);
+	error.name = "AbortError";
+	return error;
+}
 /** Canonical background-handle properties shared by the bash output union. */
 const BACKGROUND_OUTPUT_PROPERTIES = {
 	kind: {
@@ -219,6 +345,7 @@ const BACKGROUND_OUTPUT_PROPERTIES = {
 };
 function apply(ctx, config = {}) {
 	const backgroundEnabled = config.enableRunInBackground ?? true;
+	const promoteOnTimeout = (config.promoteOnTimeout ?? true) && backgroundEnabled;
 	const defaultMode = ctx.shell.sandboxMode;
 	const escalationModes = defaultMode === void 0 ? [] : ESCALATION_TARGETS;
 	const sandboxPolicy = defaultMode === void 0 ? void 0 : ctx.get("sandboxPolicy");
@@ -257,193 +384,335 @@ function apply(ctx, config = {}) {
 		order: ctx.systemPrompt.getSectionOrder("TOOL_BASH"),
 		text: `Check the [exit code: N] marker on every ${config.toolName} result; investigate failures before moving on.`
 	});
-	ctx.tools.register(defineTool({
-		name: config.toolName,
-		description: bashDescription(backgroundEnabled, escalationModes),
-		parameters: {
-			command: {
-				type: "string",
-				required: true,
-				description: "The bash command to execute."
-			},
-			description: {
-				type: "string",
-				required: true,
-				description: "Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."
-			},
-			timeoutMs: {
-				type: "number",
-				description: "Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."
-			},
-			workdir: {
-				type: "string",
-				description: "Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."
-			},
-			...backgroundEnabled ? { run_in_background: {
-				type: "boolean",
-				description: "Run in the background and return a job id immediately (collect with job_output, stop with job_kill). No timeout applies."
-			} } : {},
-			...escalationModes.length > 0 ? {
-				sandbox_permissions: {
+	/**
+	* One registration of the `bash` tool. With a registry, every call
+	* registers its process as a job at its start; without one the tool is
+	* foreground-only and the executor's deadline kills the command.
+	*/
+	const bashTool = (jobs) => {
+		const background = jobs !== void 0;
+		const promote = background && promoteOnTimeout;
+		/** Register the command as a job; the process spawns inside the starter, after admission. */
+		const startJob = (registry, args, exec, spec) => {
+			let proc;
+			let stopped;
+			return {
+				id: registry.start({
+					kind: "bash",
+					label: args.command,
+					...exec.agent ? { owner: exec.agent.id } : {},
+					output: processSources(() => proc),
+					run: () => {
+						const hooks = processJob(async (signal) => {
+							proc = await ctx.shell.execute({
+								...spec,
+								signal
+							});
+							return proc;
+						}, (started) => processOutcome(started, escalationModes));
+						return {
+							done: hooks.done,
+							cancel: (reason) => {
+								stopped = reason;
+								hooks.cancel(reason);
+							}
+						};
+					}
+				}),
+				process: () => proc,
+				stopped: () => stopped
+			};
+		};
+		/** Wait on a registered foreground command until it settles or the timeout passes. */
+		const waitOnJob = async (registry, attached, exec, spec) => {
+			const owner = exec.agent?.id;
+			const timeoutMs = spec.timeoutMs;
+			/**
+			* Stop the job on this call's own account and stay on it until it
+			* settles, so the settlement is `awaited` and no completion notice
+			* follows a result this call already carries; the record then leaves
+			* with the call, as the model never saw the id.
+			*/
+			const stop = async (reason) => {
+				registry.kill(attached.id, owner, reason);
+				const settled = await registry.wait(attached.id, timeoutMs, owner);
+				if (settled.status !== "running" && settled.status !== "stopping") registry.remove(attached.id, owner);
+				return settled;
+			};
+			let view;
+			try {
+				view = await registry.wait(attached.id, timeoutMs, owner, exec.signal);
+			} catch {
+				await stop("tool call aborted");
+				throw toolAborted();
+			}
+			if ((view.status === "running" || view.status === "stopping") && attached.process() === void 0) {
+				await stop("timed out during preparation");
+				return {
+					kind: "foreground",
+					exitCode: null,
+					signal: null,
+					timedOut: true,
+					aborted: false,
+					timeoutMs,
+					stdout: {
+						text: "",
+						truncated: false
+					},
+					stderr: {
+						text: "",
+						truncated: false
+					},
+					...spec.sandboxPolicy !== void 0 ? { sandbox: {
+						mode: spec.sandboxPolicy.mode,
+						denied: false
+					} } : {}
+				};
+			}
+			if (view.status === "running" || view.status === "stopping") {
+				const read = registry.read(attached.id, owner);
+				return {
+					kind: "promoted",
+					jobId: attached.id,
+					timeoutMs,
+					output: renderJobRead(ringDelta(read.chunks), read.lossy, read.job.output.spillPaths ?? [], attached.process()?.sandbox, escalationModes)
+				};
+			}
+			registry.remove(attached.id, owner);
+			const process = attached.process();
+			if (process === void 0) throw new Error(view.detail);
+			const result = await process.result();
+			const stopped = attached.stopped();
+			return {
+				kind: "foreground",
+				...canonicalBashResult(result),
+				...stopped !== void 0 ? { stopped } : {}
+			};
+		};
+		return defineTool({
+			name: config.toolName,
+			description: bashDescription(background, escalationModes, promote),
+			parameters: {
+				command: {
 					type: "string",
-					enum: [...escalationModes],
-					description: "The wider sandbox mode this command needs. Only valid as a one-shot retry of a command the sandbox just denied; requires justification and user approval."
+					required: true,
+					description: "The bash command to execute."
 				},
-				justification: {
+				description: {
 					type: "string",
-					description: "Required with sandbox_permissions: one sentence for the user explaining why this exact command needs the wider access."
-				}
-			} : {}
-		},
-		output: {
-			schema: { oneOf: [{
-				type: "object",
-				additionalProperties: false,
-				properties: BACKGROUND_OUTPUT_PROPERTIES
-			}, {
-				type: "object",
-				additionalProperties: false,
-				properties: {
-					kind: {
+					required: true,
+					description: "Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."
+				},
+				timeoutMs: {
+					type: "number",
+					description: promote ? "Timeout in milliseconds. The executor applies its configured default and cap; on expiry the command moves to the background as a job instead of being killed." : "Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."
+				},
+				workdir: {
+					type: "string",
+					description: "Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."
+				},
+				...background ? { run_in_background: {
+					type: "boolean",
+					description: "Run in the background and return a job id immediately (collect with job_output, stop with job_kill). No timeout applies."
+				} } : {},
+				...escalationModes.length > 0 ? {
+					sandbox_permissions: {
 						type: "string",
-						required: true,
-						const: "foreground"
-					},
-					exitCode: {
-						required: true,
-						oneOf: [{ type: "integer" }, { type: "null" }]
+						enum: [...escalationModes],
+						description: "The wider sandbox mode this command needs. Only valid as a one-shot retry of a command the sandbox just denied; requires justification and user approval."
 					},
-					signal: {
-						required: true,
-						oneOf: [{ type: "string" }, { type: "null" }]
-					},
-					timedOut: {
-						type: "boolean",
-						required: true
-					},
-					aborted: {
-						type: "boolean",
-						required: true
-					},
-					timeoutMs: {
-						type: "number",
-						required: true
+					justification: {
+						type: "string",
+						description: "Required with sandbox_permissions: one sentence for the user explaining why this exact command needs the wider access."
+					}
+				} : {}
+			},
+			output: {
+				schema: { oneOf: [
+					{
+						type: "object",
+						additionalProperties: false,
+						properties: BACKGROUND_OUTPUT_PROPERTIES
 					},
-					stdout: {
+					{
 						type: "object",
 						additionalProperties: false,
-						required: true,
 						properties: {
-							text: {
+							kind: {
+								type: "string",
+								required: true,
+								const: "promoted"
+							},
+							jobId: {
 								type: "string",
 								required: true
 							},
-							truncated: {
-								type: "boolean",
+							timeoutMs: {
+								type: "number",
 								required: true
 							},
-							spillPath: { type: "string" }
+							output: {
+								type: "string",
+								required: true
+							}
 						}
 					},
-					stderr: {
+					{
 						type: "object",
 						additionalProperties: false,
-						required: true,
 						properties: {
-							text: {
+							kind: {
 								type: "string",
-								required: true
+								required: true,
+								const: "foreground"
+							},
+							exitCode: {
+								required: true,
+								oneOf: [{ type: "integer" }, { type: "null" }]
+							},
+							signal: {
+								required: true,
+								oneOf: [{ type: "string" }, { type: "null" }]
 							},
-							truncated: {
+							timedOut: {
 								type: "boolean",
 								required: true
 							},
-							spillPath: { type: "string" }
-						}
-					},
-					sandbox: {
-						type: "object",
-						additionalProperties: false,
-						properties: {
-							mode: {
-								type: "string",
+							aborted: {
+								type: "boolean",
 								required: true
 							},
-							denied: {
-								type: "boolean",
+							stopped: { type: "string" },
+							timeoutMs: {
+								type: "number",
 								required: true
 							},
-							enforcement: { type: "string" },
-							runnerFailed: { type: "boolean" }
+							stdout: {
+								type: "object",
+								additionalProperties: false,
+								required: true,
+								properties: {
+									text: {
+										type: "string",
+										required: true
+									},
+									truncated: {
+										type: "boolean",
+										required: true
+									},
+									spillPath: { type: "string" }
+								}
+							},
+							stderr: {
+								type: "object",
+								additionalProperties: false,
+								required: true,
+								properties: {
+									text: {
+										type: "string",
+										required: true
+									},
+									truncated: {
+										type: "boolean",
+										required: true
+									},
+									spillPath: { type: "string" }
+								}
+							},
+							sandbox: {
+								type: "object",
+								additionalProperties: false,
+								properties: {
+									mode: {
+										type: "string",
+										required: true
+									},
+									denied: {
+										type: "boolean",
+										required: true
+									},
+									enforcement: { type: "string" },
+									runnerFailed: { type: "boolean" }
+								}
+							}
 						}
 					}
+				] },
+				render: (_args, value) => [{
+					type: "text",
+					text: value.kind === "background" ? `started background job ${value.jobId}` : value.kind === "promoted" ? renderPromoted(value) : renderResult(value, escalationModes)
+				}]
+			},
+			async execute(args, exec) {
+				const standingPolicy = resolveSandboxPolicy(exec);
+				validateBashArgs(args, standingPolicy?.mode);
+				const approvedMode = args.sandbox_permissions !== void 0 && args.justification !== void 0 ? await approveBashEscalation(args.sandbox_permissions, args.justification, exec, standingPolicy) : void 0;
+				const policy = approvedMode === void 0 ? standingPolicy : {
+					...standingPolicy,
+					mode: approvedMode
+				};
+				const workdir = resolveWorkdir(args.workdir, exec, standingPolicy?.workspaceRoot);
+				const dshEnv = ctx.shellEnv.collect(exec);
+				const request = {
+					command: args.command,
+					...workdir !== void 0 ? { workdir } : {},
+					...args.timeoutMs !== void 0 ? { timeoutMs: args.timeoutMs } : {},
+					dshEnv,
+					...policy !== void 0 ? { sandboxPolicy: policy } : {}
+				};
+				if (args.run_in_background === true) {
+					if (!backgroundEnabled) throw new Error("run_in_background is disabled for this deployment (enableRunInBackground: false)");
+					if (jobs === void 0) throw new Error("background jobs unavailable: load @deepseek-ai/dsh-jobs and @deepseek-ai/dsh-tool-jobs");
+					if (exec.signal.aborted) throw toolAborted();
+					return {
+						kind: "background",
+						jobId: startJob(jobs, args, exec, ctx.shell.resolve({
+							...request,
+							onExpiry: "none"
+						})).id
+					};
 				}
-			}] },
-			render: (_args, value) => [{
-				type: "text",
-				text: value.kind === "background" ? `started background job ${value.jobId}` : renderResult(value, escalationModes)
-			}]
-		},
-		async execute(args, exec) {
-			validateBashArgs(args);
-			const standingPolicy = resolveSandboxPolicy(exec);
-			const approvedMode = args.sandbox_permissions !== void 0 && args.justification !== void 0 ? await approveBashEscalation(args.sandbox_permissions, args.justification, exec, standingPolicy) : void 0;
-			const policy = approvedMode === void 0 ? standingPolicy : {
-				...standingPolicy,
-				mode: approvedMode
-			};
-			const workdir = resolveWorkdir(args.workdir, exec, standingPolicy?.workspaceRoot);
-			const dshEnv = ctx.shellEnv.collect(exec);
-			const request = {
-				command: args.command,
-				...workdir !== void 0 ? { workdir } : {},
-				...args.timeoutMs !== void 0 ? { timeoutMs: args.timeoutMs } : {},
-				dshEnv,
-				...policy !== void 0 ? { sandboxPolicy: policy } : {}
-			};
-			if (args.run_in_background === true) {
-				if (!backgroundEnabled) throw new Error("run_in_background is disabled for this deployment (enableRunInBackground: false)");
-				const jobs = ctx.get("jobs");
-				if (jobs === void 0) throw new Error("background jobs unavailable: load @deepseek-ai/dsh-jobs and @deepseek-ai/dsh-tool-jobs");
-				if (exec.signal.aborted) {
-					const error = new HarnessError("tool call aborted", TOOL_ABORTED);
-					error.name = "AbortError";
-					throw error;
+				if (jobs !== void 0 && promote) {
+					const spec = ctx.shell.resolve({
+						...request,
+						onExpiry: "none"
+					});
+					let attached;
+					try {
+						attached = startJob(jobs, args, exec, spec);
+					} catch (error) {
+						ctx.logger.warn(`bash: job registration refused, running in the foreground with the timeout kill instead: ${String(error)}`);
+					}
+					if (attached !== void 0) return waitOnJob(jobs, attached, exec, spec);
 				}
+				const result = await (await ctx.shell.execute(ctx.shell.resolve({
+					...request,
+					signal: exec.signal
+				}))).result();
+				if (result.aborted) throw toolAborted();
 				return {
-					kind: "background",
-					jobId: jobs.start({
-						kind: "bash",
-						label: args.command,
-						...exec.agent ? { owner: exec.agent } : {},
-						run: () => {
-							const proc = ctx.shell.start(ctx.shell.resolve(request));
-							return {
-								cancel: () => void proc.kill(),
-								done: proc.done.then(() => processOutcome(proc)),
-								readOutput: () => renderProcessRead(proc.readOutput(), proc.sandbox, escalationModes)
-							};
-						}
-					})
+					kind: "foreground",
+					...canonicalBashResult(result)
 				};
-			}
-			const result = await ctx.shell.run(ctx.shell.resolve({
-				...request,
-				signal: exec.signal
-			}));
-			if (result.aborted) {
-				const error = new HarnessError("tool call aborted", TOOL_ABORTED);
-				error.name = "AbortError";
-				throw error;
-			}
-			return {
-				kind: "foreground",
-				...canonicalBashResult(result)
-			};
-		},
-		presentCall: presentBashCall,
-		presentResult: presentBashResult
-	}));
+			},
+			presentCall: presentBashCall,
+			presentResult: presentBashResult
+		});
+	};
+	if (!backgroundEnabled) {
+		ctx.tools.register(bashTool(void 0));
+		return;
+	}
+	let foregroundOnly = ctx.get("jobs") === void 0 ? ctx.tools.register(bashTool(void 0)) : void 0;
+	ctx.inject(["jobs"], (jobCtx) => {
+		foregroundOnly?.();
+		foregroundOnly = void 0;
+		const unregister = ctx.tools.register(bashTool(jobCtx.jobs));
+		jobCtx.effect(() => () => {
+			unregister();
+			if (ctx.fiber.state === 2) foregroundOnly = ctx.tools.register(bashTool(void 0));
+		});
+	});
 }
 //#endregion
 export { Config, apply, inject, name };