@sema-agent/core 5.29.0 → 5.30.0

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

@@ -1,7 +1,9 @@
 import type { AgentTool, ExecutionEnv } from "../../internal/harness-types.js";
 import type { ToolEffect } from "../../core/types.js";
-export declare function createGrepTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: readonly string[]): AgentTool;
-export declare function createGlobTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: readonly string[]): AgentTool;
+import type { ReadDenyMatcher } from "./read-deny.js";
+import type { ReadFace } from "./read-face.js";
+export declare function createGrepTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: readonly string[], readDeny?: ReadDenyMatcher, readFace?: ReadFace): AgentTool;
+export declare function createGlobTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: readonly string[], readDeny?: ReadDenyMatcher, readFace?: ReadFace): AgentTool;
 /** Static side-effect class of every hand tool, by name (design/44 §3). Used by prepare-task to (a) feed
  *  wake/resume reconciliation and (b) drive the verifier read-only boundary. Every mutating hand tool is
  *  `write` (RB-264 ⑥W1 folded `Write` back in — see below); `bash` is `write` (a command can do anything);

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

@@ -2,7 +2,7 @@ import { Type } from "typebox";
 import { defineTool, errorResult } from "../../core/tools.js";
 import { resolveKey, violationText, violationDetails } from "./safety.js";
 import { runGrepDetailed, runGlobDetailed, splitAbsoluteGlobPattern, invalidGlobTokens } from "./search.js";
-export function createGrepTool(env, rootCanonical, additionalRoots) {
+export function createGrepTool(env, rootCanonical, additionalRoots, readDeny, readFace) {
     return defineTool({
         name: "Grep",
         contract: { contractId: "core.grep@1", implementationRevision: "1" },
@@ -69,10 +69,17 @@ export function createGrepTool(env, rootCanonical, additionalRoots) {
             }
             let scoped = a.path;
             if (a.path !== undefined) {
-                const r = await resolveKey(env, rootCanonical, a.path, ctx.signal, rootCanonical, additionalRoots);
+                const r = await resolveKey(env, rootCanonical, a.path, ctx.signal, rootCanonical, additionalRoots, undefined, readDeny, readFace);
                 if (!r.ok)
                     return errorResult(violationText("Grep", r.violation), violationDetails(r.violation));
                 scoped = r.key;
+                const info = await env.fileInfo(scoped, ctx.signal);
+                if (!info.ok) {
+                    const ex = await env.exists(scoped, ctx.signal);
+                    if (!(ex.ok && !ex.value)) {
+                        return errorResult(`Error (Grep): cannot determine the type of "${a.path.slice(0, 300)}" (stat failed: ${info.error.message.slice(0, 200)}); refusing to search it — if it is a FIFO/socket/device, reading it would hang. Retry if this was transient.`);
+                    }
+                }
             }
             const grepRun = await runGrepDetailed(env, rootCanonical, {
                 ...a,
@@ -83,7 +90,7 @@ export function createGrepTool(env, rootCanonical, additionalRoots) {
                 context_before: a.context_before ?? a["-B"],
                 ignore_case: a.ignore_case ?? a["-i"],
                 only_matching: a.only_matching ?? a["-o"],
-            }, ctx.signal);
+            }, ctx.signal, readDeny);
             const text = grepRun.text;
             if (text.startsWith("Error (grep)") || text.startsWith("Error (Grep)"))
                 return errorResult(text);
@@ -148,12 +155,12 @@ export function createGrepTool(env, rootCanonical, additionalRoots) {
             }
             return {
                 content: text,
-                details: { type: "grep", mode, ...detailFields, ...(grepRun.degraded ?? {}) },
+                details: { type: "grep", mode, ...detailFields, ...(grepRun.degraded ?? {}), ...(grepRun.withheld !== undefined ? { withheld: grepRun.withheld } : {}) },
             };
         },
     });
 }
-export function createGlobTool(env, rootCanonical, additionalRoots) {
+export function createGlobTool(env, rootCanonical, additionalRoots, readDeny, readFace) {
     return defineTool({
         name: "Glob",
         contract: { contractId: "core.glob@1", implementationRevision: "1" },
@@ -188,17 +195,17 @@ export function createGlobTool(env, rootCanonical, additionalRoots) {
             }
             let scoped = path;
             if (path !== undefined) {
-                const r = await resolveKey(env, rootCanonical, path, ctx.signal, rootCanonical, additionalRoots);
+                const r = await resolveKey(env, rootCanonical, path, ctx.signal, rootCanonical, additionalRoots, undefined, readDeny, readFace);
                 if (!r.ok)
                     return errorResult(violationText("Glob", r.violation), violationDetails(r.violation));
                 scoped = r.key;
             }
-            const r2 = await runGlobDetailed(env, rootCanonical, pattern, { path: scoped, max: max_results }, ctx.signal);
+            const r2 = await runGlobDetailed(env, rootCanonical, pattern, { path: scoped, max: max_results, ...(readDeny !== undefined ? { deny: readDeny } : {}) }, ctx.signal);
             if (r2.error !== undefined)
                 return errorResult(r2.error);
             return {
                 content: r2.text,
-                details: { type: "glob", filenames: r2.filenames, numFiles: r2.numFiles, truncated: r2.truncated, durationMs: r2.durationMs, totalMatches: r2.totalMatches, countIsComplete: r2.countIsComplete },
+                details: { type: "glob", filenames: r2.filenames, numFiles: r2.numFiles, truncated: r2.truncated, durationMs: r2.durationMs, totalMatches: r2.totalMatches, countIsComplete: r2.countIsComplete, ...(r2.withheld !== undefined ? { withheld: r2.withheld } : {}) },
             };
         },
     });

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

@@ -441,7 +441,11 @@ export declare function applyCompactionToReadFileState(state: ReadFileState, att
  *  plus a `Did you mean <sibling>?` correction when the parent directory holds a near-name (case
  *  variant / same stem different extension — the high-frequency self-heal path). Best-effort: a
  *  listDir failure just omits the suggestion. */
