@warlock.js/ai-workspace 5.30.0 → 5.31.0

package/cjs/index.cjs

@@ -33,6 +33,7 @@ let node_fs_promises = require("node:fs/promises");
 let _warlock_js_fs = require("@warlock.js/fs");
 let node_child_process = require("node:child_process");
 let node_process = require("node:process");
+let node_string_decoder = require("node:string_decoder");
 
 //#region ../../packages/ai-workspace/src/errors.ts
 /**
@@ -60,6 +61,8 @@ var WorkspacePolicyError = class extends _warlock_js_ai.AIError {
 		this.path = options.path;
 		this.command = options.command;
 		this.pattern = options.pattern;
+		this.reason = options.reason;
+		this.executable = options.executable;
 	}
 };
 /**
@@ -85,8 +88,896 @@ var WorkspaceEditError = class extends _warlock_js_ai.AIError {
 		this.matches = options.matches;
 		this.expectedHash = options.expectedHash;
 		this.actualHash = options.actualHash;
+		this.editIndex = options.editIndex;
 	}
 };
+/**
+* A `shell_output` / `shell_kill` call (or `shellOutput()` / `shellKill()`)
+* named a background command this workspace does not know. Returned to the
+* agent as tool-error data like the other workspace errors.
+*
+* @example
+* if (error instanceof WorkspaceJobError && error.type === "not-found") {
+*   console.warn(`No background command ${error.jobId}`);
+* }
+*/
+var WorkspaceJobError = class extends _warlock_js_ai.AIError {
+	constructor(message, options) {
+		super("TOOL_EXEC_FAILED", message, options);
+		this.name = "WorkspaceJobError";
+		this.type = options.type;
+		this.jobId = options.jobId;
+	}
+};
+
+//#endregion
+//#region ../../packages/ai-workspace/src/policy/jail.ts
+/**
+* Whether `child` is contained within `root` (or equals it), comparing
+* absolute paths. Guards against the `/srv/app-evil` vs `/srv/app`
+* prefix-collision by comparing path segments, not string prefixes.
+*/
+function isInside(child, root) {
+	const relative = node_path.default.relative(root, child);
+	return relative === "" || !relative.startsWith("..") && !node_path.default.isAbsolute(relative);
+}
+/**
+* Translate a glob (the small subset used by `denyPaths` and
+* `list.ignore` — `*`, `**`, `?`) into an anchored `RegExp` over a
+* `/`-separated relative path. `**` spans path separators; a single `*`
+* does not.
+*/
+function globToRegExp(glob) {
+	let source = "";
+	for (let index = 0; index < glob.length; index++) {
+		const char = glob.charAt(index);
+		if (char === "*") {
+			if (glob.charAt(index + 1) === "*") {
+				source += ".*";
+				index++;
+				if (glob.charAt(index + 1) === "/") index++;
+			} else source += "[^/]*";
+			continue;
+		}
+		if (char === "?") {
+			source += "[^/]";
+			continue;
+		}
+		source += char.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+	}
+	return new RegExp(`^${source}$`);
+}
+/**
+* Whether a workspace-relative (`/`-separated) path matches any of the
+* globs. A glob also covers everything beneath a matched directory
+* (`".git/**"` covers `.git/config`), and a bare name without wildcards
+* (`".git"`, `"node_modules"`) covers its contents.
+*/
+function matchesAnyGlob(relativePath, globs) {
+	return globs.some((glob) => {
+		if (globToRegExp(glob).test(relativePath)) return true;
+		if (!glob.includes("*") && !glob.includes("?")) {
+			const prefix = glob.endsWith("/") ? glob : `${glob}/`;
+			return relativePath.startsWith(prefix);
+		}
+		return false;
+	});
+}
+/**
+* The jail check without touching the filesystem: is the absolute path
+* `target` (already resolved lexically) inside `cwd` and off every
+* `denyPaths` glob, or inside an `allowPaths` root? Symlinks are NOT
+* resolved here — the shell policy uses it to refuse obvious escapes
+* synchronously, and `exec` re-checks every path with `resolveInJail`.
+*/
+function isInsideJailLexically(policy, target) {
+	const root = node_path.default.resolve(policy.cwd);
+	if (isInside(target, root)) {
+		const relative = node_path.default.relative(root, target).split(node_path.default.sep).join("/");
+		return !(policy.denyPaths && policy.denyPaths.length > 0 && matchesAnyGlob(relative, policy.denyPaths));
+	}
+	return (policy.allowPaths ?? []).some((allowRoot) => isInside(target, node_path.default.resolve(allowRoot)));
+}
+
+//#endregion
+//#region ../../packages/ai-workspace/src/policy/shell-parser.ts
+/** Deepest nesting of subshells and substitutions the parser accepts. */
+const MAX_NESTING = 16;
+/**
+* Words that start a compound command (or negate a pipeline) when they
+* appear unquoted in command position. The parser does not read compound
+* commands, so a line using one is refused.
+*/
+const RESERVED_WORDS = new Set([
+	"!",
+	"{",
+	"}",
+	"[[",
+	"]]",
+	"case",
+	"coproc",
+	"do",
+	"done",
+	"elif",
+	"else",
+	"esac",
+	"fi",
+	"for",
+	"function",
+	"if",
+	"in",
+	"select",
+	"then",
+	"until",
+	"while"
+]);
+/** cmd.exe keywords the `"cmd"` dialect refuses in command position. */
+const CMD_RESERVED_WORDS = new Set([
+	"if",
+	"for",
+	"goto",
+	"setlocal",
+	"endlocal"
+]);
+/** A parameter name inside `${…}`: a variable, a positional or a special parameter. */
+const PARAMETER_NAME = String.raw`(?:[A-Za-z_][A-Za-z0-9_]*|[0-9]+|[@*#?$!-])`;
+/**
+* Allowed `${…}` forms: `${name}`, `${#name}`, `${name-word}`,
+* `${name:-word}` (also `=`, `+`, `?`), `${name%word}`, `${name%%word}`,
+* `${name#word}`, `${name##word}`. Everything else — substrings and
+* subscripts (arithmetic in bash), `${!name}`, `${name@op}`, pattern
+* substitution — is refused.
+*/
+const PARAMETER_EXPANSION = new RegExp(`^(?:#${PARAMETER_NAME}|${PARAMETER_NAME}(?:(?::?[-=+?]|%%?|##?)[^\`\$'"\\\\{}()@\\n]*)?)$`);
+/** A refusal raised while parsing; caught by {@link parseShellLine}. */
+var ShellSyntaxRefusal = class extends Error {
+	constructor(reason, message) {
+		super(message);
+		this.reason = reason;
+	}
+};
+/** Refuse a construct the parser does not read with confidence. */
+function unsupported(message) {
+	return new ShellSyntaxRefusal("unsupported-syntax", message);
+}
+/** Refuse an unterminated quote / substitution. */
+function unbalanced(message) {
+	return new ShellSyntaxRefusal("unbalanced-quotes", message);
+}
+/** Parser for the POSIX `sh` dialect. */
+var PosixParser = class PosixParser {
+	constructor(src, state) {
+		this.src = src;
+		this.state = state;
+		this.pos = 0;
+		this.pendingHeredocs = [];
+	}
+	/** Parse the whole line as a command list. */
+	parseProgram(segments) {
+		this.parseList(null, segments);
+		this.assertNoPendingHeredocs();
+	}
+	/** Parse the contents of a backtick substitution (a full list until EOF). */
+	parseNestedProgram() {
+		this.parseList(null, void 0);
+		this.assertNoPendingHeredocs();
+	}
+	/**
+	* Scan an unquoted-delimiter here-document body: `$…`, `${…}`, `$(…)` and
+	* backticks expand there exactly as inside double quotes (but `"` is an
+	* ordinary character), so any command substitution in it runs.
+	*/
+	parseExpandingText() {
+		while (!this.atEnd()) {
+			const char = this.peek();
+			if (char === "\\") {
+				this.pos += 2;
+				continue;
+			}
+			if (char === "$") {
+				this.parseDollar("heredoc");
+				continue;
+			}
+			if (char === "`") {
+				this.parseBackticks(false);
+				continue;
+			}
+			this.pos++;
+		}
+	}
+	atEnd() {
+		return this.pos >= this.src.length;
+	}
+	peek(offset = 0) {
+		return this.src.charAt(this.pos + offset);
+	}
+	assertNoPendingHeredocs() {
+		if (this.pendingHeredocs.length > 0) throw unsupported(`The here-document delimited by \`${this.pendingHeredocs[0]?.delimiter ?? ""}\` is never terminated.`);
+	}
+	enterNesting() {
+		this.state.nesting++;
+		if (this.state.nesting > MAX_NESTING) throw unsupported("The line nests subshells or substitutions too deeply.");
+	}
+	exitNesting() {
+		this.state.nesting--;
+	}
+	/** Skip spaces, tabs and backslash-newline continuations. */
+	skipBlanks() {
+		while (!this.atEnd()) {
+			const char = this.peek();
+			if (char === " " || char === "	") {
+				this.pos++;
+				continue;
+			}
+			if (char === "\\" && this.peek(1) === "\n") {
+				this.pos += 2;
+				continue;
+			}
+			break;
+		}
+	}
+	/** Skip a `#` comment up to (not including) the newline. */
+	skipComment() {
+		const newline = this.src.indexOf("\n", this.pos);
+		this.pos = newline === -1 ? this.src.length : newline;
+	}
+	/** Consume one newline and read any here-document bodies queued before it. */
+	consumeNewline() {
+		this.pos++;
+		if (this.pendingHeredocs.length === 0) return;
+		if (this.state.nesting > 0) throw unsupported("Here-documents inside subshells or substitutions are not supported.");
+		const pending = this.pendingHeredocs;
+		this.pendingHeredocs = [];
+		for (const heredoc of pending) this.readHeredocBody(heredoc);
+	}
+	/** Skip blanks, comments and newlines (separators between commands). */
+	skipBlanksAndNewlines() {
+		while (!this.atEnd()) {
+			this.skipBlanks();
+			if (this.peek() === "#") {
+				this.skipComment();
+				continue;
+			}
+			if (this.peek() === "\n") {
+				this.consumeNewline();
+				continue;
+			}
+			break;
+		}
+	}
+	readHeredocBody(heredoc) {
+		const bodyLines = [];
+		while (true) {
+			if (this.atEnd()) throw unsupported(`The here-document delimited by \`${heredoc.delimiter}\` is never terminated.`);
+			const lineEnd = this.src.indexOf("\n", this.pos);
+			const line = lineEnd === -1 ? this.src.slice(this.pos) : this.src.slice(this.pos, lineEnd);
+			const compared = heredoc.stripTabs ? line.replace(/^\t+/, "") : line;
+			this.pos = lineEnd === -1 ? this.src.length : lineEnd + 1;
+			if (compared === heredoc.delimiter) break;
+			bodyLines.push(compared);
+		}
+		if (heredoc.expand) new PosixParser(bodyLines.join("\n"), this.state).parseExpandingText();
+	}
+	/**
+	* Parse a command list until `closing` (`")"`) or the end of the input.
+	* `segments`, when given, collects the top-level pipelines.
+	*/
+	parseList(closing, segments) {
+		let sawCommand = false;
+		while (true) {
+			this.skipBlanksAndNewlines();
+			if (this.atEnd()) {
+				if (closing !== null) throw unbalanced(`A \`(\` or \`$(\` is never closed with \`${closing}\`.`);
+				break;
+			}
+			if (closing !== null && this.peek() === closing) break;
+			const start = this.pos;
+			this.parsePipeline(closing);
+			const end = this.pos;
+			sawCommand = true;
+			this.skipBlanks();
+			if (this.peek() === "#") this.skipComment();
+			const operator = this.readListOperator();
+			segments?.push({
+				source: this.src.slice(start, end).trim(),
+				...operator !== null ? { operator } : {}
+			});
+			if (operator === "&&" || operator === "||") {
+				this.skipBlanksAndNewlines();
+				if (this.atEnd() || closing !== null && this.peek() === closing) throw unsupported(`The line ends with \`${operator}\` but no command follows it.`);
+				continue;
+			}
+			if (operator === "&") this.state.background = true;
+			if (operator === null) {
+				if (this.atEnd() || closing !== null && this.peek() === closing) break;
+				throw unsupported(`Unexpected \`${this.peek()}\`.`);
+			}
+		}
+		if (!sawCommand) throw unsupported(closing === null ? "The command is empty." : "A `( )` or `$( )` is empty.");
+	}
+	/** Read `&&`, `||`, `;`, `&` or a newline after a pipeline. */
+	readListOperator() {
+		const char = this.peek();
+		const next = this.peek(1);
+		if (char === "&") {
+			if (next === "&") {
+				this.pos += 2;
+				return "&&";
+			}
+			if (next === ">") throw unsupported("`&>` (redirect both streams) is not portable; write `> file 2>&1` instead.");
+			this.pos++;
+			return "&";
+		}
+		if (char === "|" && next === "|") {
+			this.pos += 2;
+			return "||";
+		}
+		if (char === ";") {
+			if (next === ";") throw unsupported("`;;` (a `case` clause) is not supported.");
+			this.pos++;
+			return ";";
+		}
+		if (char === "\n") {
+			this.consumeNewline();
+			return "\n";
+		}
+		return null;
+	}
+	parsePipeline(closing) {
+		this.parseCommand(closing);
+		while (true) {
+			this.skipBlanks();
+			if (this.peek() !== "|" || this.peek(1) === "|") return;
+			if (this.peek(1) === "&") throw unsupported("`|&` is not portable; write `2>&1 |` instead.");
+			this.pos++;
+			this.skipBlanksAndNewlines();
+			if (this.atEnd() || closing !== null && this.peek() === closing) throw unsupported("The line ends with `|` but no command follows it.");
+			this.parseCommand(closing);
+		}
+	}
+	parseCommand(closing) {
+		this.skipBlanks();
+		if (this.peek() === "(") {
+			if (this.peek(1) === "(") throw unsupported("`((…))` (arithmetic) is not supported.");
+			this.parseSubshell();
+			return;
+		}
+		if (this.peek() === ")") throw unsupported(closing === null ? "Unexpected `)`." : "A `( )` or `$( )` is empty.");
+		this.parseSimpleCommand();
+	}
+	parseSubshell() {
+		const start = this.pos;
+		this.pos++;
+		this.enterNesting();
+		this.parseList(")", void 0);
+		if (this.peek() !== ")") throw unbalanced("A `(` is never closed with `)`.");
+		this.pos++;
+		this.exitNesting();
+		const redirects = [];
+		while (true) {
+			this.skipBlanks();
+			if (!this.atRedirectStart()) break;
+			redirects.push(this.parseRedirect());
+		}
+		if (redirects.length > 0) this.state.commands.push({
+			assignments: [],
+			words: [],
+			redirects,
+			source: this.src.slice(start, this.pos).trim()
+		});
+		if (!this.atEnd() && !this.atOperatorBoundary()) throw unsupported("Only an operator or a redirection may follow `)`.");
+	}
+	/** Whether the next character ends a simple command. */
+	atOperatorBoundary() {
+		const char = this.peek();
+		return char === "\n" || char === ";" || char === "&" || char === "|" || char === ")" || char === "#" || char === " " || char === "	";
+	}
+	/** Whether a redirection starts here (`>`, `<`, or digits glued to one). */
+	atRedirectStart() {
+		let index = this.pos;
+		while (index < this.src.length && /[0-9]/.test(this.src.charAt(index))) index++;
+		const char = this.src.charAt(index);
+		return char === "<" || char === ">";
+	}
+	parseSimpleCommand() {
+		const start = this.pos;
+		const command = {
+			assignments: [],
+			words: [],
+			redirects: [],
+			source: ""
+		};
+		while (true) {
+			this.skipBlanks();
+			if (this.atEnd()) break;
+			const char = this.peek();
+			if (char === "\n" || char === ";" || char === "&" || char === "|" || char === ")") break;
+			if (char === "(") throw unsupported("`(` is only supported at the start of a command (a subshell); quote it to pass it as text.");
+			if (char === "#") {
+				this.skipComment();
+				break;
+			}
+			if (this.atRedirectStart()) {
+				command.redirects.push(this.parseRedirect());
+				continue;
+			}
+			const word = this.parseWord();
+			if (command.words.length === 0 && word.assignmentName !== void 0) {
+				command.assignments.push(word);
+				continue;
+			}
+			command.words.push(word);
+			if (command.words.length === 1 && !word.quoted && RESERVED_WORDS.has(word.value)) throw unsupported(`\`${word.value}\` starts a shell compound command, which is not supported; run the commands one at a time.`);
+		}
+		if (command.words.length === 0 && command.assignments.length === 0 && command.redirects.length === 0) throw unsupported("The line has an empty command (two operators in a row?).");
+		command.source = this.src.slice(start, this.pos).trim();
+		this.state.commands.push(command);
+	}
+	parseRedirect() {
+		let digits = "";
+		while (/[0-9]/.test(this.peek())) {
+			digits += this.peek();
+			this.pos++;
+		}
+		const rest = this.src.slice(this.pos, this.pos + 3);
+		let op;
+		if (rest.startsWith("<<<")) throw unsupported("`<<<` (a here-string) is not portable; use a here-document.");
+		else if (rest.startsWith("<<-")) op = "<<-";
+		else if (rest.startsWith("<<")) op = "<<";
+		else if (rest.startsWith("<>")) op = "<>";
+		else if (rest.startsWith("<&")) op = "<&";
+		else if (rest.startsWith("<(") || rest.startsWith(">(")) throw unsupported("Process substitution (`<(…)`, `>(…)`) is not supported.");
+		else if (rest.startsWith(">>")) op = ">>";
+		else if (rest.startsWith(">|")) op = ">|";
+		else if (rest.startsWith(">&")) op = ">&";
+		else op = this.peek();
+		this.pos += op.length;
+		const fd = digits === "" ? void 0 : Number(digits);
+		this.skipBlanks();
+		if (this.atEnd() || /[\n;&|<>()]/.test(this.peek())) throw unsupported(`The redirection \`${op}\` has no target.`);
+		const target = this.parseWord();
+		if (op === "<<" || op === "<<-") {
+			if (this.state.nesting > 0) throw unsupported("Here-documents inside subshells or substitutions are not supported.");
+			if (target.dynamic) throw unsupported("A here-document delimiter must be literal text.");
+			this.pendingHeredocs.push({
+				delimiter: target.value,
+				stripTabs: op === "<<-",
+				expand: !target.quoted
+			});
+			return {
+				op,
+				...fd !== void 0 ? { fd } : {},
+				target,
+				type: "heredoc"
+			};
+		}
+		if (op === ">&" || op === "<&") {
+			if (target.dynamic || !/^(?:[0-9]+|-)$/.test(target.value)) throw unsupported(`\`${op}${target.raw}\` is not portable; write \`> file 2>&1\` to send both streams to a file.`);
+			return {
+				op,
+				...fd !== void 0 ? { fd } : {},
+				target,
+				type: "dup"
+			};
+		}
+		return {
+			op,
+			...fd !== void 0 ? { fd } : {},
+			target,
+			type: op === "<" ? "read" : "write"
+		};
+	}
+	/** Parse one unquoted-context word. */
+	parseWord() {
+		const start = this.pos;
+		let value = "";
+		let dynamic = false;
+		let quoted = false;
+		let braces = false;
+		let nameCandidate = true;
+		let assignmentName;
+		while (!this.atEnd()) {
+			const char = this.peek();
+			if (char === " " || char === "	" || char === "\n" || char === ";" || char === "&" || char === "|" || char === "<" || char === ">" || char === "(" || char === ")") break;
+			if (char === "\r" || char === "\0") throw unsupported("Carriage returns and NUL bytes are not supported in a command line.");
+			if (char === "\\") {
+				const next = this.peek(1);
+				if (next === "") throw unsupported("The line ends with a backslash.");
+				this.pos += 2;
+				if (next !== "\n") {
+					value += next;
+					quoted = true;
+					nameCandidate = false;
+				}
+				continue;
+			}
+			if (char === "'") {
+				const closing = this.src.indexOf("'", this.pos + 1);
+				if (closing === -1) throw unbalanced("A `'` quote is never closed.");
+				value += this.src.slice(this.pos + 1, closing);
+				quoted = true;
+				nameCandidate = false;
+				this.pos = closing + 1;
+				continue;
+			}
+			if (char === "\"") {
+				const part = this.parseDoubleQuoted();
+				value += part.value;
+				dynamic = dynamic || part.dynamic;
+				quoted = true;
+				nameCandidate = false;
+				continue;
+			}
+			if (char === "$") {
+				const part = this.parseDollar("unquoted");
+				value += part.text;
+				dynamic = dynamic || part.dynamic;
+				nameCandidate = false;
+				continue;
+			}
+			if (char === "`") {
+				value += this.parseBackticks(false);
+				dynamic = true;
+				nameCandidate = false;
+				continue;
+			}
+			if (char === "=" && nameCandidate && assignmentName === void 0) {
+				if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) assignmentName = value;
+				nameCandidate = false;
+			} else if (!/[A-Za-z0-9_]/.test(char)) nameCandidate = false;
+			if (char === "*" || char === "?" || char === "[") dynamic = true;
+			if (char === "~") {
+				const previous = this.src.charAt(this.pos - 1);
+				if (this.pos === start || assignmentName !== void 0 && (previous === "=" || previous === ":")) dynamic = true;
+			}
+			if (char === "{" || char === "}") braces = true;
+			value += char;
+			this.pos++;
+		}
+		const raw = this.src.slice(start, this.pos);
+		if (braces && raw !== "{}") throw unsupported(`Unquoted \`{\` or \`}\` in \`${raw}\` (brace expansion or a command group) is not supported; quote it.`);
+		if (raw === "[" || raw === "]") dynamic = false;
+		return {
+			raw,
+			value,
+			dynamic,
+			quoted,
+			...assignmentName !== void 0 ? { assignmentName } : {}
+		};
+	}
+	/** Parse a `"…"` span (cursor on the opening quote). */
+	parseDoubleQuoted() {
+		this.pos++;
+		let value = "";
+		let dynamic = false;
+		while (true) {
+			if (this.atEnd()) throw unbalanced("A `\"` quote is never closed.");
+			const char = this.peek();
+			if (char === "\"") {
+				this.pos++;
+				return {
+					value,
+					dynamic
+				};
+			}
+			if (char === "\0") throw unsupported("NUL bytes are not supported in a command line.");
+			if (char === "\\") {
+				const next = this.peek(1);
+				if (next === "") throw unbalanced("A `\"` quote is never closed.");
+				if (next === "$" || next === "`" || next === "\"" || next === "\\") {
+					value += next;
+					this.pos += 2;
+					continue;
+				}
+				if (next === "\n") {
+					this.pos += 2;
+					continue;
+				}
+				value += char;
+				this.pos++;
+				continue;
+			}
+			if (char === "$") {
+				const part = this.parseDollar("dquote");
+				value += part.text;
+				dynamic = dynamic || part.dynamic;
+				continue;
+			}
+			if (char === "`") {
+				value += this.parseBackticks(true);
+				dynamic = true;
+				continue;
+			}
+			value += char;
+			this.pos++;
+		}
+	}
+	/** Parse a `$…` expansion (cursor on the `$`). */
+	parseDollar(context) {
+		const start = this.pos;
+		const next = this.peek(1);
+		if (next === "(") {
+			if (this.peek(2) === "(") throw unsupported("`$((…))` (arithmetic expansion) is not supported.");
+			this.pos += 2;
+			this.enterNesting();
+			this.parseList(")", void 0);
+			if (this.peek() !== ")") throw unbalanced("A `$(` is never closed with `)`.");
+			this.pos++;
+			this.exitNesting();
+			return {
+				text: this.src.slice(start, this.pos),
+				dynamic: true
+			};
+		}
+		if (next === "{") {
+			const closing = this.src.indexOf("}", this.pos + 2);
+			if (closing === -1) throw unbalanced("A `${` is never closed with `}`.");
+			const body = this.src.slice(this.pos + 2, closing);
+			if (!PARAMETER_EXPANSION.test(body)) throw unsupported(`\`\${${body}}\` is not a supported parameter expansion; use \`$name\`, \`\${name}\` or \`\${name:-default}\`.`);
+			this.pos = closing + 1;
+			return {
+				text: this.src.slice(start, this.pos),
+				dynamic: true
+			};
+		}
+		if (next === "[") throw unsupported("`$[…]` (arithmetic expansion) is not supported.");
+		if (context === "unquoted" && (next === "'" || next === "\"")) throw unsupported(`\`$${next}…${next}\` quoting is not portable; use plain quotes.`);
+		if (/[A-Za-z_]/.test(next)) {
+			this.pos += 2;
+			while (/[A-Za-z0-9_]/.test(this.peek())) this.pos++;
+			return {
+				text: this.src.slice(start, this.pos),
+				dynamic: true
+			};
+		}
+		if (/[0-9@*#?$!-]/.test(next) && next !== "") {
+			this.pos += 2;
+			return {
+				text: this.src.slice(start, this.pos),
+				dynamic: true
+			};
+		}
+		this.pos++;
+		return {
+			text: "$",
+			dynamic: false
+		};
+	}
+	/** Parse a backtick substitution (cursor on the opening backtick); returns its source. */
+	parseBackticks(insideDoubleQuotes) {
+		const start = this.pos;
+		let content = "";
+		this.pos++;
+		while (true) {
+			if (this.atEnd()) throw unbalanced("A backtick substitution is never closed.");
+			const char = this.peek();
+			if (char === "`") {
+				this.pos++;
+				break;
+			}
+			if (char === "\\") {
+				const next = this.peek(1);
+				if (next === "") throw unbalanced("A backtick substitution is never closed.");
+				if (next === "`" || next === "\\" || next === "$") {
+					content += next;
+					this.pos += 2;
+					continue;
+				}
+				if (next === "\"" && insideDoubleQuotes) throw unsupported("An escaped `\\\"` inside backticks inside double quotes is not portable; use `$(…)`.");
+				content += char + next;
+				this.pos += 2;
+				continue;
+			}
+			content += char;
+			this.pos++;
+		}
+		this.enterNesting();
+		new PosixParser(content, this.state).parseNestedProgram();
+		this.exitNesting();
+		return this.src.slice(start, this.pos);
+	}
+};
+/** Parser for the restricted `cmd.exe` dialect. */
+var CmdParser = class {
+	constructor(src, commands) {
+		this.src = src;
+		this.commands = commands;
+		this.pos = 0;
+	}
+	parseProgram(segments) {
+		if (/[\r\n\0]/.test(this.src)) throw unsupported("Line breaks and NUL bytes are not supported in a cmd.exe command line.");
+		while (true) {
+			this.skipBlanks();
+			if (this.atEnd()) throw unsupported(segments.length === 0 ? "The command is empty." : "The line ends with an operator but no command follows it.");
+			const start = this.pos;
+			this.parsePipeline();
+			const end = this.pos;
+			this.skipBlanks();
+			const operator = this.readListOperator();
+			segments.push({
+				source: this.src.slice(start, end).trim(),
+				...operator !== null ? { operator } : {}
+			});
+			if (operator === null) {
+				if (!this.atEnd()) throw unsupported(`Unexpected \`${this.peek()}\`.`);
+				return;
+			}
+		}
+	}
+	atEnd() {
+		return this.pos >= this.src.length;
+	}
+	peek(offset = 0) {
+		return this.src.charAt(this.pos + offset);
+	}
+	skipBlanks() {
+		while (this.peek() === " " || this.peek() === "	") this.pos++;
+	}
+	readListOperator() {
+		if (this.peek() === "&") {
+			if (this.peek(1) === "&") {
+				this.pos += 2;
+				return "&&";
+			}
+			this.pos++;
+			return "&";
+		}
+		if (this.peek() === "|" && this.peek(1) === "|") {
+			this.pos += 2;
+			return "||";
+		}
+		return null;
+	}
+	parsePipeline() {
+		this.parseSimpleCommand();
+		while (this.peek() === "|" && this.peek(1) !== "|") {
+			this.pos++;
+			this.skipBlanks();
+			if (this.atEnd()) throw unsupported("The line ends with `|` but no command follows it.");
+			this.parseSimpleCommand();
+		}
+	}
+	atRedirectStart() {
+		const char = this.peek();
+		if (char === "<" || char === ">") return true;
+		return /[0-9]/.test(char) && (this.peek(1) === ">" || this.peek(1) === "<");
+	}
+	parseSimpleCommand() {
+		const start = this.pos;
+		const command = {
+			assignments: [],
+			words: [],
+			redirects: [],
+			source: ""
+		};
+		while (true) {
+			this.skipBlanks();
+			if (this.atEnd() || this.peek() === "&" || this.peek() === "|") break;
+			if (this.atRedirectStart()) {
+				command.redirects.push(this.parseRedirect());
+				continue;
+			}
+			const word = this.parseWord();
+			command.words.push(word);
+			if (command.words.length === 1) this.checkCommandWord(word);
+		}
+		if (command.words.length === 0 && command.redirects.length === 0) throw unsupported("The line has an empty command (two operators in a row?).");
+		command.source = this.src.slice(start, this.pos).trim();
+		this.commands.push(command);
+	}
+	checkCommandWord(word) {
+		if (word.raw.startsWith("@") || word.raw.startsWith(":")) throw unsupported(`\`${word.raw}\` is not supported as a cmd.exe command name.`);
+		if (/[/=]/.test(word.value)) throw unsupported(`A cmd.exe command name may not contain \`/\` or \`=\` (\`${word.value}\`); use \`\\\` in paths.`);
+		if (!word.quoted && CMD_RESERVED_WORDS.has(word.value.toLowerCase())) throw unsupported(`\`${word.value}\` starts a cmd.exe compound command, which is not supported.`);
+	}
+	parseRedirect() {
+		let fd;
+		if (/[0-9]/.test(this.peek())) {
+			fd = Number(this.peek());
+			this.pos++;
+		}
+		let op;
+		if (this.src.startsWith(">>", this.pos)) op = ">>";
+		else if (this.src.startsWith(">&", this.pos)) op = ">&";
+		else if (this.src.startsWith("<&", this.pos) || this.src.startsWith("<<", this.pos)) throw unsupported(`\`${this.src.slice(this.pos, this.pos + 2)}\` is not supported by cmd.exe.`);
+		else op = this.peek();
+		this.pos += op.length;
+		this.skipBlanks();
+		if (this.atEnd() || /[&|<>]/.test(this.peek())) throw unsupported(`The redirection \`${op}\` has no target.`);
+		const target = this.parseWord();
+		if (op === ">&") {
+			if (!/^[0-9]$/.test(target.value)) throw unsupported(`\`>&${target.raw}\` is not supported; write \`> file 2>&1\`.`);
+			return {
+				op,
+				...fd !== void 0 ? { fd } : {},
+				target,
+				type: "dup"
+			};
+		}
+		return {
+			op,
+			...fd !== void 0 ? { fd } : {},
+			target,
+			type: op === "<" ? "read" : "write"
+		};
+	}
+	parseWord() {
+		const start = this.pos;
+		let value = "";
+		let dynamic = false;
+		let quoted = false;
+		while (!this.atEnd()) {
+			const char = this.peek();
+			if (char === " " || char === "	" || char === "&" || char === "|" || char === "<" || char === ">") break;
+			if (char === "\"") {
+				const closing = this.src.indexOf("\"", this.pos + 1);
+				if (closing === -1) throw unbalanced("A `\"` quote is never closed.");
+				const inner = this.src.slice(this.pos + 1, closing);
+				if (/[%!]/.test(inner)) throw unsupported("`%` and `!` expand even inside quotes in cmd.exe; they are not supported.");
+				if (value.endsWith("\\") || inner.endsWith("\\")) throw unsupported("A backslash before a `\"` is read differently by cmd.exe and programs.");
+				value += inner;
+				quoted = true;
+				this.pos = closing + 1;
+				continue;
+			}
+			if (char === "%" || char === "!" || char === "^" || char === "(" || char === ")" || char === ";" || char === ",") throw unsupported(`Unquoted \`${char}\` has a special meaning in cmd.exe and is not supported.`);
+			if (char === "\\" && this.peek(1) === "\"") throw unsupported("A backslash before a `\"` is read differently by cmd.exe and programs.");
+			if (char === "*" || char === "?") dynamic = true;
+			value += char;
+			this.pos++;
+		}
+		return {
+			raw: this.src.slice(start, this.pos),
+			value,
+			dynamic,
+			quoted
+		};
+	}
+};
+/**
+* Parse a command line for the shell policy. Never throws: a construct the
+* parser does not read with confidence comes back as `{ ok: false }` with a
+* message naming it.
+*
+* @example
+* const parsed = parseShellLine("git add -A && git commit -m 'wip'", "posix");
+* // parsed.ok === true; parsed.commands.map((c) => c.words.map((w) => w.value))
+* // → [["git", "add", "-A"], ["git", "commit", "-m", "wip"]]
+*/
+function parseShellLine(line, dialect) {
+	const segments = [];
+	try {
+		if (dialect === "cmd") {
+			const commands = [];
+			new CmdParser(line, commands).parseProgram(segments);
+			return {
+				ok: true,
+				commands,
+				segments,
+				background: false
+			};
+		}
+		const state = {
+			commands: [],
+			background: false,
+			nesting: 0
+		};
+		new PosixParser(line, state).parseProgram(segments);
+		return {
+			ok: true,
+			commands: state.commands,
+			segments,
+			background: state.background
+		};
+	} catch (error) {
+		if (error instanceof ShellSyntaxRefusal) return {
+			ok: false,
+			reason: error.reason,
+			message: error.message
+		};
+		throw error;
+	}
+}
 
 //#endregion
 //#region ../../packages/ai-workspace/src/policy/tokenize-command.ts
