@warlock.js/ai-workspace 5.30.0 → 5.32.0

package/llms-full.txt

@@ -8,7 +8,7 @@
 
 ---
 name: build-loop-agent
-description: 'Wire a @warlock.js/ai-workspace into a coding agent that closes the read → edit → run-tests loop on its own. Triggers: `ws.tools.all()`, `ai.agent({ tools: ws.tools.all() })`, `maxTrips`, `run_tests`, `run_shell`, ''agent that fixes a failing test'', ''make the suite green'', ''coding agent that edits a repo'', ''build-loop agent'', ''self-correcting agent'', ''read-only code reviewer'', ''scaffold then hand off to an agent'', ''share one workspace across a supervisor'', ''least-privilege agent tools'', ''errors as tool data''; typical wiring `const ws = ai.workspace({ cwd, shell }); ai.agent({ model, tools: ws.tools.all(), maxTrips })`. Skip: constructing the workspace / its policy / direct methods / readonly / scope — the `use-a-workspace` topic; the agent loop / maxTrips / events themselves — the `run-ai-agent` topic of the `warlock-js-ai` skill.'
+description: "Wire a @warlock.js/ai-workspace into a coding agent that closes the read → edit → run-tests loop on its own. Triggers: `ws.tools.all()`, `ai.agent({ tools: ws.tools.all() })`, `maxTrips`, `run_tests`, `run_shell`, 'agent that fixes a failing test', 'make the suite green', 'coding agent that edits a repo', 'build-loop agent', 'self-correcting agent', 'read-only code reviewer', 'scaffold then hand off to an agent', 'share one workspace across a supervisor', 'least-privilege agent tools', 'errors as tool data'; typical wiring `const ws = ai.workspace({ cwd, shell }); ai.agent({ model, tools: ws.tools.all(), maxTrips })`. Skip: constructing the workspace / its policy / direct methods / readonly / scope — the `use-a-workspace` topic; the agent loop / maxTrips / events themselves — the `run-ai-agent` topic of the `warlock-js-ai` skill."
 ---
 
 # Build a build-loop agent — read → edit → run tests, until green
