@sema-agent/core 7.33.8 → 7.34.0

package/dist/tools/artifact/artifact-tool.js

@@ -1,3 +1,5 @@
+import { arbitrateByMode, classifyAsk } from "../../core/ask-origin.js";
+import { deliverEngineNotice } from "../../core/engine-notice.js";
 import { createHash } from "node:crypto";
 import { Type } from "typebox";
 import { ARTIFACT_ACTION_CONCURRENCY_SAFE, ARTIFACT_COMMIT_THROW_OUTCOME, ARTIFACT_FAILURE_RESULT_CODE, ARTIFACT_HOST_ERROR_CODE, ARTIFACT_LIST_SCOPES, ARTIFACT_PLANE_CONTENT_ORIGIN, ARTIFACT_PUBLISH_CONTEXTS, } from "../../core/artifact-host.js";
@@ -128,7 +130,8 @@ function buildSchema(caps) {
 const invalid = (text) => errorResult(`Error (Artifact): ${text}`, { type: "artifact", invalidArguments: true });
 const typed = (code, text, extra = {}) => errorResult(`Error (Artifact): ${text}`, { type: "artifact", code: ARTIFACT_FAILURE_RESULT_CODE[code], ...extra });
 export function createArtifactTool(opts) {
-    const { host, capabilities: caps, runId, taskId, sessionId, agentName, readLocalFile, onAsk } = opts;
+    const { host, capabilities: caps, runId, taskId, sessionId, agentName, readLocalFile, onAsk, permissionMode, onNotice } = opts;
+    let releaseAnnounced = false;
     const versions = new Map();
     const bindings = new Map();
     const occurrences = new Map();
@@ -316,6 +319,18 @@ export function createArtifactTool(opts) {
     const sharedReadConsent = (url, ref, ctx) => {
         if (sharedReadApproved.has(url))
             return Promise.resolve({ ok: true });
+        if (permissionMode !== undefined) {
+            const verdict = arbitrateByMode(permissionMode(), classifyAsk({ action: "ask", requiresRealApproval: true, guard: "artifact_shared_read" }, { contentQuestion: false, markedUnresolvable: false, org: undefined, tightened: undefined, mandateMarks: {} }));
+            if (verdict.kind === "released") {
+                if (!releaseAnnounced && onNotice !== undefined) {
+                    releaseAnnounced = true;
+                    deliverEngineNotice(onNotice, { code: "permission.ask_released_by_mode", message: `the ${verdict.mode} permission mode released a shared-artifact read (${inlineUntrusted(url, 300)}) without asking anyone; further shared reads of this run under the mode are released the same way`, detail: { mode: verdict.mode, askClass: verdict.askClass, count: 1, firstToolCallId: ctx.toolCallId, ...(sessionId !== undefined ? { sessionId } : {}), runId } });
+                }
+                return Promise.resolve({ ok: true });
+            }
+            if (verdict.kind === "denied_by_mode")
+                return Promise.resolve({ ok: false, reason: `the ${verdict.mode} permission mode refuses to read another person's artifact without approval` });
+        }
         const pending = consentInFlight.get(url);
         if (pending !== undefined)
             return pending;

package/dist/tools/fs/bash-readonly-classifier.d.ts

@@ -15,7 +15,7 @@ import { type LexedCommand, type LexedSegment, type LexedWord, type ShellLex, ty
  * hostname), and `file` (`-C -m` → compiles/writes a magic file) were REMOVED — each is read-only by NAME
  * but state-MUTATING with args, which an argv[0]-only filter cannot tell apart. Leaving them in defeated
  * both the `effect:read` truthfulness here and the classifier's irreversibility promise (a `date -s` would
- * auto-allow an irreversible clock jump under `shellGate:"classify"`).
+ * auto-allow an irreversible clock jump on the full shell face).
  *
  * Rows 3-4 are the CC-anchored expansion — the members of CC's safe-command
  * set (pretty223.js:420513-420565 `e6s`; identical in the 220 corpus; the 220→245 campaign diff records
@@ -223,7 +223,7 @@ export declare function splitShellCompoundSegments(source: string, options?: {
     reject: string;
 };
 /**
- * Compound read-only classification for the `bash` CLASSIFY face (shellGate:"classify").
+ * Compound read-only classification for the `bash` full-shell face (the shape tier).
  * Splits a command on the connector set `;` `&&` `||` `|` and passes every segment through
  * {@link coarseReadonlyCheck} (the single {@link parseLeadingCommandName} parser + bare-name allowlist).
  * All segments green ⇒ read-only. Returns a reason when rejected, else undefined.
@@ -304,8 +304,11 @@ export interface BashReadonlyRootBoundary {
      *  EVERY read face wires this one seat, the `bash_readonly` shell included, at BOTH of its judging
      *  moments — roots answer WHERE a command may read and the allowlist WHICH verb runs, neither answers
      *  WHICH FILES are off the table. What this seat is and is not is stated once, at
-     *  `shell.read_boundary.friction_floor`. */
-    denyMatch?: (resolvedPath: string) => string | null;
+     *  `shell.read_boundary.friction_floor`. `walked` — the path is a member a traversal enumerated, not a
+     *  spelling of the command ({@link import("./read-deny.js").ReadDenyMatcher.matchPath}). */
+    denyMatch?: (resolvedPath: string, opts?: {
+        readonly walked?: boolean;
+    }) => string | null;
     /** What the wired {@link denyMatch} judge would apply — the ACTIVE deny patterns. Read for ONE question:
      *  is there anything for a traversal to defeat? EMPTY ⇒ the judge refuses nothing, so a walk under it
      *  bypasses nothing and {@link CompoundReadonlyVerdict.recursiveReadPaths} is not minted. ABSENT ⇒ the
@@ -328,7 +331,7 @@ export interface BashReadonlyRootBoundary {
  */
 export interface CompoundReadonlyVerdict {
     /** Demotion reason (the same string {@link classifyCompoundReadonly} returns), or undefined: the
-     *  command's SHAPE is not one the classify doctrine auto-allows. WHERE the command reads is not this
+     *  command's SHAPE is not one the shape tier auto-allows. WHERE the command reads is not this
      *  verdict's business — that is the gate's shell read station (`shell-read-check.ts`). */
     reason?: string;
 }
@@ -350,6 +353,24 @@ export declare function formatOutOfRootReadApprovalOption(directory: string): st
  *  operand scan below, which is safe for an unknown command because a bare word can only ever name
  *  something under the working directory. */
 export declare const NO_PATH_OPERAND_COMMANDS: ReadonlySet<string>;
+/** The no-path-operand programs that EVALUATE a word (`test -v 'a[$(…)]'` runs the substitution in the subscript): a word
+ *  the shell or that evaluation rewrites is handed over as any program's is; only their settled words name nothing. */
+export declare const NO_PATH_OPERAND_EVALUATORS: ReadonlySet<string>;
+/** The builtins whose `NAME=value` arguments are assignments bash performs (and exports, for `export`), never paths. */
+export declare const DECLARATION_BUILTINS: ReadonlySet<string>;
+/** The shell BUILTINS that open no file, start no program and evaluate nothing: an external program's loader reads its
+ *  environment (`LD_PRELOAD` for `sleep`), `printf` reads `TZ` for `%(…)T` and assigns through `-v`, `test -v` and an
+ *  array subscript evaluate arithmetic (which runs a `$(…)` inside it). A declaration builtin counts only bare — no option
+ *  word (`-i` evaluates the value) — and every inert segment's words carry no `[` `]` `$` or backquote. */
+export declare const INERT_BUILTINS: ReadonlySet<string>;
+/** The indices of the SETTLED words a {@link MESSAGE_SLOTS} row reads as message text under the subcommand's grammar:
+ *  the value of `-m` (attached, or the next word) or of `--message` (`=`, or the next word; an unambiguous prefix of it
+ *  counts). A word the shell rewrites is never claimed, and neither is any word another option consumes — those words
+ *  stay the verb-blind walk's. */
+export declare function messageSlotWords(program: string, words: readonly {
+    readonly folded: string;
+    readonly expands: unknown;
+}[], programIndex: number): Set<number>;
 /** True for a token that can denote a filesystem location OUTSIDE the working directory. A bare word
  *  (`foo`, `a.txt`, a grep pattern, an awk program) cannot: with no separator and no `..` it always
  *  resolves under the cwd, which the caller's cwd governance already covers.
@@ -934,8 +955,8 @@ export declare const POLL_LOOP_MAX_BEATS = 120;
 export declare const POLL_LOOP_MAX_SLEEP_SECONDS = 600;
 /**
  * The BOUNDED READ-ONLY POLL LOOP arm of the classify face. The compound classifier above rejects any
- * control structure (`for` is not an allowlisted name), which makes `shellGate:"classify"` behave like
- * `"always"` for a monitoring consumer whose whole idiom is `for i in $(seq 1 8); do tail -n 5 x.log;
+ * control structure (`for` is not an allowlisted name), which makes the shape tier behave like
+ * the `"always"` floor for a monitoring consumer whose whole idiom is `for i in $(seq 1 8); do tail -n 5 x.log;
  * sleep 2; done`. This arm accepts EXACTLY that grammar and nothing else. Returns the rejection
  * reason, or undefined when the command matches the grammar (⇒ safe to treat as reversible).
  *

package/dist/tools/fs/bash-readonly-classifier.js

@@ -162,7 +162,95 @@ export function formatOutOfRootReadApprovalOption(directory) {
 export const NO_PATH_OPERAND_COMMANDS = new Set([
     "pwd", "echo", "printf", "whoami", "uname", "which", "tr", "basename", "dirname",
     "cal", "uptime", "id", "groups", "nproc", "locale", "free", "true", "false", "seq", "expr", "type", "sleep",
+    "test", "[",
 ]);
+export const NO_PATH_OPERAND_EVALUATORS = new Set(["test", "["]);
+export const DECLARATION_BUILTINS = new Set(["export", "declare", "typeset", "local", "readonly"]);
+export const INERT_BUILTINS = new Set(["echo", "true", "false", "pwd", ...DECLARATION_BUILTINS]);
+const MESSAGE_SLOTS = {
+    git: {
+        globalPlain: ["-p", "--paginate", "-P", "--no-pager", "--bare", "--no-replace-objects", "--literal-pathspecs", "--glob-pathspecs", "--noglob-pathspecs", "--icase-pathspecs", "--no-optional-locks"],
+        globalValue: ["-C", "-c", "--git-dir", "--work-tree", "--namespace", "--config-env", "--super-prefix"],
+        subcommands: {
+            commit: { plain: "apsnvqeioz", optional: "Su", value: "mFCct", longValue: ["message", "file", "template", "pathspec-from-file", "author", "date", "cleanup", "fixup", "squash", "trailer", "reuse-message", "reedit-message"] },
+            tag: { plain: "asfdvle", optional: "n", value: "mFu", longValue: ["message", "file", "local-user", "cleanup", "trailer", "sort", "format", "contains", "no-contains", "points-at", "merged", "no-merged"] },
+            merge: { plain: "nqve", optional: "S", value: "mFsX", longValue: ["message", "file", "strategy", "strategy-option", "into-name", "cleanup"] },
+            stash: { plain: "pkuaqS", optional: "", value: "m", longValue: ["message", "pathspec-from-file"] },
+        },
+    },
+};
+export function messageSlotWords(program, words, programIndex) {
+    const out = new Set();
+    const row = MESSAGE_SLOTS[program];
+    if (row === undefined)
+        return out;
+    let j = programIndex + 1;
+    for (; j < words.length; j++) {
+        const w = words[j].folded;
+        if (!w.startsWith("-"))
+            break;
+        if (row.globalValue.includes(w))
+            j++;
+        else if (!row.globalPlain.includes(w) && !row.globalValue.some((o) => o.startsWith("--") && w.startsWith(`${o}=`)))
+            return out;
+    }
+    const sub = row.subcommands[words[j]?.folded ?? ""];
+    if (sub === undefined)
+        return out;
+    const settled = (k) => words[k] !== undefined && words[k].expands === false;
+    let pending;
+    for (let k = j + 1; k < words.length; k++) {
+        const w = words[k].folded;
+        if (pending !== undefined) {
+            if (pending === "message" && settled(k))
+                out.add(k);
+            pending = undefined;
+            continue;
+        }
+        if (w === "--")
+            break;
+        if (!settled(k)) {
+            pending = "other";
+            continue;
+        }
+        if (!w.startsWith("-") || w === "-")
+            continue;
+        if (w.startsWith("--")) {
+            const eq = w.indexOf("=");
+            const name = w.slice(2, eq < 0 ? undefined : eq);
+            const takers = sub.longValue.filter((n) => n.startsWith(name));
+            const message = name.length > 0 && takers.length > 0 && takers.every((n) => n === "message") || name === "message";
+            if (eq >= 0) {
+                if (message)
+                    out.add(k);
+                continue;
+            }
+            if (takers.length > 0)
+                pending = message ? "message" : "other";
+            continue;
+        }
+        const letters = w.slice(1);
+        for (let i = 0; i < letters.length; i++) {
+            const c = letters[i];
+            if (sub.plain.includes(c))
+                continue;
+            if (sub.optional.includes(c))
+                break;
+            if (sub.value.includes(c)) {
+                if (i < letters.length - 1) {
+                    if (c === "m")
+                        out.add(k);
+                }
+                else
+                    pending = c === "m" ? "message" : "other";
+                break;
+            }
+            pending = "other";
+            break;
+        }
+    }
+    return out;
+}
 const XARGS_TARGETS_ACCEPTED_UNJUDGED = NO_PATH_OPERAND_COMMANDS;
 export function isPathShapedToken(tok) {
     return tok.includes("/") || tok.startsWith("~") || tok === "." || tok === "..";

package/dist/tools/fs/containment-face.d.ts

@@ -18,8 +18,8 @@ export declare function containmentFaceSeatName(kind: ContainmentFaceKind, layer
  *  screen the seats on runs that never mount hands. The resolver itself also runs on every hands-less
  *  leg; this screen still fires first, so a garbage value refuses before any leg-shape branching. */
 export declare function assertContainmentFaceValue(v: unknown, kind: ContainmentFaceKind, layer: ContainmentFaceLayer): ContainmentFace | undefined;
-/** Inputs to {@link resolveContainmentFace} — all structural/declaration facts, never permission modes
- *  (a deliberate axis separation: this shape carries facts, not verdicts). */
+/** Inputs to {@link resolveContainmentFace} — structural/declaration facts; a permission mode enters only as
+ *  the face its table row states ({@link modeFace}), never as a mode word. */
 export interface ContainmentFaceInputs {
     /** Which face is being resolved. Selects the seat spellings and the mint codes; the ORDER below is
      *  one body, identical for both. */
@@ -41,8 +41,13 @@ export interface ContainmentFaceInputs {
      *  tool-band assembly from spec-time facts (env kind / handsReadOnly / Bash exclusion — every
      *  exclusion source is spec-time-frozen, so this is always computable). When false, the roots fence
      *  is the ONLY boundary this face has, so no IMPLICIT default may open it; an EXPLICIT "open" on
-     *  either seat still wins (row 4 of the order is a default, not a clamp). */
+     *  either seat or the mode's face still wins (row 4 of the order is a default, not a clamp). */
     fullShellReachable: boolean;
+    /** The face the leg's permission MODE states (`ModePolicy.writeFace`: `bypassPermissions` ⇒ "open"; absent ⇒
+     *  the mode states nothing). Row 3′: read after the explicit seats and before the defaults — a seat's word (the
+     *  deployment's ceiling, a task's tighten) outranks it, and neither the read-only mount nor org governance
+     *  consults it. */
+    modeFace?: ContainmentFace;
     /** Observation hook for the ONE silent branch of the order: row 1's deployment-seat clamp
      *  (readOnly mount + deps "open" + NO task seat). Fired exactly when the deps declaration was the
      *  deciding seat and the mount overrode it — not when a task-level "roots" pinned the same value
@@ -63,6 +68,7 @@ export interface ContainmentFaceInputs {
  *  2. org-governed: the task seat's "open" refuses (task layer only tightens); deps "open" wins;
  *     otherwise ROOTS.
  *  3. explicit seat: spec ?? deps.
+ *  3′. the mode's face ({@link ContainmentFaceInputs.modeFace}).
  *  4. bash-less mount: ROOTS (the fence is the only boundary there — "the fence guards nothing bash
  *     reaches anyway" does not hold, so no implicit default may open it).
  *  5. default: ROOTS — the engine never opens implicitly.

package/dist/tools/fs/containment-face.js

@@ -67,6 +67,8 @@ export function resolveContainmentFace(i) {
         return spec;
     if (deps !== undefined)
         return deps;
+    if (i.modeFace !== undefined)
+        return i.modeFace;
     if (!i.fullShellReachable)
         return "roots";
     return "roots";

package/dist/tools/fs/file-read-check.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The READ station of the file tools (Read / Grep / Glob) — the read face's twin of the shell read station, one gate
+ * input shape ({@link ShellReadCheck}) so the gate, the approved-edit re-judge and the resumed leg's belt read both:
+ * before approval, where the call's declared path target lands is resolved exactly as the tool will resolve it
+ * (`resolveKey` over the same spelling, base, roots, deny table and containment face), and a target OUTSIDE the read
+ * roots is an ORDINARY question — a person answers it, a persisted `Read(//dir/**)` row or the auto-mode classifier
+ * may, a permission mode arbitrates it — with the directory whose grant clears it on the card. The deny table and
+ * every other refusal stay the tool's own: this station judges containment only, after the deny judgment.
+ *
+ * A call whose out-of-root read the gate put to a question is ADMITTED for that one target when the gate applies the
+ * verdict ({@link ShellReadVerdict.admit}): the tool reads it once ({@link FileReadStation.admitted}), on the canonical
+ * key the station judged — a target that resolves elsewhere by then is refused by the tool's own fence, and a verdict
+ * the gate never received (its wait elapsed, the judgment threw) admits nothing.
+ */
+import type { ExecutionEnv } from "../../internal/harness-types.js";
+import type { ContainmentFace } from "./containment-face.js";
+import { type ReadDenyMatcher } from "./read-deny.js";
+import type { ShellReadCheck } from "./shell-read-check.js";
+export interface FileReadStation {
+    readonly check: ShellReadCheck;
+    /** The station's membership: the tool names whose declared read target it judges. */
+    readonly tools: ReadonlySet<string>;
+    /** Did the gate put THIS call's read of `canonicalKey` outside the roots to a question it then let through? Consumed
+     *  on a match: the admission covers one read of one target. */
+    readonly admitted: (toolCallId: string | undefined, canonicalKey: string) => boolean;
+}
+export interface FileReadStationOptions {
+    readonly env: ExecutionEnv;
+    readonly rootCanonical: string;
+    /** The extra read roots, read per call (a grant widens the live set). */
+    readonly roots: () => readonly string[];
+    readonly readDeny?: ReadDenyMatcher;
+    readonly readFace?: ContainmentFace;
+    readonly homeDir?: string;
+    /** The file tools this leg mounts (their catalog path target is the one judged). */
+    readonly tools: ReadonlySet<string>;
+    /** A target no answer may admit (the store-isolation rule's judgment, `rootAdmittingArtifactStore`): it is left to
+     *  the tool's own refusal, no question is raised for it. */
+    readonly excluded?: (canonicalKey: string) => boolean;
+    /** A target the tools' own fence admits without the roots (the engine's background output file,
+     *  `backgroundOutputReadExemption`): no question is put for it. */
+    readonly exempt?: (canonicalKey: string) => boolean;
+}
+export declare function createFileReadStation(opts: FileReadStationOptions): FileReadStation;
+/** One gate input over the leg's read stations: each call is judged by the station whose membership holds it. */
+export declare function composeReadChecks(stations: ReadonlyArray<{
+    readonly check: ShellReadCheck;
+    readonly tools: ReadonlySet<string>;
+}>): ShellReadCheck | undefined;

package/dist/tools/fs/file-read-check.js

@@ -0,0 +1,71 @@
+import { effectivePathSpellingOf } from "../../core/effective-path-target.js";
+import { pathTargetOf } from "../../core/tool-registry.js";
+import { fitMiddle, READ_DENY_SENTENCE_PART_MAX } from "./read-deny.js";
+import { resolveKey, violationDetails } from "./safety.js";
+import { grantOfferFor, parentDirLexically } from "./shell-read-judge.js";
+const ADMISSION_MAX = 1024;
+const VOUCH = { disposition: "vouch", finding: "none" };
+export function createFileReadStation(opts) {
+    const admissions = new Map();
+    const remember = (toolCallId, key) => {
+        if (admissions.size >= ADMISSION_MAX) {
+            const oldest = admissions.keys().next().value;
+            if (oldest !== undefined)
+                admissions.delete(oldest);
+        }
+        admissions.set(toolCallId, key);
+    };
+    const check = {
+        judge(toolName, args, cwd, signal, callOpts) {
+            if (!opts.tools.has(toolName))
+                return null;
+            const selection = effectivePathSpellingOf({ toolName, args }, pathTargetOf(toolName), { root: opts.rootCanonical, cwd });
+            if (selection === undefined || "refused" in selection || selection.spelled === undefined)
+                return null;
+            const spelled = selection.spelled;
+            return (async () => {
+                const extra = opts.roots();
+                const r = await resolveKey(opts.env, opts.rootCanonical, spelled, signal, selection.base, extra, undefined, opts.readDeny, opts.readFace);
+                if (r.ok || r.violation.code !== "path_not_in_root" || r.violation.target === undefined || opts.excluded?.(r.violation.target) === true || opts.exempt?.(r.violation.target) === true)
+                    return VOUCH;
+                const target = r.violation.target;
+                const toolCallId = callOpts.toolCallId;
+                const roots = [opts.rootCanonical, ...extra];
+                const details = violationDetails(r.violation);
+                const allowed = fitMiddle(roots.join(", "), READ_DENY_SENTENCE_PART_MAX);
+                if (callOpts.seat === "rejudge") {
+                    return { disposition: "refuse", finding: "outside_roots", sentence: `Error (${toolName}): the approved edit reads "${fitMiddle(target, READ_DENY_SENTENCE_PART_MAX)}", outside the directories allowed for this session (${allowed}) — re-submit it as a fresh call and answer its card.`, details };
+                }
+                const info = pathTargetOf(toolName)?.absent === "base" ? await opts.env.fileInfo(target, signal) : undefined;
+                const readsDirectory = info?.ok === true && info.value.kind === "directory";
+                const offer = grantOfferFor(readsDirectory ? target : parentDirLexically(target), target, { roots, ...(opts.homeDir !== undefined ? { homeDir: opts.homeDir } : {}) });
+                return {
+                    disposition: "ordinary",
+                    finding: "outside_roots",
+                    sentence: `reads outside the allowed directories for this session: "${fitMiddle(target, READ_DENY_SENTENCE_PART_MAX)}" is not under ${allowed}`,
+                    details,
+                    ...(offer !== undefined ? { readRootCandidate: { dir: offer.dir, ...(offer.covers !== undefined ? { covers: offer.covers } : {}), clearsThisAsk: true } } : {}),
+                    ...(toolCallId !== undefined ? { admit: () => remember(toolCallId, target) } : {}),
+                };
+            })();
+        },
+        unanswered: () => VOUCH,
+    };
+    const admitted = (toolCallId, key) => {
+        if (toolCallId === undefined || admissions.get(toolCallId) !== key)
+            return false;
+        admissions.delete(toolCallId);
+        return true;
+    };
+    return { check, tools: opts.tools, admitted };
+}
+export function composeReadChecks(stations) {
+    if (stations.length === 0)
+        return undefined;
+    if (stations.length === 1)
+        return stations[0].check;
+    return {
+        judge: (toolName, args, cwd, signal, callOpts) => stations.find((s) => s.tools.has(toolName))?.check.judge(toolName, args, cwd, signal, callOpts) ?? null,
+        unanswered: (toolName, cause) => (stations.find((s) => s.tools.has(toolName)) ?? stations[0]).check.unanswered(toolName, cause),
+    };
+}

package/dist/tools/fs/fs-bash.d.ts

@@ -4,8 +4,8 @@ import { type CwdRef } from "./fs-shared.js";
 import type { ReversibilityVerdict } from "../../core/types.js";
 import type { ShellReadAdmission } from "./shell-read-check.js";
 /**
- * The classify doctrine's SHAPE classifier for the `bash` tool, exposed as a `ToolSpec.reversibilityProbe`
- * (the "maybe" tier's probe under `shellGate:"classify"`). A command is reversible ONLY if every connected
+ * The full shell face's SHAPE classifier for the `bash` tool, exposed as a `ToolSpec.reversibilityProbe`
+ * (the "maybe" tier's probe, installed on every full shell). A command is reversible ONLY if every connected
  * segment is a bare command whose program is on the reversible allowlist (default
  * {@link bashClassifyDefaultAllow} — curated to commands with NO write/mutation mode under ANY args) and whose
  * SHAPE the compound classifier accepts (no redirects, substitutions, subshells, escapes or backgrounding; no
@@ -17,7 +17,7 @@ import type { ShellReadAdmission } from "./shell-read-check.js";
  *
  * WHERE a command reads is not this probe's question. The read boundary — deny rows, containment, symlinks,
  * patterns, traversals, the working directory a `cd` moves — is the gate's shell READ STATION
- * (`shell-read-check.ts`), judged on every shell call under every doctrine, ahead of this probe; a call the
+ * (`shell-read-check.ts`), judged on every shell call under every mode, ahead of this probe; a call the
  * station refused never reaches it, and a call the station asks about is asked about whatever this probe
  * says. `boundary` supplies only the environment's declared home, so the `$HOME`/`~` spellings fold here the
  * way the station folds them; nothing else of it is read. A caller-supplied `allow` is honored verbatim, so a

package/dist/tools/fs/fs-read.d.ts

@@ -6,4 +6,5 @@ import { type ReminderDisclosureCounts } from "../../core/reminder-disclosure.js
 export declare function createReadFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: RootsSeat, imageDownsampler?: ReadImageDownsamplerOption, pdfCapabilities?: PdfModelCapabilities, bgOutputReadExemption?: (canonicalKey: string, ctx: {
     taskId?: string;
     principal?: string;
+    toolCallId?: string;
 }) => boolean, readCyberReminder?: boolean, readDeny?: import("./read-deny.js").ReadDenyMatcher, readFace?: import("./containment-face.js").ContainmentFace, reminderMark?: string, reminderDisclosureCounts?: ReminderDisclosureCounts): AgentTool;

package/dist/tools/fs/fs-search-tools.d.ts

@@ -12,5 +12,5 @@ import type { CwdRef } from "./fs-shared.js";
  * honesty boundary.
  */
 export declare function grepDetailFields(text: string, mode: "files_with_matches" | "content" | "count", offset?: number, structuredRows?: readonly import("./search.js").GrepRow[]): Record<string, unknown>;
-export declare function createGrepTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: RootsSeat, readDeny?: ReadDenyMatcher, readFace?: ContainmentFace, cwdRef?: CwdRef): AgentTool;
-export declare function createGlobTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: RootsSeat, readDeny?: ReadDenyMatcher, readFace?: ContainmentFace, cwdRef?: CwdRef): AgentTool;
+export declare function createGrepTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: RootsSeat, readDeny?: ReadDenyMatcher, readFace?: ContainmentFace, cwdRef?: CwdRef, readAdmission?: (toolCallId: string | undefined, canonicalKey: string) => boolean): AgentTool;
+export declare function createGlobTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: RootsSeat, readDeny?: ReadDenyMatcher, readFace?: ContainmentFace, cwdRef?: CwdRef, readAdmission?: (toolCallId: string | undefined, canonicalKey: string) => boolean): AgentTool;

package/dist/tools/fs/fs-search-tools.js

@@ -74,7 +74,7 @@ export function grepDetailFields(text, mode, offset, structuredRows) {
     }
     return detailFields;
 }
-export function createGrepTool(env, rootCanonical, additionalRoots, readDeny, readFace, cwdRef) {
+export function createGrepTool(env, rootCanonical, additionalRoots, readDeny, readFace, cwdRef, readAdmission) {
     const declaredTarget = toolFace("grep").pathTarget;
     return defineTool({
         name: "Grep",
@@ -143,7 +143,7 @@ export function createGrepTool(env, rootCanonical, additionalRoots, readDeny, re
             const scopeSpelling = declaredTarget === undefined ? undefined : pathTargetValue(a, declaredTarget);
             let scoped = scopeSpelling;
             if (scopeSpelling !== undefined) {
-                const r = await resolveKey(env, rootCanonical, scopeSpelling, ctx.signal, baseCwd, additionalRoots, undefined, readDeny, readFace);
+                const r = await resolveKey(env, rootCanonical, scopeSpelling, ctx.signal, baseCwd, additionalRoots, readAdmission && ((key) => readAdmission(ctx.toolCallId, key)), readDeny, readFace);
                 if (!r.ok)
                     return errorResult(violationText("Grep", r.violation), violationDetails(r.violation));
                 scoped = r.key;
@@ -177,7 +177,7 @@ export function createGrepTool(env, rootCanonical, additionalRoots, readDeny, re
         },
     });
 }
-export function createGlobTool(env, rootCanonical, additionalRoots, readDeny, readFace, cwdRef) {
+export function createGlobTool(env, rootCanonical, additionalRoots, readDeny, readFace, cwdRef, readAdmission) {
     const declaredTarget = toolFace("glob").pathTarget;
     return defineTool({
         name: "Glob",
@@ -217,7 +217,7 @@ export function createGlobTool(env, rootCanonical, additionalRoots, readDeny, re
             const baseCwd = pathTargetBaseOf(declaredTarget, { root: rootCanonical, cwd: cwdRef?.current });
             let scoped = path;
             if (path !== undefined) {
-                const r = await resolveKey(env, rootCanonical, path, ctx.signal, baseCwd, additionalRoots, undefined, readDeny, readFace);
+                const r = await resolveKey(env, rootCanonical, path, ctx.signal, baseCwd, additionalRoots, readAdmission && ((key) => readAdmission(ctx.toolCallId, key)), readDeny, readFace);
                 if (!r.ok)
                     return errorResult(violationText("Glob", r.violation), violationDetails(r.violation));
                 scoped = r.key;

package/dist/tools/fs/fs-shared.js

@@ -4,6 +4,7 @@ import { normalizeAbsPathLexically, sha256, similarNameSuggestion, OVERSIZE_READ
 import { decodeTextBytes, normalizeFileText } from "./encoding.js";
 import { shellQuote } from "./search.js";
 import { isNotebookPath } from "./notebook.js";
+import { homeViewsOf } from "./read-deny-home.js";
 import { sharpImageDownsampler } from "../../core/mcp.js";
 import { deliverEngineNotice } from "../../core/types.js";
 import { resolveEnvBudget } from "../../core/env-budget.js";
@@ -344,24 +345,37 @@ export function applyContextShrinkToReadFileState(state, shrink) {
 export async function enoentMessage(env, key, cwd, signal, readDeny) {
     let msg = `File does not exist. Note: your current working directory is ${cwd}.`;
     const sep = Math.max(key.lastIndexOf("/"), key.lastIndexOf("\\"));
+    const views = readDeny !== undefined ? homeViewsOf(env, signal) : undefined;
+    const denied = async (path, leaf) => {
+        if (readDeny === undefined || views === undefined)
+            return false;
+        if (readDeny.matchPath(path) != null)
+            return true;
+        const view = await views.of(path, leaf !== undefined ? { leaf } : undefined);
+        return view !== undefined && readDeny.matchPath(view) != null;
+    };
     if (sep > 0) {
         const parent = key.slice(0, sep);
         const name = key.slice(sep + 1);
-        if (readDeny?.matchPath(parent) != null)
+        if (await denied(parent))
             return msg;
         const cwdSepped = cwd.replace(/[\\/]+$/, "");
         const cwdCandidate = `${cwdSepped}${cwd.includes("\\") ? "\\" : "/"}${name}`;
-        if (cwdCandidate !== key && readDeny?.matchPath(cwdCandidate) == null) {
+        if (cwdCandidate !== key && !(await denied(cwdCandidate))) {
             const hit = await env.exists(cwdCandidate, signal).catch(() => undefined);
             if (hit?.ok && hit.value)
                 return `${msg} Did you mean ${cwdCandidate}?`;
         }
         const listing = await env.listDir(parent, signal).catch(() => undefined);
         if (listing?.ok) {
-            const names = listing.value
-                .filter((e) => e.kind !== "directory")
-                .map((e) => e.path.slice(Math.max(e.path.lastIndexOf("/"), e.path.lastIndexOf("\\")) + 1))
-                .filter((n2) => readDeny?.matchPath(`${parent}/${n2}`) == null);
+            const names = [];
+            for (const e of listing.value) {
+                if (e.kind === "directory")
+                    continue;
+                const n2 = e.path.slice(Math.max(e.path.lastIndexOf("/"), e.path.lastIndexOf("\\")) + 1);
+                if (!(await denied(`${parent}/${n2}`, "file")))
+                    names.push(n2);
+            }
             const suggestion = similarNameSuggestion(names, name);
             if (suggestion)
                 msg += ` Did you mean ${suggestion}?`;

package/dist/tools/fs/fs-write.d.ts

@@ -2,6 +2,7 @@ import type { AgentTool, ExecutionEnv } from "../../internal/harness-types.js";
 import type { BeforeWriteHook, FileEditedHook, TrackFileEditHook } from "../../core/types.js";
 import { type ReadFileState } from "./safety.js";
 import type { ContainmentFace } from "./containment-face.js";
+import type { WriteDenyMatcher } from "./read-deny.js";
 import { type CwdRef } from "./fs-shared.js";
 /**
  * The `beforeWrite` CONTENT hook, mounted here rather than in ToolPolicy because only this band sees
@@ -13,8 +14,8 @@ import { type CwdRef } from "./fs-shared.js";
  * Absent hook ⇒ byte-identical behavior.
  */
 export type { BeforeWriteRequest, BeforeWriteResult, BeforeWriteHook, TrackEditRequest, TrackEditResult, TrackFileEditHook } from "../../core/types.js";
-export declare function createEditFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook, onEdited?: FileEditedHook, writeFace?: ContainmentFace): AgentTool;
-export declare function createWriteFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook, onEdited?: FileEditedHook, writeFace?: ContainmentFace): AgentTool;
+export declare function createEditFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook, onEdited?: FileEditedHook, writeFace?: () => ContainmentFace, writeDeny?: WriteDenyMatcher): AgentTool;
+export declare function createWriteFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook, onEdited?: FileEditedHook, writeFace?: () => ContainmentFace, writeDeny?: WriteDenyMatcher): AgentTool;
 /**
  * design v1.163 — NotebookEdit: replace/insert/delete a single cell in a .ipynb. CC-parity tool over the SAME hand-band
  * safety skeleton as Edit/Write (resolveKey containment → requireRead read-before-edit → checkStale content-hash
@@ -22,4 +23,4 @@ export declare function createWriteFileTool(env: ExecutionEnv, state: ReadFileSt
  * .ipynb as the cell projection but records read state (hash/totalLines) in the RAW notebook-text
  * coordinate — that raw-coordinate read record is what this tool's freshness check depends on.
  */
-export declare function createNotebookEditTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook, onEdited?: FileEditedHook, writeFace?: ContainmentFace): AgentTool;
+export declare function createNotebookEditTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook, onEdited?: FileEditedHook, writeFace?: () => ContainmentFace, writeDeny?: WriteDenyMatcher): AgentTool;

package/dist/tools/fs/fs-write.js

@@ -87,7 +87,7 @@ async function gateToolWrite(hook, tool, path, key, content) {
         return `Error (${tool}): write rejected by the write gate (${res.code}): ${clipHookText(res.reason)}`;
     return undefined;
 }
-export function createEditFileTool(env, state, rootCanonical, cwdRef, additionalRoots, beforeWrite, trackEdit, onEdited, writeFace) {
+export function createEditFileTool(env, state, rootCanonical, cwdRef, additionalRoots, beforeWrite, trackEdit, onEdited, writeFace, writeDeny) {
     return defineTool({
         name: "Edit",
         ...toolFace("edit"),
@@ -112,7 +112,7 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
             const path = fileArgPath(args);
             if (path === undefined)
                 return { ok: true };
-            const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots, undefined, undefined, writeFace);
+            const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots, undefined, writeDeny, writeFace?.());
             if (!r.ok)
                 return { ok: true };
             if (a.old_string === a.new_string)
@@ -150,7 +150,7 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
             const path = fileArgPath(args);
             if (path === undefined)
                 return errorResult(`Error (Edit): file_path is required.`);
-            const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots, undefined, undefined, writeFace);
+            const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots, undefined, writeDeny, writeFace?.());
             if (!r.ok)
                 return errorResult(violationText("Edit", r.violation), violationDetails(r.violation));
             if (!batch && a.old_string === a.new_string) {
@@ -325,7 +325,7 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
         },
     });
 }
-export function createWriteFileTool(env, state, rootCanonical, cwdRef, additionalRoots, beforeWrite, trackEdit, onEdited, writeFace) {
+export function createWriteFileTool(env, state, rootCanonical, cwdRef, additionalRoots, beforeWrite, trackEdit, onEdited, writeFace, writeDeny) {
     return defineTool({
         name: "Write",
         ...toolFace("write"),
@@ -344,7 +344,7 @@ export function createWriteFileTool(env, state, rootCanonical, cwdRef, additiona
                 return { ok: true };
             if (ipynbRedirect("Write", path))
                 return { ok: true };
-            const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots, undefined, undefined, writeFace);
+            const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots, undefined, writeDeny, writeFace?.());
             if (!r.ok)
                 return { ok: true };
             const exists = await env.exists(r.key, ctx.signal);
@@ -363,7 +363,7 @@ export function createWriteFileTool(env, state, rootCanonical, cwdRef, additiona
             const ipynb = ipynbRedirect("Write", path);
             if (ipynb)
                 return errorResult(ipynb);
-            const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots, undefined, undefined, writeFace);
+            const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots, undefined, writeDeny, writeFace?.());
             if (!r.ok)
                 return errorResult(violationText("Write", r.violation), violationDetails(r.violation));
             const exists = await env.exists(r.key, ctx.signal);
@@ -424,7 +424,7 @@ export function createWriteFileTool(env, state, rootCanonical, cwdRef, additiona
 const notebookNotIpynbMessage = (notebookPath) => `Error (NotebookEdit): "${notebookPath}" is not a .ipynb file; use Edit for other file types.`;
 const NOTEBOOK_CELL_TYPE_REQUIRED_MESSAGE = `Error (NotebookEdit): Cell type is required when using edit_mode=insert.`;
 const NOTEBOOK_CELL_ID_REQUIRED_MESSAGE = `Error (NotebookEdit): cell_id is required for replace/delete.`;
-export function createNotebookEditTool(env, state, rootCanonical, cwdRef, additionalRoots, beforeWrite, trackEdit, onEdited, writeFace) {
+export function createNotebookEditTool(env, state, rootCanonical, cwdRef, additionalRoots, beforeWrite, trackEdit, onEdited, writeFace, writeDeny) {
     return defineTool({
         name: "NotebookEdit",
         ...toolFace("notebook-edit"),
@@ -458,7 +458,7 @@ export function createNotebookEditTool(env, state, rootCanonical, cwdRef, additi
                 return { ok: false, code: "invalid", message: NOTEBOOK_CELL_TYPE_REQUIRED_MESSAGE };
             if (mode !== "insert" && !a.cell_id)
                 return { ok: false, code: "invalid", message: NOTEBOOK_CELL_ID_REQUIRED_MESSAGE };
-            const r = await resolveKey(env, rootCanonical, a.notebook_path, ctx.signal, cwdRef?.current, additionalRoots, undefined, undefined, writeFace);
+            const r = await resolveKey(env, rootCanonical, a.notebook_path, ctx.signal, cwdRef?.current, additionalRoots, undefined, writeDeny, writeFace?.());
             if (!r.ok)
                 return { ok: true };
             const notRead = requireRead(state, r.key);
@@ -478,7 +478,7 @@ export function createNotebookEditTool(env, state, rootCanonical, cwdRef, additi
                 return errorResult(NOTEBOOK_CELL_TYPE_REQUIRED_MESSAGE);
             if (mode !== "insert" && !cell_id)
                 return errorResult(NOTEBOOK_CELL_ID_REQUIRED_MESSAGE);
-            const r = await resolveKey(env, rootCanonical, notebook_path, ctx.signal, cwdRef?.current, additionalRoots, undefined, undefined, writeFace);
+            const r = await resolveKey(env, rootCanonical, notebook_path, ctx.signal, cwdRef?.current, additionalRoots, undefined, writeDeny, writeFace?.());
             if (!r.ok)
                 return errorResult(violationText("NotebookEdit", r.violation), violationDetails(r.violation));
             const notRead = requireRead(state, r.key);