@@ -110,6 +1001,85 @@ const UNQUOTED_METACHARACTERS = new Set([
 	"(",
 	")"
 ]);
+/** Two-character operators reported as one token in a refusal. */
+const TWO_CHARACTER_OPERATORS = new Set([
+	"&&",
+	"||",
+	">>",
+	"<<",
+	"$(",
+	"${",
+	">&",
+	"<&"
+]);
+/**
+* Tokenize a command line into an argv the way {@link tokenizeCommand}
+* does, but say **why** a line cannot be represented as one argv — which
+* quote is unbalanced, or which unquoted operator (`&&`, `|`, `>`, `$(`,
+* a newline, …) was found first. The shell policy uses it to phrase a
+* refusal that tells the model how to split the line.
+*
+* @example
+* analyzeArgvCommand("npm test"); // { ok: true, argv: ["npm", "test"] }
+* analyzeArgvCommand("git add -A && git commit"); // { ok: false, type: "metacharacter", token: "&&", index: 11 }
+*/
+function analyzeArgvCommand(command) {
+	const argv = [];
+	let current = "";
+	let inToken = false;
+	let index = 0;
+	while (index < command.length) {
+		const char = command.charAt(index);
+		if (char === "'" || char === "\"") {
+			const closing = command.indexOf(char, index + 1);
+			if (closing === -1) return {
+				ok: false,
+				type: "unbalanced-quotes",
+				quote: char,
+				index
+			};
+			current += command.slice(index + 1, closing);
+			inToken = true;
+			index = closing + 1;
+			continue;
+		}
+		if (char === " " || char === "	") {
+			if (inToken) {
+				argv.push(current);
+				current = "";
+				inToken = false;
+			}
+			index++;
+			continue;
+		}
+		if (char === "\n" || char === "\r") return {
+			ok: false,
+			type: "metacharacter",
+			token: "\n",
+			index
+		};
+		if (UNQUOTED_METACHARACTERS.has(char)) {
+			const pair = command.slice(index, index + 2);
+			return {
+				ok: false,
+				type: "metacharacter",
+				token: TWO_CHARACTER_OPERATORS.has(pair) ? pair : char,
+				index
+			};
+		}
+		current += char;
+		inToken = true;
+		index++;
+	}
+	if (inToken) argv.push(current);
+	return argv.length > 0 ? {
+		ok: true,
+		argv
+	} : {
+		ok: false,
+		type: "empty"
+	};
+}
 /**
 * Tokenize a command line into an argv array WITHOUT any shell semantics.
 *
@@ -125,6 +1095,7 @@ const UNQUOTED_METACHARACTERS = new Set([
 * shell metacharacter / newline (see {@link UNQUOTED_METACHARACTERS}). The
 * policy gate treats `null` as denied and the local backend refuses to
 * spawn it, which is what closes the `allowed_cmd; anything-else` injection.
+* {@link analyzeArgvCommand} says why a line was refused.
 *
 * @example
 * tokenizeCommand('npm test');                    // ["npm", "test"]
@@ -132,36 +1103,628 @@ const UNQUOTED_METACHARACTERS = new Set([
 * tokenizeCommand('npm test; curl http://evil');  // null (unquoted `;`)
 */
 function tokenizeCommand(command) {
-	const argv = [];
-	let current = "";
-	let inToken = false;
-	let index = 0;
-	while (index < command.length) {
-		const char = command[index];
-		if (char === "'" || char === "\"") {
-			const closing = command.indexOf(char, index + 1);
-			if (closing === -1) return null;
-			current += command.slice(index + 1, closing);
-			inToken = true;
-			index = closing + 1;
+	const analysis = analyzeArgvCommand(command);
+	return analysis.ok ? analysis.argv : null;
+}
+
+//#endregion
+//#region ../../packages/ai-workspace/src/policy/shell-check.ts
+/**
+* Programs and shell builtins that run a command or code the policy cannot
+* see (a script string, a file, a command read from input, another user).
+* With deny rules in force they would hide a denied command, so they are
+* refused unless the policy names them in `allow`.
+*/
+const OPAQUE_RUNNERS = new Set([
+	"sh",
+	"bash",
+	"dash",
+	"zsh",
+	"ksh",
+	"mksh",
+	"ash",
+	"yash",
+	"posh",
+	"fish",
+	"csh",
+	"tcsh",
+	"busybox",
+	"cmd",
+	"powershell",
+	"pwsh",
+	"wsl",
+	"sudo",
+	"doas",
+	"su",
+	"runuser",
+	"pkexec",
+	"runas",
+	"chroot",
+	"nsenter",
+	"unshare",
+	"setsid",
+	"systemd-run",
+	"start-stop-daemon",
+	"daemonize",
+	"xargs",
+	"parallel",
+	"watch",
+	"script",
+	"expect",
+	"at",
+	"batch",
+	"screen",
+	"tmux",
+	"stdbuf",
+	"flock"
+]);
+/** POSIX shell builtins that evaluate code or change how later names resolve. */
+const SHELL_OPAQUE_BUILTINS = new Set([
+	"eval",
+	".",
+	"source",
+	"alias",
+	"unalias",
+	"hash",
+	"enable",
+	"trap",
+	"let",
+	"declare",
+	"typeset",
+	"local",
+	"set",
+	"shopt",
+	"fc",
+	"bind",
+	"complete",
+	"compgen",
+	"compopt",
+	"mapfile",
+	"readarray"
+]);
+/** cmd.exe builtins that run commands or change the environment. */
+const CMD_OPAQUE_BUILTINS = new Set([
+	"call",
+	"start",
+	"set",
+	"pushd",
+	"popd"
+]);
+/**
+* Shell builtins whose arguments bash may evaluate as arithmetic (array
+* subscripts such as `a[$(cmd)]`): their arguments must be literal and free
+* of `[`.
+*/
+const ARITHMETIC_SENSITIVE_BUILTINS = new Set([
+	"test",
+	"[",
+	"printf",
+	"read",
+	"unset",
+	"export",
+	"readonly",
+	"getopts",
+	"wait",
+	"kill",
+	"shift",
+	"return",
+	"exit",
+	"break",
+	"continue",
+	"ulimit"
+]);
+/**
+* Variables a shell-mode line may not assign: they change how the shell
+* parses, traces or resolves what follows (`CDPATH` would move `cd` out of
+* the jail's sight, `PS4` is expanded — command substitutions included —
+* on every traced line, `IFS` re-splits expansions).
+*/
+const SENSITIVE_VARIABLES = new Set([
+	"CDPATH",
+	"ENV",
+	"BASH_ENV",
+	"SHELLOPTS",
+	"BASHOPTS",
+	"IFS",
+	"PS1",
+	"PS2",
+	"PS3",
+	"PS4",
+	"PROMPT_COMMAND",
+	"BASH_XTRACEFD",
+	"GLOBIGNORE",
+	"EXECIGNORE",
+	"BASH_LOADABLES_PATH"
+]);
+/** Redirection targets that are always fine even though they sit outside the jail. */
+const DEVICE_TARGETS = new Set([
+	"/dev/null",
+	"/dev/stdout",
+	"/dev/stderr"
+]);
+/** cmd.exe's null device. */
+const CMD_DEVICE_TARGETS = new Set(["nul"]);
+/** Deepest chain of wrappers (`env time nice …`) the policy unwraps. */
+const MAX_WRAPPER_DEPTH = 8;
+/** Most distinct directories a line may `cd` between. */
+const MAX_CD_CANDIDATES = 32;
+/** Longest command shown verbatim in a refusal before it is abbreviated. */
+const MAX_SHOWN_COMMAND = 48;
+/** The dialect shell mode parses on this platform. */
+function shellDialect() {
+	return process.platform === "win32" ? "cmd" : "posix";
+}
+/**
+* Reduce an argv's first element to the basename the allow/deny policy is
+* keyed on. `"npm"` → `"npm"`; `"/usr/bin/node"` → `"node"`; `"node.exe"`
+* → `"node"` (the `.exe`/`.cmd`/`.bat`/`.com` Windows extension is
+* stripped). The cmd dialect splits Windows paths too.
+*/
+function executableBasename(firstToken, dialect = "posix") {
+	return (dialect === "cmd" ? node_path.default.win32.basename(firstToken) : node_path.default.basename(firstToken)).replace(/\.(exe|cmd|bat|com)$/i, "");
+}
+/** Show a command in a refusal, abbreviated at a word boundary when long. */
+function show(source) {
+	const flat = source.replace(/\s+/g, " ").trim();
+	if (flat.length <= MAX_SHOWN_COMMAND) return `\`${flat}\``;
+	const cut = flat.lastIndexOf(" ", MAX_SHOWN_COMMAND);
+	return `\`${flat.slice(0, cut > 0 ? cut : MAX_SHOWN_COMMAND)} …\``;
+}
+function compilePattern(pattern) {
+	if (pattern instanceof RegExp) {
+		const regex = new RegExp(pattern.source, pattern.flags.replace(/[gy]/g, ""));
+		return {
+			source: pattern,
+			test: (argv, dialect) => regex.test([executableBasename(argv[0] ?? "", dialect), ...argv.slice(1)].join(" "))
+		};
+	}
+	const tokens = tokenizeCommand(pattern);
+	if (tokens === null) return {
+		source: pattern,
+		test: (argv, dialect) => [executableBasename(argv[0] ?? "", dialect), ...argv.slice(1)].join(" ").includes(pattern)
+	};
+	return {
+		source: pattern,
+		test: (argv, dialect) => {
+			if (argv.length < tokens.length) return false;
+			return tokens.every((token, index) => {
+				const actual = argv[index] ?? "";
+				return index === 0 ? executableBasename(actual, dialect).toLowerCase() === executableBasename(token, dialect).toLowerCase() : actual === token;
+			});
+		}
+	};
+}
+/** Thrown inside the checker to stop at the first refusal. */
+var Refusal = class extends Error {
+	constructor(reason, message, executable, refusedPath) {
+		super(message);
+		this.reason = reason;
+		this.executable = executable;
+		this.refusedPath = refusedPath;
+	}
+};
+/** Per-line checker state. */
+var LineChecker = class {
+	constructor(policy, shell, line, dialect) {
+		this.policy = policy;
+		this.shell = shell;
+		this.line = line;
+		this.dialect = dialect;
+		this.commands = [];
+		this.paths = [];
+		this.deny = new Set((shell.deny ?? []).map((name) => name.toLowerCase()));
+		this.allow = shell.allow ?? [];
+		this.patterns = (shell.denyPatterns ?? []).map(compilePattern);
+		this.interpreter = shell.interpreter ?? "none";
+		this.hasCommandRules = this.deny.size > 0 || this.patterns.length > 0 || shell.allowCommand !== void 0;
+	}
+	/** Whether argument hooks (`denyPatterns` / `allowCommand`) need literal argv. */
+	get hasArgumentHooks() {
+		return this.patterns.length > 0 || this.shell.allowCommand !== void 0;
+	}
+	get shellMode() {
+		return this.interpreter === "sh";
+	}
+	/** Run `denyPatterns` and `allowCommand` on one argv. */
+	checkHooks(argv, nested) {
+		const shown = show(argv.join(" "));
+		for (const pattern of this.patterns) if (pattern.test(argv, this.dialect)) throw new Refusal("denied-pattern", `${shown} matches a command pattern the workspace shell policy denies.`, executableBasename(argv[0] ?? "", this.dialect));
+		const hook = this.shell.allowCommand;
+		if (hook === void 0) return;
+		let verdict;
+		try {
+			verdict = hook([...argv], {
+				command: this.line,
+				interpreter: this.interpreter,
+				nested
+			});
+		} catch {
+			verdict = false;
+		}
+		if (verdict === true) return;
+		throw new Refusal("not-allowed", `${shown} was refused by the workspace shell policy.${typeof verdict === "string" && verdict.trim() !== "" ? ` ${verdict.trim()}` : ""}`, executableBasename(argv[0] ?? "", this.dialect));
+	}
+	/** Whether the policy names `executable` in a non-empty `allow` list. */
+	explicitlyAllowed(executable) {
+		return this.allow.includes(executable);
+	}
+	/** Refuse a command runner the policy cannot see into, unless explicitly allowed. */
+	checkOpaque(executable, argv) {
+		if (this.explicitlyAllowed(executable) || !this.hasCommandRules) return;
+		throw new Refusal("nested-command", `\`${executable}\` runs a command the workspace shell policy cannot inspect (in ${show(argv.join(" "))}). Run the inner command directly instead.`, executable);
+	}
+	/**
+	* Check one argv: `deny`, `allow`, `denyPatterns`, `allowCommand`, then
+	* follow wrappers and `find -exec` to the command they run. `dynamic[i]`
+	* says whether `argv[i]` is decided at run time (shell mode).
+	*/
+	checkArgv(argv, dynamic, depth) {
+		const first = argv[0] ?? "";
+		const executable = executableBasename(first, this.dialect);
+		const key = executable.toLowerCase();
+		if (executable === "") throw new Refusal("not-allowed", "The command has no executable name.");
+		if (dynamic[0] === true) throw new Refusal("unsupported-syntax", `The command name \`${first}\` is decided when the line runs, so the workspace shell policy cannot check it. Write the command name literally.`);
+		if (this.deny.has(key)) throw new Refusal("denied-executable", `\`${executable}\` is denied by the workspace shell policy (in ${show(argv.join(" "))}).`, executable);
+		if (this.allow.length > 0 && !this.allow.includes(executable)) throw new Refusal("not-allowed", `\`${executable}\` is not in the workspace shell allowlist. Allowed commands: ${this.allow.slice(0, 20).join(", ")}${this.allow.length > 20 ? ", …" : ""}.`, executable);
+		this.checkHooks(argv, depth > 0);
+		this.commands.push([...argv]);
+		if (OPAQUE_RUNNERS.has(key) || this.shellMode && this.dialect === "posix" && SHELL_OPAQUE_BUILTINS.has(key) || this.shellMode && this.dialect === "cmd" && CMD_OPAQUE_BUILTINS.has(key)) {
+			this.checkOpaque(executable, argv);
+			return;
+		}
+		if (this.shellMode && this.dialect === "posix" && ARITHMETIC_SENSITIVE_BUILTINS.has(key)) this.checkArithmeticSensitive(executable, argv, dynamic);
+		const ranges = this.unwrap(key, argv);
+		if (ranges === void 0) return;
+		if (ranges === null || depth >= MAX_WRAPPER_DEPTH) throw new Refusal("nested-command", `\`${executable}\` is used with options the workspace shell policy cannot read (in ${show(argv.join(" "))}). Run the inner command directly instead.`, executable);
+		for (const [start, end] of ranges) this.checkArgv(argv.slice(start, end), dynamic.slice(start, end), depth + 1);
+	}
+	/**
+	* Builtins bash may evaluate arguments of as arithmetic (array subscripts
+	* like `a[$(cmd)]` run the substitution): arguments must be literal, free
+	* of `[`, and must not name a variable that changes how the shell runs.
+	*/
+	checkArithmeticSensitive(executable, argv, dynamic) {
+		for (let index = 1; index < argv.length; index++) {
+			const argument = argv[index] ?? "";
+			if (dynamic[index] === true) throw new Refusal("unsupported-syntax", `\`${executable}\` arguments must be literal here (\`${argument}\` is not): bash may evaluate them as arithmetic.`, executable);
+			if (argument.includes("[") && argument !== "[" && argument !== "]") throw new Refusal("unsupported-syntax", `\`${executable}\` arguments with \`[\` (array subscripts, evaluated as arithmetic) are not supported.`, executable);
+			const name = argument.split("=")[0] ?? "";
+			if (SENSITIVE_VARIABLES.has(name) || name.startsWith("BASH_FUNC_")) throw new Refusal("unsupported-syntax", `Changing \`${name}\` is not supported: it changes how the shell runs the commands that follow.`, executable);
+		}
+	}
+	/**
+	* The argv ranges a wrapper runs. `undefined` — not a wrapper (or one that
+	* runs nothing, like a bare `env`); `null` — a wrapper whose options the
+	* policy cannot read (refused).
+	*/
+	unwrap(key, argv) {
+		switch (key) {
+			case "env": return suffixFrom(argv, unwrapEnv(argv));
+			case "nice": return suffixFrom(argv, unwrapNice(argv));
+			case "nohup": return suffixFrom(argv, unwrapSimple(argv, []));
+			case "time": return suffixFrom(argv, unwrapSimple(argv, ["-p"]));
+			case "timeout": return suffixFrom(argv, unwrapTimeout(argv));
+			case "command": return argv.slice(1).some((arg) => arg === "-v" || arg === "-V") ? void 0 : suffixFrom(argv, unwrapSimple(argv, ["-p"]));
+			case "builtin": return suffixFrom(argv, unwrapSimple(argv, []));
+			case "exec": return this.dialect === "posix" ? suffixFrom(argv, unwrapExec(argv)) : void 0;
+			case "find": return unwrapFind(argv);
+			default: return;
+		}
+	}
+	/** Check a `cd` (shell mode): literal, one operand, inside the jail from every possible cwd. */
+	checkCd(words, cwds) {
+		const argv = words.map((word) => word.value);
+		if (this.deny.has("cd")) throw new Refusal("denied-executable", "`cd` is denied by the workspace shell policy.", "cd");
+		this.checkHooks(argv, false);
+		this.commands.push(argv);
+		const operands = words.slice(1);
+		while (this.dialect === "posix" && operands.length > 0 && [
+			"-P",
+			"-L",
+			"--"
+		].includes(operands[0]?.value ?? "")) operands.shift();
+		const target = operands[0];
+		if (operands.length !== 1 || target === void 0 || target.value === "-" || target.dynamic) throw new Refusal("unsupported-syntax", "`cd` needs exactly one literal directory inside the workspace (no `-`, `~` or variables).", "cd");
+		const next = new Set(cwds);
+		for (const cwd of cwds) {
+			const resolved = this.resolveTarget(cwd, target.value);
+			this.assertInJail(resolved, target.value, "cd");
+			this.paths.push({
+				path: resolved,
+				access: "cwd",
+				target: target.value
+			});
+			next.add(resolved);
+		}
+		if (next.size > MAX_CD_CANDIDATES) throw new Refusal("unsupported-syntax", "The line changes directory too many times.", "cd");
+		return [...next];
+	}
+	/** Check a redirection target from every possible cwd. */
+	checkRedirectTarget(word, access, cwds) {
+		if (word.dynamic) throw new Refusal("unsupported-syntax", `The redirection target \`${word.raw}\` must be a literal path (no variables, globs or \`~\`).`);
+		const value = word.value;
+		if (this.dialect === "posix" && DEVICE_TARGETS.has(value) || this.dialect === "cmd" && CMD_DEVICE_TARGETS.has(value.toLowerCase())) return;
+		for (const cwd of cwds) {
+			const resolved = this.resolveTarget(cwd, value);
+			this.assertInJail(resolved, value, "redirect");
+			this.paths.push({
+				path: resolved,
+				access,
+				target: value
+			});
+		}
+	}
+	resolveTarget(cwd, target) {
+		return node_path.default.resolve(cwd, target);
+	}
+	assertInJail(resolved, target, kind) {
+		if (isInsideJailLexically(this.policy, resolved)) return;
+		throw new Refusal("path-escape", kind === "cd" ? `\`cd ${target}\` leaves the workspace jail (or enters a denied path); commands must stay inside the workspace.` : `The redirection target \`${target}\` is outside the workspace jail or on a denied path.`, void 0, target);
+	}
+};
+/**
+* Turn a wrapper's "inner command starts at `start`" into a range; a
+* wrapper that runs nothing (`start === argv.length`) becomes `undefined`.
+*/
+function suffixFrom(argv, start) {
+	if (start === null) return null;
+	return start < argv.length ? [[start, argv.length]] : void 0;
+}
+/** `nohup` / `time` / `command` / `builtin`: skip the listed flags and `--`. */
+function unwrapSimple(argv, flags) {
+	let index = 1;
+	while (index < argv.length) {
+		const arg = argv[index] ?? "";
+		if (arg === "--") {
+			index++;
+			break;
+		}
+		if (flags.includes(arg)) {
+			index++;
 			continue;
 		}
-		if (char === " " || char === "	") {
-			if (inToken) {
-				argv.push(current);
-				current = "";
-				inToken = false;
-			}
+		if (arg.startsWith("-") && arg !== "-") return null;
+		break;
+	}
+	return index;
+}
+/** `env [-i] [-u NAME] [NAME=value]… command…` */
+function unwrapEnv(argv) {
+	let index = 1;
+	while (index < argv.length) {
+		const arg = argv[index] ?? "";
+		if (arg === "-i" || arg === "-" || arg === "--ignore-environment") {
 			index++;
 			continue;
 		}
-		if (char === "\n" || char === "\r" || UNQUOTED_METACHARACTERS.has(char)) return null;
-		current += char;
-		inToken = true;
-		index++;
+		if (arg === "-u" || arg === "--unset") {
+			index += 2;
+			continue;
+		}
+		if (arg.startsWith("--unset=") || arg.startsWith("-u") && arg.length > 2) {
+			index++;
+			continue;
+		}
+		if (arg === "--") {
+			index++;
+			break;
+		}
+		if (arg.startsWith("-")) return null;
+		break;
+	}
+	while (index < argv.length && /^[^=]+=/.test(argv[index] ?? "")) index++;
+	return index;
+}
+/** `nice [-n N | -N | --adjustment=N] command…` */
+function unwrapNice(argv) {
+	let index = 1;
+	while (index < argv.length) {
+		const arg = argv[index] ?? "";
+		if (arg === "-n" || arg === "--adjustment") {
+			index += 2;
+			continue;
+		}
+		if (/^-n-?[0-9]+$/.test(arg) || /^--adjustment=-?[0-9]+$/.test(arg) || /^-[0-9]+$/.test(arg)) {
+			index++;
+			continue;
+		}
+		if (arg === "--") {
+			index++;
+			break;
+		}
+		if (arg.startsWith("-")) return null;
+		break;
+	}
+	return index;
+}
+/** `timeout [options] DURATION command…` */
+function unwrapTimeout(argv) {
+	let index = 1;
+	while (index < argv.length) {
+		const arg = argv[index] ?? "";
+		if (arg === "-s" || arg === "--signal" || arg === "-k" || arg === "--kill-after") {
+			index += 2;
+			continue;
+		}
+		if (/^-[sk].+$/.test(arg) || arg.startsWith("--signal=") || arg.startsWith("--kill-after=") || arg === "--preserve-status" || arg === "--foreground" || arg === "-v" || arg === "--verbose") {
+			index++;
+			continue;
+		}
+		if (arg === "--") {
+			index++;
+			break;
+		}
+		if (arg.startsWith("-")) return null;
+		break;
+	}
+	if (index >= argv.length - 1) return null;
+	return index + 1;
+}
+/** `exec [-cl] [-a name] command…` (bash). */
+function unwrapExec(argv) {
+	let index = 1;
+	while (index < argv.length) {
+		const arg = argv[index] ?? "";
+		if (arg === "-c" || arg === "-l" || arg === "-cl" || arg === "-lc") {
+			index++;
+			continue;
+		}
+		if (arg === "-a") {
+			index += 2;
+			continue;
+		}
+		if (arg === "--") {
+			index++;
+			break;
+		}
+		if (arg.startsWith("-")) return null;
+		break;
+	}
+	return index;
+}
+/** The commands `find -exec / -execdir / -ok / -okdir … ;|+` runs. */
+function unwrapFind(argv) {
+	const inner = [];
+	for (let index = 1; index < argv.length; index++) {
+		const arg = argv[index] ?? "";
+		if (arg !== "-exec" && arg !== "-execdir" && arg !== "-ok" && arg !== "-okdir") continue;
+		const start = index + 1;
+		let end = start;
+		while (end < argv.length && argv[end] !== ";" && argv[end] !== "+") end++;
+		if (end >= argv.length || end === start) return null;
+		inner.push([start, end]);
+		index = end;
+	}
+	return inner.length > 0 ? inner : void 0;
+}
+/** Build the argv-mode refusal for a line that is not a single argv. */
+function argvModeRefusal(command) {
+	const analysis = analyzeArgvCommand(command);
+	if (analysis.ok) return new Refusal("metacharacter", "The command cannot run as a single argv.");
+	if (analysis.type === "empty") return new Refusal("not-allowed", "The command is empty.");
+	if (analysis.type === "unbalanced-quotes") return new Refusal("unbalanced-quotes", `The command has an unbalanced \`${analysis.quote}\` quote. Close it, or quote the argument with the other kind of quote.`);
+	const token = analysis.token;
+	const suffix = " (run_shell executes a single command without a shell.)";
+	const parsed = parseShellLine(command, "posix");
+	const segments = parsed.ok ? parsed.segments : [];
+	if ((token === "&&" || token === "||" || token === ";" || token === "\n") && segments.length >= 2) {
+		const shownOperator = token === "\n" ? "A line break" : `\`${token}\``;
+		if ((segments[0]?.source ?? "").trim().split(/\s+/)[0] === "cd") return new Refusal("metacharacter", `${shownOperator} is not supported in argv mode, and \`cd\` does not carry over: every command starts in the workspace root. Run ${segments.slice(1).map((segment) => show(segment.source)).join(", then ")} on its own, with paths relative to the root.${suffix}`);
+		const steps = segments.map((segment) => show(segment.source));
+		const joiner = token === "||" ? ", and if it fails, " : ", then ";
+		return new Refusal("metacharacter", `${shownOperator} is not supported in argv mode: run ${steps.join(joiner)}, as separate commands.${suffix}`);
+	}
+	if (token === "&" && segments.length >= 1) {
+		const steps = segments.map((segment) => show(segment.source));
+		return new Refusal("metacharacter", `\`&\` is not supported in argv mode: ${steps.length === 1 ? `run ${steps[0] ?? ""} without it` : `run ${steps.join(", then ")} as separate commands`}; start a long-running command with background: true.${suffix}`);
+	}
+	if (token === "|") return new Refusal("metacharacter", `\`|\` (a pipe) is not supported in argv mode: run ${show(command.split("|").map((part) => part.trim()).filter(Boolean)[0] ?? command)} on its own and read its output yourself.${suffix}`);
+	if (token === ">" || token === ">>" || token === ">&") return new Refusal("metacharacter", `\`${token}\` (redirection) is not supported in argv mode: run the command without it and save the output with write_file if you need it.${suffix}`);
+	if (token === "<" || token === "<<" || token === "<&") return new Refusal("metacharacter", `\`${token}\` (input redirection) is not supported in argv mode: pass the file path to the command as an argument.${suffix}`);
+	if (token === "$(" || token === "`") return new Refusal("metacharacter", `Command substitution (${token === "$(" ? "`$(…)`" : "backticks"}) is not supported in argv mode: run the inner command first, then pass its output literally.${suffix}`);
+	if (token === "$" || token === "${") return new Refusal("metacharacter", `\`$\` (variable expansion) is not supported in argv mode: write the value literally, or put the \`$\` inside quotes to pass it as text.${suffix}`);
+	if (token === "(" || token === ")") return new Refusal("metacharacter", `\`${token}\` is not supported in argv mode: put it inside quotes to pass it as text.${suffix}`);
+	return new Refusal("metacharacter", `\`${token === "\n" ? "\\n" : token}\` is not supported in argv mode: run one command per call, and quote any argument that contains it.${suffix}`);
+}
+/** Check a shell-mode (`interpreter: "sh"`) line. */
+function checkShellLine(checker, policy, command, dialect) {
+	if (/^[-+]/.test(command)) throw new Refusal("unsupported-syntax", "A command line may not start with `-` or `+`.");
+	const parsed = parseShellLine(command, dialect);
+	if (!parsed.ok) throw new Refusal(parsed.reason, `${parsed.message} The workspace shell policy only runs lines it can check.`);
+	if (parsed.background) throw new Refusal("unsupported-syntax", "`&` (run in the background) is not supported in a command line: start a long-running command with background: true instead.");
+	let cwds = [node_path.default.resolve(policy.cwd)];
+	for (const simple of parsed.commands) cwds = checkSimpleCommand(checker, simple, cwds, dialect);
+}
+/** Check one parsed simple command; returns the possible working directories after it. */
+function checkSimpleCommand(checker, simple, cwds, dialect) {
+	for (const assignment of simple.assignments) {
+		const name = assignment.assignmentName ?? "";
+		if (SENSITIVE_VARIABLES.has(name) || name.startsWith("BASH_FUNC_")) throw new Refusal("unsupported-syntax", `Assigning \`${name}\` is not supported: it changes how the shell runs the commands that follow.`);
+	}
+	for (const redirect of simple.redirects) if (redirect.type === "read" || redirect.type === "write") checker.checkRedirectTarget(redirect.target, redirect.type, cwds);
+	const first = simple.words[0];
+	if (first === void 0) return cwds;
+	if (!first.dynamic && first.value.includes("=")) throw new Refusal("unsupported-syntax", `\`${first.raw}\` is not a plain command name or \`NAME=value\` assignment.`);
+	if (/^[-+]/.test(first.value)) throw new Refusal("unsupported-syntax", `\`${first.raw}\` is not a command name.`);
+	if (checker.hasArgumentHooks) {
+		const dynamic = simple.words.find((word) => word.dynamic);
+		if (dynamic !== void 0) throw new Refusal("unsupported-syntax", `\`${dynamic.raw}\` is decided when the line runs, so it cannot be checked against the workspace shell policy's command rules. Write the value literally (quote globs).`);
+	}
+	const executable = first.dynamic ? "" : executableBasename(first.value, dialect).toLowerCase();
+	if (executable === "cd") return checker.checkCd(simple.words, cwds);
+	if (dialect === "posix" && (executable === "pushd" || executable === "popd")) throw new Refusal("unsupported-syntax", `\`${executable}\` is not supported; use \`cd\`.`);
+	checker.checkArgv(simple.words.map((word) => word.dynamic ? word.raw : word.value), simple.words.map((word) => word.dynamic), 0);
+	return cwds;
+}
+/**
+* The shell policy's verdict on a command line, without touching the
+* filesystem.
+*
+* - **argv mode** (`interpreter: "none"`, the default): the line must
+*   tokenize into one argv; otherwise it is refused with a
+*   `"metacharacter"` / `"unbalanced-quotes"` reason and a message that
+*   names the operator and suggests the split.
+* - **shell mode** (`interpreter: "sh"`): the line is parsed and every
+*   simple command — inside `;`, `&&`, `||`, pipes, subshells, `$( )`,
+*   backticks and here-documents — is checked; redirection targets and `cd`
+*   directories must stay in the jail (checked lexically here; `exec`
+*   re-checks them with symlinks resolved).
+*
+* Every argv goes through `deny` (case-insensitive, wins), `allow`
+* (exhaustive when non-empty), `denyPatterns` and `allowCommand`.
+* Wrappers (`env`, `time`, `timeout`, `nice`, `nohup`, `command`,
+* `builtin`, `exec`) and `find -exec` are followed to the command they run.
+* A runner the policy cannot see into (`bash -c`, `eval`, `xargs`, `sudo`,
+* …) is refused while the policy has deny rules, unless `allow` names it.
+*
+* @example
+* checkShellCommand({ cwd, shell: { allow: ["git"] } }, "git add -A && git commit -m wip");
+* // { allowed: false, reason: "metacharacter", message: "`&&` is not supported in argv mode: run `git add -A`, then `git commit -m wip`, …" }
+*/
+function checkShellCommand(policy, command) {
+	return checkShellCommandInDialect(policy, command, shellDialect());
+}
+/**
+* {@link checkShellCommand} with the shell-mode dialect chosen explicitly
+* instead of from the platform (used to test the cmd.exe rules anywhere).
+* Argv mode ignores `dialect`.
+*/
+function checkShellCommandInDialect(policy, command, dialect) {
+	const shell = policy.shell;
+	if (!shell) return {
+		allowed: false,
+		reason: "not-allowed",
+		message: "The workspace has no shell policy, so no command may run.",
+		commands: [],
+		paths: []
+	};
+	const interpreter = shell.interpreter ?? "none";
+	const checker = new LineChecker(policy, shell, command, interpreter === "sh" ? dialect : "posix");
+	try {
+		if (command.trim() === "") throw new Refusal("not-allowed", "The command is empty.");
+		if (interpreter === "sh") checkShellLine(checker, policy, command, dialect);
+		else {
+			const argv = tokenizeCommand(command);
+			if (argv === null) throw argvModeRefusal(command);
+			checker.checkArgv(argv, argv.map(() => false), 0);
+		}
+		return {
+			allowed: true,
+			commands: checker.commands,
+			paths: checker.paths
+		};
+	} catch (error) {
+		if (!(error instanceof Refusal)) throw error;
+		return {
+			allowed: false,
+			reason: error.reason,
+			message: error.message,
+			...error.executable !== void 0 ? { executable: error.executable } : {},
+			...error.refusedPath !== void 0 ? { path: error.refusedPath } : {},
+			commands: checker.commands,
+			paths: checker.paths
+		};
 	}
-	if (inToken) argv.push(current);
-	return argv.length > 0 ? argv : null;
 }
 
 //#endregion
@@ -188,55 +1751,6 @@ async function canonicalize$1(target) {
 	}
 }
 /**
-* Whether `child` is contained within `root` (or equals it), comparing
-* canonical absolute paths. Guards against the `/srv/app-evil` vs
-* `/srv/app` prefix-collision by anchoring on a path separator.
-*/
-function isInside(child, root) {
-	const relative = node_path.default.relative(root, child);
-	return relative === "" || !relative.startsWith("..") && !node_path.default.isAbsolute(relative);
-}
-/**
-* Translate a glob (the small subset used by `denyPaths` — `*`, `**`,
-* `?`) into an anchored `RegExp` over a `/`-separated relative path.
-* `**` spans path separators; a single `*` does not.
-*/
-function globToRegExp$1(glob) {
-	let source = "";
-	for (let index = 0; index < glob.length; index++) {
-		const char = glob[index];
-		if (char === "*") {
-			if (glob[index + 1] === "*") {
-				source += ".*";
-				index++;
-				if (glob[index + 1] === "/") index++;
-			} else source += "[^/]*";
-			continue;
-		}
-		if (char === "?") {
-			source += "[^/]";
-			continue;
-		}
-		source += char.replace(/[.+^${}()|[\]\\]/g, "\\$&");
-	}
-	return new RegExp(`^${source}$`);
-}
-/**
-* Whether a workspace-relative (`/`-separated) path matches any of the
-* policy's `denyPaths` globs. A deny glob also blocks everything beneath
-* a matched directory (`".git/**"` blocks `.git/config`).
-*/
-function matchesDeny(relativePath, denyPaths) {
-	return denyPaths.some((glob) => {
-		if (globToRegExp$1(glob).test(relativePath)) return true;
-		if (!glob.includes("*") && !glob.includes("?")) {
-			const prefix = glob.endsWith("/") ? glob : `${glob}/`;
-			return relativePath.startsWith(prefix);
-		}
-		return false;
-	});
-}
-/**
 * Resolve and jail a single input path against a {@link WorkspacePolicy}.
 *
 * The input is resolved against `policy.cwd`, canonicalized (symlinks in
@@ -246,6 +1760,17 @@ function matchesDeny(relativePath, denyPaths) {
 * `denyPaths` glob even while inside `cwd`, is rejected with a
 * {@link WorkspacePolicyError} of type `"path-escape"`.
 *
+* Why this does not use `@warlock.js/fs`'s confined reader (`fs.confined`):
+* the two answer different questions. The confined reader refuses absolute
+* paths, refuses every symbolic link (or follows only links inside its one
+* root), requires the path to exist, and reads the file itself through a
+* no-follow, identity-checked open. This jail must instead accept absolute
+* paths inside `cwd`, several `allowPaths` roots, `denyPaths` globs, a
+* symlinked `cwd`, links whose target stays inside, and paths that do not
+* exist yet (`writeFile`, `mkdir`), and it returns a path that writes,
+* `exec`'s working directory and redirections use afterwards. Switching would
+* change what agents may touch, so the workspace keeps this resolver.
+*
 * @param policy - The bounding policy (its `cwd` is the jail root).
 * @param inputPath - A workspace-relative or absolute path to resolve.
 * @returns The canonical absolute path plus its `/`-separated relative form.
@@ -272,7 +1797,7 @@ async function resolveInJail(policy, inputPath) {
 	});
 	const relativeToJail = insideCwd ? node_path.default.relative(jailRoot, absolutePath).split(node_path.default.sep).join("/") : "";
 	if (insideCwd && policy.denyPaths && policy.denyPaths.length > 0) {
-		if (matchesDeny(relativeToJail, policy.denyPaths)) throw new WorkspacePolicyError(`Path "${inputPath}" is blocked by the workspace deny list.`, {
+		if (matchesAnyGlob(relativeToJail, policy.denyPaths)) throw new WorkspacePolicyError(`Path "${inputPath}" is blocked by the workspace deny list.`, {
 			type: "path-escape",
 			path: inputPath
 		});
@@ -283,32 +1808,22 @@ async function resolveInJail(policy, inputPath) {
 	};
 }
 /**
-* Reduce an argv's first element to the basename the allow/deny policy is
-* keyed on. `"npm"` → `"npm"`; `"/usr/bin/node"` → `"node"`; `"node.exe"`
-* → `"node"` (the `.exe`/`.cmd`/`.bat`/`.com` Windows extension is
-* stripped).
-*/
-function executableBasename(firstToken) {
-	return node_path.default.basename(firstToken).replace(/\.(exe|cmd|bat|com)$/i, "");
-}
-/**
-* Whether a shell command is permitted by the policy's `shell` sub-policy.
+* Whether a command line is permitted by the policy's `shell` sub-policy —
+* `checkShellCommand(policy, command).allowed`.
 *
-* The command is first tokenized via {@link tokenizeCommand} — a command
-* that cannot be represented as a single argv (unbalanced quotes, or
-* unquoted shell metacharacters such as `;`, `&&`, `|`, backticks, `$`,
-* redirection) is denied outright. The backend spawns the argv directly
-* with no shell, so such a command has no meaning here — and unquoted
-* metacharacters were exactly how an injected command chain used to ride
-* past the allowlist. The resolved `argv[0]` basename is then matched
-* against `shell.deny` then `shell.allow`. **Deny always wins.** When
-* `shell.allow` is set, the executable MUST appear in it (fail-closed
-* allowlist); when `allow` is absent/empty, any non-denied command is
-* permitted. An absent `shell` block means no command may run at all.
+* In argv mode (the default) the command must tokenize into a single argv
+* (no unquoted `;`, `&&`, `|`, backticks, `$`, redirection, …): the backend
+* spawns it with no shell, and unquoted metacharacters were exactly how an
+* injected command chain used to ride past the allowlist. In shell mode
+* (`interpreter: "sh"`) every simple command in the line is checked. Each
+* argv's executable basename is matched against `shell.deny` (wins, case
+* insensitive) then `shell.allow` (exhaustive when non-empty), then
+* `shell.denyPatterns` and `shell.allowCommand`. An absent `shell` block
+* means no command may run at all.
 *
-* Returns a plain `boolean` rather than throwing — the ops layer raises
-* the {@link WorkspacePolicyError} so the thrown context (`command`)
-* lives next to the call site.
+* Returns a plain `boolean`; use {@link checkShellCommand} for the reason
+* and the model-facing message. Redirection targets are checked lexically
+* here; `exec` re-checks them with symlinks resolved.
 *
 * @example
 * isCommandAllowed({ cwd, shell: { allow: ["npm"] } }, "npm test"); // true
@@ -316,15 +1831,7 @@ function executableBasename(firstToken) {
 * isCommandAllowed({ cwd, shell: { allow: ["npm"] } }, "npm test; rm -rf /"); // false
 */
 function isCommandAllowed(policy, command) {
-	const shell = policy.shell;
-	if (!shell) return false;
-	const argv = tokenizeCommand(command);
-	if (argv === null) return false;
-	const executable = executableBasename(argv[0]);
-	if (executable === "") return false;
-	if (shell.deny && shell.deny.includes(executable)) return false;
-	if (shell.allow && shell.allow.length > 0) return shell.allow.includes(executable);
-	return true;
+	return checkShellCommand(policy, command).allowed;
 }
 /**
 * Build the exact environment a spawned process receives — `process.env`
@@ -349,6 +1856,280 @@ function buildEnv(policy) {
 	if (shell.env) for (const [key, value] of Object.entries(shell.env)) env[key] = value;
 	return env;
 }
+/**
+* Variables removed from the environment of a shell-mode (`interpreter:
+* "sh"`) command: each changes how the shell itself starts, parses or
+* resolves the line (`ENV`/`BASH_ENV` run a startup file, `SHELLOPTS` +
+* `PS4` can run command substitutions, `BASH_FUNC_*` imports functions that
+* shadow commands, `CDPATH` moves `cd`, `IFS` re-splits words).
+*/
+const SHELL_STARTUP_VARIABLES = new Set([
+	"ENV",
+	"BASH_ENV",
+	"SHELLOPTS",
+	"BASHOPTS",
+	"CDPATH",
+	"IFS",
+	"PS4",
+	"GLOBIGNORE"
+]);
+/**
+* The environment a command actually receives: {@link buildEnv}, minus the
+* shell start-up variables when the policy runs lines through a shell.
+* Compared case-insensitively, because Windows environment names are.
+*/
+function buildCommandEnv(policy) {
+	const env = buildEnv(policy);
+	if ((policy.shell?.interpreter ?? "none") !== "sh") return env;
+	for (const key of Object.keys(env)) {
+		const upper = key.toUpperCase();
+		if (SHELL_STARTUP_VARIABLES.has(upper) || upper.startsWith("BASH_FUNC_")) delete env[key];
+	}
+	return env;
+}
+
+//#endregion
+//#region ../../packages/ai-workspace/src/shell-jobs.ts
+/** Finished commands kept for a last `shell_output` read before the oldest are pruned. */
+const MAX_FINISHED_JOBS = 16;
+/** Longest `waitMs` a `shellOutput` call may ask for. */
+const MAX_OUTPUT_WAIT_MS = 3e4;
+/** How long `kill()` / `dispose()` wait for a killed tree to report its exit. */
+const KILL_SETTLE_MS = 5e3;
+/** Resolve after `ms`, without keeping the event loop alive. */
+function delay(ms) {
+	return new Promise((resolve) => {
+		setTimeout(resolve, ms).unref?.();
+	});
+}
+/**
+* Keep the last `maxBytes` UTF-8 bytes of `text`, cutting forward to a
+* character boundary so the kept tail never starts mid-character.
+*/
+function tailUtf8(text, maxBytes) {
+	const buffer = Buffer.from(text, "utf8");
+	if (buffer.byteLength <= maxBytes) return {
+		text,
+		bytes: buffer.byteLength
+	};
+	let start = buffer.byteLength - maxBytes;
+	while (start < buffer.byteLength && ((buffer[start] ?? 0) & 192) === 128) start++;
+	const kept = buffer.subarray(start);
+	return {
+		text: kept.toString("utf8"),
+		bytes: kept.byteLength
+	};
+}
+/** Bytes of `text` from byte `skip` on, moved forward to a character boundary. */
+function skipUtf8(text, skip) {
+	const buffer = Buffer.from(text, "utf8");
+	let start = Math.max(0, skip);
+	while (start < buffer.byteLength && ((buffer[start] ?? 0) & 192) === 128) start++;
+	return buffer.subarray(start).toString("utf8");
+}
+/** One background command and its retained output. */
+var ShellJob = class {
+	constructor(id, command, retainBytes) {
+		this.id = id;
+		this.command = command;
+		this.retainBytes = retainBytes;
+		this.status = "running";
+		this.exitCode = null;
+		this.startedAt = (/* @__PURE__ */ new Date()).toISOString();
+		this.produced = 0;
+		this.readCursor = 0;
+		this.chunks = [];
+		this.retained = 0;
+		this.listeners = /* @__PURE__ */ new Set();
+		this.killRequested = false;
+		this.timedOut = false;
+	}
+	append(stream, chunk) {
+		if (chunk === "") return;
+		const bytes = Buffer.byteLength(chunk, "utf8");
+		this.chunks.push({
+			stream,
+			text: chunk,
+			offset: this.produced,
+			bytes
+		});
+		this.produced += bytes;
+		this.retained += bytes;
+		this.trim();
+		this.notify();
+	}
+	/** Drop the oldest output until at most `retainBytes` are kept. */
+	trim() {
+		while (this.retained > this.retainBytes && this.chunks.length > 0) {
+			const oldest = this.chunks[0];
+			if (oldest === void 0) return;
+			const excess = this.retained - this.retainBytes;
+			if (oldest.bytes <= excess) {
+				this.chunks.shift();
+				this.retained -= oldest.bytes;
+				continue;
+			}
+			const kept = tailUtf8(oldest.text, oldest.bytes - excess);
+			this.retained -= oldest.bytes - kept.bytes;
+			oldest.offset += oldest.bytes - kept.bytes;
+			oldest.text = kept.text;
+			oldest.bytes = kept.bytes;
+		}
+	}
+	finish(exitCode) {
+		if (this.status !== "running") return;
+		this.exitCode = exitCode;
+		this.status = this.timedOut ? "timed-out" : this.killRequested ? "killed" : "exited";
+		this.endedAt = (/* @__PURE__ */ new Date()).toISOString();
+		if (this.timer !== void 0) clearTimeout(this.timer);
+		this.notify();
+	}
+	notify() {
+		for (const listener of [...this.listeners]) listener();
+	}
+	/** Resolve on the next output or state change (or after `ms`, or on abort). */
+	waitForChange(ms, signal) {
+		return new Promise((resolve) => {
+			if (signal?.aborted) {
+				resolve();
+				return;
+			}
+			let timer;
+			const done = () => {
+				if (timer !== void 0) clearTimeout(timer);
+				this.listeners.delete(done);
+				signal?.removeEventListener("abort", done);
+				resolve();
+			};
+			timer = setTimeout(done, ms);
+			timer.unref?.();
+			this.listeners.add(done);
+			signal?.addEventListener("abort", done, { once: true });
+		});
+	}
+	info() {
+		return {
+			id: this.id,
+			command: this.command,
+			status: this.status,
+			exitCode: this.exitCode,
+			...this.process?.pid !== void 0 ? { pid: this.process.pid } : {},
+			startedAt: this.startedAt,
+			...this.endedAt !== void 0 ? { endedAt: this.endedAt } : {}
+		};
+	}
+	/** Output produced after byte `since`, plus how much of it is gone. */
+	read(since) {
+		const from = Math.min(Math.max(0, Math.floor(since)), this.produced);
+		const firstRetained = this.chunks[0]?.offset ?? this.produced;
+		const droppedBytes = Math.max(0, firstRetained - from);
+		let stdout = "";
+		let stderr = "";
+		for (const chunk of this.chunks) {
+			if (chunk.offset + chunk.bytes <= from) continue;
+			const text = chunk.offset >= from ? chunk.text : skipUtf8(chunk.text, from - chunk.offset);
+			if (chunk.stream === "stdout") stdout += text;
+			else stderr += text;
+		}
+		this.readCursor = this.produced;
+		return {
+			...this.info(),
+			stdout,
+			stderr,
+			cursor: this.produced,
+			droppedBytes,
+			truncated: droppedBytes > 0
+		};
+	}
+};
+/**
+* The background commands one workspace owns. Shared by every projection
+* (`readonly()`, `scope()`) of the workspace, so `dispose()` on any of them
+* stops them all.
+*/
+var ShellJobs = class {
+	constructor() {
+		this.jobs = /* @__PURE__ */ new Map();
+		this.nextId = 1;
+		this.disposed = false;
+	}
+	/** Whether {@link dispose} has run. */
+	get isDisposed() {
+		return this.disposed;
+	}
+	/** Start a command as a background job. */
+	start(spec) {
+		if (this.disposed) throw new WorkspacePolicyError("The workspace has been disposed; it cannot start new commands.", {
+			type: "denied-command",
+			reason: "not-allowed",
+			command: spec.command
+		});
+		const running = [...this.jobs.values()].filter((job) => job.status === "running").length;
+		if (running >= spec.maxJobs) throw new WorkspacePolicyError(`${running} background commands are already running (the limit is ${spec.maxJobs}). Stop one with shell_kill first.`, {
+			type: "denied-command",
+			reason: "not-allowed",
+			command: spec.command
+		});
+		const job = new ShellJob(`job-${this.nextId++}`, spec.command, spec.retainBytes);
+		this.jobs.set(job.id, job);
+		const handle = spec.launch((stream, chunk) => job.append(stream, chunk));
+		job.process = handle;
+		if (spec.timeoutMs !== void 0 && spec.timeoutMs > 0) {
+			job.timer = setTimeout(() => {
+				if (job.status === "running") {
+					job.timedOut = true;
+					handle.kill();
+				}
+			}, spec.timeoutMs);
+			job.timer.unref?.();
+		}
+		handle.done.then(({ exitCode }) => job.finish(exitCode));
+		this.prune();
+		return job.info();
+	}
+	/** Forget the oldest finished jobs beyond {@link MAX_FINISHED_JOBS}. */
+	prune() {
+		const finished = [...this.jobs.values()].filter((job) => job.status !== "running");
+		for (const job of finished.slice(0, Math.max(0, finished.length - MAX_FINISHED_JOBS))) this.jobs.delete(job.id);
+	}
+	get(id) {
+		const job = this.jobs.get(id);
+		if (job === void 0) throw new WorkspaceJobError(`No background command with id "${id}" exists in this workspace.`, {
+			type: "not-found",
+			jobId: id
+		});
+		return job;
+	}
+	/** New output of a job (see {@link ShellOutputOptions}). */
+	async output(id, opts) {
+		const job = this.get(id);
+		const since = opts?.since ?? job.readCursor;
+		const waitMs = Math.min(Math.max(0, opts?.waitMs ?? 0), MAX_OUTPUT_WAIT_MS);
+		if (waitMs > 0 && job.status === "running" && job.produced <= since) await job.waitForChange(waitMs, opts?.signal);
+		return job.read(since);
+	}
+	/** Kill a job's process tree and wait (bounded) for it to stop. */
+	async kill(id) {
+		const job = this.get(id);
+		await this.stop(job);
+		return job.info();
+	}
+	async stop(job) {
+		if (job.status !== "running" || job.process === void 0) return;
+		job.killRequested = true;
+		job.process.kill();
+		await Promise.race([job.process.done, delay(KILL_SETTLE_MS)]);
+	}
+	/** Every job, oldest first. */
+	list() {
+		return [...this.jobs.values()].map((job) => job.info());
+	}
+	/** Kill every running job and refuse new ones. Idempotent. */
+	async dispose() {
+		this.disposed = true;
+		await Promise.all([...this.jobs.values()].map((job) => this.stop(job)));
+	}
+};
 
 //#endregion
 //#region ../../packages/ai-workspace/src/ops.ts
@@ -358,6 +2139,14 @@ const DEFAULT_READ_LINES = 2e3;
 const DEFAULT_MAX_GREP_MATCHES = 1e3;
 /** Default per-command output byte cap when the policy sets none. */
 const DEFAULT_MAX_OUTPUT_BYTES = 1e6;
+/** Default `list.ignore` when the policy sets none. */
+const DEFAULT_LIST_IGNORE = ["node_modules", ".git"];
+/** Default deepest `depth` a listing may ask for. */
+const DEFAULT_LIST_MAX_DEPTH = 5;
+/** Default most entries one listing returns. */
+const DEFAULT_LIST_MAX_ENTRIES = 500;
+/** Most edits one `multiEdit` call may carry. */
+const MAX_MULTI_EDITS = 100;
 /**
 * Exit code reported for a command refused because its signal was already
 * aborted (the shell convention for an interrupted command). Callers should
@@ -448,32 +2237,6 @@ function capOutput(value, maxBytes) {
 	return clipUtf8(value, maxBytes);
 }
 /**
-* Minimal glob match over a `/`-separated relative path. Supports `**`
-* (spans separators), `*` (within a segment), and `?` (one non-separator
-* char) — enough for the workspace's `glob`/grep narrowing without
-* pulling in a runtime dependency.
-*/
-function globToRegExp(glob) {
-	let source = "";
-	for (let index = 0; index < glob.length; index++) {
-		const char = glob[index];
-		if (char === "*") {
-			if (glob[index + 1] === "*") {
-				source += ".*";
-				index++;
-				if (glob[index + 1] === "/") index++;
-			} else source += "[^/]*";
-			continue;
-		}
-		if (char === "?") {
-			source += "[^/]";
-			continue;
-		}
-		source += char.replace(/[.+^${}()|[\]\\]/g, "\\$&");
-	}
-	return new RegExp(`^${source}$`);
-}
-/**
 * A quantifier: `+`, `*`, `?`, or a `{m,n}` bound.
 */
 const QUANTIFIER_SOURCE = String.raw`[+*?]|\{\d*,?\d*\}`;
@@ -495,17 +2258,11 @@ function isSafeGrepPattern(pattern) {
 	if (pattern.length > MAX_GREP_PATTERN_LENGTH) return false;
 	return !NESTED_QUANTIFIER_PATTERN.test(pattern);
 }
-/**
-* The internal, single-instance implementation of {@link WorkspaceOps}.
-* Holds the backend + policy and is the one place the jail, command
-* gating, read caps, and the read-before-edit guard are enforced — both
-* the agent-facing tools and the human-facing direct methods funnel
-* through this object, so there is exactly one set of rules.
-*/
 var Ops = class {
-	constructor(backend, policy) {
+	constructor(backend, policy, runtime) {
 		this.backend = backend;
 		this.policy = policy;
+		this.runtime = runtime;
 		this.pathLocks = /* @__PURE__ */ new Map();
 	}
 	/** Run `task` after every earlier mutation of `absolutePath` has settled. */
@@ -599,30 +2356,76 @@ var Ops = class {
 			expectedHash: input.expectHash,
 			actualHash: currentHash
 		});
-		const occurrences = countOccurrences(current, input.oldString);
-		if (occurrences === 0) throw new WorkspaceEditError(`The text to replace was not found in "${input.path}".`, {
-			type: "not-found",
-			path: relativePath || input.path,
-			matches: 0
-		});
-		if (occurrences > 1 && !input.replaceAll) throw new WorkspaceEditError(`The text to replace is not unique in "${input.path}" (${occurrences} matches); pass replaceAll or include more surrounding context.`, {
-			type: "not-unique",
-			path: relativePath || input.path,
-			matches: occurrences
-		});
-		const updated = input.replaceAll ? current.split(input.oldString).join(input.newString) : replaceFirst(current, input.oldString, input.newString);
+		const { content: updated, replacements } = applyReplacement(current, input, input.path, relativePath || input.path);
 		await this.backend.writeFile(absolutePath, updated);
 		return {
 			path: relativePath || input.path,
-			replacements: input.replaceAll ? occurrences : 1,
+			replacements,
 			hash: _warlock_js_fs.fs.hash.string(updated)
 		};
 	}
-	async exec(command, opts) {
-		if (!isCommandAllowed(this.policy, command)) throw new WorkspacePolicyError(`Command is not permitted by the workspace shell policy: ${command}`, {
+	async multiEdit(input) {
+		const { absolutePath, relativePath } = await resolveInJail(this.policy, input.path);
+		const shownPath = relativePath || input.path;
+		if (input.edits.length === 0 || input.edits.length > 100) throw new RangeError(`A multi-edit needs between 1 and ${100} edits (got ${input.edits.length}).`);
+		return this.withPathLock(absolutePath, async () => {
+			const current = await this.backend.readFile(absolutePath);
+			const currentHash = _warlock_js_fs.fs.hash.string(current);
+			if (input.expectHash !== void 0 && input.expectHash !== currentHash) throw new WorkspaceEditError(`File "${input.path}" changed since it was read; none of the edits were applied.`, {
+				type: "stale-hash",
+				path: shownPath,
+				expectedHash: input.expectHash,
+				actualHash: currentHash
+			});
+			let content = current;
+			let replacements = 0;
+			input.edits.forEach((edit, editIndex) => {
+				const applied = applyReplacement(content, edit, input.path, shownPath, editIndex);
+				content = applied.content;
+				replacements += applied.replacements;
+			});
+			await this.backend.writeFile(absolutePath, content);
+			return {
+				path: shownPath,
+				edits: input.edits.length,
+				replacements,
+				hash: _warlock_js_fs.fs.hash.string(content)
+			};
+		});
+	}
+	/**
+	* Check a command line against the shell policy: every command in it
+	* (argv or shell mode), then — shell mode — every redirection target and
+	* `cd` directory against the jail with symlinks resolved.
+	*/
+	async assertCommandAllowed(command) {
+		const verdict = checkShellCommand(this.policy, command);
+		if (!verdict.allowed) throw new WorkspacePolicyError(verdict.message ?? `Command is not permitted by the workspace shell policy: ${command}`, {
+			type: "denied-command",
+			command,
+			...verdict.reason !== void 0 ? { reason: verdict.reason } : {},
+			...verdict.executable !== void 0 ? { executable: verdict.executable } : {},
+			...verdict.path !== void 0 ? { path: verdict.path } : {}
+		});
+		for (const target of verdict.paths) try {
+			await resolveInJail(this.policy, target.path);
+		} catch (error) {
+			if (!(error instanceof WorkspacePolicyError)) throw error;
+			throw new WorkspacePolicyError(target.access === "cwd" ? `\`cd ${target.target}\` resolves (through a symlink) outside the workspace jail or onto a denied path.` : `The redirection target \`${target.target}\` resolves (through a symlink) outside the workspace jail or onto a denied path.`, {
+				type: "denied-command",
+				reason: "path-escape",
+				command,
+				path: target.target
+			});
+		}
+		if (this.runtime.jobs.isDisposed) throw new WorkspacePolicyError("The workspace has been disposed; it cannot run new commands.", {
 			type: "denied-command",
+			reason: "not-allowed",
 			command
 		});
+	}
+	async exec(command, opts) {
+		await this.assertCommandAllowed(command);
 		const signal = opts?.signal;
 		if (signal?.aborted) return {
 			exitCode: CANCELLED_BEFORE_START_EXIT_CODE,
@@ -635,11 +2438,13 @@ var Ops = class {
 		const shell = this.policy.shell;
 		const timeoutMs = opts?.timeoutMs ?? shell?.timeoutMs;
 		const maxOutputBytes = shell?.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+		const interpreter = shell?.interpreter ?? "none";
 		const result = await this.backend.exec(command, {
 			cwd: this.policy.cwd,
 			timeoutMs,
-			env: buildEnv(this.policy),
-			...signal ? { signal } : {}
+			env: buildCommandEnv(this.policy),
+			...signal ? { signal } : {},
+			...interpreter !== "none" ? { interpreter } : {}
 		});
 		const stdout = capOutput(result.stdout, maxOutputBytes);
 		const stderr = capOutput(result.stderr, maxOutputBytes);
@@ -653,6 +2458,120 @@ var Ops = class {
 			cancelled
 		};
 	}
+	async startShell(command, opts) {
+		const background = this.policy.shell?.background;
+		if (background === void 0) throw new WorkspacePolicyError("Background commands are not enabled for this workspace. Run the command without background, or ask for shell.background to be enabled.", {
+			type: "denied-command",
+			reason: "not-allowed",
+			command
+		});
+		await this.assertCommandAllowed(command);
+		const start = this.backend.start?.bind(this.backend);
+		if (start === void 0) throw new WorkspacePolicyError("This workspace backend cannot run background commands.", {
+			type: "denied-command",
+			reason: "not-allowed",
+			command
+		});
+		const shell = this.policy.shell;
+		const interpreter = shell?.interpreter ?? "none";
+		const timeoutMs = lowerOf(background.timeoutMs, opts?.timeoutMs);
+		const env = buildCommandEnv(this.policy);
+		return this.runtime.jobs.start({
+			command,
+			retainBytes: shell?.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES,
+			maxJobs: background.maxJobs ?? 4,
+			...timeoutMs !== void 0 ? { timeoutMs } : {},
+			launch: (onOutput) => start(command, {
+				cwd: this.policy.cwd,
+				env,
+				...interpreter !== "none" ? { interpreter } : {},
+				onOutput
+			})
+		});
+	}
+	shellOutput(id, opts) {
+		return this.runtime.jobs.output(id, opts);
+	}
+	shellKill(id) {
+		return this.runtime.jobs.kill(id);
+	}
+	listShells() {
+		return this.runtime.jobs.list();
+	}
+	dispose() {
+		return this.runtime.jobs.dispose();
+	}
+	async listDir(inputPath = ".", opts) {
+		const { absolutePath: root, relativePath: rootRelative } = await resolveInJail(this.policy, inputPath);
+		const { absolutePath: jailRoot } = await resolveInJail(this.policy, ".");
+		const listPolicy = this.policy.list;
+		const maxDepth = Math.max(1, Math.floor(listPolicy?.maxDepth ?? DEFAULT_LIST_MAX_DEPTH));
+		const depth = Math.min(Math.max(1, Math.floor(opts?.depth ?? 1)), maxDepth);
+		const maxEntries = Math.max(1, Math.floor(listPolicy?.maxEntries ?? DEFAULT_LIST_MAX_ENTRIES));
+		const ignore = [...listPolicy?.ignore ?? DEFAULT_LIST_IGNORE, ...opts?.ignore ?? []];
+		const insideCwd = isInside(root, jailRoot);
+		if (!await this.isDirectory(root)) throw new Error(`"${inputPath}" is not a directory in the workspace.`);
+		const entries = [];
+		let level = [root];
+		let truncated = false;
+		for (let currentDepth = 1; currentDepth <= depth && level.length > 0; currentDepth++) {
+			const nextLevel = [];
+			for (const directory of level) {
+				let children;
+				try {
+					children = await this.backend.list(directory);
+				} catch {
+					continue;
+				}
+				children.sort((left, right) => left < right ? -1 : left > right ? 1 : 0);
+				for (const child of children) {
+					const relativeToJail = insideCwd ? node_path.default.relative(jailRoot, child).split(node_path.default.sep).join("/") : child;
+					if (insideCwd && (this.isDenied(relativeToJail) || matchesAnyGlob(relativeToJail, ignore))) continue;
+					const relativeToRoot = node_path.default.relative(root, child).split(node_path.default.sep).join("/");
+					if (!insideCwd && matchesAnyGlob(relativeToRoot, ignore)) continue;
+					if (entries.length >= maxEntries) {
+						truncated = true;
+						break;
+					}
+					const described = await this.describe(child);
+					entries.push({
+						path: relativeToJail,
+						type: described.type,
+						...described.size !== void 0 ? { size: described.size } : {},
+						depth: currentDepth
+					});
+					if (described.type === "directory") nextLevel.push(child);
+				}
+				if (truncated) break;
+			}
+			if (truncated) break;
+			level = nextLevel;
+		}
+		return {
+			path: insideCwd ? rootRelative || "." : root,
+			entries,
+			truncated
+		};
+	}
+	/** Kind and size of a listed entry; symlinks are reported, never followed. */
+	async describe(absPath) {
+		if (this.backend.stat) try {
+			const stats = await this.backend.stat(absPath);
+			return stats.type === "file" ? {
+				type: "file",
+				size: stats.size
+			} : { type: stats.type };
+		} catch {
+			return { type: "other" };
+		}
+		if (await this.isDirectory(absPath)) try {
+			await resolveInJail(this.policy, absPath);
+			return { type: "directory" };
+		} catch {
+			return { type: "other" };
+		}
+		return { type: "file" };
+	}
 	async grep(pattern, opts) {
 		if (!isSafeGrepPattern(pattern)) throw new WorkspacePolicyError(`Grep pattern is too long or too likely to cause catastrophic regex backtracking: ${pattern}`, {
 			type: "unsafe-pattern",
@@ -676,7 +2595,7 @@ var Ops = class {
 			}
 			const lines = content.split("\n");
 			for (let index = 0; index < lines.length; index++) {
-				const line = lines[index];
+				const line = lines[index] ?? "";
 				if (line.length > MAX_GREP_LINE_SCAN_LENGTH) continue;
 				if (regex.test(line)) {
 					matches.push({
@@ -723,17 +2642,40 @@ var Ops = class {
 	/** Whether a `/`-separated relative path hits the policy deny list. */
 	isDenied(relativePath) {
 		const denyPaths = this.policy.denyPaths;
-		if (!denyPaths || denyPaths.length === 0) return false;
-		return denyPaths.some((glob) => {
-			if (globToRegExp(glob).test(relativePath)) return true;
-			if (!glob.includes("*") && !glob.includes("?")) {
-				const prefix = glob.endsWith("/") ? glob : `${glob}/`;
-				return relativePath.startsWith(prefix);
-			}
-			return false;
-		});
+		return denyPaths !== void 0 && denyPaths.length > 0 && matchesAnyGlob(relativePath, denyPaths);
 	}
 };
+/** The lower of two optional limits (either may be absent). */
+function lowerOf(policyLimit, requested) {
+	if (requested === void 0 || requested <= 0) return policyLimit;
+	return policyLimit === void 0 ? requested : Math.min(policyLimit, requested);
+}
+/**
+* Apply one exact-string replacement to `content` under the edit rules:
+* `oldString` must occur, and exactly once unless `replaceAll`.
+*/
+function applyReplacement(content, edit, inputPath, shownPath, editIndex) {
+	const occurrences = countOccurrences(content, edit.oldString);
+	const which = editIndex === void 0 ? "" : `Edit ${editIndex + 1}: `;
+	const nothingApplied = editIndex === void 0 ? "" : " None of the edits were applied.";
+	const indexOption = editIndex === void 0 ? {} : { editIndex };
+	if (occurrences === 0) throw new WorkspaceEditError(`${which}The text to replace was not found in "${inputPath}".${nothingApplied}`, {
+		type: "not-found",
+		path: shownPath,
+		matches: 0,
+		...indexOption
+	});
+	if (occurrences > 1 && !edit.replaceAll) throw new WorkspaceEditError(`${which}The text to replace is not unique in "${inputPath}" (${occurrences} matches); pass replaceAll or include more surrounding context.${nothingApplied}`, {
+		type: "not-unique",
+		path: shownPath,
+		matches: occurrences,
+		...indexOption
+	});
+	return {
+		content: edit.replaceAll ? content.split(edit.oldString).join(edit.newString) : replaceFirst(content, edit.oldString, edit.newString),
+		replacements: edit.replaceAll ? occurrences : 1
+	};
+}
 /** Count non-overlapping occurrences of `needle` in `haystack`. */
 function countOccurrences(haystack, needle) {
 	if (needle === "") return 0;
@@ -765,13 +2707,15 @@ function replaceFirst(haystack, needle, replacement) {
 *
 * @param backend - The dumb IO executor (local disk or in-memory mock).
 * @param policy - The policy that bounds every operation.
+* @param runtime - State shared with other views of the same workspace
+*   (its background commands); a fresh one when omitted.
 *
 * @example
 * const ops = createOps(localBackend, { cwd: "/srv/api", shell: { allow: ["npm"] } });
 * const { content, hash } = await ops.readFile("src/index.ts");
 */
-function createOps(backend, policy) {
-	return new Ops(backend, policy);
+function createOps(backend, policy, runtime) {
+	return new Ops(backend, policy, runtime ?? { jobs: new ShellJobs() });
 }
 
 //#endregion
@@ -866,6 +2810,74 @@ function toWin32CmdInvocation(argv) {
 		]
 	};
 }
+/** The shell a POSIX shell-mode line runs through — an absolute path, never a PATH lookup. */
+const POSIX_SHELL = "/bin/sh";
+/**
+* Work out the spawn for a command line.
+*
+* - argv mode: tokenize (no shell semantics) and spawn the argv directly —
+*   on Windows through an individually-quoted `cmd.exe` wrapper.
+* - shell mode: `/bin/sh -c <line>`, or `cmd.exe /d /v:off /s /c "<line>"`
+*   on Windows (`/d` skips AutoRun, `/v:off` disables delayed `!` expansion,
+*   `/s` keeps the line verbatim inside the outer quotes). The ops layer has
+*   already checked every command in the line.
+*/
+function planSpawn(command, interpreter) {
+	if (interpreter === "sh") {
+		if (node_process.platform === "win32") return {
+			file: process.env.ComSpec ?? "cmd.exe",
+			args: [
+				"/d",
+				"/v:off",
+				"/s",
+				"/c",
+				`"${command}"`
+			],
+			windowsVerbatimArguments: true
+		};
+		return {
+			file: POSIX_SHELL,
+			args: ["-c", command],
+			windowsVerbatimArguments: false
+		};
+	}
+	const argv = tokenizeCommand(command);
+	const executable = argv?.[0];
+	if (argv === null || executable === void 0) return { refused: "Command was not executed: it is empty, has unbalanced quotes, or contains unquoted shell metacharacters (;, &, |, `, $, <, >, parentheses). Commands run without a shell — pass metacharacters inside quotes as literal arguments, or run one command at a time." };
+	if (node_process.platform === "win32") {
+		const invocation = toWin32CmdInvocation(argv);
+		if (invocation === null) return { refused: "Command was not executed: on Windows, arguments containing \", %, or newlines cannot be passed to cmd.exe safely." };
+		return {
+			...invocation,
+			windowsVerbatimArguments: true
+		};
+	}
+	return {
+		file: executable,
+		args: argv.slice(1),
+		windowsVerbatimArguments: false
+	};
+}
+/**
+* Kill functions of every background process still running, so they can
+* be reaped if the Node process exits without the workspace being disposed
+* (detached process groups would otherwise outlive it).
+*/
+const liveBackgroundKills = /* @__PURE__ */ new Set();
+let exitHookInstalled = false;
+/** Track a live background tree; installs (once) the exit hook that kills them. */
+function trackBackgroundProcess(kill) {
+	liveBackgroundKills.add(kill);
+	if (!exitHookInstalled) {
+		exitHookInstalled = true;
+		process.on("exit", () => {
+			for (const killTreeNow of liveBackgroundKills) killTreeNow();
+		});
+	}
+	return () => {
+		liveBackgroundKills.delete(kill);
+	};
+}
 /**
 * The real-disk executor: every filesystem method delegates to
 * `@warlock.js/fs` (never `node:fs`), and {@link LocalBackend.exec} spawns a
@@ -922,6 +2934,17 @@ var LocalBackend = class {
 		return _warlock_js_fs.fs.dirs.list(absDir);
 	}
 	/**
+	* Describe a path without following a final symlink (`lstat` — like
+	* `realpath`, a filesystem operation `@warlock.js/fs` does not expose).
+	*/
+	async stat(absPath) {
+		const stats = await (0, node_fs_promises.lstat)(absPath);
+		return {
+			type: stats.isSymbolicLink() ? "symlink" : stats.isDirectory() ? "directory" : stats.isFile() ? "file" : "other",
+			size: stats.size
+		};
+	}
+	/**
 	* Resolve symlinks and `..` segments to a canonical absolute path — the
 	* primitive the ops-layer jail uses to detect escapes. Delegates to
 	* `node:fs/promises` `realpath`, the one filesystem operation `@warlock.js/fs`
@@ -931,14 +2954,17 @@ var LocalBackend = class {
 		return (0, node_fs_promises.realpath)(absPath);
 	}
 	/**
-	* Run a command and capture its outcome. The command line is tokenized
-	* into an argv (quotes respected, NO shell semantics — see
-	* `tokenizeCommand`) and spawned **without a shell**, so metacharacters
-	* like `;`, `&&`, `|`, backticks, and `$()` can never chain extra
-	* commands past the ops layer's allowlist; a command they appear
-	* unquoted in is refused with exit code 127. On Windows the argv runs
-	* through a `cmd.exe /d /s /c` wrapper (batch shims like `npm.cmd`
+	* Run a command and capture its outcome. In argv mode (the default) the
+	* command line is tokenized into an argv (quotes respected, NO shell
+	* semantics — see `tokenizeCommand`) and spawned **without a shell**, so
+	* metacharacters like `;`, `&&`, `|`, backticks, and `$()` can never
+	* chain extra commands past the ops layer's allowlist; a command they
+	* appear unquoted in is refused with exit code 127. On Windows the argv
+	* runs through a `cmd.exe /d /s /c` wrapper (batch shims like `npm.cmd`
 	* cannot be spawned shell-less) with every element individually quoted.
+	* With `interpreter: "sh"` the line runs through `/bin/sh -c` (or
+	* `cmd.exe /d /v:off /s /c` on Windows) — only after the ops layer has
+	* checked every command in it.
 	* `cwd`, `env`, and the timeout are taken verbatim from the ops layer
 	* (the environment is NOT merged with `process.env`). On timeout the
 	* process tree is SIGKILLed and `timedOut` is set. When `signal` aborts
@@ -970,31 +2996,17 @@ var LocalBackend = class {
 				});
 				return;
 			}
-			const argv = tokenizeCommand(command);
-			const executable = argv?.[0];
-			if (argv === null || executable === void 0) {
-				refuse("Command was not executed: it is empty, has unbalanced quotes, or contains unquoted shell metacharacters (;, &, |, `, $, <, >, parentheses). Commands run without a shell — pass metacharacters inside quotes as literal arguments, or run one command at a time.");
+			const plan = planSpawn(command, opts.interpreter ?? "none");
+			if ("refused" in plan) {
+				refuse(plan.refused);
 				return;
 			}
-			let file = executable;
-			let args = argv.slice(1);
-			let windowsVerbatimArguments = false;
-			if (node_process.platform === "win32") {
-				const invocation = toWin32CmdInvocation(argv);
-				if (invocation === null) {
-					refuse("Command was not executed: on Windows, arguments containing \", %, or newlines cannot be passed to cmd.exe safely.");
-					return;
-				}
-				file = invocation.file;
-				args = invocation.args;
-				windowsVerbatimArguments = true;
-			}
-			const child = (0, node_child_process.spawn)(file, args, {
+			const child = (0, node_child_process.spawn)(plan.file, plan.args, {
 				cwd: opts.cwd,
 				env: opts.env,
 				shell: false,
 				windowsHide: true,
-				windowsVerbatimArguments,
+				windowsVerbatimArguments: plan.windowsVerbatimArguments,
 				detached: node_process.platform !== "win32"
 			});
 			const stdoutChunks = [];
@@ -1050,6 +3062,75 @@ var LocalBackend = class {
 			});
 		});
 	}
+	/**
+	* Start a long-running command and return at once. Spawned like
+	* {@link exec} (same argv/shell planning, own process group on POSIX), with
+	* stdin closed. Output is decoded per stream with a `StringDecoder`, so a
+	* chunk never ends inside a character. `kill()` kills the whole tree; a
+	* still-running tree is also killed when the Node process exits.
+	*/
+	start(command, opts) {
+		const plan = planSpawn(command, opts.interpreter ?? "none");
+		if ("refused" in plan) {
+			opts.onOutput("stderr", plan.refused);
+			return {
+				done: Promise.resolve({ exitCode: 127 }),
+				kill: () => {}
+			};
+		}
+		const child = (0, node_child_process.spawn)(plan.file, plan.args, {
+			cwd: opts.cwd,
+			env: opts.env,
+			shell: false,
+			windowsHide: true,
+			windowsVerbatimArguments: plan.windowsVerbatimArguments,
+			detached: node_process.platform !== "win32",
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		const stdoutDecoder = new node_string_decoder.StringDecoder("utf8");
+		const stderrDecoder = new node_string_decoder.StringDecoder("utf8");
+		let finished = false;
+		const kill = () => {
+			if (!finished) killTree(child.pid, child);
+		};
+		const untrack = trackBackgroundProcess(kill);
+		child.stdout?.on("data", (chunk) => {
+			const text = stdoutDecoder.write(chunk);
+			if (text !== "") opts.onOutput("stdout", text);
+		});
+		child.stderr?.on("data", (chunk) => {
+			const text = stderrDecoder.write(chunk);
+			if (text !== "") opts.onOutput("stderr", text);
+		});
+		const done = new Promise((resolve) => {
+			const finish = (exitCode) => {
+				if (finished) return;
+				finished = true;
+				untrack();
+				const stdoutTail = stdoutDecoder.end();
+				const stderrTail = stderrDecoder.end();
+				if (stdoutTail !== "") opts.onOutput("stdout", stdoutTail);
+				if (stderrTail !== "") opts.onOutput("stderr", stderrTail);
+				resolve({ exitCode });
+			};
+			child.on("error", (error) => {
+				opts.onOutput("stderr", `Command could not be started: ${error.message}`);
+				finish(127);
+			});
+			child.on("close", (code, signal) => {
+				finish(code === null ? 128 + (signal === "SIGKILL" ? 9 : 1) : code);
+			});
+		});
+		return {
+			...child.pid !== void 0 ? { pid: child.pid } : {},
+			done,
+			kill
+		};
+	}
 };
 /**
 * Create the **local** workspace backend — the default executor that runs the
@@ -1171,6 +3252,40 @@ var MockBackend = class {
 	async realpath(absPath) {
 		return canonicalize(absPath);
 	}
+	async stat(absPath) {
+		const canonical = canonicalize(absPath);
+		const content = this.files.get(canonical);
+		if (content !== void 0) return {
+			type: "file",
+			size: Buffer.byteLength(content, "utf8")
+		};
+		if (this.directories.has(canonical)) return {
+			type: "directory",
+			size: 0
+		};
+		throw new Error(`Mock backend: no such file or directory: ${canonical}`);
+	}
+	/**
+	* Scripted background start: emits the registered `stdout` / `stderr`
+	* synchronously, then exits with `exitCode` — or, when scripted with
+	* `running: true`, stays running until `kill()` (exit code 137).
+	*/
+	start(command, opts) {
+		const scripted = this.commands.get(command);
+		if (scripted?.stdout) opts.onOutput("stdout", scripted.stdout);
+		if (scripted?.stderr) opts.onOutput("stderr", scripted.stderr);
+		if (scripted?.running !== true) return {
+			done: Promise.resolve({ exitCode: scripted?.exitCode ?? 0 }),
+			kill: () => {}
+		};
+		let stop = () => {};
+		return {
+			done: new Promise((resolve) => {
+				stop = resolve;
+			}),
+			kill: () => stop({ exitCode: 137 })
+		};
+	}
 	async exec(command, opts) {
 		if (opts?.signal?.aborted) return {
 			exitCode: 130,
@@ -1261,6 +3376,10 @@ function isMockBackendSeed(seed) {
 */
 /** The vendor tag stamped on every issue these builders produce. */
 const VENDOR = "ai-workspace";
+/** Attach a JSON Schema description to a hand-rolled Standard Schema. */
+function withJsonSchema(schema, jsonSchema) {
+	return Object.assign(schema, { jsonSchema });
+}
 /** Required string field — rejects anything that is not a string. */
 function stringField() {
 	return (value, key) => {
@@ -1311,24 +3430,25 @@ function optionalBooleanField() {
 	};
 }
 /**
-* Build a {@link StandardSchemaV1} for a flat object whose every property
-* is validated by a {@link FieldValidator}. The input must be a non-null
-* object; each declared field is validated and the (possibly coerced)
-* values are collected into the typed result. All field issues are merged
-* so the caller sees every problem at once.
-*
-* `T` is constrained to `object` rather than `Record<string, unknown>` so
-* the tool IO `interface`s (which carry no implicit string index
-* signature) satisfy it directly — only the declared keys in `shape` are
-* ever read, so a string index signature is never required.
-*
-* @example
-* const schema = objectSchema<{ path: string; limit?: number }>({
-*   path: stringField(),
-*   limit: optionalNumberField(),
-* });
+* Optional array-of-strings field — accepts `undefined` or an array whose
+* every element is a string (at most `maxItems` of them).
 */
-function objectSchema(shape) {
+function optionalStringArrayField(maxItems = 50) {
+	return (value, key) => {
+		if (value === void 0) return { value: void 0 };
+		if (Array.isArray(value) && value.length <= maxItems && value.every((item) => typeof item === "string")) return { value };
+		return { issues: [{
+			message: `"${key}" must be an array of at most ${maxItems} strings when provided`,
+			path: [key]
+		}] };
+	};
+}
+function objectSchema(shape, jsonSchema) {
+	const schema = buildObjectSchema(shape);
+	return jsonSchema === void 0 ? schema : withJsonSchema(schema, jsonSchema);
+}
+/** The validator behind {@link objectSchema}. */
+function buildObjectSchema(shape) {
 	return { "~standard": {
 		version: 1,
 		vendor: VENDOR,
@@ -1352,18 +3472,191 @@ function objectSchema(shape) {
 	} };
 }
 
+//#endregion
+//#region ../../packages/ai-workspace/src/tools/json-schemas.ts
+/**
+* The JSON Schemas the workspace tools publish for their input (read by
+* `extractJsonSchema` and sent to the provider with each tool), kept short
+* because they ride along on every model call. They describe what the
+* hand-rolled validators accept; the validators remain the authority.
+*/
+const string = (description) => ({
+	type: "string",
+	description
+});
+const integer = (description) => ({
+	type: "integer",
+	description
+});
+const boolean = (description) => ({
+	type: "boolean",
+	description
+});
+/** `read_file`. */
+const READ_FILE_JSON_SCHEMA = {
+	type: "object",
+	properties: {
+		path: string("Workspace-relative file path."),
+		startLine: integer("1-based first line to return."),
+		limit: integer("Most lines to return.")
+	},
+	required: ["path"]
+};
+/** `edit_file`. */
+const EDIT_FILE_JSON_SCHEMA = {
+	type: "object",
+	properties: {
+		path: string("Workspace-relative file path."),
+		oldString: string("Exact text to replace; must be unique unless replaceAll."),
+		newString: string("Replacement text."),
+		replaceAll: boolean("Replace every occurrence."),
+		expectHash: string("Hash from read_file; rejects the edit if the file changed.")
+	},
+	required: [
+		"path",
+		"oldString",
+		"newString"
+	]
+};
+/** `multi_edit`. */
+const MULTI_EDIT_JSON_SCHEMA = {
+	type: "object",
+	properties: {
+		path: string("Workspace-relative file path."),
+		edits: {
+			type: "array",
+			description: "Replacements applied in order, each to the result of the previous; all or none.",
+			minItems: 1,
+			maxItems: 100,
+			items: {
+				type: "object",
+				properties: {
+					oldString: string("Exact text to replace; must be unique unless replaceAll."),
+					newString: string("Replacement text."),
+					replaceAll: boolean("Replace every occurrence.")
+				},
+				required: ["oldString", "newString"]
+			}
+		},
+		expectHash: string("Hash from read_file; rejects every edit if the file changed.")
+	},
+	required: ["path", "edits"]
+};
+/** `write_file`. */
+const WRITE_FILE_JSON_SCHEMA = {
+	type: "object",
+	properties: {
+		path: string("Workspace-relative file path."),
+		content: string("Full file content.")
+	},
+	required: ["path", "content"]
+};
+/** `list_dir`. */
+const LIST_DIR_JSON_SCHEMA = {
+	type: "object",
+	properties: {
+		path: string("Workspace-relative directory (default \".\")."),
+		depth: integer("Levels to list; 1 = direct children (default)."),
+		ignore: {
+			type: "array",
+			items: { type: "string" },
+			description: "Extra globs to leave out."
+		}
+	}
+};
+/** `run_shell` (the `background` property is only listed when background commands are enabled). */
+function runShellJsonSchema(background) {
+	return {
+		type: "object",
+		properties: {
+			command: string("The command line to run."),
+			timeoutMs: integer("Wall-clock cap in ms (can only lower the workspace limit)."),
+			...background ? { background: boolean("Start it in the background and return its id at once (dev servers, watchers).") } : {}
+		},
+		required: ["command"]
+	};
+}
+/** `shell_output`. */
+const SHELL_OUTPUT_JSON_SCHEMA = {
+	type: "object",
+	properties: {
+		id: string("Background command id from run_shell."),
+		since: integer("A cursor from an earlier result; omit for output since the last read."),
+		waitMs: integer("Wait up to this long (max 30000) for new output.")
+	},
+	required: ["id"]
+};
+/** `shell_kill`. */
+const SHELL_KILL_JSON_SCHEMA = {
+	type: "object",
+	properties: { id: string("Background command id from run_shell.") },
+	required: ["id"]
+};
+/** `run_tests`. */
+const RUN_TESTS_JSON_SCHEMA = {
+	type: "object",
+	properties: { pattern: string("Optional test path or name filter.") }
+};
+/** `grep`. */
+const GREP_JSON_SCHEMA = {
+	type: "object",
+	properties: {
+		pattern: string("Regular expression to search for."),
+		glob: string("Only search files matching this glob (e.g. \"src/**/*.ts\")."),
+		ignoreCase: boolean("Case-insensitive match.")
+	},
+	required: ["pattern"]
+};
+/** `glob`. */
+const GLOB_JSON_SCHEMA = {
+	type: "object",
+	properties: { pattern: string("Glob such as \"src/**/*.ts\".") },
+	required: ["pattern"]
+};
+/** `todo_write`. */
+const TODO_WRITE_JSON_SCHEMA = {
+	type: "object",
+	properties: { todos: {
+		type: "array",
+		description: "The complete updated list (replaces the old one).",
+		maxItems: 100,
+		items: {
+			type: "object",
+			properties: {
+				id: string("Stable id; omit to number items by position."),
+				content: string("The step."),
+				status: {
+					type: "string",
+					enum: [
+						"pending",
+						"in_progress",
+						"completed"
+					]
+				}
+			},
+			required: ["content", "status"]
+		}
+	} },
+	required: ["todos"]
+};
+/** `todo_read`. */
+const TODO_READ_JSON_SCHEMA = {
+	type: "object",
+	properties: {}
+};
+
 //#endregion
 //#region ../../packages/ai-workspace/src/tools/edit-file.ts
 /** Default tool name exposed to the LLM. */
-const DEFAULT_NAME$2 = "edit_file";
+const DEFAULT_NAME$6 = "edit_file";
 /** Input schema for the `edit_file` tool. */
-const inputSchema$2 = objectSchema({
+const inputSchema$6 = objectSchema({
 	path: stringField(),
 	oldString: stringField(),
 	newString: stringField(),
 	replaceAll: optionalBooleanField(),
 	expectHash: optionalStringField()
-});
+}, EDIT_FILE_JSON_SCHEMA);
 /**
 * Build the agent-facing `edit_file` tool over a workspace's policy-
 * enforced {@link WorkspaceOps}.
@@ -1395,9 +3688,9 @@ const inputSchema$2 = objectSchema({
 */
 function makeEditFileTool(ops, options) {
 	return (0, _warlock_js_ai.tool)({
-		name: options?.name ?? DEFAULT_NAME$2,
+		name: options?.name ?? DEFAULT_NAME$6,
 		description: "Replace an exact substring in a workspace file. oldString must match uniquely unless replaceAll is set. Pass expectHash (from read_file) to reject the edit if the file changed since you read it. Returns the number of replacements and the new content hash.",
-		input: inputSchema$2,
+		input: inputSchema$6,
 		async execute(input) {
 			return ops.editFile(input);
 		}
@@ -1412,7 +3705,7 @@ function makeEditFileTool(ops, options) {
 * (no schema library, matching the validator idiom the `@warlock.js/ai`
 * tool runtime expects).
 */
-const globInputSchema = objectSchema({ pattern: stringField() });
+const globInputSchema = objectSchema({ pattern: stringField() }, GLOB_JSON_SCHEMA);
 /**
 * Build the agent-facing `glob` tool — resolve a glob pattern to the
 * matching workspace-relative paths within the jail. The returned
@@ -1456,7 +3749,7 @@ const grepInputSchema = objectSchema({
 	pattern: stringField(),
 	glob: optionalStringField(),
 	ignoreCase: optionalBooleanField()
-});
+}, GREP_JSON_SCHEMA);
 /**
 * Build the agent-facing `grep` tool — a regex content search across the
 * jailed file set. The returned {@link ToolContract} validates the LLM's
@@ -1490,16 +3783,174 @@ function makeGrepTool(ops, options) {
 	});
 }
 
+//#endregion
+//#region ../../packages/ai-workspace/src/tools/list-dir.ts
+/** Default tool name exposed to the LLM. */
+const DEFAULT_NAME$5 = "list_dir";
+/** Input schema for the `list_dir` tool. */
+const inputSchema$5 = objectSchema({
+	path: optionalStringField(),
+	depth: optionalNumberField(),
+	ignore: optionalStringArrayField()
+}, LIST_DIR_JSON_SCHEMA);
+/**
+* Build the agent-facing `list_dir` tool over a workspace's policy-enforced
+* {@link WorkspaceOps}: a bounded, jailed listing of one directory.
+*
+* Entries come back breadth-first (each level sorted by name) with their
+* type and — for files — size, down to `depth` levels (capped by
+* `list.maxDepth`) and at most `list.maxEntries` entries (`truncated` says
+* when the cap hit). `denyPaths` are always left out, as are the
+* `list.ignore` globs (default `node_modules`, `.git`) and any `ignore`
+* globs the model passes. Symlinks are reported as `"symlink"` and never
+* followed. A path outside the jail surfaces as a `WorkspacePolicyError` in
+* the result's `error` field.
+*
+* @param ops - The shared, policy-enforced operation layer.
+* @param options - Optional overrides; `name` renames the LLM-visible tool.
+*
+* @example
+* const listDir = makeListDirTool(ops);
+* const { data } = await listDir.invoke({ path: "src", depth: 2 });
+* for (const entry of data?.entries ?? []) console.log(entry.type, entry.path, entry.size);
+*/
+function makeListDirTool(ops, options) {
+	return (0, _warlock_js_ai.tool)({
+		name: options?.name ?? DEFAULT_NAME$5,
+		description: "List a workspace directory: entries with their type and file size, breadth-first, `depth` levels deep (default 1). Dependency and VCS folders are left out unless you list them directly.",
+		action: (input) => `Listing ${typeof input.path === "string" ? input.path : "."}`,
+		input: inputSchema$5,
+		execute: (input) => ops.listDir(input.path ?? ".", {
+			...input.depth !== void 0 ? { depth: input.depth } : {},
+			...input.ignore !== void 0 ? { ignore: input.ignore } : {}
+		})
+	});
+}
+
+//#endregion
+//#region ../../packages/ai-workspace/src/tools/multi-edit.ts
+/** Default tool name exposed to the LLM. */
+const DEFAULT_NAME$4 = "multi_edit";
+/** Validate one element of `edits`. */
+function validateEdit(value, index) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return { issues: [{
+		message: `edits[${index}] must be an object`,
+		path: ["edits", index]
+	}] };
+	const candidate = value;
+	const issues = [];
+	if (typeof candidate.oldString !== "string" || candidate.oldString === "") issues.push({
+		message: `edits[${index}].oldString must be a non-empty string`,
+		path: [
+			"edits",
+			index,
+			"oldString"
+		]
+	});
+	if (typeof candidate.newString !== "string") issues.push({
+		message: `edits[${index}].newString must be a string`,
+		path: [
+			"edits",
+			index,
+			"newString"
+		]
+	});
+	if (candidate.replaceAll !== void 0 && typeof candidate.replaceAll !== "boolean") issues.push({
+		message: `edits[${index}].replaceAll must be a boolean when provided`,
+		path: [
+			"edits",
+			index,
+			"replaceAll"
+		]
+	});
+	if (issues.length > 0 || typeof candidate.oldString !== "string" || typeof candidate.newString !== "string") return { issues };
+	return { edit: {
+		oldString: candidate.oldString,
+		newString: candidate.newString,
+		...candidate.replaceAll === true ? { replaceAll: true } : {}
+	} };
+}
+/** Input schema for the `multi_edit` tool. */
+const inputSchema$4 = withJsonSchema({ "~standard": {
+	version: 1,
+	vendor: "ai-workspace",
+	validate(value) {
+		if (typeof value !== "object" || value === null || Array.isArray(value)) return { issues: [{ message: "input must be an object" }] };
+		const candidate = value;
+		const issues = [];
+		const edits = [];
+		if (typeof candidate.path !== "string" || candidate.path === "") issues.push({
+			message: "\"path\" must be a non-empty string",
+			path: ["path"]
+		});
+		if (candidate.expectHash !== void 0 && typeof candidate.expectHash !== "string") issues.push({
+			message: "\"expectHash\" must be a string when provided",
+			path: ["expectHash"]
+		});
+		if (!Array.isArray(candidate.edits) || candidate.edits.length === 0 || candidate.edits.length > 100) issues.push({
+			message: `"edits" must be an array of 1 to ${100} edits`,
+			path: ["edits"]
+		});
+		else candidate.edits.forEach((item, index) => {
+			const outcome = validateEdit(item, index);
+			if ("issues" in outcome) issues.push(...outcome.issues);
+			else edits.push(outcome.edit);
+		});
+		if (issues.length > 0 || typeof candidate.path !== "string") return { issues };
+		return { value: {
+			path: candidate.path,
+			edits,
+			...typeof candidate.expectHash === "string" ? { expectHash: candidate.expectHash } : {}
+		} };
+	}
+} }, MULTI_EDIT_JSON_SCHEMA);
+/**
+* Build the agent-facing `multi_edit` tool over a workspace's policy-
+* enforced {@link WorkspaceOps}: several exact-string replacements in one
+* file, **atomic** — every edit applies, in order (each against the result
+* of the previous ones), and the file is written once; or one edit fails
+* and nothing is written.
+*
+* Each edit follows the `edit_file` rules: `oldString` must be found, and
+* found exactly once unless `replaceAll`. An optional `expectHash` (from
+* `read_file`) rejects the whole call when the file changed since it was
+* read. A failure surfaces as a `WorkspaceEditError` in the result's
+* `error` field, with `editIndex` naming the failing edit.
+*
+* @param ops - The shared, policy-enforced operation layer.
+* @param options - Optional overrides; `name` renames the LLM-visible tool.
+*
+* @example
+* const multiEdit = makeMultiEditTool(ops);
+* const { data, error } = await multiEdit.invoke({
+*   path: "src/cart.ts",
+*   expectHash,
+*   edits: [
+*     { oldString: "let total = 0;", newString: "let total = 0n;" },
+*     { oldString: "total += price;", newString: "total += BigInt(price);" },
+*   ],
+* });
+*/
+function makeMultiEditTool(ops, options) {
+	return (0, _warlock_js_ai.tool)({
+		name: options?.name ?? DEFAULT_NAME$4,
+		description: "Make several exact-string replacements in one workspace file at once. Edits apply in order, each to the result of the previous; if any edit fails (text not found, or not unique without replaceAll) none are applied. Pass expectHash (from read_file) to reject the call if the file changed since you read it.",
+		action: (input) => `Editing ${typeof input.path === "string" ? input.path : "a file"}`,
+		input: inputSchema$4,
+		execute: (input) => ops.multiEdit(input)
+	});
+}
+
 //#endregion
 //#region ../../packages/ai-workspace/src/tools/read-file.ts
 /** Default tool name exposed to the LLM. */
-const DEFAULT_NAME$1 = "read_file";
+const DEFAULT_NAME$3 = "read_file";
 /** Input schema for the `read_file` tool. */
-const inputSchema$1 = objectSchema({
+const inputSchema$3 = objectSchema({
 	path: stringField(),
 	startLine: optionalNumberField(),
 	limit: optionalNumberField()
-});
+}, READ_FILE_JSON_SCHEMA);
 /**
 * Build the agent-facing `read_file` tool over a workspace's policy-
 * enforced {@link WorkspaceOps}.
@@ -1526,9 +3977,9 @@ const inputSchema$1 = objectSchema({
 */
 function makeReadFileTool(ops, options) {
 	return (0, _warlock_js_ai.tool)({
-		name: options?.name ?? DEFAULT_NAME$1,
+		name: options?.name ?? DEFAULT_NAME$3,
 		description: "Read a file from the workspace, returning a numbered line window plus the file's content hash. Pass the hash to edit_file's expectHash to guard against editing a stale version. Use startLine/limit to page through large files. Output is byte-capped by the workspace policy; when bytesCapped is true the last returned line may be cut short.",
-		input: inputSchema$1,
+		input: inputSchema$3,
 		async execute(input) {
 			return ops.readFile(input.path, {
 				offset: input.startLine !== void 0 ? Math.max(1, input.startLine) : 1,
@@ -1545,64 +3996,67 @@ const DEFAULT_RUN_SHELL_TOOL_NAME = "run_shell";
 /**
 * Hand-rolled Standard Schema for {@link RunShellInput}. We validate the
 * model's arguments without a runtime schema dependency: `command` must be
-* a non-empty string, and `timeoutMs` (when present) a positive number.
-* Invalid args surface as a `SchemaValidationError` in the tool result's
-* `error` field rather than reaching `ops.exec`.
-*/
-const runShellInputSchema = { "~standard": {
-	version: 1,
-	vendor: "@warlock.js/ai-workspace",
-	validate: (value) => {
-		if (typeof value !== "object" || value === null) return { issues: [{ message: "expected an object" }] };
-		const candidate = value;
-		if (typeof candidate.command !== "string" || candidate.command.length === 0) return { issues: [{
-			message: "command must be a non-empty string",
-			path: ["command"]
-		}] };
-		if (candidate.timeoutMs !== void 0 && (typeof candidate.timeoutMs !== "number" || candidate.timeoutMs <= 0)) return { issues: [{
-			message: "timeoutMs must be a positive number",
-			path: ["timeoutMs"]
-		}] };
-		const result = { command: candidate.command };
-		if (candidate.timeoutMs !== void 0) result.timeoutMs = candidate.timeoutMs;
-		return { value: result };
-	}
-} };
-/**
-* Build the `run_shell` tool — a {@link ToolContract} that runs a single
-* shell command through the policy-enforced {@link WorkspaceOps} layer.
-*
-* The command's leading executable basename is gated against the shell
-* allow/deny policy by `ops.exec`; a blocked command throws a
-* `WorkspacePolicyError` which the `tool()` runtime catches and surfaces
-* in the result's `error` field (never a thrown run-killer), so the agent
-* reads the refusal as tool data and self-corrects. A command that runs
-* but exits non-zero is *not* an error — its `exitCode`/`stderr` come back
-* in `data` for the agent to inspect.
-*
-* The agent run's cancellation `signal` (from the dispatch `ctx`) is passed
-* to `ops.exec` per invocation: a cancelled run never starts the command,
-* and one cancelled mid-command kills its process tree (`cancelled: true`).
-*
-* @param ops - The policy-enforced operation layer to delegate `exec` to.
-* @param options - Optional tool-name override.
-*
-* @example
-* const runShell = makeRunShellTool(ops);
-* const { data, error } = await runShell.invoke({ command: "npm run build" });
-* if (error) handleDenied(error);
-* else console.log(data.exitCode, data.stdout);
+* a non-empty string, `timeoutMs` (when present) a positive number and
+* `background` (when present) a boolean. Invalid args surface as a
+* `SchemaValidationError` in the tool result's `error` field rather than
+* reaching `ops.exec`.
 */
+function runShellInputSchema(background) {
+	return withJsonSchema({ "~standard": {
+		version: 1,
+		vendor: "@warlock.js/ai-workspace",
+		validate: (value) => {
+			if (typeof value !== "object" || value === null) return { issues: [{ message: "expected an object" }] };
+			const candidate = value;
+			if (typeof candidate.command !== "string" || candidate.command.length === 0) return { issues: [{
+				message: "command must be a non-empty string",
+				path: ["command"]
+			}] };
+			if (candidate.timeoutMs !== void 0 && (typeof candidate.timeoutMs !== "number" || candidate.timeoutMs <= 0)) return { issues: [{
+				message: "timeoutMs must be a positive number",
+				path: ["timeoutMs"]
+			}] };
+			if (candidate.background !== void 0 && typeof candidate.background !== "boolean") return { issues: [{
+				message: "background must be a boolean",
+				path: ["background"]
+			}] };
+			const result = { command: candidate.command };
+			if (typeof candidate.timeoutMs === "number") result.timeoutMs = candidate.timeoutMs;
+			if (candidate.background === true) result.background = true;
+			return { value: result };
+		}
+	} }, runShellJsonSchema(background));
+}
+/** The lower of the model's timeout and the cap (either may be absent). */
+function cappedTimeout(requested, cap) {
+	if (requested === void 0) return cap;
+	return cap === void 0 ? requested : Math.min(requested, cap);
+}
 function makeRunShellTool(ops, options) {
+	const background = options?.background === true;
 	return (0, _warlock_js_ai.tool)({
 		name: options?.name ?? DEFAULT_RUN_SHELL_TOOL_NAME,
-		description: "Run a single shell command inside the workspace. The command's executable must be permitted by the shell policy; output is byte-capped and the run is time-limited. A non-zero exit code is returned as data, not an error.",
+		description: "Run a shell command inside the workspace. Every command in it must be permitted by the shell policy; a refusal explains how to fix the command. Output is byte-capped and the run is time-limited. A non-zero exit code is returned as data, not an error." + (background ? " Pass background: true for a long-running command (dev server, watcher): it returns an id at once; read its output with shell_output and stop it with shell_kill." : ""),
 		action: (input) => `Running \`${input.command}\``,
-		input: runShellInputSchema,
-		execute: (input, ctx) => ops.exec(input.command, {
-			timeoutMs: input.timeoutMs,
-			...ctx?.signal ? { signal: ctx.signal } : {}
-		})
+		input: runShellInputSchema(background),
+		execute: async (input, ctx) => {
+			if (input.background === true) {
+				if (!background) throw new WorkspacePolicyError("Background commands are not enabled for this workspace; run the command without background.", {
+					type: "denied-command",
+					reason: "not-allowed",
+					command: input.command
+				});
+				return {
+					...await ops.startShell(input.command, input.timeoutMs !== void 0 ? { timeoutMs: input.timeoutMs } : void 0),
+					background: true
+				};
+			}
+			const timeoutMs = cappedTimeout(input.timeoutMs, options?.maxTimeoutMs);
+			return ops.exec(input.command, {
+				...timeoutMs !== void 0 ? { timeoutMs } : {},
+				...ctx?.signal ? { signal: ctx.signal } : {}
+			});
+		}
 	});
 }
 
@@ -1621,7 +4075,7 @@ const DEFAULT_TEST_COMMAND = "npm test";
 * happens without a runtime schema dependency, mirroring the wider tool
 * layer.
 */
-const runTestsInputSchema = { "~standard": {
+const runTestsInputSchema = withJsonSchema({ "~standard": {
 	version: 1,
 	vendor: "@warlock.js/ai-workspace",
 	validate: (value) => {
@@ -1640,7 +4094,12 @@ const runTestsInputSchema = { "~standard": {
 		if (candidate.pattern !== void 0) result.pattern = candidate.pattern;
 		return { value: result };
 	}
-} };
+} }, RUN_TESTS_JSON_SCHEMA);
+/** Quote the test pattern as one literal argument for the line's interpreter. */
+function quotePattern(pattern, interpreter) {
+	if (interpreter === "sh" && process.platform !== "win32") return `'${pattern.replace(/'/g, "'\\''")}'`;
+	return `"${pattern}"`;
+}
 /**
 * Build the `run_tests` tool — a {@link ToolContract} convenience over
 * `run_shell` that runs the workspace's configured test command through
@@ -1673,12 +4132,275 @@ function makeRunTestsTool(ops, options) {
 		action: (input) => input.pattern ? `Running tests matching "${input.pattern}"` : "Running tests",
 		input: runTestsInputSchema,
 		execute: (input, ctx) => {
-			const command = input.pattern ? `${baseCommand} "${input.pattern}"` : baseCommand;
+			const command = input.pattern ? `${baseCommand} ${quotePattern(input.pattern, options?.interpreter ?? "none")}` : baseCommand;
 			return ops.exec(command, ctx?.signal ? { signal: ctx.signal } : void 0);
 		}
 	});
 }
 
+//#endregion
+//#region ../../packages/ai-workspace/src/tools/shell-kill.ts
+/** Default tool name exposed to the LLM. */
+const DEFAULT_NAME$2 = "shell_kill";
+/** Input schema for the `shell_kill` tool. */
+const inputSchema$2 = objectSchema({ id: stringField() }, SHELL_KILL_JSON_SCHEMA);
+/**
+* Build the agent-facing `shell_kill` tool: stop a background command
+* started with `run_shell({ background: true })`, killing its whole process
+* tree, and return its final state. Killing a command that already stopped
+* just reports its state. An unknown id surfaces as a `WorkspaceJobError`
+* in the result's `error` field.
+*
+* @param ops - The shared, policy-enforced operation layer.
+* @param options - Optional overrides; `name` renames the LLM-visible tool.
+*
+* @example
+* const { data } = await makeShellKillTool(ops).invoke({ id: "job-1" });
+* console.log(data?.status); // "killed"
+*/
+function makeShellKillTool(ops, options) {
+	return (0, _warlock_js_ai.tool)({
+		name: options?.name ?? DEFAULT_NAME$2,
+		description: "Stop a background command started with run_shell (background: true), killing it and everything it started. Returns its final state.",
+		action: (input) => `Stopping ${typeof input.id === "string" ? input.id : "a background command"}`,
+		input: inputSchema$2,
+		execute: (input) => ops.shellKill(input.id)
+	});
+}
+
+//#endregion
+//#region ../../packages/ai-workspace/src/tools/shell-output.ts
+/** Default tool name exposed to the LLM. */
+const DEFAULT_NAME$1 = "shell_output";
+/** Input schema for the `shell_output` tool. */
+const inputSchema$1 = objectSchema({
+	id: stringField(),
+	since: optionalNumberField(),
+	waitMs: optionalNumberField()
+}, SHELL_OUTPUT_JSON_SCHEMA);
+/**
+* Build the agent-facing `shell_output` tool: the new output of a
+* background command started with `run_shell({ background: true })`, plus
+* its state (`running` / `exited` / `killed` / `timed-out`, `exitCode`).
+*
+* Without `since` it returns everything produced since the previous read;
+* `cursor` in the result is the position to pass as `since` next time.
+* `waitMs` (at most 30 s) waits for new output or for the command to stop
+* when there is nothing new yet — the agent run's signal ends the wait
+* early. Only the newest `shell.maxOutputBytes` of a command's output are
+* kept; `droppedBytes` says how much the reader missed.
+*
+* @param ops - The shared, policy-enforced operation layer.
+* @param options - Optional overrides; `name` renames the LLM-visible tool.
+*
+* @example
+* const { data } = await makeShellOutputTool(ops).invoke({ id: "job-1", waitMs: 2_000 });
+* if (data?.stdout.includes("ready")) console.log("dev server is up");
+*/
+function makeShellOutputTool(ops, options) {
+	return (0, _warlock_js_ai.tool)({
+		name: options?.name ?? DEFAULT_NAME$1,
+		description: "Read new output of a background command started with run_shell (background: true) and see whether it is still running. Returns output since the last read; waitMs waits briefly for more.",
+		action: (input) => `Reading output of ${typeof input.id === "string" ? input.id : "a background command"}`,
+		input: inputSchema$1,
+		execute: (input, ctx) => ops.shellOutput(input.id, {
+			...input.since !== void 0 ? { since: input.since } : {},
+			...input.waitMs !== void 0 ? { waitMs: input.waitMs } : {},
+			...ctx?.signal ? { signal: ctx.signal } : {}
+		})
+	});
+}
+
+//#endregion
+//#region ../../packages/ai-workspace/src/todos.ts
+/** Most items a todo list may hold. */
+const MAX_TODOS = 100;
+/** Longest `content` one todo item may have. */
+const MAX_TODO_CONTENT_LENGTH = 1e3;
+/** The statuses a todo item may have, in display order. */
+const TODO_STATUSES = [
+	"pending",
+	"in_progress",
+	"completed"
+];
+/**
+* Validate a whole replacement list. Returns the problems found (empty when
+* the list is valid) so the tool schema and the direct method share one
+* set of rules.
+*/
+function todoListProblems(todos) {
+	const problems = [];
+	const ids = /* @__PURE__ */ new Set();
+	if (todos.length > 100) problems.push(`a todo list holds at most ${100} items (got ${todos.length})`);
+	todos.forEach((todo, index) => {
+		if (todo.content.trim() === "") problems.push(`todos[${index}].content must not be empty`);
+		if (todo.content.length > 1e3) problems.push(`todos[${index}].content is longer than ${MAX_TODO_CONTENT_LENGTH} characters`);
+		if (!TODO_STATUSES.includes(todo.status)) problems.push(`todos[${index}].status must be one of ${TODO_STATUSES.join(", ")}`);
+		const id = todo.id ?? String(index + 1);
+		if (ids.has(id)) problems.push(`todos[${index}].id "${id}" is used more than once`);
+		ids.add(id);
+	});
+	return problems;
+}
+/**
+* The in-memory todo list of one workspace (shared by its projections).
+* `write` replaces the whole list, the way an agent's plan tool usually
+* works: the model sends the full updated list every time.
+*/
+var TodoStore = class {
+	constructor() {
+		this.items = [];
+	}
+	/** The current list and a count per status. */
+	read() {
+		const counts = {
+			pending: 0,
+			in_progress: 0,
+			completed: 0
+		};
+		for (const item of this.items) counts[item.status]++;
+		return {
+			todos: this.items.map((item) => ({ ...item })),
+			counts
+		};
+	}
+	/**
+	* Replace the list. Items without an `id` get their 1-based position as
+	* one. Throws a `RangeError` naming every problem when the list is invalid
+	* (too long, empty content, unknown status, duplicate id); the old list is
+	* kept in that case.
+	*/
+	write(todos) {
+		const problems = todoListProblems(todos);
+		if (problems.length > 0) throw new RangeError(`Invalid todo list: ${problems.join("; ")}.`);
+		this.items = todos.map((todo, index) => ({
+			id: todo.id ?? String(index + 1),
+			content: todo.content.trim(),
+			status: todo.status
+		}));
+		return this.read();
+	}
+};
+
+//#endregion
+//#region ../../packages/ai-workspace/src/tools/todo.ts
+/** Whether `value` is a todo status. */
+function isTodoStatus(value) {
+	return typeof value === "string" && TODO_STATUSES.includes(value);
+}
+/** Input schema for the `todo_write` tool. */
+const todoWriteSchema = withJsonSchema({ "~standard": {
+	version: 1,
+	vendor: "ai-workspace",
+	validate(value) {
+		if (typeof value !== "object" || value === null || Array.isArray(value)) return { issues: [{ message: "input must be an object" }] };
+		const raw = value.todos;
+		if (!Array.isArray(raw) || raw.length > 100) return { issues: [{
+			message: `"todos" must be an array of at most ${100} items`,
+			path: ["todos"]
+		}] };
+		const issues = [];
+		const todos = [];
+		raw.forEach((item, index) => {
+			if (typeof item !== "object" || item === null || Array.isArray(item)) {
+				issues.push({
+					message: `todos[${index}] must be an object`,
+					path: ["todos", index]
+				});
+				return;
+			}
+			const candidate = item;
+			if (typeof candidate.content !== "string") issues.push({
+				message: `todos[${index}].content must be a string`,
+				path: [
+					"todos",
+					index,
+					"content"
+				]
+			});
+			if (!isTodoStatus(candidate.status)) issues.push({
+				message: `todos[${index}].status must be one of ${TODO_STATUSES.join(", ")}`,
+				path: [
+					"todos",
+					index,
+					"status"
+				]
+			});
+			if (candidate.id !== void 0 && typeof candidate.id !== "string") issues.push({
+				message: `todos[${index}].id must be a string when provided`,
+				path: [
+					"todos",
+					index,
+					"id"
+				]
+			});
+			if (typeof candidate.content === "string" && isTodoStatus(candidate.status)) todos.push({
+				content: candidate.content,
+				status: candidate.status,
+				...typeof candidate.id === "string" ? { id: candidate.id } : {}
+			});
+		});
+		if (issues.length === 0) for (const problem of todoListProblems(todos)) issues.push({
+			message: problem,
+			path: ["todos"]
+		});
+		return issues.length > 0 ? { issues } : { value: { todos } };
+	}
+} }, TODO_WRITE_JSON_SCHEMA);
+/** Input schema for the `todo_read` tool (no arguments). */
+const todoReadSchema = withJsonSchema({ "~standard": {
+	version: 1,
+	vendor: "ai-workspace",
+	validate: () => ({ value: {} })
+} }, TODO_READ_JSON_SCHEMA);
+/**
+* Build the agent-facing `todo_write` tool over a workspace's todo list:
+* the model sends the **complete** updated list (each item `content` +
+* `status` of `pending` / `in_progress` / `completed`, optional `id`) and it
+* replaces the old one. The list lives in memory, per workspace (shared by
+* its `readonly()` / `scope()` projections), for the length of the run.
+*
+* @param store - The workspace's todo list.
+* @param options - Optional overrides; `name` renames the LLM-visible tool.
+*
+* @example
+* await makeTodoWriteTool(store).invoke({
+*   todos: [
+*     { content: "Reproduce the failing test", status: "completed" },
+*     { content: "Fix the rounding bug", status: "in_progress" },
+*   ],
+* });
+*/
+function makeTodoWriteTool(store, options) {
+	return (0, _warlock_js_ai.tool)({
+		name: options?.name ?? "todo_write",
+		description: "Replace your todo list for this task with the complete updated list (each item: content and status pending | in_progress | completed). Use it to plan multi-step work and to mark progress.",
+		action: "Updating the todo list",
+		input: todoWriteSchema,
+		execute: async (input) => store.write(input.todos)
+	});
+}
+/**
+* Build the agent-facing `todo_read` tool: the workspace's current todo
+* list and a count per status.
+*
+* @param store - The workspace's todo list.
+* @param options - Optional overrides; `name` renames the LLM-visible tool.
+*
+* @example
+* const { data } = await makeTodoReadTool(store).invoke({});
+* console.log(data?.counts.pending);
+*/
+function makeTodoReadTool(store, options) {
+	return (0, _warlock_js_ai.tool)({
+		name: options?.name ?? "todo_read",
+		description: "Read your current todo list for this task.",
+		action: "Reading the todo list",
+		input: todoReadSchema,
+		execute: async () => store.read()
+	});
+}
+
 //#endregion
 //#region ../../packages/ai-workspace/src/tools/write-file.ts
 /** Default tool name exposed to the LLM. */
@@ -1687,7 +4409,7 @@ const DEFAULT_NAME = "write_file";
 const inputSchema = objectSchema({
 	path: stringField(),
 	content: stringField()
-});
+}, WRITE_FILE_JSON_SCHEMA);
 /**
 * Build the agent-facing `write_file` tool over a workspace's policy-
 * enforced {@link WorkspaceOps}.
@@ -1735,23 +4457,35 @@ function makeWriteFileTool(ops, options) {
 const ALL_TOOL_NAMES = [
 	"readFile",
 	"editFile",
+	"multiEdit",
 	"writeFile",
+	"listDir",
 	"runShell",
+	"shellOutput",
+	"shellKill",
 	"runTests",
 	"grep",
-	"glob"
+	"glob",
+	"todoWrite",
+	"todoRead"
 ];
 /**
 * The subset a {@link Workspace.readonly} projection exposes — the
-* non-mutating tools only. `editFile` / `writeFile` / `runShell` /
-* `runTests` are deliberately omitted so a reviewer agent has no path to
-* change the tree.
+* tools that cannot change the tree. `editFile` / `multiEdit` /
+* `writeFile` / the shell tools / `runTests` are deliberately omitted so a
+* reviewer agent has no path to change it. The todo tools stay: they only
+* touch the in-memory plan.
 */
 const READONLY_TOOL_NAMES = [
 	"readFile",
+	"listDir",
 	"grep",
-	"glob"
+	"glob",
+	"todoWrite",
+	"todoRead"
 ];
+/** Tools vended only when the policy enables background commands. */
+const BACKGROUND_TOOL_NAMES = new Set(["shellOutput", "shellKill"]);
 /**
 * Choose the dumb IO executor for a policy. `"mock"` selects the
 * in-memory backend (hermetic tests); anything else — including the
@@ -1776,11 +4510,15 @@ function selectBackend(policy) {
 * Constructed via {@link workspace}; the class itself is internal.
 */
 var WorkspaceImpl = class WorkspaceImpl {
-	constructor(policy, allowedTools = ALL_TOOL_NAMES) {
+	constructor(policy, allowedTools = ALL_TOOL_NAMES, state) {
 		this.policy = policy;
 		this.allowedTools = new Set(allowedTools);
+		this.state = state ?? {
+			jobs: new ShellJobs(),
+			todos: new TodoStore()
+		};
 		const backend = selectBackend(policy);
-		this.ops = createOps(backend, policy);
+		this.ops = createOps(backend, policy, { jobs: this.state.jobs });
 		this.tools = this.buildTools();
 	}
 	/**
@@ -1792,26 +4530,49 @@ var WorkspaceImpl = class WorkspaceImpl {
 	*/
 	buildTools() {
 		const erase = (contract) => contract;
+		const shell = this.policy.shell;
+		const background = shell?.background !== void 0;
+		const interpreter = shell?.interpreter ?? "none";
 		const factories = {
 			readFile: (opts) => erase(makeReadFileTool(this.ops, opts)),
 			editFile: (opts) => erase(makeEditFileTool(this.ops, opts)),
+			multiEdit: (opts) => erase(makeMultiEditTool(this.ops, opts)),
 			writeFile: (opts) => erase(makeWriteFileTool(this.ops, opts)),
-			runShell: (opts) => erase(makeRunShellTool(this.ops, opts)),
-			runTests: (opts) => erase(makeRunTestsTool(this.ops, opts)),
+			listDir: (opts) => erase(makeListDirTool(this.ops, opts)),
+			runShell: (opts) => erase(makeRunShellTool(this.ops, {
+				...opts?.name !== void 0 ? { name: opts.name } : {},
+				...shell?.timeoutMs !== void 0 ? { maxTimeoutMs: shell.timeoutMs } : {},
+				background
+			})),
+			shellOutput: (opts) => erase(makeShellOutputTool(this.ops, opts)),
+			shellKill: (opts) => erase(makeShellKillTool(this.ops, opts)),
+			runTests: (opts) => erase(makeRunTestsTool(this.ops, {
+				...opts,
+				interpreter
+			})),
 			grep: (opts) => erase(makeGrepTool(this.ops, opts)),
-			glob: (opts) => erase(makeGlobTool(this.ops, opts))
+			glob: (opts) => erase(makeGlobTool(this.ops, opts)),
+			todoWrite: (opts) => erase(makeTodoWriteTool(this.state.todos, opts)),
+			todoRead: (opts) => erase(makeTodoReadTool(this.state.todos, opts))
 		};
 		const build = (name, opts) => factories[name](opts);
+		const vendedByAll = (name) => this.allowedTools.has(name) && (background || !BACKGROUND_TOOL_NAMES.has(name));
 		return {
-			all: () => ALL_TOOL_NAMES.filter((name) => this.allowedTools.has(name)).map((name) => build(name)),
+			all: () => ALL_TOOL_NAMES.filter(vendedByAll).map((name) => build(name)),
 			pick: (...names) => names.filter((name) => this.allowedTools.has(name)).map((name) => build(name)),
 			readFile: (opts) => build("readFile", opts),
 			editFile: (opts) => build("editFile", opts),
+			multiEdit: (opts) => build("multiEdit", opts),
 			writeFile: (opts) => build("writeFile", opts),
+			listDir: (opts) => build("listDir", opts),
 			runShell: (opts) => build("runShell", opts),
+			shellOutput: (opts) => build("shellOutput", opts),
+			shellKill: (opts) => build("shellKill", opts),
 			runTests: (opts) => build("runTests", opts),
 			grep: (opts) => build("grep", opts),
-			glob: (opts) => build("glob", opts)
+			glob: (opts) => build("glob", opts),
+			todoWrite: (opts) => build("todoWrite", opts),
+			todoRead: (opts) => build("todoRead", opts)
 		};
 	}
 	/**
@@ -1837,10 +4598,40 @@ var WorkspaceImpl = class WorkspaceImpl {
 		this.assertWritable("editFile");
 		return this.ops.editFile(input);
 	}
+	async multiEdit(input) {
+		this.assertWritable("multiEdit");
+		return this.ops.multiEdit(input);
+	}
+	listDir(dirPath, opts) {
+		return this.ops.listDir(dirPath, opts);
+	}
 	async exec(command, opts) {
 		this.assertWritable("exec");
 		return this.ops.exec(command, opts);
 	}
+	async startShell(command, opts) {
+		this.assertWritable("startShell");
+		return this.ops.startShell(command, opts);
+	}
+	shellOutput(id, opts) {
+		return this.ops.shellOutput(id, opts);
+	}
+	async shellKill(id) {
+		this.assertWritable("shellKill");
+		return this.ops.shellKill(id);
+	}
+	listShells() {
+		return this.ops.listShells();
+	}
+	readTodos() {
+		return this.state.todos.read();
+	}
+	writeTodos(todos) {
+		return this.state.todos.write(todos);
+	}
+	dispose() {
+		return this.ops.dispose();
+	}
 	grep(pattern, opts) {
 		return this.ops.grep(pattern, opts);
 	}
@@ -1859,44 +4650,49 @@ var WorkspaceImpl = class WorkspaceImpl {
 		return this.ops.remove(filePath);
 	}
 	/**
-	* A read-only projection over the SAME policy — only the read/grep/glob
-	* tools are vended and every mutating direct method rejects with a
-	* {@link WorkspacePolicyError}. A fresh ops/backend is built from the
-	* identical policy, so the projection sees the same jailed tree.
+	* A read-only projection over the SAME policy — only the read / list /
+	* grep / glob / todo tools are vended and every mutating direct method
+	* rejects with a {@link WorkspacePolicyError}. A fresh ops/backend is
+	* built from the identical policy, so the projection sees the same jailed
+	* tree; it shares this workspace's background commands and todo list.
 	*/
 	readonly() {
-		return new WorkspaceImpl(this.policy, READONLY_TOOL_NAMES);
+		return new WorkspaceImpl(this.policy, READONLY_TOOL_NAMES.filter((name) => this.allowedTools.has(name)), this.state);
 	}
 	/**
 	* A sub-jailed view rooted at `subdir` (relative to this workspace's
 	* `cwd`). Returns a brand-new workspace whose policy is this policy
 	* with `cwd` narrowed to `join(cwd, subdir)` — same backend selection,
-	* same allow/deny/shell/read sub-policies, but a tighter jail root.
+	* same allow/deny/shell/read sub-policies, but a tighter jail root. It
+	* shares this workspace's background commands and todo list.
 	*/
 	scope(subdir) {
 		return new WorkspaceImpl({
 			...this.policy,
 			cwd: node_path.default.join(this.policy.cwd, subdir)
-		}, [...this.allowedTools]);
+		}, [...this.allowedTools], this.state);
 	}
 };
 /**
 * Build a {@link Workspace} — the integrator that wires a
 * {@link WorkspacePolicy} to a backend, the shared policy-enforced ops
-* layer, and the seven agent-facing tool factories.
+* layer, and the agent-facing tool factories.
 *
 * The backend is chosen from `policy.backend`: `"mock"` runs in memory
 * (hermetic tests); the `"local"` default (and any absent value) runs
 * over the real disk via `@warlock.js/fs` + `node:child_process`. The
 * returned workspace exposes:
 *
-* - **`tools.*`** — `readFile` / `editFile` / `writeFile` / `runShell` /
-*   `runTests` / `grep` / `glob`, plus `all()` (every tool) and
-*   `pick(...)` (a least-privilege subset).
-* - **direct methods** — `readFile` / `writeFile` / `editFile` / `exec` /
-*   `grep` / `glob` / `exists` / `mkdir` / `remove`, each delegating 1:1
-*   to the shared ops layer.
-* - **`readonly()`** — a projection that vends only read/grep/glob and
+* - **`tools.*`** — `readFile` / `editFile` / `multiEdit` / `writeFile` /
+*   `listDir` / `runShell` / `shellOutput` / `shellKill` / `runTests` /
+*   `grep` / `glob` / `todoWrite` / `todoRead`, plus `all()` (every tool)
+*   and `pick(...)` (a least-privilege subset).
+* - **direct methods** — `readFile` / `writeFile` / `editFile` /
+*   `multiEdit` / `listDir` / `exec` / `startShell` / `shellOutput` /
+*   `shellKill` / `listShells` / `grep` / `glob` / `exists` / `mkdir` /
+*   `remove` / `readTodos` / `writeTodos`, each delegating to the shared
+*   ops layer, and `dispose()`.
+* - **`readonly()`** — a projection that vends only the read-side tools and
 *   rejects every mutating direct method.
 * - **`scope(subdir)`** — a sub-jailed workspace rooted at `subdir`.
 *
@@ -1921,9 +4717,13 @@ function workspace(policy) {
 _warlock_js_ai.ai.workspace = workspace;
 
 //#endregion
+exports.TodoStore = TodoStore;
 exports.WorkspaceEditError = WorkspaceEditError;
+exports.WorkspaceJobError = WorkspaceJobError;
 exports.WorkspacePolicyError = WorkspacePolicyError;
+exports.analyzeArgvCommand = analyzeArgvCommand;
 exports.buildEnv = buildEnv;
+exports.checkShellCommand = checkShellCommand;
 exports.createLocalBackend = createLocalBackend;
 exports.createMockBackend = createMockBackend;
 exports.createOps = createOps;
@@ -1931,10 +4731,17 @@ exports.isCommandAllowed = isCommandAllowed;
 exports.makeEditFileTool = makeEditFileTool;
 exports.makeGlobTool = makeGlobTool;
 exports.makeGrepTool = makeGrepTool;
+exports.makeListDirTool = makeListDirTool;
+exports.makeMultiEditTool = makeMultiEditTool;
 exports.makeReadFileTool = makeReadFileTool;
 exports.makeRunShellTool = makeRunShellTool;
 exports.makeRunTestsTool = makeRunTestsTool;
+exports.makeShellKillTool = makeShellKillTool;
+exports.makeShellOutputTool = makeShellOutputTool;
+exports.makeTodoReadTool = makeTodoReadTool;
+exports.makeTodoWriteTool = makeTodoWriteTool;
 exports.makeWriteFileTool = makeWriteFileTool;
 exports.resolveInJail = resolveInJail;
+exports.tokenizeCommand = tokenizeCommand;
 exports.workspace = workspace;
 //# sourceMappingURL=index.cjs.map