@@ -27,8 +27,8 @@ const ws = ai.workspace({
 
 const dev = ai.agent({
   model,
-  tools: ws.tools.all(),   // read_file, edit_file, write_file, run_shell, run_tests, grep, glob
-  maxTrips: 25,            // give the loop room to iterate
+  tools: ws.tools.all(), // read/edit/multi_edit/write, list_dir, run_shell, run_tests, grep, glob, todo_write/todo_read
+  maxTrips: 25, // give the loop room to iterate
 });
 
 await dev.execute("`npm test` fails on the cart-total suite. Make it green.");
@@ -51,7 +51,7 @@ Override the base command per agent: `ws.tools.runTests({ command: "vitest run"
 
 ### A read-only reviewer
 
-A reviewer should never write or run a shell. Pick exactly the read tools, or hand it a `readonly()` projection (which omits the mutating tools *and* rejects the mutating direct methods):
+A reviewer should never write or run a shell. Pick exactly the read tools, or hand it a `readonly()` projection (which omits the mutating tools _and_ rejects the mutating direct methods):
 
 ```ts
 const reviewer = ai.agent({
@@ -61,7 +61,7 @@ const reviewer = ai.agent({
 await reviewer.execute("Review src/cart for off-by-one bugs and summarize.");
 
 // Equivalent projection of the same jail:
-ai.agent({ model, tools: ws.readonly().tools.all() }); // read_file + grep + glob only
+ai.agent({ model, tools: ws.readonly().tools.all() }); // read_file, list_dir, grep, glob, todo tools
 ```
 
 ### Scope an agent to one package
@@ -69,8 +69,8 @@ ai.agent({ model, tools: ws.readonly().tools.all() }); // read_file + grep + glo
 `scope(subdir)` narrows the jail so a per-package agent can't reach outside it — one sub-agent per package, isolated blast radius:
 
 ```ts
-const apiDev  = ai.agent({ model, tools: ws.scope("packages/api").tools.all() });
-const webDev  = ai.agent({ model, tools: ws.scope("packages/web").tools.all() });
+const apiDev = ai.agent({ model, tools: ws.scope("packages/api").tools.all() });
+const webDev = ai.agent({ model, tools: ws.scope("packages/web").tools.all() });
 ```
 
 ## Scaffold from code, then hand off
@@ -112,7 +112,7 @@ ai.supervisor({
 
 ---
 name: use-a-workspace
-description: 'Build and operate a policy-jailed filesystem + shell workspace with @warlock.js/ai-workspace. Triggers: `ai.workspace`, `workspace(`, `WorkspacePolicy`, `WorkspaceShellPolicy`, `WorkspaceToolName`, `ws.tools.all`, `ws.tools.pick`, `ws.readFile`, `ws.writeFile`, `ws.editFile`, `ws.exec`, `ws.grep`, `ws.glob`, `ws.readonly`, `ws.scope`, `WorkspacePolicyError`, `WorkspaceEditError`, `denyPaths`, `inheritEnv`, `expectHash`, `read.maxBytes`, `bytesCapped`, `cancelled`, `ExecOptions`, `tokenizeCommand`, `read_file`/`edit_file`/`write_file`/`run_shell`/`run_tests`/`grep`; ''give an agent file tools'', ''jail an agent to a directory'', ''let an agent read/write/grep a repo'', ''read-only workspace for a reviewer'', ''scope an agent to a subdirectory'', ''run a shell command under policy'', ''edit a file with a stale-hash guard'', ''command injection guard for an agent shell tool'', ''ReDoS-safe grep for an agent'', ''cap how many bytes a read returns'', ''cancel a running workspace command''; typical import `import "@warlock.js/ai-workspace"; import { ai } from "@warlock.js/ai"`. Skip: building the agent loop that consumes the tools — the `build-loop-agent` topic; defining a non-filesystem custom tool — the `define-ai-tool` topic of the `warlock-js-ai` skill.'
+description: 'Build and operate a policy-jailed filesystem + shell workspace with @warlock.js/ai-workspace. Triggers: `ai.workspace`, `workspace(`, `WorkspacePolicy`, `WorkspaceShellPolicy`, `WorkspaceToolName`, `ws.tools.all`, `ws.tools.pick`, `ws.readFile`, `ws.writeFile`, `ws.editFile`, `ws.exec`, `ws.grep`, `ws.glob`, `ws.readonly`, `ws.scope`, `ws.multiEdit`, `ws.listDir`, `ws.startShell`, `ws.shellOutput`, `ws.shellKill`, `ws.dispose`, `ws.readTodos`, `ws.writeTodos`, `WorkspacePolicyError`, `WorkspaceEditError`, `WorkspaceJobError`, `WorkspaceShellRefusalReason`, `checkShellCommand`, `denyPaths`, `denyPatterns`, `allowCommand`, `interpreter`, `shell.background`, `list.ignore`, `inheritEnv`, `expectHash`, `read.maxBytes`, `bytesCapped`, `cancelled`, `ExecOptions`, `tokenizeCommand`, `read_file`/`edit_file`/`multi_edit`/`write_file`/`list_dir`/`run_shell`/`shell_output`/`shell_kill`/`run_tests`/`grep`/`todo_write`/`todo_read`; ''give an agent file tools'', ''jail an agent to a directory'', ''let an agent read/write/grep a repo'', ''read-only workspace for a reviewer'', ''scope an agent to a subdirectory'', ''run a shell command under policy'', ''edit a file with a stale-hash guard'', ''command injection guard for an agent shell tool'', ''ReDoS-safe grep for an agent'', ''cap how many bytes a read returns'', ''cancel a running workspace command'', ''let the agent use pipes and &&'', ''why was my shell command refused'', ''deny git push --force'', ''run a dev server in the background'', ''atomic multi-edit'', ''list a directory for an agent'', ''todo list tool for an agent''; typical import `import "@warlock.js/ai-workspace"; import { ai } from "@warlock.js/ai"`. Skip: building the agent loop that consumes the tools — the `build-loop-agent` topic; defining a non-filesystem custom tool — the `define-ai-tool` topic of the `warlock-js-ai` skill.'
 ---
 
 # Use a workspace — a policy jail for an agent's filesystem + shell
@@ -134,21 +134,29 @@ const ws = ai.workspace({
 
 ## A policy jail, NOT OS isolation
 
-This is least-privilege guardrails for a **trusted** agent — not a sandbox around hostile code. It enforces a `realpath`-resolved `cwd` jail, path allow/deny, a fail-closed shell allow/deny list, timeouts, output caps, and a non-inherited environment. It does **not** contain what an *allowed* process does once it runs. Real isolation (container / microVM) is a later phase.
+This is least-privilege guardrails for a **trusted** agent — not a sandbox around hostile code. It enforces a `realpath`-resolved `cwd` jail, path allow/deny, a fail-closed shell allow/deny list, timeouts, output caps, and a non-inherited environment. It does **not** contain what an _allowed_ process does once it runs.
+
+Paths are resolved against `cwd` with symlinks collapsed and accepted inside `cwd` or an `allowPaths` root, off `denyPaths`; absolute paths inside the jail, links that stay inside and not-yet-existing paths (for writes) are accepted. To read a folder you do not trust from app code (no links at all, size and entry caps), use `fs.confined(root)` from `@warlock.js/fs` (the `read-a-folder-confined` topic) instead of a workspace.
+
+**Shell mode (`interpreter: "sh"`) is a policy layer (defence in depth), not an OS sandbox.** It parses the line before `/bin/sh` runs it and refuses what it cannot read, but `/bin/sh` differs between systems (bash, dash, busybox ash), an allowed program (`node`, `npm`, `make`, a git hook) can still start anything the OS user can, and a symlink can change between the jail re-check and the write. For an untrusted agent (one that reads untrusted repos, issues, web pages or tool output), run the workspace in a container or microVM with only the project mounted, or at least as a separate unprivileged user, and keep the policy as a second layer. Prefer argv mode (the default) when the agent does not need pipes or redirections.
 
 ## The policy surface
 
-| Field | What it does |
-|---|---|
-| `cwd` | **Absolute** jail root. Every path resolves against it and must stay inside. |
-| `allowPaths` | Extra readable roots outside `cwd`. |
-| `denyPaths` | Globs (`*`, `**`, `?`) blocked **even inside `cwd`** — e.g. `[".git/**", ".env*"]`. A bare dir name (`"node_modules"`) also blocks its contents. |
-| `shell.allow` / `shell.deny` | Executable **basenames** matched against the command's leading argv token (after tokenizing — see below). **Deny wins.** An `allow` list is exhaustive (fail-closed); no `shell` block at all ⇒ nothing may run. |
-| `shell.inheritEnv` | Opt-in `process.env` keys to pass through (e.g. `["PATH"]`). **Nothing leaks in otherwise** — a command can't find `node`/`npm` without `PATH`. |
-| `shell.env` | Explicit env vars injected into every spawned process (override inherited on collision). |
-| `shell.timeoutMs` / `shell.maxOutputBytes` | Per-command wall-clock cap (process tree SIGKILLed on expiry) and stdout/stderr byte cap (clipped on a character boundary). |
-| `read.defaultLines` / `read.maxBytes` | Default read window + a ceiling on the UTF-8 bytes of the returned `content` (line numbers included). See [Read windows and the byte ceiling](#read-windows-and-the-byte-ceiling). |
-| `backend` | `"local"` (default — real disk) or `"mock"` (in-memory, for tests). |
+| Field                                               | What it does                                                                                                                                                                                                             |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `cwd`                                               | **Absolute** jail root. Every path resolves against it and must stay inside.                                                                                                                                             |
+| `allowPaths`                                        | Extra readable roots outside `cwd`.                                                                                                                                                                                      |
+| `denyPaths`                                         | Globs (`*`, `**`, `?`) blocked **even inside `cwd`** — e.g. `[".git/**", ".env*"]`. A bare dir name (`"node_modules"`) also blocks its contents.                                                                         |
+| `shell.allow` / `shell.deny`                        | Executable **basenames** matched against every command's argv (after tokenizing — see below). **Deny wins**, case-insensitively. An `allow` list is exhaustive (fail-closed); no `shell` block at all ⇒ nothing may run. |
+| `shell.denyPatterns` / `shell.allowCommand`         | Argument rules on every command: string prefix patterns (`"git push --force"`) or RegExps, and a predicate `(argv, ctx) => true \| false \| "why"`.                                                                      |
+| `shell.interpreter`                                 | `"none"` (default, argv) or `"sh"` (opt-in shell syntax, every command checked).                                                                                                                                         |
+| `shell.background`                                  | `{ maxJobs?, timeoutMs? }` — enables background commands. Absent ⇒ refused.                                                                                                                                              |
+| `list.ignore` / `list.maxDepth` / `list.maxEntries` | `list_dir` bounds: hidden globs (default `node_modules`, `.git`), depth cap (5), entry cap (500).                                                                                                                        |
+| `shell.inheritEnv`                                  | Opt-in `process.env` keys to pass through (e.g. `["PATH"]`). **Nothing leaks in otherwise** — a command can't find `node`/`npm` without `PATH`.                                                                          |
+| `shell.env`                                         | Explicit env vars injected into every spawned process (override inherited on collision).                                                                                                                                 |
+| `shell.timeoutMs` / `shell.maxOutputBytes`          | Per-command wall-clock cap (process tree SIGKILLed on expiry) and stdout/stderr byte cap (clipped on a character boundary).                                                                                              |
+| `read.defaultLines` / `read.maxBytes`               | Default read window + a ceiling on the UTF-8 bytes of the returned `content` (line numbers included). See [Read windows and the byte ceiling](#read-windows-and-the-byte-ceiling).                                       |
+| `backend`                                           | `"local"` (default — real disk) or `"mock"` (in-memory, for tests).                                                                                                                                                      |
 
 > **The most common gotcha:** `run_shell` fails to find `node`/`npm` because the env is empty. Add `shell: { allow: ["npm", "node"], inheritEnv: ["PATH"] }`.
 
@@ -157,27 +165,64 @@ This is least-privilege guardrails for a **trusted** agent — not a sandbox aro
 Commands are tokenized (via `tokenizeCommand`) into an argv and spawned with **no shell semantics** — no pipes, redirection, chaining, backticks, or variable expansion. `npm test && rm -rf /` or `` `curl evil` `` doesn't chain or substitute; it's rejected outright rather than executed piecemeal:
 
 ```ts
-await ws.exec("npm test");                    // OK — ["npm", "test"]
-await ws.exec('node -e "console.log(1)"');     // OK — quotes respected, one argv element
-await ws.exec("npm test; curl http://evil");   // rejected — unquoted `;` is a metacharacter
+await ws.exec("npm test"); // OK — ["npm", "test"]
+await ws.exec('node -e "console.log(1)"'); // OK — quotes respected, one argv element
+await ws.exec("npm test; curl http://evil"); // rejected — unquoted `;` is a metacharacter
 ```
 
 - **Quoting is respected**; **unquoted** shell metacharacters — `;` `&` `|` `<` `>` `` ` `` `$` `(` `)` and newlines — are rejected as a `WorkspacePolicyError` `type: "denied-command"` before anything spawns. The `shell.allow`/`shell.deny` basename check runs against the tokenized argv's first element, not a raw string prefix, so a disguised leading token can't slip past the gate.
 - **On Windows**, the argv is run through a `cmd.exe /d /s /c` wrapper with every element individually quoted (needed because batch shims like `npm.cmd` can't be spawned shell-less); arguments containing `"`, `%`, or newlines are refused there rather than risked (guards the BatBadBut-class argument-smuggling bug class).
 - **`run_tests`'s `pattern`** (model-controlled test-name filter) is forwarded as a **single double-quoted argv token** to the runner, not concatenated into the command string — a pattern containing double quotes or newlines is rejected at input validation rather than passed through.
-- This is a **behavior change, not just a hardening detail**: shell conveniences your commands may have relied on (pipes, redirection, `&&` chaining, `$(...)` substitution) no longer work in `run_shell`/`exec`. Compose multi-step work as separate `ws.exec()` calls instead of a single shelled pipeline.
+- Shell conveniences (pipes, redirection, `&&` chaining, `$(...)` substitution) don't work in argv mode. The refusal (`reason: "metacharacter"`) names the operator and suggests the split — e.g. "`&&` is not supported in argv mode: run `git add -A`, then `git commit -m "wip"`, as separate commands." — so the model retries correctly.
+- **Wrappers are followed**: `env`, `time`, `timeout`, `nice`, `nohup`, `command`, `builtin`, `exec`, `find -exec` — the inner command is checked too. Runners the policy can't see into (`sh -c`, `bash`, `eval`, `source`, `xargs`, `sudo`, `setsid`, …) are refused with `reason: "nested-command"` while deny rules are in force, unless `allow` names them.
+
+## Argument rules and shell mode
+
+```ts
+import { workspace, WorkspacePolicyError } from "@warlock.js/ai-workspace";
+
+export async function commitWork(cwd: string) {
+  const ws = workspace({
+    cwd,
+    shell: {
+      interpreter: "sh", // opt in: pipes, &&, redirections — every command still checked
+      allow: ["git", "npm", "grep"],
+      denyPatterns: ["git push --force", /^git reset --hard\b/],
+      allowCommand: (argv) => (argv[0] === "git" && argv[1] === "push" ? "CI pushes." : true),
+      inheritEnv: ["PATH"],
+      timeoutMs: 120_000,
+    },
+  });
+
+  try {
+    await ws.exec("git add -A && git commit -m 'wip'");
+    return await ws.exec("npm test 2>&1 | grep -i fail > logs/failures.txt");
+  } catch (error) {
+    if (error instanceof WorkspacePolicyError && error.type === "denied-command") {
+      console.warn(error.reason, error.message); // e.g. "denied-pattern", "path-escape"
+    }
+
+    throw error;
+  }
+}
+```
+
+- Shell mode parses the line and checks every simple command — inside `;`, `&&`, `||`, pipes, `( )`, `$( )`, backticks, here-documents and `NAME=value cmd` prefixes. Redirection targets and `cd` directories must be literal paths inside the jail (`/dev/null` is fine), re-checked with symlinks resolved.
+- It refuses what it can't parse with confidence (`reason: "unsupported-syntax"`): compound commands, arithmetic, brace expansion, unusual `${…}` forms, bash-only redirections, a command name decided at run time, `&` in a line (use `background: true`), assignments to `IFS`/`PS4`/`CDPATH`/`BASH_ENV`…; it drops shell start-up variables (`ENV`, `BASH_ENV`, `SHELLOPTS`, `BASH_FUNC_*`, …) from the environment.
+- `reason` values: `"metacharacter"`, `"unbalanced-quotes"`, `"denied-executable"`, `"not-allowed"`, `"denied-pattern"`, `"nested-command"`, `"unsupported-syntax"`, `"path-escape"`. `checkShellCommand(policy, line)` returns the verdict without running anything.
+- Pair shell mode with an exhaustive `allow`: `deny` alone is a best-effort filter.
 
 ## Two callers, one jail
 
 ### Agent-facing — `ws.tools.*`
 
-Each tool is a `ToolContract` ready for `ai.agent({ tools })`. The seven LLM-visible tool names are `read_file`, `edit_file`, `write_file`, `run_shell`, `run_tests`, `grep`, `glob`.
+Each tool is a `ToolContract` (with a JSON Schema of its input) ready for `ai.agent({ tools })`. The LLM-visible tool names are `read_file`, `edit_file`, `multi_edit`, `write_file`, `list_dir`, `run_shell`, `shell_output`, `shell_kill`, `run_tests`, `grep`, `glob`, `todo_write`, `todo_read` — `shell_output` / `shell_kill` only in `all()` when `shell.background` is set.
 
 ```ts
-ws.tools.all();                              // all seven, canonical order
-ws.tools.pick("readFile", "grep", "glob");   // a least-privilege subset
-ws.tools.readFile({ name: "open" });          // one tool, optionally renamed
-ws.tools.runTests({ command: "vitest run" });  // override the test base command
+ws.tools.all(); // every tool, canonical order
+ws.tools.pick("readFile", "grep", "glob"); // a least-privilege subset
+ws.tools.readFile({ name: "open" }); // one tool, optionally renamed
+ws.tools.runTests({ command: "vitest run" }); // override the test base command
 ```
 
 ### Human-facing — direct methods
@@ -185,7 +230,10 @@ ws.tools.runTests({ command: "vitest run" });  // override the test base command
 The same policy seam, callable from code (no LLM):
 
 ```ts
-const { content, hash, totalLines, endLine, truncated, bytesCapped } = await ws.readFile("src/index.ts", { offset: 1, limit: 200 });
+const { content, hash, totalLines, endLine, truncated, bytesCapped } = await ws.readFile(
+  "src/index.ts",
+  { offset: 1, limit: 200 },
+);
 await ws.writeFile("src/new.ts", "export const x = 1;\n");
 await ws.editFile({ path: "src/index.ts", oldString: "old", newString: "new", expectHash: hash });
 const { exitCode, stdout, stderr, timedOut, cancelled, truncated } = await ws.exec("npm test");
@@ -196,6 +244,51 @@ await ws.mkdir("src/generated");
 await ws.remove("dist");
 ```
 
+## The coding-agent tool belt
+
+```ts
+import { workspace } from "@warlock.js/ai-workspace";
+
+export async function devLoop(cwd: string) {
+  const ws = workspace({
+    cwd,
+    list: { maxEntries: 300 },
+    shell: { allow: ["npm", "node"], inheritEnv: ["PATH"], background: { maxJobs: 2 } },
+  });
+
+  try {
+    const { entries } = await ws.listDir("src", { depth: 2 }); // bounded, jailed, node_modules/.git hidden
+    console.info(entries.map((entry) => `${entry.type} ${entry.path}`));
+
+    const { hash } = await ws.readFile("src/cart.ts");
+    await ws.multiEdit({
+      path: "src/cart.ts",
+      expectHash: hash,
+      edits: [
+        { oldString: "let total = 0;", newString: "let total = 0n;" },
+        { oldString: "total += price;", newString: "total += BigInt(price);" },
+      ], // all apply, or none (WorkspaceEditError.editIndex names the failing one)
+    });
+
+    const server = await ws.startShell("npm run dev"); // run_shell({ command, background: true })
+    const { stdout, cursor } = await ws.shellOutput(server.id, { waitMs: 5_000 });
+    console.info(stdout, cursor); // pass `since: cursor` to read only what comes next
+    await ws.shellKill(server.id); // kills the whole process tree
+
+    ws.writeTodos([{ content: "Fix the rounding bug", status: "completed" }]); // todo_write
+    return ws.readTodos().counts; // todo_read
+  } finally {
+    await ws.dispose(); // kills every background command; the workspace refuses new commands
+  }
+}
+```
+
+- `list_dir({ path?, depth?, ignore? })` → `{ path, entries: [{ path, type, size?, depth }], truncated }`; `denyPaths` always hidden, `list.ignore` (default `node_modules`, `.git`) hidden from listings, symlinks reported but never followed.
+- `multi_edit({ path, edits, expectHash? })` → `{ path, edits, replacements, hash }`; same uniqueness rules as `edit_file`, at most 100 edits.
+- Background: `shell_output({ id, since?, waitMs? })` → `{ stdout, stderr, cursor, droppedBytes, truncated, status, exitCode }`; only the newest `shell.maxOutputBytes` per command are kept. States `"running"`, `"exited"`, `"killed"`, `"timed-out"`. Unknown id → `WorkspaceJobError`. Background commands outlive the agent run; `dispose()` (or process exit) kills them. Only processes the workspace spawned are ever signalled.
+- Todos: one in-memory list per workspace, shared with `readonly()` / `scope()`; `todo_write` replaces the whole list (≤ 100 items, status `pending` / `in_progress` / `completed`).
+- `run_shell`'s model-supplied `timeoutMs` can only lower `shell.timeoutMs`.
+
 ## `grep` is ReDoS-bounded
 
 The model supplies `pattern` freely, so `grep` treats it as untrusted input before compiling it into a `RegExp`: patterns over 200 characters and patterns matching a nested-quantifier shape (`(x+)+`, `(x*)*`, `(x+)*`, `(x*)+`-style groups — the classic catastrophic-backtracking shape) are rejected up front as a `WorkspacePolicyError` `type: "unsafe-pattern"`, before any regex is compiled. Any scanned line longer than 2000 characters is skipped (not tested), bounding the worst-case backtracking cost of any single call regardless of pattern shape.
@@ -256,17 +349,18 @@ try {
 }
 ```
 
-- `WorkspacePolicyError.type`: `"path-escape"` (jail escape / deny glob) | `"denied-command"` (not allow-listed, or rejected during tokenizing — unquoted metacharacters, disallowed Windows-wrapper characters) | `"unsafe-pattern"` (`grep` pattern too long or nested-quantifier ReDoS shape).
-- `WorkspaceEditError.type`: `"not-found"` | `"not-unique"` | `"stale-hash"`.
+- `WorkspacePolicyError.type`: `"path-escape"` (jail escape / deny glob) | `"denied-command"` (the shell policy refused the line — `reason` says why) | `"unsafe-pattern"` (`grep` pattern too long or nested-quantifier ReDoS shape).
+- `WorkspaceEditError.type`: `"not-found"` | `"not-unique"` | `"stale-hash"` (+ `editIndex` for `multiEdit`).
+- `WorkspaceJobError.type`: `"not-found"` (unknown background command id).
 
 ## Composition — `readonly()` and `scope()`
 
 ```ts
-const ro = ws.readonly();         // vends only read/grep/glob; mutating direct methods reject
+const ro = ws.readonly(); // vends only read/grep/glob; mutating direct methods reject
 const api = ws.scope("packages/api"); // a sub-jailed workspace rooted at the subdir
 ```
 
-`readonly()` is the least-privilege reviewer projection — `tools.all()` on it returns `read_file` + `grep` + `glob` only, and `writeFile` / `editFile` / `exec` / `mkdir` / `remove` throw a `WorkspacePolicyError`. `scope(subdir)` narrows `cwd` to `join(cwd, subdir)` (same sub-policies, same backend), so a per-package agent gets a tighter blast radius.
+`readonly()` is the least-privilege reviewer projection — `tools.all()` on it returns `read_file`, `list_dir`, `grep`, `glob` and the todo tools only, and `writeFile` / `editFile` / `multiEdit` / `exec` / `startShell` / `shellKill` / `mkdir` / `remove` throw a `WorkspacePolicyError`. Projections share the workspace's background commands and todo list. `scope(subdir)` narrows `cwd` to `join(cwd, subdir)` (same sub-policies, same backend), so a per-package agent gets a tighter blast radius.
 
 ## Hermetic tests with the mock backend
 
@@ -283,4 +377,31 @@ const ws = ai.workspace({ cwd: "/srv/app", backend: "mock", shell: { allow: ["np
 - The `run-ai-agent` topic of the `warlock-js-ai` skill — running the agent that consumes `ws.tools.all()`.
 - The `define-ai-tool` topic of the `warlock-js-ai` skill — the `tool()` / `ToolContract` seam every workspace tool is built on.
 
+## Complete bounded-read and cancellation example
+
+```ts
+import { workspace } from "@warlock.js/ai-workspace";
+
+export async function inspectWorkspace(cwd: string) {
+  const ws = workspace({
+    cwd,
+    read: { maxBytes: 64_000, defaultLines: 400 },
+    shell: { allow: ["node"], inheritEnv: ["PATH"] },
+  });
+  const page = await ws.readFile("package.json");
+  console.info(page.bytesCapped, page.endLine, page.hash);
+
+  const controller = new AbortController();
+  controller.abort();
+  const result = await ws.exec('node -e "console.log(1)"', { signal: controller.signal });
+  if (result.cancelled) console.info("Command cancelled before it started");
+  return page;
+}
+```
+
+The caller supplies an absolute existing workspace root. The already-aborted
+signal demonstrates the no-spawn path; a later abort also kills a running
+command's process tree. The byte ceiling limits returned content, while the
+hash still describes the whole file.
+
 

package/llms.txt

@@ -7,4 +7,4 @@
 ## Skills
 
 - [build-loop-agent](@warlock.js/ai-workspace/build-loop-agent/SKILL.md): Wire a @warlock.js/ai-workspace into a coding agent that closes the read → edit → run-tests loop on its own. Triggers: `ws.tools.all()`, `ai.agent({ tools: ws.tools.all() })`, `maxTrips`, `run_tests`, `run_shell`, 'agent that fixes a failing test', 'make the suite green', 'coding agent that edits a repo', 'build-loop agent', 'self-correcting agent', 'read-only code reviewer', 'scaffold then hand off to an agent', 'share one workspace across a supervisor', 'least-privilege agent tools', 'errors as tool data'; typical wiring `const ws = ai.workspace({ cwd, shell }); ai.agent({ model, tools: ws.tools.all(), maxTrips })`. Skip: constructing the workspace / its policy / direct methods / readonly / scope — the `use-a-workspace` topic; the agent loop / maxTrips / events themselves — the `run-ai-agent` topic of the `warlock-js-ai` skill.
-- [use-a-workspace](@warlock.js/ai-workspace/use-a-workspace/SKILL.md): Build and operate a policy-jailed filesystem + shell workspace with @warlock.js/ai-workspace. Triggers: `ai.workspace`, `workspace(`, `WorkspacePolicy`, `WorkspaceShellPolicy`, `WorkspaceToolName`, `ws.tools.all`, `ws.tools.pick`, `ws.readFile`, `ws.writeFile`, `ws.editFile`, `ws.exec`, `ws.grep`, `ws.glob`, `ws.readonly`, `ws.scope`, `WorkspacePolicyError`, `WorkspaceEditError`, `denyPaths`, `inheritEnv`, `expectHash`, `read.maxBytes`, `bytesCapped`, `cancelled`, `ExecOptions`, `tokenizeCommand`, `read_file`/`edit_file`/`write_file`/`run_shell`/`run_tests`/`grep`; 'give an agent file tools', 'jail an agent to a directory', 'let an agent read/write/grep a repo', 'read-only workspace for a reviewer', 'scope an agent to a subdirectory', 'run a shell command under policy', 'edit a file with a stale-hash guard', 'command injection guard for an agent shell tool', 'ReDoS-safe grep for an agent', 'cap how many bytes a read returns', 'cancel a running workspace command'; typical import `import "@warlock.js/ai-workspace"; import { ai } from "@warlock.js/ai"`. Skip: building the agent loop that consumes the tools — the `build-loop-agent` topic; defining a non-filesystem custom tool — the `define-ai-tool` topic of the `warlock-js-ai` skill.
+- [use-a-workspace](@warlock.js/ai-workspace/use-a-workspace/SKILL.md): Build and operate a policy-jailed filesystem + shell workspace with @warlock.js/ai-workspace. Triggers: `ai.workspace`, `workspace(`, `WorkspacePolicy`, `WorkspaceShellPolicy`, `WorkspaceToolName`, `ws.tools.all`, `ws.tools.pick`, `ws.readFile`, `ws.writeFile`, `ws.editFile`, `ws.exec`, `ws.grep`, `ws.glob`, `ws.readonly`, `ws.scope`, `ws.multiEdit`, `ws.listDir`, `ws.startShell`, `ws.shellOutput`, `ws.shellKill`, `ws.dispose`, `ws.readTodos`, `ws.writeTodos`, `WorkspacePolicyError`, `WorkspaceEditError`, `WorkspaceJobError`, `WorkspaceShellRefusalReason`, `checkShellCommand`, `denyPaths`, `denyPatterns`, `allowCommand`, `interpreter`, `shell.background`, `list.ignore`, `inheritEnv`, `expectHash`, `read.maxBytes`, `bytesCapped`, `cancelled`, `ExecOptions`, `tokenizeCommand`, `read_file`/`edit_file`/`multi_edit`/`write_file`/`list_dir`/`run_shell`/`shell_output`/`shell_kill`/`run_tests`/`grep`/`todo_write`/`todo_read`; 'give an agent file tools', 'jail an agent to a directory', 'let an agent read/write/grep a repo', 'read-only workspace for a reviewer', 'scope an agent to a subdirectory', 'run a shell command under policy', 'edit a file with a stale-hash guard', 'command injection guard for an agent shell tool', 'ReDoS-safe grep for an agent', 'cap how many bytes a read returns', 'cancel a running workspace command', 'let the agent use pipes and &&', 'why was my shell command refused', 'deny git push --force', 'run a dev server in the background', 'atomic multi-edit', 'list a directory for an agent', 'todo list tool for an agent'; typical import `import "@warlock.js/ai-workspace"; import { ai } from "@warlock.js/ai"`. Skip: building the agent loop that consumes the tools — the `build-loop-agent` topic; defining a non-filesystem custom tool — the `define-ai-tool` topic of the `warlock-js-ai` skill.

package/package.json

@@ -19,13 +19,13 @@
     "directory": "packages/ai-workspace"
   },
   "peerDependencies": {
-    "@warlock.js/ai": "5.30.0"
+    "@warlock.js/ai": "5.32.0"
   },
   "dependencies": {
     "@standard-schema/spec": "^1.0.0",
-    "@warlock.js/fs": "5.30.0"
+    "@warlock.js/fs": "5.32.0"
   },
-  "version": "5.30.0",
+  "version": "5.32.0",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

package/skills/README.md

@@ -6,8 +6,8 @@ Per-task skills. Cross-references name the topic ("the `<topic>` topic"), and fo
 
 ### `use-a-workspace`
 
-Build a policy-jailed filesystem + shell workspace with `ai.workspace(policy)` and operate it from both ends — the agent-facing `ws.tools.*` (the seven tools + `all()` / `pick(...)`) and the human-facing direct methods (`readFile` / `writeFile` / `editFile` / `exec` / `grep` / `glob` / `exists` / `mkdir` / `remove`). Covers the policy surface (the `cwd` jail, `allowPaths` / `denyPaths`, the fail-closed shell allow/deny + `inheritEnv`, read caps), the local vs mock backend, the read-before-edit stale-hash guard, the typed `WorkspacePolicyError` / `WorkspaceEditError`, and the `readonly()` / `scope(subdir)` projections. Load when constructing a workspace, choosing a policy, vending tools to an agent, or driving the filesystem programmatically.
+Build a policy-jailed filesystem + shell workspace with `ai.workspace(policy)` and operate it from both ends — the agent-facing `ws.tools.*` (files, `list_dir`, `multi_edit`, `run_shell` with background commands, `shell_output` / `shell_kill`, `run_tests`, `grep`, `glob`, `todo_write` / `todo_read`, plus `all()` / `pick(...)`) and the human-facing direct methods (`readFile` / `writeFile` / `editFile` / `multiEdit` / `listDir` / `exec` / `startShell` / `shellOutput` / `shellKill` / `grep` / `glob` / `exists` / `mkdir` / `remove` / `readTodos` / `writeTodos` / `dispose`). Covers the policy surface (the `cwd` jail, `allowPaths` / `denyPaths`, the fail-closed shell allow/deny + `denyPatterns` / `allowCommand` + `inheritEnv`, the opt-in `interpreter: "sh"` shell mode and its refusal reasons, read caps, list bounds), the local vs mock backend, the read-before-edit stale-hash guard, the typed `WorkspacePolicyError` / `WorkspaceEditError`, and the `readonly()` / `scope(subdir)` projections. Load when constructing a workspace, choosing a policy, vending tools to an agent, or driving the filesystem programmatically.
 
 ### `build-loop-agent`
 
-Wire a workspace into a coding agent that closes the read → edit → run-tests loop on its own — `ai.agent({ tools: ws.tools.all() })` so a failing suite comes back as tool *data* and the model self-corrects until green. Covers the minimal build-loop wiring, why errors-as-data drives the loop, the shell policy a test command needs (`shell.allow` + `inheritEnv: ["PATH"]`), the read-only reviewer via `tools.pick` / `readonly()`, scaffolding from code before handing off, and sharing one jail across a supervisor's members. Load when building an agent that edits a repo, runs tests, reviews code, or scaffolds then hands off.
+Wire a workspace into a coding agent that closes the read → edit → run-tests loop on its own — `ai.agent({ tools: ws.tools.all() })` so a failing suite comes back as tool _data_ and the model self-corrects until green. Covers the minimal build-loop wiring, why errors-as-data drives the loop, the shell policy a test command needs (`shell.allow` + `inheritEnv: ["PATH"]`), the read-only reviewer via `tools.pick` / `readonly()`, scaffolding from code before handing off, and sharing one jail across a supervisor's members. Load when building an agent that edits a repo, runs tests, reviews code, or scaffolds then hands off.

package/skills/build-loop-agent/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: build-loop-agent
-description: 'Wire a @warlock.js/ai-workspace into a coding agent that closes the read → edit → run-tests loop on its own. Triggers: `ws.tools.all()`, `ai.agent({ tools: ws.tools.all() })`, `maxTrips`, `run_tests`, `run_shell`, ''agent that fixes a failing test'', ''make the suite green'', ''coding agent that edits a repo'', ''build-loop agent'', ''self-correcting agent'', ''read-only code reviewer'', ''scaffold then hand off to an agent'', ''share one workspace across a supervisor'', ''least-privilege agent tools'', ''errors as tool data''; typical wiring `const ws = ai.workspace({ cwd, shell }); ai.agent({ model, tools: ws.tools.all(), maxTrips })`. Skip: constructing the workspace / its policy / direct methods / readonly / scope — the `use-a-workspace` topic; the agent loop / maxTrips / events themselves — the `run-ai-agent` topic of the `warlock-js-ai` skill.'
+description: "Wire a @warlock.js/ai-workspace into a coding agent that closes the read → edit → run-tests loop on its own. Triggers: `ws.tools.all()`, `ai.agent({ tools: ws.tools.all() })`, `maxTrips`, `run_tests`, `run_shell`, 'agent that fixes a failing test', 'make the suite green', 'coding agent that edits a repo', 'build-loop agent', 'self-correcting agent', 'read-only code reviewer', 'scaffold then hand off to an agent', 'share one workspace across a supervisor', 'least-privilege agent tools', 'errors as tool data'; typical wiring `const ws = ai.workspace({ cwd, shell }); ai.agent({ model, tools: ws.tools.all(), maxTrips })`. Skip: constructing the workspace / its policy / direct methods / readonly / scope — the `use-a-workspace` topic; the agent loop / maxTrips / events themselves — the `run-ai-agent` topic of the `warlock-js-ai` skill."
 ---
 
 # Build a build-loop agent — read → edit → run tests, until green
@@ -19,8 +19,8 @@ const ws = ai.workspace({
 
 const dev = ai.agent({
   model,
-  tools: ws.tools.all(),   // read_file, edit_file, write_file, run_shell, run_tests, grep, glob
-  maxTrips: 25,            // give the loop room to iterate
+  tools: ws.tools.all(), // read/edit/multi_edit/write, list_dir, run_shell, run_tests, grep, glob, todo_write/todo_read
+  maxTrips: 25, // give the loop room to iterate
 });
 
 await dev.execute("`npm test` fails on the cart-total suite. Make it green.");
@@ -43,7 +43,7 @@ Override the base command per agent: `ws.tools.runTests({ command: "vitest run"
 
 ### A read-only reviewer
 
-A reviewer should never write or run a shell. Pick exactly the read tools, or hand it a `readonly()` projection (which omits the mutating tools *and* rejects the mutating direct methods):
+A reviewer should never write or run a shell. Pick exactly the read tools, or hand it a `readonly()` projection (which omits the mutating tools _and_ rejects the mutating direct methods):
 
 ```ts
 const reviewer = ai.agent({
@@ -53,7 +53,7 @@ const reviewer = ai.agent({
 await reviewer.execute("Review src/cart for off-by-one bugs and summarize.");
 
 // Equivalent projection of the same jail:
-ai.agent({ model, tools: ws.readonly().tools.all() }); // read_file + grep + glob only
+ai.agent({ model, tools: ws.readonly().tools.all() }); // read_file, list_dir, grep, glob, todo tools
 ```
 
 ### Scope an agent to one package
@@ -61,8 +61,8 @@ ai.agent({ model, tools: ws.readonly().tools.all() }); // read_file + grep + glo
 `scope(subdir)` narrows the jail so a per-package agent can't reach outside it — one sub-agent per package, isolated blast radius:
 
 ```ts
-const apiDev  = ai.agent({ model, tools: ws.scope("packages/api").tools.all() });
-const webDev  = ai.agent({ model, tools: ws.scope("packages/web").tools.all() });
+const apiDev = ai.agent({ model, tools: ws.scope("packages/api").tools.all() });
+const webDev = ai.agent({ model, tools: ws.scope("packages/web").tools.all() });
 ```
 
 ## Scaffold from code, then hand off

package/skills/index.md

@@ -1,17 +1,22 @@
 ---
 description: "Policy-jailed filesystem and shell access for @warlock.js/ai agents, for coding and build-loop agents. Exports `workspace`, `makeEditFileTool`, `makeRunShellTool`, `makeRunTestsTool`, `createLocalBackend`, `createMockBackend`, `WorkspacePolicyError`. Use for: let an agent read, edit or write files, run shell commands or tests safely, sandbox an agent to a directory, build a coding agent that loops until tests pass, test file tools with a fake backend. Not this package: web, HTTP or MCP tools → @warlock.js/ai-tools; agents and custom tools → @warlock.js/ai; tracing runs → @warlock.js/ai-panoptic."
 ---
+
 # @warlock.js/ai-workspace
 
-A workspace is a policy jail around a directory: it decides which paths an agent may read or write and which shell commands may run, then exposes read, write, edit, glob, grep, shell and test tools bound to that policy. Importing the package registers `ai.workspace(...)` on the shared `ai` object.
+A workspace is a policy jail around a directory: it decides which paths an agent may read or write and which shell commands may run, then exposes read, write, edit, multi-edit, list, glob, grep, shell (argv by default, opt-in `sh`, background commands), test and todo tools bound to that policy. Importing the package registers `ai.workspace(...)` on the shared `ai` object.
 
 ## The 80% path
+
 1. Create a workspace with a root and policy (`use-a-workspace.md`).
 2. Hand its tools to an `ai.agent()`.
 3. For a coding agent, follow the read → edit → run tests loop until green (`build-loop-agent.md`).
 
 ## Conventions and pitfalls
+
 - The policy is the security boundary: keep the root narrow and the shell allowlist explicit; violations throw `WorkspacePolicyError`.
 - Paths resolve inside the jail; escaping it via `..` or symlinks is rejected on purpose.
 - The local backend runs real processes. Use `createMockBackend` in tests so no disk or shell is touched.
+- Shell refusals carry a `reason` and a message that says how to split the command; `interpreter: "sh"` is an explicit opt-in that still checks every command in the line.
+- Call `ws.dispose()` when done: it kills background commands (whole process trees).
 - Edits fail loudly (`WorkspaceEditError`) when the target text is not found; re-read the file rather than retrying blindly.