-export declare function enoentMessage(env: ExecutionEnv, key: string, cwd: string, signal?: AbortSignal): Promise<string>;
+export declare function enoentMessage(env: ExecutionEnv, key: string, cwd: string, signal?: AbortSignal, readDeny?: {
+    matchPath(path: string): {
+        pattern: string;
+    } | null;
+}): Promise<string>;
 /** Per-task mutable working directory shared by the shell and the path-taking fs tools (design/64 §16.3).
  *  Holds the RAW path (never canonicalized): bash `cd` updates `current`, and the fs tools resolve relative
  *  paths against it. Containment is still enforced per-op by resolveKey (canonicalize + within), so a `cd`

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

@@ -275,22 +275,27 @@ export function applyCompactionToReadFileState(state, attachedComplete, preserve
         state.set(f.path, { hash: sha256(f.content), totalLines, truncated: false, view: { start: 1, end: displayLines }, lastReadAt: Date.now() });
     }
 }
-export async function enoentMessage(env, key, cwd, signal) {
+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("\\"));
     if (sep > 0) {
         const parent = key.slice(0, sep);
         const name = key.slice(sep + 1);
+        if (readDeny?.matchPath(parent) != null)
+            return msg;
         const cwdSepped = cwd.replace(/[\\/]+$/, "");
         const cwdCandidate = `${cwdSepped}${cwd.includes("\\") ? "\\" : "/"}${name}`;
-        if (cwdCandidate !== key) {
+        if (cwdCandidate !== key && readDeny?.matchPath(cwdCandidate) == null) {
             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));
+            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 suggestion = similarNameSuggestion(names, name);
             if (suggestion)
                 msg += ` Did you mean ${suggestion}?`;

package/dist/tools/fs/index.d.ts

@@ -10,6 +10,9 @@ export * from "./fs-write.js";
 export * from "./fs-search-tools.js";
 export * from "./bash-readonly-classifier.js";
 export * from "./fs-bash.js";
+export * from "./read-deny.js";
+import { type ReadDenyEntry } from "./read-deny.js";
+export * from "./read-face.js";
 import { type CwdRef, type ReadImageDownsamplerOption } from "./fs-shared.js";
 /** Options for {@link createHandsToolkit}. */
 export interface HandsToolkitOptions {
@@ -115,6 +118,21 @@ export interface HandsToolkitOptions {
      *  this run's roster (the Runner mounts Monitor, this band never does). `false` drops the gh
      *  rate-limit hint's Monitor clause; absent ⇒ historic full wording (byte-compat). */
     monitorToolActive?: boolean;
+    /** design/199 件B — ADDITIONS to the built-in sensitive-path READ deny set
+     *  ({@link import("./read-deny.js").READ_FACE_DEFAULT_DENY_ENTRIES}), judged by the structured read
+     *  faces (Read/Grep/Glob/RepoMap and their traversals) in BOTH containment modes. Add-only at every
+     *  layer (D-4 zero-shrink ruling): the built-ins are always in force, `[]` ≡ absent (union
+     *  identity), and there is no replacement escape hatch. Bad entry shapes throw at wiring time
+     *  (#123). The write faces are untouched (their guard is createSensitivePathPolicy). */
+    readDenyPatterns?: readonly ReadDenyEntry[];
+    /** design/199 件A — the READ-face containment state for the structured read faces
+     *  ({@link import("./read-face.js").ReadFace}; resolved through the SAME
+     *  {@link import("./read-face.js").resolveReadFace} order prepare-task uses). Absent ⇒ the
+     *  resolution order's default = "roots" (D-1b: the engine never opens implicitly). "open" skips
+     *  ONLY the roots containment judgment — the deny set, the UNC out-of-set refusal and the
+     *  special-file type gates run in both faces (§2.0). Refused loudly beside `readOnly: true`
+     *  (the verifier mount's containment is load-bearing). Never affects the write faces. */
+    readFace?: "open" | "roots";
 }
 /**
  * Build the per-task hand tool band over an injected env + fresh per-task read state (design/44 §11 A).

package/dist/tools/fs/index.js

@@ -9,7 +9,11 @@ export * from "./fs-write.js";
 export * from "./fs-search-tools.js";
 export * from "./bash-readonly-classifier.js";
 export * from "./fs-bash.js";
+export * from "./read-deny.js";
 import { BASH_READONLY_DEFAULT_ALLOW, } from "./bash-readonly-classifier.js";
+import { compileReadDeny } from "./read-deny.js";
+import { resolveReadFace } from "./read-face.js";
+export * from "./read-face.js";
 import {} from "./fs-shared.js";
 import { createReadFileTool } from "./fs-read.js";
 import { createEditFileTool, createWriteFileTool, createNotebookEditTool } from "./fs-write.js";
@@ -29,13 +33,20 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
             scope: c.principal ?? opts.taskScope,
             ...(opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {}),
         }, env);
+    const readDeny = compileReadDeny(opts.readDenyPatterns ?? [], "HandsToolkitOptions.readDenyPatterns");
+    const readFace = resolveReadFace({
+        depsReadFace: opts.readFace,
+        readOnlyMount: readOnly,
+        orgGoverned: false,
+        fullShellReachable: includeShell && !readOnly,
+    });
     const tools = [
-        createReadFileTool(env, readFileState, rootCanonical, readOnly ? undefined : cwdRef, readFaceRoots, opts.readImageDownsampler, opts.pdfModelCapabilities, bgOutputReadExemption, opts.readCyberReminder),
+        createReadFileTool(env, readFileState, rootCanonical, readOnly ? undefined : cwdRef, readFaceRoots, opts.readImageDownsampler, opts.pdfModelCapabilities, bgOutputReadExemption, opts.readCyberReminder, readDeny, readFace),
     ];
     if (!readOnly) {
         tools.push(createEditFileTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite), createWriteFileTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite), createNotebookEditTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite));
     }
-    tools.push(createGrepTool(env, rootCanonical, readFaceRoots), createGlobTool(env, rootCanonical, readFaceRoots), createRepoMapTool(env, rootCanonical, readFaceRoots));
+    tools.push(createGrepTool(env, rootCanonical, readFaceRoots, readDeny, readFace), createGlobTool(env, rootCanonical, readFaceRoots, readDeny, readFace), createRepoMapTool(env, rootCanonical, readFaceRoots, readDeny, readFace));
     if (includeShell) {
         tools.push(readOnly
             ? createBashReadonlyTool(env, rootCanonical, new Set(bashReadonlyAllow ?? BASH_READONLY_DEFAULT_ALLOW), {

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

@@ -0,0 +1,105 @@
+/**
+ * One deny entry: a `/`-separated run of path SEGMENTS. `*` matches any run of non-separator
+ * characters within one segment and is the ONLY metacharacter (everything else is literal). The run
+ * may match ANYWHERE in the judged path (`.ssh` covers `~/.ssh/…` and any other `.ssh` directory).
+ * String shorthand ≡ `{ pattern }`. Matching is ASCII-case-insensitive by default (a case-insensitive
+ * filesystem serves `.SSH` and `.ssh` as the same directory); `caseSensitive: true` opts a single
+ * entry out. Unicode normalization (NFC/NFD) and volume-level case semantics are NOT modeled (v1
+ * residual, shared with the write guard; the canonical view — realpath returns the on-disk spelling —
+ * covers half of it).
+ */
+export type ReadDenyEntry = string | {
+    pattern: string;
+    caseSensitive?: boolean;
+};
+/** The normalized (validated, defaulted) form of one entry. */
+export interface NormalizedReadDenyEntry {
+    pattern: string;
+    caseSensitive: boolean;
+}
+/** A deny verdict: which entry's pattern matched. */
+export interface ReadDenyHit {
+    pattern: string;
+}
+/** One compiled ripgrep glob flag for the traversal legs (`--iglob` = case-insensitive entry). */
+export interface ReadDenyRgGlob {
+    flag: "--glob" | "--iglob";
+    glob: string;
+}
+/**
+ * The compiled deny judge — ONE compilation, consumed by every judgment point (target judgment in
+ * resolveKey, the JS walker, the rg exclusion/probe legs, the classify operand probe, the ENOENT
+ * sibling filter, the attachment reader), so the legs cannot drift apart.
+ */
+export interface ReadDenyMatcher {
+    /** Normalized entries (built-ins first, then additions; exact duplicates folded). The disclosure /
+     *  persistence face. */
+    readonly entries: readonly NormalizedReadDenyEntry[];
+    /** Judge ONE path view (segment-window semantics). Returns the first matching entry, or null. */
+    matchPath(path: string): ReadDenyHit | null;
+    /** §3.3 target judgment: canonical view + lexical view; EITHER hit decides. */
+    matchTarget(canonicalKey: string, lexicalView?: string): ReadDenyHit | null;
+    /** Traversal exclusions for the rg legs: `!`-polarity glob pairs — `!**\/<p>` plus `!**\/<p>/…`
+     *  (the entry itself and its descendants). */
+    readonly rgExclusionGlobs: readonly ReadDenyRgGlob[];
+    /** Positive-polarity twins of the exclusions, for the bounded existence probe (first hit = entries
+     *  matching the deny list exist under the scope and were excluded). */
+    readonly rgProbeGlobs: readonly ReadDenyRgGlob[];
+}
+/**
+ * READ_FACE_DEFAULT_DENY_ENTRIES — the built-in table (D-4 ruling: ONE tier, credential-class path
+ * families; the design's `outside_workspace` tier was ruled OUT, and the dotenv family is deliberately
+ * NOT here — workspace `.env` files are working material for the tasks this engine runs).
+ *
+ * Each row states its tradeoff. Rows are matched as segment runs anywhere in the path, so a repo
+ * fixture spelled `fixtures/.ssh/id_rsa` is refused too — deliberate: the refusal names the pattern,
+ * and a false refusal on a fixture is the cheap direction (deny errs strict).
+ *
+ * NOT listed, deliberately: `.env`/`.env.*` (ruled out — workspace material; the WRITE guard still
+ * covers them); `*.pem`/`*.key`/`*.p12`/`*.pfx` (repo certificates/test keys are routinely READ —
+ * refusing them breaks ordinary work, the write guard covers the mutation direction); `.git/hooks`/
+ * `.git/config` (reads are harmless; writes are the escalation and stay guarded); `.claude*`/
+ * `.mcp.json` (agent config is routinely read for debugging); the engine's own data root
+ * (transcript integrity policy owns it with an ask on the write face).
+ */
+export declare const READ_FACE_DEFAULT_DENY_ENTRIES: readonly ReadDenyEntry[];
+/** A compiled segment-run pattern (shared engine — the write guard delegates here too). */
+export interface CompiledSegmentPattern {
+    raw: string;
+    segments: RegExp[];
+    /** Fold BOTH sides through {@link asciiLower} before testing (compile lowered the pattern side). */
+    foldAscii: boolean;
+}
+/**
+ * Compile one segment-glob pattern (shared engine). `fold`:
+ *  · "none"    — byte-exact segments;
+ *  · "ascii"   — ASCII-case-insensitive (deny-set contract);
+ *  · "unicode" — RegExp `i` flag (the write guard's historical host-keyed behavior — kept for it
+ *    byte-identically; NOT used by the deny set).
+ * Returns null when the pattern reduces to zero segments — the CALLER owns its loud path (#123: the
+ * two consumers refuse with their own surface-specific texts).
+ */
+export declare function compileSegmentPattern(raw: string, fold: "none" | "ascii" | "unicode"): CompiledSegmentPattern | null;
+/**
+ * Does the path contain a compiled pattern as a CONTIGUOUS run of full path segments? (Shared engine:
+ * `.git/hooks` matches `/repo/.git/hooks/pre-commit`; `.ssh` matches any `.ssh` segment.) Splits on
+ * BOTH separator families — win32 canonical keys are backslash-form. Returns the matched raw pattern
+ * or null.
+ */
+export declare function matchSegmentPatterns(path: string, compiled: readonly CompiledSegmentPattern[]): string | null;
+/**
+ * codex r3 — the PURE validation/canonicality predicate over a PERSISTED deny entry (checkpoint v9
+ * face section), for the resume pre-CAS ladder: it must refuse BEFORE the approval CAS everything
+ * {@link compileReadDeny} would throw on AFTER it (a post-CAS compile throw consumes the human's
+ * approval and strands the row), plus non-canonical spellings (normalizeEntry canonicalizes at every
+ * mint, so a persisted non-canonical pattern was not minted by any release = damaged). Returns the
+ * refusal reason, or null when the entry is valid.
+ */
+export declare function persistedReadDenyEntryProblem(e: unknown): string | null;
+/**
+ * Compile the read-face deny judge: built-in table ∪ additions (add-only at every layer — D-4
+ * zero-shrink; `[]` additions ≡ absent, deliberately a no-op rather than a refusal: an array API
+ * cannot observe a "replace" intent, and union-with-empty is the identity, not a silent fallback).
+ * Bad entry shapes / zero-segment patterns throw loudly, naming the layer (#123).
+ */
+export declare function compileReadDeny(additions?: readonly ReadDenyEntry[], layer?: string): ReadDenyMatcher;

package/dist/tools/fs/read-deny.js

@@ -0,0 +1,151 @@
+export const READ_FACE_DEFAULT_DENY_ENTRIES = [
+    ".ssh",
+    "id_rsa*",
+    "id_ed25519*",
+    "id_ecdsa*",
+    ".gnupg",
+    ".aws",
+    ".config/gcloud",
+    ".azure",
+    ".kube",
+    ".netrc",
+    "_netrc",
+    ".git-credentials",
+    ".docker/config.json",
+    ".config/gh",
+    ".npmrc",
+    ".pypirc",
+    ".local/share/keyrings",
+    "Library/Keychains",
+    ".bash_history",
+    ".zsh_history",
+    "Library/Application Support/Google/Chrome",
+    "Library/Application Support/Firefox",
+    "Library/Safari",
+    ".config/google-chrome",
+    ".config/chromium",
+    ".mozilla/firefox",
+    "AppData/Local/Google/Chrome/User Data",
+    "AppData/Local/Microsoft/Edge/User Data",
+    "AppData/Roaming/Mozilla/Firefox",
+    ".bitcoin",
+    ".ethereum",
+    ".electrum",
+    "Library/Application Support/Exodus",
+    "Library/Application Support/Ledger Live",
+    "wallet.dat",
+];
+function asciiLower(s) {
+    let out = "";
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        out += c >= 0x41 && c <= 0x5a ? String.fromCharCode(c + 32) : s[i];
+    }
+    return out;
+}
+export function compileSegmentPattern(raw, fold) {
+    const source = fold === "ascii" ? asciiLower(raw) : raw;
+    const parts = source.split("/").filter(Boolean);
+    if (parts.length === 0)
+        return null;
+    const flags = fold === "unicode" ? "i" : "";
+    const segments = parts.map((segment) => {
+        const escaped = segment.replace(/[.+^${}()|[\]\\?]/g, "\\$&").replace(/\*/g, "[^/]*");
+        return new RegExp(`^${escaped}$`, flags);
+    });
+    return { raw, segments, foldAscii: fold === "ascii" };
+}
+export function matchSegmentPatterns(path, compiled) {
+    const rawSegs = path.split(/[\\/]/).filter(Boolean);
+    let loweredSegs;
+    for (const pat of compiled) {
+        const segs = pat.foldAscii ? (loweredSegs ??= rawSegs.map(asciiLower)) : rawSegs;
+        const n = pat.segments.length;
+        for (let i = 0; i + n <= segs.length; i++) {
+            if (pat.segments.every((re, j) => re.test(segs[i + j] ?? "")))
+                return pat.raw;
+        }
+    }
+    return null;
+}
+function rgGlobEscape(pattern) {
+    return pattern.replace(/[?[\]{}]/g, (c) => `[${c}]`);
+}
+function normalizeEntry(entry, layer) {
+    const shape = typeof entry === "string" ? { pattern: entry, caseSensitive: false } : entry;
+    if (typeof shape !== "object" || shape === null || typeof shape.pattern !== "string") {
+        throw new Error(`readDenyPatterns (${layer}): entry ${JSON.stringify(entry)} is not a pattern string or { pattern, caseSensitive? } object.`);
+    }
+    if (shape.caseSensitive !== undefined && typeof shape.caseSensitive !== "boolean") {
+        throw new Error(`readDenyPatterns (${layer}): entry ${JSON.stringify(entry)} has a non-boolean caseSensitive.`);
+    }
+    if (shape.pattern.includes("\\")) {
+        throw new Error(`readDenyPatterns (${layer}): pattern ${JSON.stringify(shape.pattern)} contains a backslash — patterns are "/"-separated segment runs (both path families are matched); spell the segments with "/".`);
+    }
+    const segments = shape.pattern.split("/").filter(Boolean);
+    if (segments.length === 0) {
+        throw new Error(`readDenyPatterns (${layer}): pattern ${JSON.stringify(shape.pattern)} contains no path segments and would deny nothing. ` +
+            `Patterns are "/"-separated runs of path SEGMENTS (e.g. ".ssh", ".config/gcloud", "id_rsa*"); remove the entry or spell the segments.`);
+    }
+    return { pattern: segments.join("/"), caseSensitive: shape.caseSensitive === true };
+}
+export function persistedReadDenyEntryProblem(e) {
+    if (typeof e !== "object" || e === null)
+        return "entry is not an object";
+    const pattern = e.pattern;
+    const caseSensitive = e.caseSensitive;
+    if (typeof pattern !== "string")
+        return "pattern is not a string";
+    if (typeof caseSensitive !== "boolean")
+        return "caseSensitive is not a boolean";
+    if (pattern.includes("\\"))
+        return "pattern contains a backslash";
+    const segments = pattern.split("/").filter(Boolean);
+    if (segments.length === 0)
+        return "pattern has no path segments";
+    if (segments.join("/") !== pattern)
+        return "pattern is not in canonical a/b form";
+    return null;
+}
+export function compileReadDeny(additions = [], layer = "additions") {
+    const normalized = [];
+    const seen = new Set();
+    const push = (e) => {
+        const key = `${e.caseSensitive ? "s" : "i"}:${e.pattern}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        normalized.push(e);
+    };
+    for (const entry of READ_FACE_DEFAULT_DENY_ENTRIES)
+        push(normalizeEntry(entry, "built-in"));
+    for (const entry of additions)
+        push(normalizeEntry(entry, layer));
+    const compiled = normalized.map((e) => {
+        const c = compileSegmentPattern(e.pattern, e.caseSensitive ? "none" : "ascii");
+        if (c === null)
+            throw new Error(`readDenyPatterns: pattern ${JSON.stringify(e.pattern)} compiled to zero segments.`);
+        return c;
+    });
+    const rgExclusionGlobs = [];
+    const rgProbeGlobs = [];
+    for (const e of normalized) {
+        const flag = e.caseSensitive ? "--glob" : "--iglob";
+        const g = rgGlobEscape(e.pattern);
+        rgExclusionGlobs.push({ flag, glob: `!**/${g}` }, { flag, glob: `!**/${g}/**` });
+        rgProbeGlobs.push({ flag, glob: `**/${g}` }, { flag, glob: `**/${g}/**` });
+    }
+    const matchPath = (path) => {
+        const hit = matchSegmentPatterns(path, compiled);
+        return hit === null ? null : { pattern: hit };
+    };
+    return {
+        entries: normalized,
+        matchPath,
+        matchTarget(canonicalKey, lexicalView) {
+            return matchPath(canonicalKey) ?? (lexicalView !== undefined ? matchPath(lexicalView) : null);
+        },
+        rgExclusionGlobs,
+        rgProbeGlobs,
+    };
+}

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

@@ -0,0 +1,43 @@
+/** The read-face containment state. `"roots"` = the historical containment judgment, unchanged.
+ *  `"open"` = the containment step is skipped (canonicalization, deny set, UNC out-of-set refusal
+ *  and the type gates all still run). */
+export type ReadFace = "open" | "roots";
+/** Inputs to {@link resolveReadFace} — all structural/declaration facts, never permission modes
+ *  (a deliberate axis separation: this shape carries facts, not verdicts). */
+export interface ReadFaceInputs {
+    /** TaskSpec.readFace (raw — validated here). The TASK layer: may only tighten under governance. */
+    specReadFace?: unknown;
+    /** RunnerDeps.readFace / HandsToolkitOptions.readFace (raw) — the DEPLOYMENT's own declaration. */
+    depsReadFace?: unknown;
+    /** The verifier read-only mount (`handsReadOnly` / toolkit `readOnly`): its containment is a
+     *  LOAD-BEARING wall (bash_readonly is genuinely confined by it) — never openable. */
+    readOnlyMount: boolean;
+    /** Org governance declared (RunnerDeps.permissionRuleOrg in place): default roots; the task layer
+     *  may not open (D-2 — tighten-only under governance; the deps layer, being the deployment's own
+     *  declaration, still may). */
+    orgGoverned: boolean;
+    /** D-6: is the FULL shell (`core.bash@1`) structurally reachable on this mount? Computed BEFORE
+     *  tool-band assembly from spec-time facts (env kind / handsReadOnly / Bash exclusion — recon §3:
+     *  every exclusion source is spec-time-frozen, so this is always computable). When false, the
+     *  roots fence is the ONLY read boundary and the default stays roots even under a deps-layer
+     *  "open"… no — see the resolution order: an EXPLICIT open still wins (row 4 is a default, not a
+     *  clamp); what it changes is that NOTHING implicit opens a bash-less mount. */
+    fullShellReachable: boolean;
+}
+/**
+ * The ONE resolution order (§2.2), first hit wins. prepare-task AND createHandsToolkit both call
+ * this — a library-direct mount gets identical validation and identical defaults.
+ *
+ *  1. read-only (verifier) mount → ROOTS; an explicit "open" on the TASK seat is a genuine
+ *     per-call CONTRADICTION and refuses loudly (#123 — never silently pick a side). An "open"
+ *     on the DEPLOYMENT seat alone is a deployment-wide default, not a per-task assertion — it
+ *     silently CLAMPS to roots (stricter-wins), same seat distinction row 2 already draws for
+ *     org governance below.
+ *  2. org-governed: TaskSpec "open" refuses (task layer only tightens, D-2); deps "open" wins;
+ *     otherwise ROOTS.
+ *  3. explicit seat: spec ?? deps.
+ *  4. bash-less mount (D-6): ROOTS (the fence is the only read boundary there — "the fence guards
+ *     nothing bash reaches anyway" does not hold, so no implicit default may open it).
+ *  5. default: ROOTS (D-1b — the engine never opens implicitly).
+ */
+export declare function resolveReadFace(i: ReadFaceInputs): ReadFace;

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

@@ -0,0 +1,38 @@
+function assertReadFaceValue(v, seat) {
+    if (v === undefined)
+        return undefined;
+    if (v === "open" || v === "roots")
+        return v;
+    const e = new Error(`${seat}: invalid readFace value ${JSON.stringify(v)} — expected "open" or "roots" (bad values refuse loudly; nothing falls back to a default).`);
+    e.code = "config.read_face_invalid";
+    throw e;
+}
+export function resolveReadFace(i) {
+    const spec = assertReadFaceValue(i.specReadFace, "TaskSpec.readFace");
+    const deps = assertReadFaceValue(i.depsReadFace, "readFace (deployment seat)");
+    if (i.readOnlyMount) {
+        if (spec === "open") {
+            const e = new Error(`readFace: "open" contradicts the read-only (verifier) mount — that mount's containment is load-bearing (its read-only shell face is confined by it) and is never openable. Drop the readFace declaration or the readOnly mount.`);
+            e.code = "config.read_face_readonly_conflict";
+            throw e;
+        }
+        return "roots";
+    }
+    if (i.orgGoverned) {
+        if (spec === "open") {
+            const e = new Error(`TaskSpec.readFace: "open" is refused under organization governance — the task layer may only tighten (set RunnerDeps.readFace: "open" if the DEPLOYMENT declares the open read face).`);
+            e.code = "config.read_face_org_task_escalation";
+            throw e;
+        }
+        if (spec === "roots")
+            return "roots";
+        return deps ?? "roots";
+    }
+    if (spec !== undefined)
+        return spec;
+    if (deps !== undefined)
+        return deps;
+    if (!i.fullShellReachable)
+        return "roots";
+    return "roots";
+}

package/dist/tools/fs/repo-map.d.ts

@@ -1,5 +1,7 @@
 import type { AgentTool } from "../../internal/harness-types.js";
 import type { ExecutionEnv } from "../../internal/harness-types.js";
+import type { ReadDenyMatcher } from "./read-deny.js";
+import type { ReadFace } from "./read-face.js";
 /** Extract top-level symbol names (deduped, in first-seen order) from source text. A lightweight
  *  comment/docstring state machine (council #4) skips column-0 declaration-like lines that are really
  *  inside a `/* … *​/` block comment or a Python `"""`/`'''` docstring — otherwise e.g. a module
@@ -11,4 +13,4 @@ import type { ExecutionEnv } from "../../internal/harness-types.js";
  *  auto-promote tripwire (src/core/auto-promote.ts) consumes it in ESCALATE-ONLY mode — a clean scan
  *  contributes nothing; it can only ever raise an escalation, never clear one. */
 export declare function extractSymbols(text: string): string[];
-export declare function createRepoMapTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: readonly string[]): AgentTool;
+export declare function createRepoMapTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: readonly string[], readDeny?: ReadDenyMatcher, readFace?: ReadFace): AgentTool;

