@basein/runner 0.3.19 → 0.3.21

package/dist/record/recorder.d.ts

@@ -197,8 +197,13 @@ export declare function isRecorderHealthReporter(r: Recorder): r is Recorder & R
  * callers must stop recording it. What the caller does *instead* of recording is
  * v2's subject (docs/calculatedReplay.md); stopping is mandatory either way.
  */
-/** Which of a segment's two keys scored against the live step (R-OUT-3). */
-export type MatchKey = "intent" | "firstStep";
+/**
+ * Which of a segment's two keys scored against the live step (R-OUT-3).
+ * `decision`: no score at all — one of the calculated scenarios that can follow
+ * a plan's decision, handed out for the agent's next call (the service's
+ * offer1.md O3).
+ */
+export type MatchKey = "intent" | "firstStep" | "decision";
 /** The cheap model's answer about one live step and one segment (R-VERIFY-1). */
 export interface MatchVerdict {
     model: string;
@@ -406,6 +411,36 @@ export interface IntentMatcher {
     matchIntent(req: IntentMatchRequest, opts?: IntentMatchOptions): Promise<IntentMatchAnswer | null>;
 }
 export declare function isIntentMatcher(r: Recorder): r is Recorder & IntentMatcher;
+/** What a turn sends when a plan of it has stopped at its decision (the service's offer1.md O3). */
+export interface NextScenariosRequest {
+    /** The turn's identity, as a probe sends it (R-HIT-6). */
+    turnId?: string;
+    /** Always true from this runner (R-CALL-28). */
+    supportsCalls?: boolean;
+}
+/**
+ * One calculated scenario that can follow a plan's decision: a hand-out in the
+ * shape of a match, with its own ticket, `key: "decision"`, and the tool of its
+ * first step. The service leaves withheld ones out.
+ */
+export interface NextHandOut extends RunMatch {
+    /** The tool its first served step calls; null when the service could not say. */
+    firstTool?: string | null;
+}
+/** The service's answer: the scenarios, and where the plan's decision is. */
+export interface NextScenariosAnswer {
+    next: NextHandOut[];
+    decisionStep: number | null;
+}
+/**
+ * Optional capability: the calculated scenarios that can follow a decision
+ * (offer1.md O3) need a service. `null` is "none" — an older service (404), a
+ * cool-down, or any failure: the agent then does the work itself, as before.
+ */
+export interface NextScenarioSource {
+    nextScenarios(planId: string, req: NextScenariosRequest, opts?: IntentMatchOptions): Promise<NextScenariosAnswer | null>;
+}
+export declare function isNextScenarioSource(r: Recorder): r is Recorder & NextScenarioSource;
 /**
  * What a matched turn actually cost, reported once per match
  * (docs/calculatedReplay.md §11).

package/dist/record/recorder.js

@@ -20,6 +20,9 @@ export function isServiceProber(r) {
 export function isIntentMatcher(r) {
     return typeof r.matchIntent === "function";
 }
+export function isNextScenarioSource(r) {
+    return typeof r.nextScenarios === "function";
+}
 export function isToolListReporter(r) {
     return typeof r.reportTools === "function";
 }

package/dist/record/remote-recorder.d.ts

@@ -50,7 +50,7 @@
  */
 import { type AuthSession } from "../auth/client.js";
 import { type ServiceHealth } from "../util/service-health.js";
-import type { AnswerCall, AttentionPlan, DisputeAnswer, ExecutionReport, FlushOptions, IntentMatchAnswer, IntentMatchOptions, IntentMatchRequest, Recorder, RecorderHealth, RecorderHealthReporter, RunCreation, RunMatch, RunMetrics, StartRunOptions, StepMetadata, ToolListEntry } from "./recorder.js";
+import type { AnswerCall, AttentionPlan, DisputeAnswer, ExecutionReport, FlushOptions, IntentMatchAnswer, IntentMatchOptions, IntentMatchRequest, NextScenariosAnswer, NextScenariosRequest, Recorder, RecorderHealth, RecorderHealthReporter, RunCreation, RunMatch, RunMetrics, StartRunOptions, StepMetadata, ToolListEntry } from "./recorder.js";
 /**
  * Caps for the free text this recorder sends, in UTF-8 bytes. Tool payloads
  * arrive capped at 64 KiB by their producers; text never passed through one,
@@ -206,6 +206,14 @@ export declare class RemoteRecorder implements Recorder, RecorderHealthReporter
      * waiting, so an abandoned probe does not hold a socket for minutes.
      */
     matchIntent(req: IntentMatchRequest, opts?: IntentMatchOptions): Promise<IntentMatchAnswer | null>;
+    /**
+     * The calculated scenarios that can follow a plan's decision (the service's
+     * offer1.md O3), each handed out with a ticket of its own. Asked once per
+     * decision hand-over, while the agent decides. An older service (404), a
+     * cool-down or any failure answers null: the agent then does the work
+     * itself, exactly as before.
+     */
+    nextScenarios(planId: string, req: NextScenariosRequest, opts?: IntentMatchOptions): Promise<NextScenariosAnswer | null>;
     /**
      * The similar-prompt match for a run's create call (null = fresh run). Like
      * {@link runCreated}, answers null at once while a failure is on record —

package/dist/record/remote-recorder.js

@@ -713,6 +713,36 @@ export class RemoteRecorder {
             return null;
         }
     }
+    /**
+     * The calculated scenarios that can follow a plan's decision (the service's
+     * offer1.md O3), each handed out with a ticket of its own. Asked once per
+     * decision hand-over, while the agent decides. An older service (404), a
+     * cool-down or any failure answers null: the agent then does the work
+     * itself, exactly as before.
+     */
+    async nextScenarios(planId, req, opts = {}) {
+        try {
+            if (!this.mayHotWait())
+                return null;
+            const answer = await this.request("POST", `/scenarios/${encodeURIComponent(planId)}/next`, JSON.stringify(req), { signal: opts.signal, timeoutMs: opts.timeoutMs ?? PROBE_TIMEOUT_MS });
+            const b = answer && typeof answer === "object" ? answer : {};
+            const next = Array.isArray(b.next)
+                ? b.next.filter((n) => !!n && typeof n === "object" && typeof n.scenarioId === "string")
+                : [];
+            return { next, decisionStep: typeof b.decisionStep === "number" ? b.decisionStep : null };
+        }
+        catch (err) {
+            if (!opts.signal?.aborted) {
+                logEvery("recorder.next_scenarios_failed", 30_000, "replay.next_failed", {
+                    error: errText(err),
+                    why: err instanceof ServiceError && err.status === 404
+                        ? "the service has no next scenarios — an older service, or not this account's plan"
+                        : "no next scenarios this time — the agent does the work after the decision",
+                });
+            }
+            return null;
+        }
+    }
     /**
      * The similar-prompt match for a run's create call (null = fresh run). Like
      * {@link runCreated}, answers null at once while a failure is on record —

package/dist/record/switchable-recorder.js

@@ -49,6 +49,8 @@ const NEUTRAL = {
     settledMatch: () => Promise.resolve(null),
     runCreated: () => Promise.resolve({ created: true }),
     matchIntent: () => Promise.resolve(null),
+    // Signed out: no scenario follows a decision (offer1.md O3); the agent goes on.
+    nextScenarios: () => Promise.resolve(null),
     reportExecution: () => undefined,
     backfillContext: () => undefined,
     probeIfFailing: () => undefined,

package/dist/replay/builtins.d.ts

@@ -5,7 +5,7 @@
  * A built-in lives inside the host session, not behind any MCP server, so there
  * is no proxy to relay it to: historically every built-in step threw `not_run`
  * and the plan handed the task back to the model. This module is the other
- * option: execute the step here, against the *session's own project directory*,
+ * option: execute the step here, from the *session's own project directory*,
  * so a chain that starts with a `Read` no longer costs a hand-over.
  *
  * THE RULES, because this bypasses the host's permission prompts entirely:
@@ -17,10 +17,17 @@
  *     already has — its pinned call is answered `allow` too. What running it
  *     here changes is that no model sees the call before it runs, so an
  *     operator who wants one in the loop takes the tool off the list.
- *   - **Path jail.** Every path is resolved against, and confined to, the
- *     session's project directory ({@link jailed}), symlinks included. The
- *     daemon's own cwd is never used: it is `~/.baseinstrunner`, not the
- *     project (§5.1 of the change plan).
+ *   - **Any path the agent could reach, unless `BIR_PATH_ALLOW` narrows it.**
+ *     A relative path resolves against the session's project directory, as
+ *     the host's tools resolve it; the daemon's own cwd is never used: it is
+ *     `~/.baseinstrunner`, not the project (§5.1 of the change plan). An
+ *     absolute path is taken as it is, inside the project or not: the agent's
+ *     own tools reach any folder its session allows — the recorded call was
+ *     one of them — and a runner-side `Bash` reaches any folder already. Up
+ *     to 0.3.20 every path was confined to the project directory;
+ *     `BIR_PATH_ALLOW=project` brings that back, and a list of folders
+ *     ({@link parsePathAllow}) confines the file tools to those, symlinks
+ *     included ({@link allowedPath}).
  *   - **Bash runs any command unless `BIR_BASH_ALLOW` narrows it.** Set, a
  *     command must match one of its prefixes ({@link bashAllowed}); `none`
  *     allows no command, and then `Bash` counts as off the list, so its steps
@@ -48,6 +55,12 @@ export declare const EXECUTABLE_BUILTINS: ReadonlySet<string>;
  * set (`Read,Glob,Grep`).
  */
 export declare const DEFAULT_BUILTIN_TOOLS: readonly string[];
+/**
+ * The built-ins that reach files by a path, the ones `BIR_PATH_ALLOW`
+ * governs. `Bash` is not among them: what a command touches is
+ * `BIR_BASH_ALLOW`'s business.
+ */
+export declare const FILE_BUILTINS: ReadonlySet<string>;
 /**
  * Parse `BIR_BUILTIN_TOOLS`. Unset means {@link DEFAULT_BUILTIN_TOOLS}; set,
  * it is the whole list — `none` (or an empty value) turns built-ins off
@@ -63,6 +76,19 @@ export declare function parseBuiltinTools(value: string | undefined): ReadonlySe
  * value) allows no command.
  */
 export declare function parseBashAllow(value: string | undefined): readonly string[];
+/**
+ * Parse `BIR_PATH_ALLOW`: the folders a runner-side `Read`, `Glob`, `Grep`,
+ * `Edit` or `Write` may touch, comma-separated, `*` for anywhere. Unset means
+ * anywhere, as the agent's own tools reach any folder its session allows (up
+ * to 0.3.20 it was the project directory alone). In a list, `project` is the
+ * session's project directory, `~` the home folder (`~/.claude` a folder in
+ * it), and any other relative folder resolves against the project directory.
+ * Set, it is the whole list, as `BIR_BASH_ALLOW` is: `none` (or an empty
+ * value) allows no folder, and the file tools then count as off
+ * `BIR_BUILTIN_TOOLS`, so their steps are steered in the session
+ * (controller.ts).
+ */
+export declare function parsePathAllow(value: string | undefined): readonly string[];
 /**
  * Whether `command` matches the `BIR_BASH_ALLOW` prefixes. A prefix that ends
  * mid-word must end the command's word too: `git` allows `git status` and
@@ -72,8 +98,9 @@ export declare function parseBashAllow(value: string | undefined): readonly stri
 export declare function bashAllowed(command: string, allow: readonly string[] | undefined): boolean;
 /**
  * The step cannot run here — policy, not breakage: the tool is not
- * implemented, its path leaves the project, `Bash` is not allowed, or the
- * input is not even the right shape. Maps to `not_run`: nothing happened, the
+ * implemented, its path is outside the folders `BIR_PATH_ALLOW` names, the
+ * command is not one `BIR_BASH_ALLOW` allows, or the input is not even the
+ * right shape. Maps to `not_run`: nothing happened, the
  * session may still do it, a recorded output may stand in.
  */
 export declare class BuiltinNotRunnable extends Error {
@@ -90,8 +117,9 @@ export declare class BuiltinTimeout extends Error {
 }
 export interface BuiltinContext {
     /**
-     * The session's project directory — the jail every path resolves against.
-     * The caller (controller.ts) refuses to execute at all without one; the
+     * The session's project directory — what a relative path resolves
+     * against, and the folder `project` names in {@link pathAllow}. The
+     * caller (controller.ts) refuses to execute at all without one; the
      * daemon's own cwd is never a substitute.
      */
     cwd: string;
@@ -99,6 +127,14 @@ export interface BuiltinContext {
     timeoutMs?: number;
     /** Parsed `BIR_BASH_ALLOW` ({@link parseBashAllow}). Absent or empty, no command runs. */
     bashAllow?: readonly string[];
+    /**
+     * Parsed `BIR_PATH_ALLOW` ({@link parsePathAllow}): the folders a file
+     * step may touch, `*` for any. Absent means the project directory alone —
+     * a caller that says nothing gets the narrow answer, as with
+     * {@link bashAllow}; the controller always passes the environment's, which
+     * is `*` when the variable is unset. Empty, no file step runs.
+     */
+    pathAllow?: readonly string[];
     /**
      * Where this plan's *previous* `Bash` step left its shell — the host's own
      * semantics, which a recorded chain was written against: the working

package/dist/replay/builtins.js

@@ -5,7 +5,7 @@
  * A built-in lives inside the host session, not behind any MCP server, so there
  * is no proxy to relay it to: historically every built-in step threw `not_run`
  * and the plan handed the task back to the model. This module is the other
- * option: execute the step here, against the *session's own project directory*,
+ * option: execute the step here, from the *session's own project directory*,
  * so a chain that starts with a `Read` no longer costs a hand-over.
  *
  * THE RULES, because this bypasses the host's permission prompts entirely:
@@ -17,10 +17,17 @@
  *     already has — its pinned call is answered `allow` too. What running it
  *     here changes is that no model sees the call before it runs, so an
  *     operator who wants one in the loop takes the tool off the list.
- *   - **Path jail.** Every path is resolved against, and confined to, the
- *     session's project directory ({@link jailed}), symlinks included. The
- *     daemon's own cwd is never used: it is `~/.baseinstrunner`, not the
- *     project (§5.1 of the change plan).
+ *   - **Any path the agent could reach, unless `BIR_PATH_ALLOW` narrows it.**
+ *     A relative path resolves against the session's project directory, as
+ *     the host's tools resolve it; the daemon's own cwd is never used: it is
+ *     `~/.baseinstrunner`, not the project (§5.1 of the change plan). An
+ *     absolute path is taken as it is, inside the project or not: the agent's
+ *     own tools reach any folder its session allows — the recorded call was
+ *     one of them — and a runner-side `Bash` reaches any folder already. Up
+ *     to 0.3.20 every path was confined to the project directory;
+ *     `BIR_PATH_ALLOW=project` brings that back, and a list of folders
+ *     ({@link parsePathAllow}) confines the file tools to those, symlinks
+ *     included ({@link allowedPath}).
  *   - **Bash runs any command unless `BIR_BASH_ALLOW` narrows it.** Set, a
  *     command must match one of its prefixes ({@link bashAllowed}); `none`
  *     allows no command, and then `Bash` counts as off the list, so its steps
@@ -43,7 +50,8 @@ import { execFile } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import { existsSync } from "node:fs";
 import { readdir, readFile, realpath, stat, writeFile } from "node:fs/promises";
-import { dirname, join, resolve, sep } from "node:path";
+import { homedir } from "node:os";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
 // ── configuration ────────────────────────────────────────────────────────────
 /** The built-ins {@link runBuiltin} actually implements. */
 export const EXECUTABLE_BUILTINS = new Set([
@@ -61,8 +69,24 @@ export const EXECUTABLE_BUILTINS = new Set([
  * set (`Read,Glob,Grep`).
  */
 export const DEFAULT_BUILTIN_TOOLS = [...EXECUTABLE_BUILTINS];
+/**
+ * The built-ins that reach files by a path, the ones `BIR_PATH_ALLOW`
+ * governs. `Bash` is not among them: what a command touches is
+ * `BIR_BASH_ALLOW`'s business.
+ */
+export const FILE_BUILTINS = new Set(["Read", "Glob", "Grep", "Edit", "Write"]);
 /** `read` → `Read`: the vocabulary is small enough to forgive casing. */
 const CANONICAL_BUILTIN = new Map([...EXECUTABLE_BUILTINS].map((name) => [name.toLowerCase(), name]));
+/**
+ * A switch's list once it is set: comma-separated, trimmed, empty entries
+ * dropped, and `none` / `off` / `0` meaning nothing at all.
+ */
+function parseList(value) {
+    return value
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0 && !["none", "off", "0"].includes(s.toLowerCase()));
+}
 /**
  * Parse `BIR_BUILTIN_TOOLS`. Unset means {@link DEFAULT_BUILTIN_TOOLS}; set,
  * it is the whole list — `none` (or an empty value) turns built-ins off
@@ -73,12 +97,7 @@ const CANONICAL_BUILTIN = new Map([...EXECUTABLE_BUILTINS].map((name) => [name.t
 export function parseBuiltinTools(value) {
     if (value === undefined)
         return new Set(DEFAULT_BUILTIN_TOOLS);
-    const names = value
-        .split(",")
-        .map((s) => s.trim())
-        .filter((s) => s.length > 0 && !["none", "off", "0"].includes(s.toLowerCase()))
-        .map((s) => CANONICAL_BUILTIN.get(s.toLowerCase()) ?? s);
-    return new Set(names);
+    return new Set(parseList(value).map((s) => CANONICAL_BUILTIN.get(s.toLowerCase()) ?? s));
 }
 /**
  * Parse `BIR_BASH_ALLOW`: comma-separated command prefixes, `*` for
@@ -89,10 +108,24 @@ export function parseBuiltinTools(value) {
 export function parseBashAllow(value) {
     if (value === undefined)
         return ["*"];
-    return value
-        .split(",")
-        .map((s) => s.trim())
-        .filter((s) => s.length > 0 && !["none", "off", "0"].includes(s.toLowerCase()));
+    return parseList(value);
+}
+/**
+ * Parse `BIR_PATH_ALLOW`: the folders a runner-side `Read`, `Glob`, `Grep`,
+ * `Edit` or `Write` may touch, comma-separated, `*` for anywhere. Unset means
+ * anywhere, as the agent's own tools reach any folder its session allows (up
+ * to 0.3.20 it was the project directory alone). In a list, `project` is the
+ * session's project directory, `~` the home folder (`~/.claude` a folder in
+ * it), and any other relative folder resolves against the project directory.
+ * Set, it is the whole list, as `BIR_BASH_ALLOW` is: `none` (or an empty
+ * value) allows no folder, and the file tools then count as off
+ * `BIR_BUILTIN_TOOLS`, so their steps are steered in the session
+ * (controller.ts).
+ */
+export function parsePathAllow(value) {
+    if (value === undefined)
+        return ["*"];
+    return parseList(value);
 }
 /**
  * Whether `command` matches the `BIR_BASH_ALLOW` prefixes. A prefix that ends
@@ -117,8 +150,9 @@ export function bashAllowed(command, allow) {
 // ── the failure contract ─────────────────────────────────────────────────────
 /**
  * The step cannot run here — policy, not breakage: the tool is not
- * implemented, its path leaves the project, `Bash` is not allowed, or the
- * input is not even the right shape. Maps to `not_run`: nothing happened, the
+ * implemented, its path is outside the folders `BIR_PATH_ALLOW` names, the
+ * command is not one `BIR_BASH_ALLOW` allows, or the input is not even the
+ * right shape. Maps to `not_run`: nothing happened, the
  * session may still do it, a recorded output may stand in.
  */
 export class BuiltinNotRunnable extends Error {
@@ -186,7 +220,9 @@ export async function runBuiltin(toolName, input, ctx) {
             throw new BuiltinNotRunnable(`no runner-side implementation for ${toolName}`);
     }
 }
-// ── the path jail ────────────────────────────────────────────────────────────
+// ── which paths a file step may touch ────────────────────────────────────────
+/** The word in `BIR_PATH_ALLOW` that stands for the session's project directory. */
+const PROJECT_WORD = "project";
 /** Case-blind on Windows, where `C:\Repo` and `c:\repo` are one directory. */
 function samePath(a, b) {
     return process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b;
@@ -199,54 +235,87 @@ function underRoot(root, abs) {
             : abs.startsWith(prefix)));
 }
 /**
- * Resolve `p` against the session root and refuse anything outside it — first
- * textually, then through `realpath` so a symlink inside the project cannot
- * point the step at a file beyond it. The nearest existing ancestor is what
- * gets resolved, so a `Write` to a new file is judged by its real directory.
+ * The folders the context's `BIR_PATH_ALLOW` list names, as absolute paths,
+ * or `anywhere` for `*`. `project` is the session's project directory, `~`
+ * the home folder, and any other relative entry resolves against the project.
  */
-async function jailed(root, p, what = "file_path") {
-    if (typeof p !== "string" || p.trim() === "") {
-        throw new BuiltinNotRunnable(`${what} is required`);
-    }
-    const r = resolve(root);
-    const abs = resolve(r, p);
-    const outside = () => {
-        throw new BuiltinNotRunnable(`${p} is outside the session's project directory, so bir does not touch it unattended`);
-    };
-    if (!underRoot(r, abs))
-        outside();
-    // The textual check passed; now the physical one. Walk up to what exists,
-    // realpath it, and require *that* to sit under the root's own realpath.
+function allowedFolders(ctx) {
+    const allow = ctx.pathAllow ?? [PROJECT_WORD];
+    if (allow.includes("*"))
+        return "anywhere";
+    const project = resolve(ctx.cwd);
+    return allow.map((entry) => {
+        if (entry.toLowerCase() === PROJECT_WORD)
+            return project;
+        if (entry === "~")
+            return homedir();
+        if (entry.startsWith("~/") || entry.startsWith("~\\"))
+            return resolve(homedir(), entry.slice(2));
+        return resolve(project, entry);
+    });
+}
+/** Why a path was refused, naming the switch that refused it. */
+function outsideMessage(p, allow) {
+    return allow.length === 1 && allow[0].toLowerCase() === PROJECT_WORD
+        ? `${p} is outside the session's project directory, and BIR_PATH_ALLOW=project keeps bir inside it`
+        : `${p} is outside the folders BIR_PATH_ALLOW names (${allow.join(", ")}), so bir does not touch it unattended`;
+}
+/**
+ * `abs` as it is on disk: its longest existing ancestor replaced by that
+ * ancestor's realpath (symlinks resolved, and on macOS `/var` read as
+ * `/private/var`), the rest kept as written. A path none of which exists
+ * comes back as it is.
+ */
+async function physical(abs) {
     let probe = abs;
-    let real;
+    const rest = [];
     for (;;) {
         try {
-            real = await realpath(probe);
-            break;
+            const real = await realpath(probe);
+            return rest.length > 0 ? join(real, ...rest.reverse()) : real;
         }
         catch {
             const parent = dirname(probe);
             if (samePath(parent, probe))
-                break; // hit the filesystem root: nothing exists
+                return abs; // the filesystem root: nothing exists
+            rest.push(basename(probe));
             probe = parent;
         }
     }
-    if (real !== undefined) {
-        let realRoot;
-        try {
-            realRoot = await realpath(r);
-        }
-        catch {
-            throw new BuiltinNotRunnable(`the session's project directory does not exist: ${root}`);
-        }
-        if (!underRoot(realRoot, real))
-            outside();
+}
+/**
+ * Resolve `p` as the host does — against the session's project directory
+ * when it is relative — and allow it anywhere, as the agent's own tools
+ * would, unless `BIR_PATH_ALLOW` names folders. Then anything outside them is
+ * refused: first as written, then physically ({@link physical}, both sides),
+ * so a symlink inside an allowed folder cannot point the step at a file
+ * beyond it, and a `Write` to a new file is judged by its real folder.
+ */
+async function allowedPath(ctx, p, what = "file_path") {
+    if (typeof p !== "string" || p.trim() === "") {
+        throw new BuiltinNotRunnable(`${what} is required`);
     }
+    const abs = resolve(ctx.cwd, p);
+    const folders = allowedFolders(ctx);
+    if (folders === "anywhere")
+        return abs;
+    if (folders.length === 0) {
+        throw new BuiltinNotRunnable("BIR_PATH_ALLOW allows no folder, so bir touches no file unattended");
+    }
+    const outside = () => {
+        throw new BuiltinNotRunnable(outsideMessage(p, ctx.pathAllow ?? [PROJECT_WORD]));
+    };
+    if (!folders.some((folder) => underRoot(folder, abs)))
+        outside();
+    const real = await physical(abs);
+    const realFolders = await Promise.all(folders.map(physical));
+    if (!realFolders.some((folder) => underRoot(folder, real)))
+        outside();
     return abs;
 }
 // ── Read ─────────────────────────────────────────────────────────────────────
 async function runRead(input, ctx) {
-    const filePath = await jailed(ctx.cwd, input.file_path);
+    const filePath = await allowedPath(ctx, input.file_path);
     const size = (await stat(filePath)).size;
     if (size > MAX_FILE_BYTES) {
         throw new Error(`file is ${size} bytes, more than the ${MAX_FILE_BYTES} this runner reads`);
@@ -276,7 +345,7 @@ async function runGlob(input, ctx, deadline) {
     if (typeof pattern !== "string" || pattern.trim() === "") {
         throw new BuiltinNotRunnable("pattern is required");
     }
-    const root = await jailed(ctx.cwd, typeof input.path === "string" ? input.path : ".", "path");
+    const root = await allowedPath(ctx, typeof input.path === "string" ? input.path : ".", "path");
     const startedAt = Date.now();
     const re = globToRegExp(pattern);
     const found = [];
@@ -324,7 +393,7 @@ async function runGrep(input, ctx, deadline) {
     catch (err) {
         throw new BuiltinNotRunnable(`the pattern is not a regular expression this runner can run: ${err.message}`);
     }
-    const target = await jailed(ctx.cwd, typeof input.path === "string" ? input.path : ".", "path");
+    const target = await allowedPath(ctx, typeof input.path === "string" ? input.path : ".", "path");
     // ripgrep's `-g '*.ts'` matches the basename at any depth; only a pattern
     // with a `/` in it speaks about the path.
     const globRe = typeof input.glob === "string" && input.glob
@@ -417,7 +486,7 @@ async function matchFile(path, re, firstOnly) {
 }
 // ── Edit / Write ─────────────────────────────────────────────────────────────
 async function runEdit(input, ctx) {
-    const filePath = await jailed(ctx.cwd, input.file_path);
+    const filePath = await allowedPath(ctx, input.file_path);
     const oldString = input.old_string;
     const newString = input.new_string;
     if (typeof oldString !== "string" || oldString === "") {
@@ -452,7 +521,7 @@ async function runEdit(input, ctx) {
     };
 }
 async function runWrite(input, ctx) {
-    const filePath = await jailed(ctx.cwd, input.file_path);
+    const filePath = await allowedPath(ctx, input.file_path);
     const content = input.content;
     if (typeof content !== "string")
         throw new BuiltinNotRunnable("content is required");
@@ -579,9 +648,10 @@ function takePwdMarker(stderr, mark) {
 const SKIP_DIRS = new Set([".git", "node_modules", ".hg", ".svn"]);
 /**
  * Walk `root`, calling `visit(relativePath, absolutePath, mtimeMs)` for every
- * regular file. Never follows directory symlinks — the jail was checked at
- * the root, and a link out of it must not re-open the door. Returns whether
- * the walk was cut short (entry cap, deadline, or `visit` saying stop).
+ * regular file. Never follows directory symlinks — the folder was checked at
+ * the root, and under a `BIR_PATH_ALLOW` list a link out of it must not
+ * re-open the door (nor may a link loop the walk). Returns whether the walk
+ * was cut short (entry cap, deadline, or `visit` saying stop).
  */
 async function walk(root, deadline, visit) {
     let seen = 0;
@@ -617,7 +687,9 @@ async function walk(root, deadline, visit) {
             catch {
                 continue;
             }
-            const rel = abs.slice(resolve(root).length + 1).split(sep).join("/");
+            // `relative`, not a slice: a walk may now start at a drive's or the
+            // disk's root (`C:\`, `/`), which already ends in a separator.
+            const rel = relative(root, abs).split(sep).join("/");
             if (!visit(rel, abs, mtime))
                 return true;
         }

package/dist/replay/controller.d.ts

@@ -266,6 +266,16 @@ export interface ReplayOptions {
      * rather than armed `direct` and stopped at the first one.
      */
     bashAllow?: readonly string[];
+    /**
+     * `BIR_PATH_ALLOW` — the folders a runner-side `Read`, `Glob`, `Grep`,
+     * `Edit` or `Write` may touch (`*` for any; `project` is the session's
+     * project directory). Omitted, the environment decides; the default is
+     * `*`, any path the agent's own tools could reach (up to 0.3.20 the
+     * project directory alone). Empty allows no folder, and then the file tools
+     * count as off {@link ReplayOptions.builtinTools}, as `Bash` does under an
+     * empty {@link ReplayOptions.bashAllow}.
+     */
+    pathAllow?: readonly string[];
     budgets?: Partial<ReplayBudgets>;
     /**
      * The service: the lazy source-run fetch, and the parameter derivation this
@@ -418,8 +428,9 @@ export interface ReplayState {
     /**
      * That session's project directory, set by the control server from the
      * hook payloads — never the daemon's own cwd, which is `~/.baseinstrunner`.
-     * It is where an allow-listed built-in step executes and the jail it may
-     * not leave (replay/builtins.ts). Absent — `bir replay`, an older server —
+     * It is where an allow-listed built-in step executes and what its relative
+     * paths resolve against (replay/builtins.ts; `BIR_PATH_ALLOW=project`
+     * confines the file tools to it). Absent — `bir replay`, an older server —
      * no built-in executes: the step is `not_run`, exactly as before.
      */
     sessionCwd?: string;
@@ -689,6 +700,8 @@ export declare class ReplayController {
     private readonly builtinTools;
     /** See {@link ReplayOptions.bashAllow}. */
     private readonly bashAllow;
+    /** See {@link ReplayOptions.pathAllow}. */
+    private readonly pathAllow;
     /** Calls waiting for a plan's pins to change (see `awaitPins`). */
     private readonly pinWaiters;
     /**