@warlock.js/ai-workspace 5.28.0 → 5.30.0

package/CHANGELOG.md

@@ -4,6 +4,36 @@ All notable changes to `@warlock.js/ai-workspace` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 5.30.0 - 2026-10-16
+
+### Upgrading
+
+- `RunShellResult.cancelled` is now a required field: a custom `WorkspaceOps`/`Workspace` implementation or a test double that builds a `RunShellResult` must set it (`false` unless the command was cancelled).
+- `Workspace.readFile()` and `WorkspaceOps.readFile()` now return `ReadFileResult` (adds `startLine`, `endLine`, `truncated`, `bytesCapped`, `totalBytes`); custom implementations must return those fields.
+- A read window that starts past the end of the file now returns empty `content` instead of one numbered empty line.
+- `read.maxBytes` now actually caps the returned `content`; a read that used to return a whole long file under a small cap now comes back cut, with `bytesCapped: true`.
+
+### Added
+
+- `exec()` takes a per-call `signal` (`ExecOptions`); `run_shell` and `run_tests` pass the agent run's `ctx.signal`. An already-aborted signal never starts the command; an abort mid-run kills the process tree. Both resolve with the new `cancelled: true` on `RunShellResult`, never together with `timedOut` (WR-010).
+- `WorkspaceBackendExecOptions.signal` and `WorkspaceBackendExecResult.cancelled?` for custom backends; the local backend removes its abort listener when the command settles, and the mock backend honours a pre-aborted signal.
+- Read results carry `startLine`, `endLine`, `truncated`, `bytesCapped` and `totalBytes`; `readFile()` and the `read_file` tool now return the same `ReadFileResult` for the same arguments.
+
+### Fixed
+
+- `read.maxBytes` is enforced: the returned `content` (line-number prefixes and newlines included) never exceeds it, so a single long line no longer bypasses the cap. Lines are cut on a character boundary, never mid-character; `hash` remains the SHA-256 of the whole file (WR-009).
+- Command output clipped at `shell.maxOutputBytes` is cut on a character boundary instead of ending in a replacement character.
+- A read window past the end of the file returns empty `content` instead of one numbered empty line.
+- Writes, edits and removes of the same path are serialized, so two concurrent `edit_file` calls (the agent now dispatches a trip's tool calls concurrently) can no longer both pass the stale-hash guard and silently drop one edit; the second re-reads and is rejected as stale, or applies on top when it pinned no hash.
+- Aborting a command after it has already exited (while its stdio is still draining) no longer reports it as `cancelled`; the tree is still reaped so the result settles.
+- On Windows, a `taskkill` that cannot be started no longer crashes the process with an unhandled `'error'` event; the direct child is killed instead.
+
+## 5.29.0 - 2026-10-01
+
+### Changed
+
+- Lockstep release; package APIs are unchanged. Skills refer to other topics by name instead of file paths, so cross-references keep working after `agent-kit` copies them into an app.
+
 ## 5.28.0 - 2026-10-01
 
 ### Changed

package/README.md

@@ -133,6 +133,12 @@ for (const file of await ws.glob("src/models/**/*.ts")) {
 - **Read-before-edit guard** — `read_file` returns a SHA-256 `hash`; `edit_file`
   requires an exact, unique `oldString` (or `replaceAll`) and rejects on an
   `expectHash` mismatch.
+- **Bounded reads** — `read.maxBytes` caps the UTF-8 bytes a read returns (line
+  numbers included), cutting on a character boundary and flagging `bytesCapped`;
+  the `hash` still covers the whole file.
+- **Cancellable commands** — `exec(cmd, { signal })`, and the agent run's signal
+  in `run_shell` / `run_tests`, stop the command (process tree killed, or never
+  started when already aborted) and report `cancelled: true`.
 
 **Deferred to later phases** (intentionally absent here): the transactional
 lifecycle (`snapshot` / `restore` / `diff` / `changes`), `on()` hooks, `dispose`,

package/cjs/index.cjs

@@ -34,7 +34,7 @@ let _warlock_js_fs = require("@warlock.js/fs");
 let node_child_process = require("node:child_process");
 let node_process = require("node:process");
 
-//#region ../ai-workspace/src/errors.ts
+//#region ../../packages/ai-workspace/src/errors.ts
 /**
 * The workspace policy engine refused an operation — a path escaped the
 * jail (or hit a deny glob), or a shell command's executable was not
@@ -89,7 +89,7 @@ var WorkspaceEditError = class extends _warlock_js_ai.AIError {
 };
 
 //#endregion
-//#region ../ai-workspace/src/policy/tokenize-command.ts
+//#region ../../packages/ai-workspace/src/policy/tokenize-command.ts
 /**
 * Characters that are refused when they appear UNQUOTED in a command line.
 * Workspace commands are executed as a direct argv spawn — never through a
@@ -165,7 +165,7 @@ function tokenizeCommand(command) {
 }
 
 //#endregion
-//#region ../ai-workspace/src/policy/policy.ts
+//#region ../../packages/ai-workspace/src/policy/policy.ts
 /**
 * Resolve the canonical absolute form of `target`, collapsing any
 * symlinks. `target` may not yet exist (a fresh `writeFile`/`mkdir`),
@@ -351,7 +351,7 @@ function buildEnv(policy) {
 }
 
 //#endregion
-//#region ../ai-workspace/src/ops.ts
+//#region ../../packages/ai-workspace/src/ops.ts
 /** Default line window a read returns when the policy sets no `defaultLines`. */
 const DEFAULT_READ_LINES = 2e3;
 /** Hard ceiling on grep matches returned, so a broad pattern can't flood. */
@@ -359,6 +359,12 @@ const DEFAULT_MAX_GREP_MATCHES = 1e3;
 /** Default per-command output byte cap when the policy sets none. */
 const DEFAULT_MAX_OUTPUT_BYTES = 1e6;
 /**
+* Exit code reported for a command refused because its signal was already
+* aborted (the shell convention for an interrupted command). Callers should
+* branch on `cancelled`, not on this number.
+*/
+const CANCELLED_BEFORE_START_EXIT_CODE = 130;
+/**
 * Hard ceiling on `grep` pattern length. A model-controlled regex has no
 * legitimate reason to be this long; longer patterns are rejected outright
 * rather than compiled.
@@ -372,33 +378,76 @@ const MAX_GREP_PATTERN_LENGTH = 200;
 * this are skipped rather than scanned.
 */
 const MAX_GREP_LINE_SCAN_LENGTH = 2e3;
-/**
-* Number the lines of `content` `cat -n` style: a right-aligned line
-* number (min width 6), a tab, then the line. `startLine` is the 1-based
-* number of the first line in the window.
-*/
-function numberLines(content, startLine) {
-	return content.split("\n").map((line, index) => {
-		const lineNumber = startLine + index;
-		return `${String(lineNumber).padStart(6, " ")}\t${line}`;
-	}).join("\n");
+/** The `cat -n` prefix for a line: right-aligned number (min width 6) and a tab. */
+function linePrefix(lineNumber) {
+	return `${String(lineNumber).padStart(6, " ")}\t`;
 }
 /**
-* Clip a captured stream at `maxBytes` (measured in UTF-8 bytes).
-* Returns the possibly-clipped string plus whether clipping occurred.
+* Clip `value` to at most `maxBytes` UTF-8 bytes without splitting a
+* character: the cut backs off over continuation bytes (`10xxxxxx`) to the
+* start of the character it would have split, so the result never carries
+* a replacement character.
 */
-function capOutput(value, maxBytes) {
+function clipUtf8(value, maxBytes) {
 	const bytes = Buffer.from(value, "utf8");
 	if (bytes.byteLength <= maxBytes) return {
 		value,
 		truncated: false
 	};
+	let cut = Math.max(0, maxBytes);
+	while (cut > 0 && ((bytes[cut] ?? 0) & 192) === 128) cut--;
 	return {
-		value: bytes.subarray(0, maxBytes).toString("utf8"),
+		value: bytes.subarray(0, cut).toString("utf8"),
 		truncated: true
 	};
 }
 /**
+* Number a window of lines `cat -n` style, keeping the joined output within
+* `maxBytes` UTF-8 bytes (prefixes and newlines included) when a cap is set.
+* A line that does not fit whole is clipped on a character boundary; it is
+* still counted as returned when its prefix and at least one character fit.
+*/
+function numberWindow(lines, startLine, maxBytes) {
+	const parts = [];
+	let used = 0;
+	for (let index = 0; index < lines.length; index++) {
+		const prefix = linePrefix(startLine + index);
+		const numbered = prefix + lines[index];
+		const separator = parts.length > 0 ? 1 : 0;
+		if (maxBytes === void 0) {
+			parts.push(numbered);
+			continue;
+		}
+		const cost = separator + Buffer.byteLength(numbered, "utf8");
+		if (used + cost <= maxBytes) {
+			parts.push(numbered);
+			used += cost;
+			continue;
+		}
+		const room = maxBytes - used - separator - Buffer.byteLength(prefix, "utf8");
+		const clipped = room > 0 ? clipUtf8(lines[index] ?? "", room).value : "";
+		if (clipped.length > 0) parts.push(prefix + clipped);
+		return {
+			content: parts.join("\n"),
+			returnedLines: parts.length,
+			bytesCapped: true
+		};
+	}
+	return {
+		content: parts.join("\n"),
+		returnedLines: parts.length,
+		bytesCapped: false
+	};
+}
+/**
+* Clip a captured stream at `maxBytes` (measured in UTF-8 bytes), on a
+* character boundary. Returns the possibly-clipped string plus whether
+* clipping occurred.
+*/
+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
@@ -457,6 +506,24 @@ var Ops = class {
 	constructor(backend, policy) {
 		this.backend = backend;
 		this.policy = policy;
+		this.pathLocks = /* @__PURE__ */ new Map();
+	}
+	/** Run `task` after every earlier mutation of `absolutePath` has settled. */
+	async withPathLock(absolutePath, task) {
+		const previous = this.pathLocks.get(absolutePath) ?? Promise.resolve();
+		let release = () => {};
+		const current = new Promise((resolve) => {
+			release = resolve;
+		});
+		const tail = previous.then(() => current);
+		this.pathLocks.set(absolutePath, tail);
+		try {
+			await previous;
+			return await task();
+		} finally {
+			release();
+			if (this.pathLocks.get(absolutePath) === tail) this.pathLocks.delete(absolutePath);
+		}
 	}
 	/**
 	* Recursively collect every file under `absDir` as absolute paths,
@@ -491,25 +558,39 @@ var Ops = class {
 		const totalLines = lines.length;
 		const offset = Math.max(1, opts?.offset ?? 1);
 		const limit = opts?.limit ?? this.policy.read?.defaultLines ?? DEFAULT_READ_LINES;
+		const maxBytes = this.policy.read?.maxBytes;
 		const startIndex = offset - 1;
+		const { content, returnedLines, bytesCapped } = numberWindow(lines.slice(startIndex, startIndex + Math.max(0, limit)), offset, maxBytes === void 0 ? void 0 : Math.max(0, Math.floor(maxBytes)));
+		const endLine = offset + returnedLines - 1;
 		return {
-			content: numberLines(lines.slice(startIndex, startIndex + limit).join("\n"), offset),
-			hash,
-			totalLines
+			content,
+			startLine: offset,
+			endLine,
+			totalLines,
+			truncated: bytesCapped || endLine < totalLines,
+			bytesCapped,
+			totalBytes: Buffer.byteLength(raw, "utf8"),
+			hash
 		};
 	}
 	async writeFile(inputPath, content) {
 		const { absolutePath } = await resolveInJail(this.policy, inputPath);
-		const parent = node_path.default.dirname(absolutePath);
-		await this.backend.mkdir(parent);
-		await this.backend.writeFile(absolutePath, content);
-		return {
-			hash: _warlock_js_fs.fs.hash.string(content),
-			bytesWritten: Buffer.byteLength(content, "utf8")
-		};
+		return this.withPathLock(absolutePath, async () => {
+			const parent = node_path.default.dirname(absolutePath);
+			await this.backend.mkdir(parent);
+			await this.backend.writeFile(absolutePath, content);
+			return {
+				hash: _warlock_js_fs.fs.hash.string(content),
+				bytesWritten: Buffer.byteLength(content, "utf8")
+			};
+		});
 	}
 	async editFile(input) {
 		const { absolutePath, relativePath } = await resolveInJail(this.policy, input.path);
+		return this.withPathLock(absolutePath, () => this.applyEdit(input, absolutePath, relativePath));
+	}
+	/** The read-check-replace-write of {@link editFile}, run under its path lock. */
+	async applyEdit(input, absolutePath, relativePath) {
 		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; the edit is stale.`, {
@@ -542,22 +623,34 @@ var Ops = class {
 			type: "denied-command",
 			command
 		});
+		const signal = opts?.signal;
+		if (signal?.aborted) return {
+			exitCode: CANCELLED_BEFORE_START_EXIT_CODE,
+			stdout: "",
+			stderr: "Command was not executed: the invocation was cancelled before it started.",
+			truncated: false,
+			timedOut: false,
+			cancelled: true
+		};
 		const shell = this.policy.shell;
 		const timeoutMs = opts?.timeoutMs ?? shell?.timeoutMs;
 		const maxOutputBytes = shell?.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
 		const result = await this.backend.exec(command, {
 			cwd: this.policy.cwd,
 			timeoutMs,
-			env: buildEnv(this.policy)
+			env: buildEnv(this.policy),
+			...signal ? { signal } : {}
 		});
 		const stdout = capOutput(result.stdout, maxOutputBytes);
 		const stderr = capOutput(result.stderr, maxOutputBytes);
+		const cancelled = result.cancelled === true;
 		return {
 			exitCode: result.exitCode,
 			stdout: stdout.value,
 			stderr: stderr.value,
 			truncated: stdout.truncated || stderr.truncated,
-			timedOut: result.timedOut
+			timedOut: result.timedOut && !cancelled,
+			cancelled
 		};
 	}
 	async grep(pattern, opts) {
@@ -625,7 +718,7 @@ var Ops = class {
 	}
 	async remove(inputPath) {
 		const { absolutePath } = await resolveInJail(this.policy, inputPath);
-		await this.backend.remove(absolutePath);
+		await this.withPathLock(absolutePath, () => this.backend.remove(absolutePath));
 	}
 	/** Whether a `/`-separated relative path hits the policy deny list. */
 	isDenied(relativePath) {
@@ -682,7 +775,7 @@ function createOps(backend, policy) {
 }
 
 //#endregion
-//#region ../ai-workspace/src/backends/local.ts
+//#region ../../packages/ai-workspace/src/backends/local.ts
 /**
 * Hard ceiling on captured `stdout`/`stderr` per stream, in bytes. The raw
 * executor truncates each stream once this many bytes have accumulated so a
@@ -729,7 +822,9 @@ function killTree(pid, child) {
 			String(pid),
 			"/T",
 			"/F"
-		], { windowsHide: true });
+		], { windowsHide: true }).on("error", () => {
+			child.kill("SIGKILL");
+		});
 		return;
 	}
 	try {
@@ -846,11 +941,13 @@ var LocalBackend = class {
 	* cannot be spawned shell-less) with every element individually quoted.
 	* `cwd`, `env`, and the timeout are taken verbatim from the ops layer
 	* (the environment is NOT merged with `process.env`). On timeout the
-	* process is SIGKILLed and `timedOut` is set. `stdout`/`stderr` are
-	* captured and byte-capped per {@link MAX_STREAM_BYTES}.
+	* process tree is SIGKILLed and `timedOut` is set. When `signal` aborts
+	* mid-run the process tree is SIGKILLed the same way and `cancelled` is
+	* set; an already-aborted `signal` resolves `cancelled` without spawning.
+	* `stdout`/`stderr` are captured and byte-capped per {@link MAX_STREAM_BYTES}.
 	*
 	* Never rejects for a non-zero exit, a missing executable, a refused
-	* command line, or a timeout — those are reported through the resolved
+	* command line, a timeout or a cancellation — those are reported through the resolved
 	* {@link WorkspaceBackendExecResult} so the ops layer can surface them
 	* as tool-error data.
 	*/
@@ -862,12 +959,24 @@ var LocalBackend = class {
 				stderr,
 				timedOut: false
 			});
+			const signal = opts.signal;
+			if (signal?.aborted) {
+				resolve({
+					exitCode: 130,
+					stdout: "",
+					stderr: "Command was not executed: the invocation was cancelled before it started.",
+					timedOut: false,
+					cancelled: true
+				});
+				return;
+			}
 			const argv = tokenizeCommand(command);
-			if (argv === null) {
+			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.");
 				return;
 			}
-			let file = argv[0];
+			let file = executable;
 			let args = argv.slice(1);
 			let windowsVerbatimArguments = false;
 			if (node_process.platform === "win32") {
@@ -893,20 +1002,31 @@ var LocalBackend = class {
 			let stdoutBytes = 0;
 			let stderrBytes = 0;
 			let timedOut = false;
+			let cancelled = false;
 			let settled = false;
+			let exited = false;
 			const timer = opts.timeoutMs !== void 0 && opts.timeoutMs > 0 ? setTimeout(() => {
+				if (cancelled) return;
 				timedOut = true;
 				killTree(child.pid, child);
 			}, opts.timeoutMs) : void 0;
+			const onAbort = () => {
+				if (settled || timedOut) return;
+				if (!exited) cancelled = true;
+				killTree(child.pid, child);
+			};
+			signal?.addEventListener("abort", onAbort, { once: true });
 			const settle = (exitCode) => {
 				if (settled) return;
 				settled = true;
 				if (timer !== void 0) clearTimeout(timer);
+				signal?.removeEventListener("abort", onAbort);
 				resolve({
 					exitCode,
 					stdout: Buffer.concat(stdoutChunks).toString("utf8"),
 					stderr: Buffer.concat(stderrChunks).toString("utf8"),
-					timedOut
+					timedOut,
+					cancelled
 				});
 			};
 			child.stdout?.on("data", (chunk) => {
@@ -918,6 +1038,9 @@ var LocalBackend = class {
 			child.on("error", () => {
 				settle(127);
 			});
+			child.on("exit", () => {
+				exited = true;
+			});
 			child.on("close", (code, signal) => {
 				if (code === null) {
 					settle(128 + (signal === "SIGKILL" ? 9 : 1));
@@ -948,7 +1071,7 @@ function createLocalBackend() {
 }
 
 //#endregion
-//#region ../ai-workspace/src/backends/mock.ts
+//#region ../../packages/ai-workspace/src/backends/mock.ts
 /**
 * Normalize an absolute path to a stable in-memory key: forward slashes,
 * collapsed duplicate separators, and resolved `.` / `..` segments. There
@@ -1048,13 +1171,21 @@ var MockBackend = class {
 	async realpath(absPath) {
 		return canonicalize(absPath);
 	}
-	async exec(command, _opts) {
+	async exec(command, opts) {
+		if (opts?.signal?.aborted) return {
+			exitCode: 130,
+			stdout: "",
+			stderr: "",
+			timedOut: false,
+			cancelled: true
+		};
 		const scripted = this.commands.get(command);
 		return {
 			exitCode: scripted?.exitCode ?? 0,
 			stdout: scripted?.stdout ?? "",
 			stderr: scripted?.stderr ?? "",
-			timedOut: scripted?.timedOut ?? false
+			timedOut: scripted?.timedOut ?? false,
+			cancelled: scripted?.cancelled ?? false
 		};
 	}
 };
@@ -1113,7 +1244,7 @@ function isMockBackendSeed(seed) {
 }
 
 //#endregion
-//#region ../ai-workspace/src/tools/schema.ts
+//#region ../../packages/ai-workspace/src/tools/schema.ts
 /**
 * Tiny, dependency-free [Standard Schema](https://standardschema.dev)
 * builders for the workspace tools' input validation. The package pins
@@ -1222,7 +1353,7 @@ function objectSchema(shape) {
 }
 
 //#endregion
-//#region ../ai-workspace/src/tools/edit-file.ts
+//#region ../../packages/ai-workspace/src/tools/edit-file.ts
 /** Default tool name exposed to the LLM. */
 const DEFAULT_NAME$2 = "edit_file";
 /** Input schema for the `edit_file` tool. */
@@ -1274,7 +1405,7 @@ function makeEditFileTool(ops, options) {
 }
 
 //#endregion
-//#region ../ai-workspace/src/tools/glob.ts
+//#region ../../packages/ai-workspace/src/tools/glob.ts
 /**
 * Standard Schema for {@link GlobInput} — a single required `pattern`
 * string. Built on the package's shared, dependency-free schema builders
@@ -1314,7 +1445,7 @@ function makeGlobTool(ops, options) {
 }
 
 //#endregion
-//#region ../ai-workspace/src/tools/grep.ts
+//#region ../../packages/ai-workspace/src/tools/grep.ts
 /**
 * Standard Schema for {@link GrepInput} — `pattern` is a required string;
 * `glob` and `ignoreCase` are optional. Built on the package's shared,
@@ -1360,7 +1491,7 @@ function makeGrepTool(ops, options) {
 }
 
 //#endregion
-//#region ../ai-workspace/src/tools/read-file.ts
+//#region ../../packages/ai-workspace/src/tools/read-file.ts
 /** Default tool name exposed to the LLM. */
 const DEFAULT_NAME$1 = "read_file";
 /** Input schema for the `read_file` tool. */
@@ -1375,10 +1506,10 @@ const inputSchema$1 = objectSchema({
 *
 * The tool validates `{ path, startLine?, limit? }` against a Standard
 * Schema, then delegates to `ops.readFile`, mapping the result into the
-* agent wire shape {@link ReadFileResult} — the `hash` an agent must
-* carry into a later `edit_file` (read-before-edit), plus the `startLine`
-* / `endLine` / `truncated` window metadata derived from the requested
-* range and the file's `totalLines`.
+* agent wire shape {@link ReadFileResult} — the full file's `hash` an
+* agent must carry into a later `edit_file` (read-before-edit), plus the
+* `startLine` / `endLine` / `truncated` / `bytesCapped` window metadata.
+* The returned `content` never exceeds the policy's `read.maxBytes`.
 *
 * **Errors flow as data.** Policy violations (a jail escape) are thrown
 * by `ops`; the `tool()` wrapper catches them and surfaces them in the
@@ -1396,30 +1527,19 @@ const inputSchema$1 = objectSchema({
 function makeReadFileTool(ops, options) {
 	return (0, _warlock_js_ai.tool)({
 		name: options?.name ?? DEFAULT_NAME$1,
-		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.",
+		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,
 		async execute(input) {
-			const startLine = input.startLine !== void 0 ? Math.max(1, input.startLine) : 1;
-			const { content, hash, totalLines } = await ops.readFile(input.path, {
-				offset: startLine,
+			return ops.readFile(input.path, {
+				offset: input.startLine !== void 0 ? Math.max(1, input.startLine) : 1,
 				limit: input.limit
 			});
-			const returnedLines = content.length === 0 ? 0 : content.split("\n").length;
-			const endLine = Math.min(totalLines, startLine + Math.max(returnedLines, 1) - 1);
-			return {
-				content,
-				startLine,
-				endLine,
-				totalLines,
-				truncated: endLine < totalLines,
-				hash
-			};
 		}
 	});
 }
 
 //#endregion
-//#region ../ai-workspace/src/tools/run-shell.ts
+//#region ../../packages/ai-workspace/src/tools/run-shell.ts
 /** The default tool name `run_shell` is exposed to the LLM under. */
 const DEFAULT_RUN_SHELL_TOOL_NAME = "run_shell";
 /**
@@ -1460,6 +1580,10 @@ const runShellInputSchema = { "~standard": {
 * 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.
 *
@@ -1475,12 +1599,15 @@ function makeRunShellTool(ops, options) {
 		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.",
 		action: (input) => `Running \`${input.command}\``,
 		input: runShellInputSchema,
-		execute: (input) => ops.exec(input.command, { timeoutMs: input.timeoutMs })
+		execute: (input, ctx) => ops.exec(input.command, {
+			timeoutMs: input.timeoutMs,
+			...ctx?.signal ? { signal: ctx.signal } : {}
+		})
 	});
 }
 
 //#endregion
-//#region ../ai-workspace/src/tools/run-tests.ts
+//#region ../../packages/ai-workspace/src/tools/run-tests.ts
 /** The default tool name `run_tests` is exposed to the LLM under. */
 const DEFAULT_RUN_TESTS_TOOL_NAME = "run_tests";
 /** The default command run when no `command` override is configured. */
@@ -1527,7 +1654,8 @@ const runTestsInputSchema = { "~standard": {
 * data, never a second command. Like `run_shell`, the resolved command's
 * executable is gated by the shell policy — a denial surfaces in the
 * result's `error` field — and a non-zero exit (failing tests) comes back
-* as `data` for the agent to read and fix.
+* as `data` for the agent to read and fix. The agent run's cancellation
+* `signal` is threaded per invocation, exactly as for `run_shell`.
 *
 * @param ops - The policy-enforced operation layer to delegate `exec` to.
 * @param options - Optional tool-name and base-command overrides.
@@ -1544,15 +1672,15 @@ function makeRunTestsTool(ops, options) {
 		description: "Run the workspace's test suite, optionally narrowed to a path or name pattern forwarded to the test runner. Failing tests return a non-zero exit code as data, not an error.",
 		action: (input) => input.pattern ? `Running tests matching "${input.pattern}"` : "Running tests",
 		input: runTestsInputSchema,
-		execute: (input) => {
+		execute: (input, ctx) => {
 			const command = input.pattern ? `${baseCommand} "${input.pattern}"` : baseCommand;
-			return ops.exec(command);
+			return ops.exec(command, ctx?.signal ? { signal: ctx.signal } : void 0);
 		}
 	});
 }
 
 //#endregion
-//#region ../ai-workspace/src/tools/write-file.ts
+//#region ../../packages/ai-workspace/src/tools/write-file.ts
 /** Default tool name exposed to the LLM. */
 const DEFAULT_NAME = "write_file";
 /** Input schema for the `write_file` tool. */
@@ -1599,7 +1727,7 @@ function makeWriteFileTool(ops, options) {
 }
 
 //#endregion
-//#region ../ai-workspace/src/workspace.ts
+//#region ../../packages/ai-workspace/src/workspace.ts
 /**
 * The full set of tool names a writable workspace vends, in a stable
 * canonical order so `tools.all()` is deterministic.