@sema-agent/core 5.28.0 → 5.30.0

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}".`;

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

@@ -3,7 +3,7 @@ import type { ExecutionEnv } from "../../internal/harness-types.js";
  * batch-B (CC 2.1.187 parity): Read/Edit/Write take the file path as `file_path`. Read the target the same way
  * EVERYWHERE the path is consumed from a tool-call's args — not just the tool body but ALSO every gate that
  * extracts the write target to confine it (sensitive-path, skill allowPaths, session allowDirs). A gate that only
- * read `args.path` would see `undefined` for a `file_path` call and either fail-OPEN (bypass the guard — a real
+ * read `args.path` would see `undefined` for a `file_path` call and either fail-OPEN (circumvent the guard — a real
  * hole) or fail-closed (deny a legitimate write). Single source.
  *
  * The `path` arm is deliberately BROADER than what Read/Edit/Write accept (ruled 2026-08-03): their schema requires
@@ -85,20 +85,23 @@ export type ReadFileState = Map<string, ReadEntry>;
 export declare function sha256(content: string): string;
 /** A failed path resolution / invariant check, surfaced to the model as a self-correctable tool error. */
 export interface FsViolation {
-    code: "path_not_in_root" | "not_read" | "stale" | "ambiguous_edit" | "invalid";
+    code: "path_not_in_root" | "not_read" | "stale" | "ambiguous_edit" | "invalid" | "read_path_denied";
     /** RB-264 N1: set on the `not_read` violation raised by an AUTO-TRUNCATED read
      *  ({@link ReadEntry.isPartialView}) rather than by a never-read file. Both carry the same CC-verbatim
      *  message; only this one needs {@link PARTIAL_VIEW_READ_ESCAPE_HINT} appended, because for it a plain
      *  re-read is a fixpoint. */
     partialView?: true;
-    /** RB-371 ④: set ONLY on `path_not_in_root` — the CANONICAL key the refused path resolved to
-     *  (symlinks followed, tracked cwd applied), i.e. the value the fence actually judged. Rides into
-     *  the tool result's `details` (see {@link violationDetails}) so a consumer can count/aggregate
-     *  boundary refusals from fields instead of regexing the prose. */
+    /** RB-371 ④: set on `path_not_in_root` (and design/199 `read_path_denied`) — the CANONICAL key the
+     *  refused path resolved to (symlinks followed, tracked cwd applied), i.e. the value the fence
+     *  actually judged. Rides into the tool result's `details` (see {@link violationDetails}) so a
+     *  consumer can count/aggregate boundary refusals from fields instead of regexing the prose. */
     target?: string;
     /** RB-371 ④: set ONLY on `path_not_in_root` — the containment roots in effect (primary first,
      *  then additionalDirectories), canonical form. */
     roots?: readonly string[];
+    /** design/199 件B: set ONLY on `read_path_denied` — the deny-list pattern (verbatim entry text)
+     *  the judged target matched. */
+    pattern?: string;
     message: string;
 }
 /**
@@ -250,6 +253,12 @@ export declare function isBinaryContent(sample: string): boolean;
  * This function stays a pure spelling test with no verdict of its own.
  */
 export declare function isUncPath(path: string): boolean;
+/** design/199 件B — the family-aware LEXICAL view of a possibly-relative spelling against a
+ *  resolution base (no I/O, `.`/`..` folded via {@link normalizeAbsPathLexically}): the §3.3 second
+ *  deny-judgment view. It asks "does the NAME land on a guarded path", complementing the canonical
+ *  view's "does the TARGET" — a symlink AT a guarded spelling resolves away from it canonically,
+ *  and only this view still names it. */
+export declare function lexicalViewOf(spelled: string, base: string): string;
 /**
  * Resolve a model-supplied path to a canonical key AND enforce rootPath containment (design/44 §4
  * inv 5/6/7). Existing paths use `canonicalPath` (resolves symlinks, so the same file can't get two
@@ -258,7 +267,11 @@ export declare function isUncPath(path: string): boolean;
  * `path_not_in_root` violation. (Defense-in-depth at the tool layer; NOT a substitute for a sandboxed
  * `executionEnv` — see design/44 §5.)
  */
-export declare function resolveKey(env: ExecutionEnv, rootCanonical: string, path: string, signal?: AbortSignal, baseCwd?: string, additionalRootsCanonical?: readonly string[], exactFileReadExemption?: (canonicalKey: string) => boolean): Promise<{
+export declare function resolveKey(env: ExecutionEnv, rootCanonical: string, path: string, signal?: AbortSignal, baseCwd?: string, additionalRootsCanonical?: readonly string[], exactFileReadExemption?: (canonicalKey: string) => boolean, readDeny?: {
+    matchTarget(canonicalKey: string, lexicalView?: string): {
+        pattern: string;
+    } | null;
+}, readFace?: "open" | "roots"): Promise<{
     ok: true;
     key: string;
 } | {
@@ -301,6 +314,11 @@ export declare function violationDetails(v: FsViolation): {
     code: "path_not_in_root";
     target: string;
     roots: readonly string[];
+} | {
+    type: "read_path_denied";
+    code: "read_path_denied";
+    target: string;
+    pattern: string;
 } | undefined;
 /**
  * RB-371 ② — does `p` sit inside ANY of the canonical containment roots? Exposed for the Bash
@@ -313,12 +331,16 @@ export declare function withinAnyRoot(rootsCanonical: readonly string[], p: stri
 /**
  * RB-371 ① — the escape-hatch tail for the `path_not_in_root` refusal: its three sibling hints
  * below each name a sanctioned next step; this refusal named none, leaving the model to oscillate
- * between "the boundary is hard" and discovering by trial that bash is not confined by it. Both
- * stated ways out are consistent with the Bash tool's own card (the shell is deliberately NOT
- * sandboxed by this fence — design/44 §5 — and every call still passes the deployment's approval
- * policy) and with the deployment-side widening knob (`additionalDirectories`, design/119).
+ * between "the boundary is hard" and discovering by trial that bash is not confined by it.
+ *
+ * Ordering is deliberate (ruled 2026-08-12, fence = the deployment's declared containment
+ * boundary): the SANCTIONED way out — widening the declaration (`additionalDirectories` /
+ * read-only `additionalReadDirectories`, design/119) — leads; the Bash sentence stays as a FACT
+ * (the shell genuinely is not confined by this fence — design/44 §5 — and omitting that would
+ * just let the model discover it by trial), but it is a statement, not a recommendation, and it
+ * comes last. Every shell call still passes the deployment's approval policy.
  */
-export declare const PATH_NOT_IN_ROOT_ESCAPE_HINT = "(This boundary applies to the structured file tools. If you genuinely need content outside the allowed root(s) and the deployment permits it, use the Bash tool \u2014 it is not confined by this fence, though every call remains subject to the deployment's approval policy. Or ask for the directory to be added to additionalDirectories.)";
+export declare const PATH_NOT_IN_ROOT_ESCAPE_HINT = "(This boundary applies to the structured file tools. If you genuinely need content outside the allowed root(s), ask for the directory to be added to the deployment's additionalDirectories \u2014 or additionalReadDirectories for read-only access. For completeness: the Bash tool is not confined by this fence, and every Bash call remains subject to the deployment's approval policy.)";
 /** inv 1 (read-before-edit): a file must have been read this task before it can be edited/overwritten.
  *  Message is CC 2.1.198 live-verbatim (all-tools-live-probe 2026-07-08 §2.1/§3.1/§5.1 — one message for
  *  Edit/Write/NotebookEdit: "before writing to it", not the old sema "before editing").