@garuda-agent/garuda 0.16.1 → 0.18.0

package/dist/{chunk-GXZACJUI.js → chunk-B4SJY7KT.js}

@@ -1,16 +1,22 @@
 #!/usr/bin/env node
-import {
-  realRelative
-} from "./chunk-WMOLXTBU.js";
 import {
   EFFORTS
-} from "./chunk-3EQU2GUX.js";
+} from "./chunk-BHZ6G65V.js";
 import {
+  PROFILES,
   isCommandDisallowedByPolicy,
   isHostBlockedByPolicy,
   isPathDeniedByPolicy,
   isSandboxRequiredByPolicy
-} from "./chunk-HUIK3WXO.js";
+} from "./chunk-P6XWWIEK.js";
+import {
+  prepareWriteScope,
+  scopeDenial,
+  scopePaths
+} from "./chunk-UIRJOQQS.js";
+import {
+  realRelative
+} from "./chunk-4LFJFDCF.js";
 import {
   CASE_INSENSITIVE_FS,
   formatRule,
@@ -131,6 +137,14 @@ function unique(paths) {
   return [...new Set(paths.filter((p) => isAbsolute(p)))];
 }
 var MAX_POLICY_DENIED_PATHS = 1e3;
+var PolicyPathsOverflow = class extends Error {
+  name = "PolicyPathsOverflow";
+  constructor(found) {
+    super(
+      `The team policy's denyPaths match ${found} paths in this project, more paths than the OS sandbox can protect (at most ${MAX_POLICY_DENIED_PATHS}). The command does not run. Narrow the patterns, or deny a folder instead of its files.`
+    );
+  }
+};
 function policyDeniedPaths(root, patterns, ignoreCase = CASE_INSENSITIVE_FS) {
   if (patterns.length === 0) return [];
   const found = globbySync(patterns.map(fullGlob), {
@@ -140,10 +154,10 @@ function policyDeniedPaths(root, patterns, ignoreCase = CASE_INSENSITIVE_FS) {
     onlyFiles: false,
     followSymbolicLinks: false,
     gitignore: false,
-    caseSensitiveMatch: !ignoreCase,
-    ignore: ["**/node_modules/**", "**/.git/**"]
+    caseSensitiveMatch: !ignoreCase
   });
-  return found.slice(0, MAX_POLICY_DENIED_PATHS);
+  if (found.length > MAX_POLICY_DENIED_PATHS) throw new PolicyPathsOverflow(found.length);
+  return found;
 }
 
 // src/sandbox/process.ts
@@ -372,13 +386,61 @@ var ProcessExecutor = class {
   daemons = new DaemonManager(this);
   /** Process group ids of running commands. */
   running = /* @__PURE__ */ new Set();
+  /** Markers of commands and processes that still run (0.17, IPI-04): shutdown() reaps them. */
+  trackers = /* @__PURE__ */ new Set();
+  /**
+   * Markers for one command, when this executor can find the processes that leave its process
+   * group (Seatbelt with the helper). Others need none: bubblewrap's PID namespace ends them all.
+   */
+  track(_policy) {
+    return void 0;
+  }
+  /** Remove what tracking keeps (the markers folder), at shutdown. */
+  closeTracking() {
+  }
   shutdown() {
     this.daemons.shutdown();
     for (const pid of this.running) signalGroup(pid, "SIGKILL");
     this.running.clear();
+    for (const tracker of this.trackers) {
+      try {
+        tracker.reapSync();
+      } catch {
+      }
+    }
+    this.trackers.clear();
+    this.closeTracking();
+  }
+  /** The launch, with markers; the markers go away when the launch fails. */
+  launchTracked(argv, policy) {
+    const tracker = this.track(policy);
+    try {
+      const launch = this.launch(argv, policy, tracker);
+      if (tracker === void 0) return launch;
+      this.trackers.add(tracker);
+      return { ...launch, tracker };
+    } catch (error) {
+      tracker?.dispose();
+      throw error;
+    }
+  }
+  /** Kill the tracked processes that still run (the command's own group is already gone). */
+  async reap(tracker) {
+    try {
+      const n = await tracker.reap();
+      return n > 0 ? { reaped: n } : {};
+    } catch (error) {
+      return { reapProblem: error.message };
+    } finally {
+      this.trackers.delete(tracker);
+    }
+  }
+  dropTracker(tracker) {
+    if (tracker === void 0 || !this.trackers.delete(tracker)) return;
+    tracker.dispose();
   }
   start(argv, policy, env = {}) {
-    const { file, args } = this.launch(argv, policy);
+    const { file, args, tracker } = this.launchTracked(argv, policy);
     const child = spawn(file, args, {
       cwd: policy.root,
       env: { ...allowedEnv(policy.envAllowlist), ...proxyEnv(policy), ...env },
@@ -394,7 +456,9 @@ var ProcessExecutor = class {
         signalGroup(pid, "SIGKILL");
       }
       if (killTimer !== void 0) clearTimeout(killTimer);
+      if (tracker !== void 0) void this.reap(tracker);
     });
+    child.on("error", () => this.dropTracker(tracker));
     return {
       pid,
       stdin: child.stdin,
@@ -423,7 +487,7 @@ var ProcessExecutor = class {
         reject(options.signal.reason);
         return;
       }
-      const { file, args } = this.launch(["bash", "-c", command], policy);
+      const { file, args, tracker } = this.launchTracked(["bash", "-c", command], policy);
       const child = spawn(file, args, {
         cwd: policy.root,
         env: { ...allowedEnv(policy.envAllowlist), ...proxyEnv(policy), ...options.env },
@@ -458,6 +522,7 @@ var ProcessExecutor = class {
       child.on("error", (error) => {
         if (finished) return;
         finished = true;
+        this.dropTracker(tracker);
         if (pid !== void 0) this.running.delete(pid);
         clearTimeout(timer);
         if (drainTimer !== void 0) clearTimeout(drainTimer);
@@ -473,7 +538,7 @@ var ProcessExecutor = class {
         if (killTimer !== void 0) clearTimeout(killTimer);
         options.signal?.removeEventListener("abort", onAbort);
         if (child.pid !== void 0) signalGroup(child.pid, "SIGKILL");
-        resolve2({
+        const result = {
           exitCode: code,
           signal,
           stdout: stdout.result(),
@@ -481,7 +546,12 @@ var ProcessExecutor = class {
           timedOut,
           aborted,
           durationMs: Date.now() - started
-        });
+        };
+        if (tracker === void 0) {
+          resolve2(result);
+          return;
+        }
+        void this.reap(tracker).then((reaped) => resolve2({ ...result, ...reaped }));
       };
       child.on("exit", (code, signal) => {
         drainTimer = setTimeout(() => {
@@ -541,9 +611,9 @@ var HostExecutor = class extends ProcessExecutor {
 };
 
 // src/sandbox/index.ts
-import { spawnSync } from "child_process";
-import { existsSync as existsSync2 } from "fs";
-import { delimiter, join as join2 } from "path";
+import { spawnSync as spawnSync2 } from "child_process";
+import { existsSync as existsSync3 } from "fs";
+import { delimiter, join as join3 } from "path";
 
 // src/sandbox/bwrap.ts
 import { existsSync, statSync } from "fs";
@@ -564,6 +634,12 @@ function bwrapArgv(argv, policy, kind = pathKind) {
   const args = ["--ro-bind", "/", "/", "--dev", "/dev"];
   for (const path of policy.writePaths)
     if (kind(path) !== void 0) args.push("--bind", path, path);
+  for (const mount of policy.mounts ?? []) args.push("--bind", mount.source, mount.target);
+  if (policy.writeScope !== void 0) {
+    args.push("--ro-bind", policy.writeScope.root, policy.writeScope.root);
+    for (const path of policy.writeScope.paths)
+      if (kind(path) !== void 0) args.push("--bind", path, path);
+  }
   for (const path of policy.denyWritePaths) {
     if (kind(path) !== void 0) args.push("--ro-bind", path, path);
   }
@@ -600,24 +676,146 @@ function pathKind(path) {
   return statSync(path).isDirectory() ? "dir" : "file";
 }
 
+// src/sandbox/reaper.ts
+import { execFile, spawnSync } from "child_process";
+import { randomBytes } from "crypto";
+import { existsSync as existsSync2, mkdtempSync, realpathSync as realpathSync2, rmSync, writeFileSync } from "fs";
+import { tmpdir as tmpdir2 } from "os";
+import { dirname, join as join2 } from "path";
+import { fileURLToPath } from "url";
+var HELPER_TIMEOUT_MS = 1e4;
+var ReapError = class extends Error {
+  name = "ReapError";
+};
+var Reaper = class {
+  constructor(helper, parent = tmpdir2()) {
+    this.helper = helper;
+    this.parent = parent;
+  }
+  helper;
+  parent;
+  folder;
+  /** The markers folder, made at the first command. Seatbelt matches real paths (/private/var). */
+  dir() {
+    this.folder ??= realpathSync2(mkdtempSync(join2(this.parent, "garuda-markers-")));
+    return this.folder;
+  }
+  /** Remove the markers folder (at shutdown). */
+  close() {
+    if (this.folder !== void 0) rmSync(this.folder, { recursive: true, force: true });
+    this.folder = void 0;
+  }
+  /** New markers for one command. */
+  track() {
+    const dir = this.dir();
+    const id = randomBytes(8).toString("hex");
+    const a = join2(dir, `${id}-a`);
+    const b = join2(dir, `${id}-b`);
+    writeFileSync(a, "", { mode: 384 });
+    writeFileSync(b, "", { mode: 384 });
+    const remove = () => {
+      rmSync(a, { force: true });
+      rmSync(b, { force: true });
+    };
+    const helper = this.helper;
+    return {
+      rules: [
+        `(deny file-read* (literal ${quote(a)}))`,
+        `(allow file-read* (literal ${quote(b)}))`,
+        `(deny file-write* (subpath ${quote(dir)}))`
+      ],
+      reap: () => new Promise((resolve2, reject) => {
+        execFile(
+          helper,
+          [a, b],
+          { timeout: HELPER_TIMEOUT_MS, encoding: "utf8" },
+          (error, stdout, stderr) => {
+            remove();
+            if (error) reject(new ReapError(why(error.message, stderr)));
+            else resolve2(killed(stdout));
+          }
+        );
+      }),
+      reapSync: () => {
+        const r = spawnSync(helper, [a, b], { timeout: HELPER_TIMEOUT_MS, encoding: "utf8" });
+        remove();
+        if (r.status !== 0) throw new ReapError(why(r.error?.message ?? "", r.stderr ?? ""));
+        return killed(r.stdout ?? "");
+      },
+      dispose: remove
+    };
+  }
+};
+function locateHelper() {
+  let dir;
+  try {
+    dir = dirname(fileURLToPath(import.meta.url));
+  } catch {
+    return void 0;
+  }
+  for (let i = 0; i < 5; i++) {
+    const candidate = join2(dir, "native", "bin", "garuda-reap");
+    if (existsSync2(candidate)) return candidate;
+    const up = dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return void 0;
+}
+function killed(stdout) {
+  const match = /killed (\d+)/.exec(stdout);
+  return match === null ? 0 : Number(match[1]);
+}
+function why(message, stderr) {
+  return `garuda-reap failed: ${(stderr.trim() || message).split("\n")[0]}`;
+}
+function quote(path) {
+  return `"${path.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+}
+
 // src/sandbox/seatbelt.ts
 var SANDBOX_EXEC = "/usr/bin/sandbox-exec";
 var SeatbeltExecutor = class extends ProcessExecutor {
+  /**
+   * `reaper` (0.17, IPI-04): finds and kills the processes that leave a command's process group.
+   * Without it, such a process outlives the command (index.ts warns, or strict refuses).
+   */
+  constructor(reaper) {
+    super();
+    this.reaper = reaper;
+  }
+  reaper;
   name = "seatbelt";
   isolation = "os";
-  launch(argv, policy) {
+  track(policy) {
+    return policy.sandbox && this.reaper !== void 0 ? this.reaper.track() : void 0;
+  }
+  closeTracking() {
+    this.reaper?.close();
+  }
+  launch(argv, policy, tracker) {
     if (!policy.sandbox) return plain(argv);
-    return { file: SANDBOX_EXEC, args: ["-p", seatbeltProfile(policy), ...argv] };
+    if ((policy.mounts ?? []).length > 0) throw new Error("Seatbelt cannot mount folders.");
+    return {
+      file: SANDBOX_EXEC,
+      args: ["-p", seatbeltProfile(policy, tracker?.rules), ...argv]
+    };
   }
 };
-function seatbeltProfile(policy) {
-  const paths = (list) => list.map((p) => `(subpath ${quote(p)})`).join(" ");
+function seatbeltProfile(policy, extra = []) {
+  const paths = (list) => list.map((p) => `(subpath ${quote2(p)})`).join(" ");
   const lines = [
     "(version 1)",
     "(allow default)",
     "(deny file-write*)",
     `(allow file-write* ${paths(policy.writePaths)} (literal "/dev/null") (literal "/dev/zero") (literal "/dev/dtracehelper") (regex #"^/dev/tty") (regex #"^/dev/fd/"))`
   ];
+  if (policy.writeScope !== void 0) {
+    lines.push(`(deny file-write* ${paths([policy.writeScope.root])})`);
+    if (policy.writeScope.paths.length > 0) {
+      lines.push(`(allow file-write* ${paths(policy.writeScope.paths)})`);
+    }
+  }
   if (policy.denyWritePaths.length > 0) {
     lines.push(`(deny file-write* ${paths(policy.denyWritePaths)})`);
   }
@@ -635,42 +833,75 @@ function seatbeltProfile(policy) {
       '(allow network-bind (local ip "localhost:*"))'
     );
   }
+  lines.push(...extra);
   return lines.join("\n");
 }
-function quote(path) {
+function quote2(path) {
   return `"${path.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
 }
 
 // src/sandbox/index.ts
 var EXECUTOR_NAMES = ["auto", "os", "host"];
-function createExecutor(name = "auto", find = findOsSandbox) {
+var StrictProfileError = class extends Error {
+};
+function strictFix(platform) {
+  if (platform === "linux")
+    return "Install bubblewrap (for example: sudo apt install bubblewrap) and allow user namespaces, or remove the strict profile.";
+  return 'Run Garuda where the OS sandbox works, or remove the strict profile ("profile": "strict").';
+}
+function createExecutor(name = "auto", find = findOsSandbox, strict = false, platform = process.platform) {
+  if (strict && name === "host") {
+    throw new StrictProfileError(
+      'The strict profile requires the OS sandbox, but "executor" is "host". Remove "executor": "host" from .garuda/settings.json, or remove the strict profile.'
+    );
+  }
   if (name === "host") return { executor: new HostExecutor() };
   const found = find();
-  if ("executor" in found) return { executor: found.executor };
+  if ("executor" in found) {
+    if (found.warning === void 0) return { executor: found.executor };
+    if (strict) {
+      throw new StrictProfileError(
+        `The strict profile requires the macOS helper garuda-reap. ${found.warning}`
+      );
+    }
+    return { executor: found.executor, notice: found.warning };
+  }
+  if (strict) {
+    throw new StrictProfileError(
+      `The strict profile requires the OS sandbox, and this machine has none: ${found.problem} Garuda does not run commands on the host in this profile. ${strictFix(platform)}`
+    );
+  }
   if (name === "os") throw new Error(`No OS sandbox: ${found.problem} ${found.fix}`);
   return {
     executor: new HostExecutor(),
-    notice: `No OS sandbox: ${found.problem} Commands run on your machine, and each one asks for approval. ${found.fix}`
+    notice: `No OS sandbox: ${found.problem} Commands run on your machine, and each one asks for approval, unless an allow rule covers it. ${found.fix}`
   };
 }
+var HELPER_MISSING = "The macOS helper garuda-reap is missing, so a process that leaves a command's process group (for example with setsid) can keep running after the command, inside the sandbox. Reinstall Garuda; in a source checkout, run `pnpm build` (it needs the Command Line Tools).";
 var cached;
 function findOsSandbox() {
   cached ??= detect(process.platform);
-  return "make" in cached ? { executor: cached.make() } : cached;
+  if (!("make" in cached)) return cached;
+  return cached.warning === void 0 ? { executor: cached.make() } : { executor: cached.make(), warning: cached.warning };
 }
 function detect(platform) {
   const fix = 'Set "executor": "host" in .garuda/settings.json to hide this notice.';
   if (platform === "darwin") {
-    if (!existsSync2(SANDBOX_EXEC)) {
+    if (!existsSync3(SANDBOX_EXEC)) {
       return { problem: `${SANDBOX_EXEC} is missing.`, fix };
     }
-    const probe = spawnSync(SANDBOX_EXEC, ["-p", "(version 1)(allow default)", "--", "true"], {
+    const probe = spawnSync2(SANDBOX_EXEC, ["-p", "(version 1)(allow default)", "--", "true"], {
       encoding: "utf8",
       timeout: 5e3
     });
-    if (probe.status === 0) return { make: () => new SeatbeltExecutor() };
-    const why = (probe.stderr || probe.error?.message || "unknown error").trim().split("\n")[0];
-    return { problem: `sandbox-exec cannot start a sandbox here (${why}).`, fix };
+    if (probe.status === 0) {
+      const helper = locateHelper();
+      if (helper === void 0)
+        return { make: () => new SeatbeltExecutor(), warning: HELPER_MISSING };
+      return { make: () => new SeatbeltExecutor(new Reaper(helper)) };
+    }
+    const why2 = (probe.stderr || probe.error?.message || "unknown error").trim().split("\n")[0];
+    return { problem: `sandbox-exec cannot start a sandbox here (${why2}).`, fix };
   }
   if (platform === "linux") {
     const bwrap = onPath("bwrap");
@@ -680,33 +911,34 @@ function detect(platform) {
         fix: 'Install it (for example: sudo apt install bubblewrap), or set "executor": "host" in .garuda/settings.json.'
       };
     }
-    const probe = spawnSync(
+    const probe = spawnSync2(
       bwrap,
       ["--ro-bind", "/", "/", "--dev", "/dev", "--unshare-net", "--die-with-parent", "--", "true"],
       { encoding: "utf8", timeout: 5e3 }
     );
     if (probe.status === 0) return { make: () => new BwrapExecutor(bwrap) };
-    const why = (probe.stderr || probe.error?.message || "unknown error").trim().split("\n")[0];
-    return { problem: `bubblewrap cannot start a sandbox here (${why}).`, fix };
+    const why2 = (probe.stderr || probe.error?.message || "unknown error").trim().split("\n")[0];
+    return { problem: `bubblewrap cannot start a sandbox here (${why2}).`, fix };
   }
   return { problem: `Garuda has no OS sandbox for ${platform}.`, fix };
 }
 function onPath(program) {
   for (const dir of (process.env.PATH ?? "").split(delimiter)) {
-    const path = join2(dir, program);
-    if (dir !== "" && existsSync2(path)) return path;
+    const path = join3(dir, program);
+    if (dir !== "" && existsSync3(path)) return path;
   }
   return void 0;
 }
 
 // src/permissions/settings.ts
 import { readFile } from "fs/promises";
-import { join as join3 } from "path";
+import { join as join4 } from "path";
 import { z } from "zod";
-var SETTINGS_FILE = join3(".garuda", "settings.json");
+var SETTINGS_FILE = join4(".garuda", "settings.json");
 var NOTIFY_CHOICES = ["auto", "osc9", "bell", "off"];
 var schema = z.strictObject({
   executor: z.enum(EXECUTOR_NAMES).optional(),
+  profile: z.enum(PROFILES).optional(),
   sandbox: z.strictObject({
     writePaths: z.array(z.string()).optional(),
     denyRead: z.array(z.string()).optional()
@@ -782,6 +1014,11 @@ var schema = z.strictObject({
    * (merge gate): no measured gain yet, and they add tools and long-lived processes.
    */
   daemons: z.strictObject({ enabled: z.boolean().optional() }).optional(),
+  /**
+   * Staged commands (0.17, review T5): "staged" runs each sandboxed command in a staging copy and
+   * asks before its changes reach the project. Default "direct".
+   */
+  commands: z.strictObject({ mode: z.enum(["direct", "staged"]).optional() }).optional(),
   /** Mixture-of-Experts language specialist subagent dispatch (0.17). */
   moe: z.strictObject({
     enabled: z.boolean().optional(),
@@ -810,6 +1047,7 @@ function parseSettings(json, source = SETTINGS_FILE) {
   if (!parsed.success) throw new Error(`${source}: ${z.prettifyError(parsed.error)}`);
   const {
     executor = "auto",
+    profile,
     sandbox,
     web,
     permissions = {},
@@ -820,6 +1058,7 @@ function parseSettings(json, source = SETTINGS_FILE) {
     subagents,
     moe,
     daemons,
+    commands,
     todo,
     lsp,
     undo,
@@ -843,6 +1082,7 @@ function parseSettings(json, source = SETTINGS_FILE) {
   });
   return {
     executor,
+    ...profile === void 0 ? {} : { profile },
     allow: rules(permissions.allow),
     deny: rules(permissions.deny),
     envAllow: env.allow ?? [],
@@ -859,6 +1099,7 @@ function parseSettings(json, source = SETTINGS_FILE) {
     ...limits.tokenBudget === void 0 ? {} : { tokenBudget: limits.tokenBudget },
     ...model.contextWindow === void 0 ? {} : { contextWindow: model.contextWindow },
     ...model.price === void 0 ? {} : { price: model.price },
+    ...commands?.mode === void 0 ? {} : { commands: { mode: commands.mode } },
     ...todo?.enabled === void 0 ? {} : { todo: { enabled: todo.enabled } },
     ...lsp?.enabled === void 0 ? {} : { lsp: { enabled: lsp.enabled } },
     ...undo?.enabled === void 0 ? {} : { undo: { enabled: undo.enabled } },
@@ -904,7 +1145,7 @@ function parseSettings(json, source = SETTINGS_FILE) {
 async function loadSettings(root) {
   let text;
   try {
-    text = await readFile(join3(root, SETTINGS_FILE), "utf8");
+    text = await readFile(join4(root, SETTINGS_FILE), "utf8");
   } catch (error) {
     if (error.code === "ENOENT") return DEFAULT_SETTINGS;
     throw error;
@@ -1119,6 +1360,31 @@ var PermissionEngine = class {
       return { decision: this.planDecision(tool, target, allowRule !== void 0) };
     }
     if (request.readOnly) return { decision: { allowed: true, by: "read_only" } };
+    if (target?.kind === "command" && target.outsideSandbox === true && (this.unattended !== void 0 || this.settings.writeScope !== void 0)) {
+      this.unattended?.onDeny?.(tool, target);
+      return {
+        decision: {
+          allowed: false,
+          by: "rule",
+          reason: "A scheduled job runs commands only in the OS sandbox: outside_sandbox is not allowed. Do not retry it; list it in your final answer as work left for the user."
+        }
+      };
+    }
+    const scope = this.settings.writeScope;
+    const ruled = allowRule !== void 0 && !(target?.kind === "url" && target.alwaysAsk === true) || this.sessionRules.some((r) => ruleMatches(r, tool, target, "allow"));
+    if (scope !== void 0 && target?.kind === "path" && (ruled || this.unattended === void 0)) {
+      const outside = await scopeDenial(this.root, target.path, scope);
+      if (outside !== void 0) {
+        this.unattended?.onDeny?.(tool, target);
+        return {
+          decision: {
+            allowed: false,
+            by: "rule",
+            reason: `${outside}. Do not retry it; list it in your final answer as work left for the user.`
+          }
+        };
+      }
+    }
     if (target?.kind === "command" && !target.outsideSandbox && this.isolation !== "none") {
       return { decision: { allowed: true, by: "sandbox" } };
     }
@@ -1252,17 +1518,25 @@ var PermissionEngine = class {
     const denied = policyDeniedPaths(this.root, this.policy?.denyPaths ?? []);
     let writePaths = [.../* @__PURE__ */ new Set([...paths.writePaths, ...this.access.writePaths])];
     let denyWritePaths = [...paths.denyWritePaths, ...denied];
+    const inRoot = (p) => p === this.root || p.startsWith(`${this.root}${sep}`);
     if (readOnlyRoot) {
-      const inRoot = (p) => p === this.root || p.startsWith(`${this.root}${sep}`);
       writePaths = writePaths.filter((p) => !inRoot(p));
       denyWritePaths = [this.root, ...denyWritePaths];
     }
+    const scope = !readOnlyRoot && sandbox && this.settings.writeScope !== void 0 ? { root: this.root, paths: scopePaths(this.root, this.settings.writeScope) } : void 0;
+    if (scope !== void 0) {
+      writePaths = writePaths.filter((p) => !inRoot(p));
+      const problem = prepareWriteScope(this.root, this.settings.writeScope ?? []);
+      if (problem !== void 0)
+        throw new Error(`The job's write scope cannot be used: ${problem}.`);
+    }
     return {
       root: this.root,
       sandbox,
       ...paths,
       denyReadPaths: [...paths.denyReadPaths, ...denied],
       writePaths,
+      ...scope === void 0 ? {} : { writeScope: scope },
       denyWritePaths,
       network: !sandbox,
       ...sandbox && this.network !== void 0 ? { proxy: this.network.policy } : {},
@@ -1273,6 +1547,15 @@ var PermissionEngine = class {
       maxOutputBytes: DEFAULT_MAX_OUTPUT_BYTES
     };
   }
+  /**
+   * Why a write to this path is outside the job's write scope, or undefined (no scope, or inside
+   * it). Write tools call it again just before they write (second review of 0.17): a link can
+   * change between the permission check and the write.
+   */
+  async writeScopeDenial(path) {
+    const scope = this.settings.writeScope;
+    return scope === void 0 ? void 0 : scopeDenial(this.root, path, scope);
+  }
   /** The network allowlist (0.13): the runtime sets it when the proxy runs. */
   setNetwork(network) {
     this.network = network;
@@ -1319,4 +1602,4 @@ export {
   JOB_DENIAL,
   PermissionEngine
 };
-//# sourceMappingURL=chunk-GXZACJUI.js.map
+//# sourceMappingURL=chunk-B4SJY7KT.js.map

package/dist/{chunk-3EQU2GUX.js → chunk-BHZ6G65V.js}

@@ -8,6 +8,9 @@ var ZERO_USAGE = {
   cacheReadTokens: 0,
   cacheWriteTokens: 0
 };
+function reportedUsage(response) {
+  return response.usageReported === false ? ZERO_USAGE : response.usage;
+}
 function addUsage(a, b) {
   const searches = (a.webSearches ?? 0) + (b.webSearches ?? 0);
   return {
@@ -22,6 +25,7 @@ function addUsage(a, b) {
 export {
   EFFORTS,
   ZERO_USAGE,
+  reportedUsage,
   addUsage
 };
-//# sourceMappingURL=chunk-3EQU2GUX.js.map
+//# sourceMappingURL=chunk-BHZ6G65V.js.map

package/dist/chunk-C57GHLKP.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+// src/version.ts
+var VERSION = "0.18.0";
+
+export {
+  VERSION
+};
+//# sourceMappingURL=chunk-C57GHLKP.js.map