@celestea/tools 2.7.1

package/dist/fs/file-io.js

@@ -0,0 +1,239 @@
+/**
+ * File IO for `read_file` / `write_file` / `list_dir`, with the two protections
+ * the tool contract promises: **truncation** (a bounded read keeps a huge file
+ * from flooding the context) and **binary protection** (a NUL-bearing file is
+ * rejected instead of being decoded into mojibake).
+ *
+ * The guard already arbitrated *where* the path may point; this module only
+ * performs the IO and reports structured failures (`<tool>: code=… msg="…"`).
+ */
+import { open, readdir, writeFile } from "node:fs/promises";
+import { contractError } from "../errors.js";
+import { ToolFailure } from "../tool-failure.js";
+/** Bytes returned by one `read_file` call (beyond this: `truncated`). */
+export const MAX_READ_BYTES = 256 * 1024;
+/** Entry names returned by one `list_dir` call. */
+export const MAX_DIR_ENTRIES = 1000;
+/** Window inspected for the binary heuristic. */
+export const BINARY_SNIFF_BYTES = 8192;
+/** Default `limit` (lines) for a paged `read_file` when only `offset` is given. */
+export const DEFAULT_READ_LIMIT = 2000;
+/** Bytes read per streaming chunk by `readTextLines`. */
+const READ_CHUNK_BYTES = 64 * 1024;
+/** NUL byte inside the sniff window ⇒ binary (the classic, cheap heuristic). */
+export function isProbablyBinary(bytes) {
+    const window = bytes.subarray(0, BINARY_SNIFF_BYTES);
+    return window.includes(0);
+}
+export async function readTextFile(path) {
+    let handle;
+    try {
+        handle = await open(path, "r");
+    }
+    catch (e) {
+        throw ioFailure("read_file", "io", describe(e));
+    }
+    try {
+        const stat = await handle.stat();
+        if (stat.isDirectory())
+            throw ioFailure("read_file", "io", `'${path}' is a directory, not a file`);
+        const wanted = Math.min(MAX_READ_BYTES + 1, Math.max(stat.size, 1));
+        const buffer = Buffer.alloc(wanted);
+        const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+        const bytes = buffer.subarray(0, bytesRead);
+        if (isProbablyBinary(bytes)) {
+            throw ioFailure("read_file", "binary_file", `'${path}' looks binary (NUL byte in the first ${BINARY_SNIFF_BYTES} bytes)`);
+        }
+        const truncated = bytesRead > MAX_READ_BYTES || stat.size > MAX_READ_BYTES;
+        return { text: bytes.subarray(0, MAX_READ_BYTES).toString("utf8"), truncated, totalBytes: stat.size };
+    }
+    catch (e) {
+        throw e instanceof ToolFailure ? e : ioFailure("read_file", "io", describe(e));
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+}
+/** Accumulates one line window under the byte budget (read_file pagination). */
+class LineWindow {
+    captured = [];
+    capturedBytes = 0;
+    offset;
+    limit;
+    lineCount = 0;
+    totalLines = 0;
+    truncated = false;
+    constructor(offset, limit) {
+        this.offset = offset;
+        this.limit = limit;
+    }
+    /** Admit one line unit (its bytes including the trailing `\n`, when present). */
+    admit(unit) {
+        this.totalLines += 1;
+        const index = this.totalLines - 1;
+        if (index < this.offset || this.lineCount >= this.limit || this.truncated)
+            return;
+        if (this.capturedBytes + unit.length <= MAX_READ_BYTES) {
+            this.captured.push(unit);
+            this.capturedBytes += unit.length;
+            this.lineCount += 1;
+            return;
+        }
+        if (this.lineCount === 0) {
+            const prefix = utf8WholePrefix(unit, MAX_READ_BYTES);
+            if (prefix.length > 0) {
+                this.captured.push(prefix);
+                this.capturedBytes += prefix.length;
+                this.lineCount += 1;
+            }
+        }
+        this.truncated = true;
+    }
+    text() {
+        return Buffer.concat(this.captured).toString("utf8");
+    }
+}
+/**
+ * Feed one buffered chunk through the window; complete line units go to
+ * `admit`, the unterminated tail is returned as the carry. A tail larger than
+ * the budget with no terminator is itself an over-budget line: admit it and
+ * flag that the remainder of the line is discarded.
+ */
+function drainUnits(data, window, state) {
+    let start = 0;
+    for (;;) {
+        const nl = data.indexOf(0x0a, start);
+        if (nl === -1)
+            break;
+        if (state.discarding)
+            state.discarding = false; // this terminator closes the over-budget line
+        else
+            window.admit(data.subarray(start, nl + 1));
+        start = nl + 1;
+    }
+    let tail = data.subarray(start);
+    if (!state.discarding && tail.length > MAX_READ_BYTES) {
+        window.admit(tail);
+        state.discarding = true;
+        tail = Buffer.alloc(0);
+    }
+    return tail;
+}
+/**
+ * Line-window read for `read_file` pagination (W846).
+ *
+ * A SINGLE streaming pass from byte 0: `readTextFile` only ever returns the
+ * first MAX_READ_BYTES from offset 0, so an `offset` past that window needs its
+ * own reader. The window itself is bounded by MAX_READ_BYTES; `totalLines`
+ * costs a scan to EOF (O(file size)) and is the price of exact
+ * `hasMore`/`nextOffset`. `truncated` means the byte budget clipped the window
+ * before `limit` lines; a line larger than the budget is returned as a
+ * UTF-8-safe prefix and `nextOffset` skips past it (use run_shell for such a
+ * pathological line).
+ */
+export async function readTextLines(path, offset, limit) {
+    let handle;
+    try {
+        handle = await open(path, "r");
+    }
+    catch (e) {
+        throw ioFailure("read_file", "io", describe(e));
+    }
+    try {
+        const stat = await handle.stat();
+        if (stat.isDirectory())
+            throw ioFailure("read_file", "io", `'${path}' is a directory, not a file`);
+        const totalBytes = stat.size;
+        // Binary protection first: a NUL in the sniff window rejects before windowing.
+        const sniffLen = Math.min(BINARY_SNIFF_BYTES, totalBytes);
+        if (sniffLen > 0) {
+            const sniff = Buffer.alloc(sniffLen);
+            const { bytesRead } = await handle.read(sniff, 0, sniffLen, 0);
+            if (isProbablyBinary(sniff.subarray(0, bytesRead))) {
+                throw ioFailure("read_file", "binary_file", `'${path}' looks binary (NUL byte in the first ${BINARY_SNIFF_BYTES} bytes)`);
+            }
+        }
+        const window = new LineWindow(offset, limit);
+        const state = { discarding: false };
+        let position = 0;
+        let carry = Buffer.alloc(0);
+        for (;;) {
+            const chunk = Buffer.alloc(READ_CHUNK_BYTES);
+            const { bytesRead } = await handle.read(chunk, 0, chunk.length, position);
+            if (bytesRead === 0)
+                break;
+            position += bytesRead;
+            const data = carry.length === 0 ? chunk.subarray(0, bytesRead) : Buffer.concat([carry, chunk.subarray(0, bytesRead)]);
+            carry = drainUnits(data, window, state);
+        }
+        if (carry.length > 0 && !state.discarding)
+            window.admit(carry);
+        const hasMore = window.totalLines > offset + window.lineCount;
+        return {
+            text: window.text(),
+            offset,
+            limit,
+            lineCount: window.lineCount,
+            totalLines: window.totalLines,
+            hasMore,
+            nextOffset: hasMore ? offset + window.lineCount : null,
+            truncated: window.truncated,
+            totalBytes,
+        };
+    }
+    catch (e) {
+        throw e instanceof ToolFailure ? e : ioFailure("read_file", "io", describe(e));
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+}
+/** Longest prefix of `buf` no longer than `max` that ends on a UTF-8 boundary. */
+function utf8WholePrefix(buf, max) {
+    if (buf.length <= max)
+        return buf;
+    let end = max;
+    while (end > 0 && ((buf[end] ?? 0) & 0xc0) === 0x80)
+        end -= 1;
+    return buf.subarray(0, end);
+}
+export async function writeTextFile(path, content) {
+    try {
+        await writeFile(path, content, "utf8");
+    }
+    catch (e) {
+        throw ioFailure("write_file", "io", describe(e));
+    }
+}
+export async function listDirNames(path) {
+    let entries;
+    try {
+        entries = await readdir(path);
+    }
+    catch (e) {
+        throw ioFailure("list_dir", "io", describe(e));
+    }
+    entries.sort();
+    return { names: entries.slice(0, MAX_DIR_ENTRIES), truncated: entries.length > MAX_DIR_ENTRIES, total: entries.length };
+}
+/**
+ * The authored omission note (W855).
+ *
+ * Discipline: this note — and every `truncated` flag it accompanies — means THE
+ * BUDGET kept obtainable content out. An upstream that returned an incomplete
+ * body is a different fact and keeps its own domain field; it must never be
+ * described by this note.
+ *
+ * The omission is ALWAYS paired with a retrieval instruction (`retrieve`), so
+ * the model is never told "there was more" without being told how to get it.
+ */
+export function truncationNote(what, shown, total, unit, retrieve) {
+    const base = "[truncated] " + what + ": showing first " + String(shown) + " of " + String(total) + " " + unit + " (budget)";
+    return retrieve === "" ? base : base + "; " + retrieve;
+}
+function ioFailure(tool, code, message) {
+    return new ToolFailure(code, contractError(tool, code, message));
+}
+function describe(e) {
+    return e instanceof Error ? e.message : String(e);
+}

package/dist/guard/path-guard.d.ts

@@ -0,0 +1,144 @@
+/**
+ * The production path-whitelist guard (`crates/tools/src/guard.rs`).
+ *
+ * Policy:
+ * - the **workspace** (`CELESTEA_TOOL_WORKDIR`, default: process cwd) is the
+ *   only writable root — W768: for a composed SESSION it is that session's own
+ *   workspace root (passed as a [SessionFsScope]), because a process serves many
+ *   sessions and one env knob cannot be all of their workspaces;
+ * - `CELESTEA_TOOL_ROOTS` is a comma-separated list of extra READ roots
+ *   (whitelist roots are read-only: the workspace is the writable subset);
+ * - **argument-driven, never a name whitelist (W738 P1)**: the guard inspects the
+ *   ARGUMENTS of the call. Any tool whose arguments carry a path-like value (see
+ *   [PATH_ARG_KEYS]) is arbitrated; [PATH_ACCESS] only declares *which* access a
+ *   **known** tool needs — `read` (`read_file`, `list_dir`), `write`
+ *   (`write_file`), or `self` for the tools that carry their own confinement
+ *   layer (`run_shell`: the sandbox root; `spawn_worker`: the host-side session
+ *   RPC). A tool that is NOT declared is checked as a **write**: it may only
+ *   touch the writable roots. A newly registered tool is therefore constrained
+ *   by default and can never be fail-OPEN just because nobody added it to a
+ *   list;
+ * - a missing/ill-typed path argument passes through: the tool's own validation
+ *   reports it, the guard only arbitrates real paths.
+ *
+ * **Fail closed**: when `CELESTEA_TOOL_ROOTS` is set but an entry cannot be used
+ * (missing, not a directory, unlistable), the policy denies every path-bearing
+ * call with `code=tool_roots_invalid` instead of silently ignoring the entry —
+ * an operator typo must never quietly widen or narrow access.
+ *
+ * `CELESTEA_TOOL_GUARD=0` skips *mounting* the chain (explicit escape hatch; it
+ * never weakens the http policy or the sandbox).
+ *
+ * W516 (session grants): a host may pass a [PathGuardGrants] view with extra
+ * read/write roots read from the session's `grants.json`. Grants are strictly
+ * ADDITIVE — the workspace stays writable, env read roots stay read-only, the
+ * mount decision is untouched — and a bad grant root is dropped by the host
+ * (ignore-the-entry), the exact opposite of the env fail-closed rule above.
+ * Both policies are deliberate: env is the operator's posture (a typo must be
+ * loud), grants are a per-session widening (ignoring one falls back to least
+ * privilege, and a hard failure would only push users to `CELESTEA_TOOL_GUARD=0`).
+ */
+import type { ToolDecision, ToolGuard, ToolInput, ToolRegistry } from "@celestea/core";
+import type { SessionFsScope } from "../sandbox/config.js";
+export declare const ENV_TOOL_ROOTS = "CELESTEA_TOOL_ROOTS";
+export declare const ENV_TOOL_WORKDIR = "CELESTEA_TOOL_WORKDIR";
+export declare const ENV_TOOL_GUARD = "CELESTEA_TOOL_GUARD";
+export declare const GUARD_ERROR_PREFIX = "toolguard";
+/** Access a tool needs to its path-like arguments. */
+export type PathAccess = "read" | "write" | "self";
+/**
+ * Declared access per **known** tool (W738 P1). `self` = the tool confines the
+ * path in its own layer, so this guard stays out of the way. Everything absent
+ * from this map is treated as `write` (the fail-closed floor), NOT as `allow`.
+ */
+export declare const PATH_ACCESS: ReadonlyMap<string, PathAccess>;
+/**
+ * Argument names carrying a path. Deliberately argument-based: a new tool with a
+ * `path`/`dir`/`workspace` argument is arbitrated without any registration step.
+ */
+export declare const PATH_ARG_KEYS: readonly string[];
+/**
+ * Split a root list (platform separator or comma; empty entries skipped).
+ *
+ * W885: the separator is resolved from the INJECTED platform (default: the
+ * host), so a win32 test proves a drive letter survives the split instead of
+ * being cut at its colon.
+ */
+export declare function parseToolRoots(value: string | undefined, platform?: string): string[];
+export interface PathGuardPolicyInit {
+    workspace: string;
+    readRoots?: readonly string[];
+    /**
+     * Extra WRITABLE roots (session grants only, W516). The workspace is always a
+     * writable root and can never be removed: grants only ADD roots.
+     */
+    writeRoots?: readonly string[];
+    /** W9: false = a read-only permission; the workspace is NOT a write root. */
+    workspaceWritable?: boolean;
+    /** Set when the declared roots were unusable → every path call is denied. */
+    failClosedReason?: string | null;
+}
+/**
+ * Session-grant view of the path policy (W516). Structural on purpose: the
+ * tools package never imports the host's grants module. Both lists are already
+ * validated + canonicalized by the host (`effectiveGrantsOf`), and neither can
+ * *narrow* anything — they are appended to the env-derived roots.
+ */
+export interface PathGuardGrants {
+    readRoots?: readonly string[];
+    writeRoots?: readonly string[];
+    /** W9: the permission baseline's write capability (false = read-only). */
+    workspaceWritable?: boolean;
+}
+/** Canonical writable workspace + canonical read/write roots (workspace first). */
+export declare class PathGuardPolicy {
+    readonly workspace: string;
+    readonly readRoots: readonly string[];
+    /** Workspace first; grants may only append (never remove or demote). */
+    readonly writeRoots: readonly string[];
+    readonly failClosedReason: string | null;
+    constructor(init: PathGuardPolicyInit);
+    /**
+     * Policy from the environment (`CELESTEA_TOOL_WORKDIR` + `CELESTEA_TOOL_ROOTS`).
+     *
+     * W768: `scope` replaces the WORKSPACE with the session's own root. That is the
+     * one thing a session may move, and it moves only the writable root plus the
+     * implicit read root ([PathGuardPolicy] always lists the workspace first in
+     * both) — `CELESTEA_TOOL_ROOTS` keeps contributing exactly the read roots the
+     * operator declared, and grants keep appending. No env entry is dropped, so a
+     * session cannot end up narrower than the posture it was composed under.
+     */
+    static fromEnv(env?: NodeJS.ProcessEnv, grants?: PathGuardGrants, scope?: SessionFsScope | null): PathGuardPolicy;
+    /** read/list: the canonical target must resolve inside a read root. */
+    checkRead(target: string): ToolDecision;
+    /**
+     * write: the canonical target must land inside ONE writable root. The
+     * workspace is always one (§5.6: grants can only add roots); read roots are
+     * still read-only and a write root overlapping a read root is rejected by the
+     * host before it ever reaches this policy.
+     */
+    checkWrite(target: string): ToolDecision;
+    /** Verbatim legacy message with no extra roots; explicit root list beyond it. */
+    private writeDenyMessage;
+    private failClosed;
+}
+/**
+ * The guard: arbitrates every path-like argument of every tool. Only an explicit
+ * `self` declaration (see [PATH_ACCESS]) hands a tool's paths back to its own
+ * confinement layer; an unknown tool is checked as a write.
+ */
+export declare class PathGuard implements ToolGuard {
+    private readonly policy;
+    private readonly access;
+    constructor(policy: PathGuardPolicy, access?: ReadonlyMap<string, PathAccess>);
+    static fromEnv(env?: NodeJS.ProcessEnv, grants?: PathGuardGrants, access?: ReadonlyMap<string, PathAccess>, scope?: SessionFsScope | null): PathGuard;
+    check(input: ToolInput): Promise<ToolDecision>;
+    /** Every path-like argument must pass; the first denial wins. */
+    private checkAll;
+}
+/**
+ * Mount the production guard chain. Returns whether it was mounted;
+ * `CELESTEA_TOOL_GUARD=0` explicitly opts out (documented escape hatch — the
+ * caller is responsible for surfacing that in its own diagnostics).
+ */
+export declare function mountProductionGuards(registry: ToolRegistry, env?: NodeJS.ProcessEnv, grants?: PathGuardGrants, scope?: SessionFsScope | null): boolean;

package/dist/guard/path-guard.js

@@ -0,0 +1,289 @@
+/**
+ * The production path-whitelist guard (`crates/tools/src/guard.rs`).
+ *
+ * Policy:
+ * - the **workspace** (`CELESTEA_TOOL_WORKDIR`, default: process cwd) is the
+ *   only writable root — W768: for a composed SESSION it is that session's own
+ *   workspace root (passed as a [SessionFsScope]), because a process serves many
+ *   sessions and one env knob cannot be all of their workspaces;
+ * - `CELESTEA_TOOL_ROOTS` is a comma-separated list of extra READ roots
+ *   (whitelist roots are read-only: the workspace is the writable subset);
+ * - **argument-driven, never a name whitelist (W738 P1)**: the guard inspects the
+ *   ARGUMENTS of the call. Any tool whose arguments carry a path-like value (see
+ *   [PATH_ARG_KEYS]) is arbitrated; [PATH_ACCESS] only declares *which* access a
+ *   **known** tool needs — `read` (`read_file`, `list_dir`), `write`
+ *   (`write_file`), or `self` for the tools that carry their own confinement
+ *   layer (`run_shell`: the sandbox root; `spawn_worker`: the host-side session
+ *   RPC). A tool that is NOT declared is checked as a **write**: it may only
+ *   touch the writable roots. A newly registered tool is therefore constrained
+ *   by default and can never be fail-OPEN just because nobody added it to a
+ *   list;
+ * - a missing/ill-typed path argument passes through: the tool's own validation
+ *   reports it, the guard only arbitrates real paths.
+ *
+ * **Fail closed**: when `CELESTEA_TOOL_ROOTS` is set but an entry cannot be used
+ * (missing, not a directory, unlistable), the policy denies every path-bearing
+ * call with `code=tool_roots_invalid` instead of silently ignoring the entry —
+ * an operator typo must never quietly widen or narrow access.
+ *
+ * `CELESTEA_TOOL_GUARD=0` skips *mounting* the chain (explicit escape hatch; it
+ * never weakens the http policy or the sandbox).
+ *
+ * W516 (session grants): a host may pass a [PathGuardGrants] view with extra
+ * read/write roots read from the session's `grants.json`. Grants are strictly
+ * ADDITIVE — the workspace stays writable, env read roots stay read-only, the
+ * mount decision is untouched — and a bad grant root is dropped by the host
+ * (ignore-the-entry), the exact opposite of the env fail-closed rule above.
+ * Both policies are deliberate: env is the operator's posture (a typo must be
+ * loud), grants are a per-session widening (ignoring one falls back to least
+ * privilege, and a hard failure would only push users to `CELESTEA_TOOL_GUARD=0`).
+ */
+import { resolve } from "node:path";
+import { envFlag, envString } from "../env.js";
+import { contractError } from "../errors.js";
+import { pathDelimiter } from "../platform/paths.js";
+import { absolutize, isDirectory, isInside, resolveExistingTarget, resolveWriteTarget } from "./paths.js";
+export const ENV_TOOL_ROOTS = "CELESTEA_TOOL_ROOTS";
+export const ENV_TOOL_WORKDIR = "CELESTEA_TOOL_WORKDIR";
+export const ENV_TOOL_GUARD = "CELESTEA_TOOL_GUARD";
+export const GUARD_ERROR_PREFIX = "toolguard";
+const ALLOW = { kind: "allow" };
+/**
+ * Declared access per **known** tool (W738 P1). `self` = the tool confines the
+ * path in its own layer, so this guard stays out of the way. Everything absent
+ * from this map is treated as `write` (the fail-closed floor), NOT as `allow`.
+ */
+export const PATH_ACCESS = new Map([
+    ["read_file", "read"],
+    ["list_dir", "read"],
+    // W819-7: read_image(path=...) is the documented peer of read_file under
+    // the same sandbox guard (docs/feature-multimodal-attachments.md 5.5);
+    // leaving it undeclared made the write floor refuse a readable root.
+    ["read_image", "read"],
+    ["write_file", "write"],
+    ["run_shell", "self"],
+    ["spawn_worker", "self"],
+]);
+/**
+ * Argument names carrying a path. Deliberately argument-based: a new tool with a
+ * `path`/`dir`/`workspace` argument is arbitrated without any registration step.
+ */
+export const PATH_ARG_KEYS = [
+    "path",
+    "paths",
+    "file",
+    "files",
+    "dir",
+    "dirs",
+    "directory",
+    "workdir",
+    "cwd",
+    "root",
+    "roots",
+    "workspace",
+];
+/**
+ * Platform path-list separator: `:` on unix, `;` on windows — the same
+ * semantics as `std::env::split_paths`. A comma is ALSO accepted (the
+ * earlier TS-only documentation used commas), so `CELESTEA_TOOL_ROOTS` may be
+ * written either way.
+ *
+ * Note the platform distinction matters: a windows drive letter (`C:\dir`)
+ * must not be split on `:`.
+ */
+function listSeparator(platform) {
+    return new RegExp(`[${pathDelimiter(platform)},]`);
+}
+/**
+ * Split a root list (platform separator or comma; empty entries skipped).
+ *
+ * W885: the separator is resolved from the INJECTED platform (default: the
+ * host), so a win32 test proves a drive letter survives the split instead of
+ * being cut at its colon.
+ */
+export function parseToolRoots(value, platform = process.platform) {
+    if (value === undefined)
+        return [];
+    return value
+        .split(listSeparator(platform))
+        .map((entry) => entry.trim())
+        .filter((entry) => entry !== "");
+}
+/** Canonical writable workspace + canonical read/write roots (workspace first). */
+export class PathGuardPolicy {
+    workspace;
+    readRoots;
+    /** Workspace first; grants may only append (never remove or demote). */
+    writeRoots;
+    failClosedReason;
+    constructor(init) {
+        this.workspace = init.workspace;
+        this.readRoots = [init.workspace, ...(init.readRoots ?? [])];
+        this.writeRoots = init.workspaceWritable === false ? [...(init.writeRoots ?? [])] : [init.workspace, ...(init.writeRoots ?? [])];
+        this.failClosedReason = init.failClosedReason ?? null;
+    }
+    /**
+     * Policy from the environment (`CELESTEA_TOOL_WORKDIR` + `CELESTEA_TOOL_ROOTS`).
+     *
+     * W768: `scope` replaces the WORKSPACE with the session's own root. That is the
+     * one thing a session may move, and it moves only the writable root plus the
+     * implicit read root ([PathGuardPolicy] always lists the workspace first in
+     * both) — `CELESTEA_TOOL_ROOTS` keeps contributing exactly the read roots the
+     * operator declared, and grants keep appending. No env entry is dropped, so a
+     * session cannot end up narrower than the posture it was composed under.
+     */
+    static fromEnv(env = process.env, grants = {}, scope = null) {
+        const workspaceRaw = scope?.workspace ?? envString(env, ENV_TOOL_WORKDIR) ?? process.cwd();
+        const workspace = resolveExistingTarget(workspaceRaw, process.cwd()) ?? resolve(workspaceRaw);
+        const grantRead = [...(grants.readRoots ?? [])];
+        const writeRoots = [...(grants.writeRoots ?? [])];
+        const raw = envString(env, ENV_TOOL_ROOTS);
+        if (raw === undefined)
+            return new PathGuardPolicy({ workspace, readRoots: grantRead, writeRoots, workspaceWritable: grants.workspaceWritable });
+        const entries = parseToolRoots(raw);
+        if (entries.length === 0) {
+            return new PathGuardPolicy({
+                workspace,
+                readRoots: grantRead,
+                writeRoots,
+                workspaceWritable: grants.workspaceWritable,
+                failClosedReason: `${ENV_TOOL_ROOTS} is set but lists no directory`,
+            });
+        }
+        const readRoots = [];
+        let failClosedReason = null;
+        for (const entry of entries) {
+            const canonical = resolveExistingTarget(entry, workspace);
+            if (canonical === null)
+                failClosedReason ??= `${ENV_TOOL_ROOTS} entry '${entry}' does not exist`;
+            else if (!isDirectory(canonical))
+                failClosedReason ??= `${ENV_TOOL_ROOTS} entry '${entry}' is not a directory`;
+            else
+                readRoots.push(canonical);
+        }
+        return new PathGuardPolicy({ workspace, readRoots: [...readRoots, ...grantRead], writeRoots, failClosedReason });
+    }
+    /** read/list: the canonical target must resolve inside a read root. */
+    checkRead(target) {
+        const blocked = this.failClosed();
+        if (blocked !== null)
+            return blocked;
+        const canonical = resolveExistingTarget(target, this.workspace);
+        if (canonical === null)
+            return ALLOW;
+        if (this.readRoots.some((root) => isInside(canonical, root)))
+            return ALLOW;
+        return deny("path_forbidden", `read/list path '${target}' is outside the allowed roots (workspace '${this.workspace}' + ${ENV_TOOL_ROOTS})`);
+    }
+    /**
+     * write: the canonical target must land inside ONE writable root. The
+     * workspace is always one (§5.6: grants can only add roots); read roots are
+     * still read-only and a write root overlapping a read root is rejected by the
+     * host before it ever reaches this policy.
+     */
+    checkWrite(target) {
+        const blocked = this.failClosed();
+        if (blocked !== null)
+            return blocked;
+        const canonical = resolveWriteTarget(target, this.workspace);
+        if (canonical === null)
+            return ALLOW;
+        if (this.writeRoots.some((root) => isInside(canonical, root)))
+            return ALLOW;
+        return deny("path_forbidden", this.writeDenyMessage(target));
+    }
+    /** Verbatim legacy message with no extra roots; explicit root list beyond it. */
+    writeDenyMessage(target) {
+        if (this.writeRoots.length <= 1)
+            return `write path '${target}' is outside the workspace '${this.workspace}'`;
+        return `write path '${target}' is outside every writable root (${this.writeRoots.join(", ")})`;
+    }
+    failClosed() {
+        if (this.failClosedReason === null)
+            return null;
+        return deny("tool_roots_invalid", `${this.failClosedReason} — failing closed: path tools are denied until ${ENV_TOOL_ROOTS} is fixed`);
+    }
+}
+/**
+ * The guard: arbitrates every path-like argument of every tool. Only an explicit
+ * `self` declaration (see [PATH_ACCESS]) hands a tool's paths back to its own
+ * confinement layer; an unknown tool is checked as a write.
+ */
+export class PathGuard {
+    policy;
+    access;
+    constructor(policy, access = PATH_ACCESS) {
+        this.policy = policy;
+        this.access = access;
+    }
+    static fromEnv(env = process.env, grants = {}, access = PATH_ACCESS, scope = null) {
+        return new PathGuard(PathGuardPolicy.fromEnv(env, grants, scope), access);
+    }
+    async check(input) {
+        const access = this.access.get(input.name) ?? "write";
+        if (access === "self")
+            return ALLOW;
+        // W824 (W812 P0-2): normalize relative path arguments against the SESSION
+        // workspace BEFORE arbitrating and before the tool opens them. The fs tools
+        // receive the same args object the guard inspected, so rewriting it here
+        // makes the checked path and the opened path byte-identical; leaving them
+        // relative let the guard check <workspace>/x while fs opened
+        // <process.cwd()>/x.
+        const targets = normalizePathArguments(input.args, this.policy.workspace);
+        if (targets.length === 0)
+            return ALLOW;
+        return this.checkAll(targets, access);
+    }
+    /** Every path-like argument must pass; the first denial wins. */
+    checkAll(targets, access) {
+        for (const target of targets) {
+            const decision = access === "read" ? this.policy.checkRead(target) : this.policy.checkWrite(target);
+            if (decision.kind !== "allow")
+                return decision;
+        }
+        return ALLOW;
+    }
+}
+/**
+ * Rewrite every relative path-like argument to its absolute workspace-relative
+ * form (in place) and return the normalized values in [PATH_ARG_KEYS] order.
+ */
+function normalizePathArguments(args, workspace) {
+    if (typeof args !== "object" || args === null)
+        return [];
+    const record = args;
+    const found = [];
+    for (const key of PATH_ARG_KEYS) {
+        const value = record[key];
+        if (typeof value === "string") {
+            const absolute = absolutize(value, workspace);
+            if (absolute !== value)
+                record[key] = absolute;
+            found.push(absolute);
+        }
+        else if (Array.isArray(value)) {
+            record[key] = value.map((entry) => {
+                if (typeof entry !== "string")
+                    return entry;
+                const absolute = absolutize(entry, workspace);
+                found.push(absolute);
+                return absolute;
+            });
+        }
+    }
+    return found;
+}
+function deny(code, message) {
+    return { kind: "deny", reason: contractError(GUARD_ERROR_PREFIX, code, message) };
+}
+/**
+ * Mount the production guard chain. Returns whether it was mounted;
+ * `CELESTEA_TOOL_GUARD=0` explicitly opts out (documented escape hatch — the
+ * caller is responsible for surfacing that in its own diagnostics).
+ */
+export function mountProductionGuards(registry, env = process.env, grants = {}, scope = null) {
+    if (!envFlag(envString(env, ENV_TOOL_GUARD), true))
+        return false;
+    registry.addGuard(PathGuard.fromEnv(env, grants, PATH_ACCESS, scope));
+    return true;
+}