package/dist/tools/fs/repo-map.js

@@ -1,7 +1,7 @@
 import { Type } from "typebox";
 import { defineTool, errorResult } from "../../core/tools.js";
 import { resolveKey, violationText, violationDetails } from "./safety.js";
-import { buildIgnore, walk, walkIsPartial } from "./search.js";
+import { buildIgnore, denyWithheldNote, walk, walkIsPartial } from "./search.js";
 const DEFAULT_MAX_CHARS = 16_000;
 const DEFAULT_MAX_FILES = 400;
 const FILE_SCAN_MAX_BYTES = 256 * 1024;
@@ -79,7 +79,7 @@ function rankEntries(a, b) {
         return b.symbols.length - a.symbols.length;
     return a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0;
 }
-export function createRepoMapTool(env, rootCanonical, additionalRoots) {
+export function createRepoMapTool(env, rootCanonical, additionalRoots, readDeny, readFace) {
     return defineTool({
         name: "RepoMap",
         contract: { contractId: "core.repo_map@1", implementationRevision: "1" },
@@ -88,7 +88,7 @@ export function createRepoMapTool(env, rootCanonical, additionalRoots) {
             "what exists and where, so you can jump to the relevant files. Token-budgeted and honest about " +
             "truncation. Optionally scope to a sub-directory.",
         parameters: Type.Object({
-            path: Type.Optional(Type.String({ description: "Restrict the map to a sub-directory (relative to root)." })),
+            path: Type.Optional(Type.String({ description: "Restrict the map to a directory (relative paths resolve against the root)." })),
             max_chars: Type.Optional(Type.Number({ description: `Token budget for the rendered map in chars (default ${DEFAULT_MAX_CHARS}; a very small value yields only a truncation note).` })),
             max_files: Type.Optional(Type.Number({ description: `Max files to scan (default ${DEFAULT_MAX_FILES}).` })),
         }),
@@ -99,7 +99,7 @@ export function createRepoMapTool(env, rootCanonical, additionalRoots) {
             const rootPrefix = rootCanonical.replace(/[\\/]+$/, "") + (rootCanonical.includes("\\") ? "\\" : "/");
             let start = rootCanonical;
             if (a.path !== undefined) {
-                const r = await resolveKey(env, rootCanonical, a.path, signal, rootCanonical, additionalRoots);
+                const r = await resolveKey(env, rootCanonical, a.path, signal, rootCanonical, additionalRoots, undefined, readDeny, readFace);
                 if (!r.ok)
                     return errorResult(violationText("RepoMap", r.violation), violationDetails(r.violation));
                 start = r.key;
@@ -107,7 +107,7 @@ export function createRepoMapTool(env, rootCanonical, additionalRoots) {
             const maxChars = Math.max(1, Math.floor(a.max_chars ?? DEFAULT_MAX_CHARS));
             const maxFiles = Math.max(1, Math.floor(a.max_files ?? DEFAULT_MAX_FILES));
             const ignore = await buildIgnore(env, rootCanonical, signal);
-            const walked = await walk(env, rootCanonical, start, ignore, signal);
+            const walked = await walk(env, rootCanonical, start, ignore, signal, readDeny);
             const rel = (abs) => (abs.startsWith(rootPrefix) ? abs.slice(rootPrefix.length) : abs);
             const entries = [];
             const nonSource = [];
@@ -180,6 +180,11 @@ export function createRepoMapTool(env, rootCanonical, additionalRoots) {
                 notes.push("…[the symbol scan was interrupted before finishing — the map is partial]");
             if (skippedUnreadableFiles > 0)
                 notes.push(`…[${skippedUnreadableFiles} source file${skippedUnreadableFiles === 1 ? "" : "s"} could not be read — ${skippedUnreadableFiles === 1 ? "it is" : "they are"} missing from the map]`);
+            {
+                const denyNote = denyWithheldNote(walked).trim();
+                if (denyNote.length > 0)
+                    notes.push(denyNote);
+            }
             if (nonSource.length > 0) {
                 if (!budgetHit) {
                     const NON_SOURCE_CAP = 40;
@@ -198,6 +203,7 @@ export function createRepoMapTool(env, rootCanonical, additionalRoots) {
                 renderedFiles: rendered,
                 nonSourceFiles: nonSource.length,
                 truncated: budgetHit || scanIncomplete || scanAborted || skippedUnreadableFiles > 0 || walkIsPartial(walked) || rendered < entries.length,
+                ...(walked.denyPruned > 0 ? { withheld: { kind: "pruned_count", count: walked.denyPruned, patterns: walked.denyPatterns } } : {}),
             };
             if (lines.length === 0) {
                 const base = start === rootCanonical ? "Repository is empty or has no readable files." : `No readable files under "${a.path}".`;