@sema-agent/core 5.29.0 → 5.31.0

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

@@ -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,12 @@ 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;
+        matchedView?: string;
+    } | null;
+}, readFace?: "open" | "roots"): Promise<{
     ok: true;
     key: string;
 } | {
@@ -301,6 +315,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 +332,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").

package/dist/tools/fs/safety.js

@@ -23,7 +23,10 @@ export function isAbsolutePathForm(p) {
     return p.startsWith("/") || /^[A-Za-z]:[\\/]/.test(p) || p.startsWith("\\\\");
 }
 function normalizeForCompare(p) {
-    let n = isWinFormPath(p) ? p.replace(/\\/g, "/") : p;
+    let n = stripWin32ExtendedPrefix(p);
+    if (isUncPath(n) && isWinFormPath(n) && !isWin32DeviceNamespacePath(n))
+        n = foldUncLexically(n).key;
+    n = isWinFormPath(n) ? n.replace(/\\/g, "/") : n;
     if (/^[A-Za-z]:(\/|$)/.test(n))
         n = n[0].toLowerCase() + n.slice(1);
     return n;
@@ -46,7 +49,7 @@ const PROC_SENSITIVE_SUFFIXES = ["/environ", "/cmdline", "/auxv", "/maps", "/mem
 function isProcSensitiveFile(key) {
     return key.startsWith("/proc/") && PROC_SENSITIVE_SUFFIXES.some((suf) => key.endsWith(suf));
 }
-const WIN_RESERVED_RE = /^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(\.[^\\/]*)?$/i;
+const WIN_RESERVED_RE = /^(CON|PRN|AUX|NUL|COM[0-9¹²³]|LPT[0-9¹²³]|CONIN\$|CONOUT\$)(\.[^\\/]*)?$/i;
 export function isWinFormPath(p) {
     return /^[A-Za-z]:[\\/]/.test(p) || p.startsWith("\\\\") || (!p.startsWith("/") && p.includes("\\"));
 }
@@ -67,6 +70,7 @@ export function foldRedundantPathSegments(p) {
     return foldSegmentsLexically(p, false);
 }
 function foldSegmentsLexically(p, foldParents) {
+    p = stripWin32ExtendedPrefix(p);
     const isUnc = p.startsWith("\\\\");
     const drive = /^[A-Za-z]:/.exec(p)?.[0] ?? "";
     const winForm = isUnc || drive !== "" || (!p.startsWith("/") && p.includes("\\"));
@@ -101,7 +105,7 @@ function foldSegmentsLexically(p, foldParents) {
         outSegs.push(seg);
     }
     if (outSegs.length === 0)
-        return abs ? prefix + sep : prefix === "" ? "." : prefix;
+        return abs ? (isUnc ? prefix : prefix + sep) : prefix === "" ? "." : prefix;
     return prefix + (abs ? sep : "") + outSegs.join(sep);
 }
 const BINARY_EXTENSIONS = new Set([
@@ -262,6 +266,58 @@ export function isBinaryContent(sample) {
 export function isUncPath(path) {
     return path.startsWith("\\\\") || path.startsWith("//");
 }
+function isWin32DeviceNamespacePath(p) {
+    return p.startsWith("\\\\.\\") || p.startsWith("\\\\./");
+}
+function stripWin32ExtendedPrefix(p) {
+    if (!p.startsWith("\\\\?\\"))
+        return p;
+    const rest = p.slice(4);
+    const unc = /^UNC\\/i.exec(rest);
+    const body = unc !== null ? rest.slice(unc[0].length) : /^[A-Za-z]:\\/.test(rest) ? rest.slice(3) : undefined;
+    if (body === undefined)
+        return p;
+    if (body !== "") {
+        for (const seg of body.split("\\")) {
+            if (seg === "" || seg === "." || seg === "..")
+                return p;
+            if (seg.endsWith(".") || seg.endsWith(" ") || seg.includes("/"))
+                return p;
+            if (WIN_RESERVED_RE.test(seg))
+                return p;
+        }
+    }
+    return unc ? "\\\\" + rest.slice(unc[0].length) : rest;
+}
+function foldUncLexically(p) {
+    const body = p.slice(2);
+    const segs = body.split(/[\\/]+/).filter((s) => s !== "");
+    const host = segs.shift() ?? "";
+    const share = segs.shift();
+    const out = [];
+    let climbed = false;
+    for (const seg of segs) {
+        if (seg === ".")
+            continue;
+        if (seg === "..") {
+            if (out.length === 0)
+                climbed = true;
+            else
+                out.pop();
+            continue;
+        }
+        const stripped = seg.replace(/[. ]+$/, "");
+        out.push(stripped.length > 0 ? stripped : seg);
+    }
+    const anchor = `\\\\${host}${share !== undefined ? `\\${share}` : ""}`;
+    return { key: out.length > 0 ? `${anchor}\\${out.join("\\")}` : anchor, climbedAboveShare: climbed };
+}
+export function lexicalViewOf(spelled, base) {
+    const abs = isAbsolutePathForm(spelled)
+        ? spelled
+        : `${base.replace(/[\\/]+$/, "")}${isWinFormPath(base) && base.includes("\\") ? "\\" : "/"}${spelled}`;
+    return normalizeAbsPathLexically(abs);
+}
 function within(rootCanonical, p) {
     if (!rootCanonical)
         return false;
@@ -274,7 +330,7 @@ function within(rootCanonical, p) {
     const base = rootN.endsWith(SEP) ? rootN : rootN + SEP;
     return pN.startsWith(base);
 }
-export async function resolveKey(env, rootCanonical, path, signal, baseCwd, additionalRootsCanonical, exactFileReadExemption) {
+export async function resolveKey(env, rootCanonical, path, signal, baseCwd, additionalRootsCanonical, exactFileReadExemption, readDeny, readFace) {
     const canon = await canonicalizeTarget(env, path, signal, baseCwd);
     if (!canon.ok)
         return { ok: false, violation: { code: "invalid", message: canon.message } };
@@ -282,6 +338,36 @@ export async function resolveKey(env, rootCanonical, path, signal, baseCwd, addi
     if (isBlockedDevicePath(key)) {
         return { ok: false, violation: { code: "invalid", message: `path "${path}" is a blocked device/special file (reading it can hang the process); refused.` } };
     }
+    if (readDeny !== undefined) {
+        const hit = readDeny.matchTarget(key, lexicalViewOf(path, baseCwd ?? rootCanonical));
+        if (hit !== null) {
+            const lexicalHit = hit.matchedView !== undefined && hit.matchedView !== key;
+            const judged = lexicalHit
+                ? `the requested path's spelling ("${hit.matchedView}") matches`
+                : `the target matches`;
+            return {
+                ok: false,
+                violation: {
+                    code: "read_path_denied",
+                    message: `reading "${path}" ${key !== path ? `(canonical target: "${key}") ` : ""}is refused: ${judged} the sensitive-path read deny list (pattern "${hit.pattern}"). This list guards credential-class paths and applies regardless of the containment roots.`,
+                    target: key,
+                    pattern: hit.pattern,
+                },
+            };
+        }
+    }
+    if (readFace === "open") {
+        if (isUncPath(key) && isWinFormPath(key) && !within(rootCanonical, key) && !additionalRootsCanonical?.some((r) => within(r, key))) {
+            return {
+                ok: false,
+                violation: {
+                    code: "invalid",
+                    message: `path "${path}" names a network (UNC) location outside the declared roots; refused even under the open read face — a read against an undeclared share can hang on the SMB mount timeout and offers credentials to the remote host.`,
+                },
+            };
+        }
+        return { ok: true, key };
+    }
     if (!within(rootCanonical, key) && !additionalRootsCanonical?.some((r) => within(r, key))) {
         if (exactFileReadExemption?.(key) === true)
             return { ok: true, key };
@@ -299,10 +385,21 @@ export async function resolveKey(env, rootCanonical, path, signal, baseCwd, addi
     return { ok: true, key };
 }
 export async function canonicalizeTarget(env, path, signal, baseCwd) {
-    if (isUncPath(path) && isWinFormPath(path)) {
-        return { ok: true, key: path };
+    if (isWin32DeviceNamespacePath(path)) {
+        return { ok: false, message: `path "${path}" is a Win32 device-namespace path (\\\\.\\ names a raw device object, not a file); refused.` };
+    }
+    const unprefixed = stripWin32ExtendedPrefix(path);
+    if (unprefixed.startsWith("\\\\?\\")) {
+        return { ok: false, message: `path "${path}" is a Win32 extended-length namespace path with no DOS-path equivalent (only \\\\?\\<drive>: and \\\\?\\UNC\\ forms name files); refused.` };
     }
-    const spelled = path.startsWith("//") ? path.replace(/^\/+/, "/") : path;
+    if (isUncPath(unprefixed) && isWinFormPath(unprefixed)) {
+        const folded = foldUncLexically(unprefixed);
+        if (folded.climbedAboveShare) {
+            return { ok: false, message: `path "${path}" climbs above its UNC share root via ".." (\\\\host\\share is the root of a network path); refused.` };
+        }
+        return { ok: true, key: folded.key };
+    }
+    const spelled = unprefixed.startsWith("//") ? unprefixed.replace(/^\/+/, "/") : unprefixed;
     const target = baseCwd && !isAbsolutePathForm(spelled) ? `${baseCwd.replace(/[\\/]+$/, "")}/${spelled}` : spelled;
     const absR = await env.absolutePath(target, signal);
     if (!absR.ok)
@@ -384,6 +481,9 @@ export function violationText(toolName, v) {
     return `Error (${toolName}): ${v.message}`;
 }
 export function violationDetails(v) {
+    if (v.code === "read_path_denied" && v.target !== undefined && v.pattern !== undefined) {
+        return { type: "read_path_denied", code: "read_path_denied", target: v.target, pattern: v.pattern };
+    }
     return v.code === "path_not_in_root" && v.target !== undefined
         ? { type: "path_not_in_root", code: "path_not_in_root", target: v.target, roots: v.roots ?? [] }
         : undefined;
@@ -391,7 +491,7 @@ export function violationDetails(v) {
 export function withinAnyRoot(rootsCanonical, p) {
     return rootsCanonical.some((r) => within(r, p));
 }
-export 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 — 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 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 — 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.)";
 export function requireRead(state, key) {
     const entry = state.get(key);
     if (entry === undefined || entry.isPartialView) {

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

@@ -126,12 +126,27 @@ export interface WalkResult {
      *  without a second stat pass. An env whose listings carry no numeric `mtimeMs` simply leaves
      *  entries out of this map (consumers fall back to name order). */
     mtimes: Map<string, number>;
+    /** design/199 件B — entries withheld by the sensitive-path read deny list: PRUNE-ROOT count only
+     *  (a denied directory's descendants are not enumerated, so they cannot be counted — the note says
+     *  so). 0 when no deny judge was supplied or nothing matched. */
+    denyPruned: number;
+    /** The deny patterns that pruned something, first-seen order (for the disclosure note). */
+    denyPatterns: string[];
 }
 /** F2: any-cause incompleteness — a result built on this walk must not present itself as exhaustive. */
 export declare function walkIsPartial(w: WalkResult): boolean;
 /** Bounded, ignore-aware recursive walk. Returns absolute file paths under `start`. Exported for
  *  repo-map (design/72 §1) — same bounded/ignore-aware traversal as grep/glob, one source of truth. */
-export declare function walk(env: ExecutionEnv, root: string, start: string, ignore: (rel: string, isDir: boolean) => boolean, signal?: AbortSignal): Promise<WalkResult>;
+export declare function walk(env: ExecutionEnv, root: string, start: string, ignore: (rel: string, isDir: boolean) => boolean, signal?: AbortSignal, deny?: {
+    matchPath(path: string): {
+        pattern: string;
+    } | null;
+}): Promise<WalkResult>;
+/** design/199 件B — the JS-leg withholding disclosure (§3.1: an empty result must stay
+ *  distinguishable from searched-and-empty, so this note rides EVERY output shape when something was
+ *  pruned). Distinct from {@link walkCaveat}: pruning is deliberate withholding, not incompleteness.
+ *  The `[note:` prefix keeps it out of the tool layer's structured row extraction. */
+export declare function denyWithheldNote(w: Pick<WalkResult, "denyPruned" | "denyPatterns">): string;
 /** Injectable execution boundaries for the JS-fallback scan (tests shrink them; callers use defaults). */
 export interface JsGrepGuards {
     /** Wall-clock budget (ms) for matching a SINGLE file before the scan stops with a diagnosable error. */
@@ -139,8 +154,37 @@ export interface JsGrepGuards {
     /** Longest line/content (chars) a gray-zone pattern may be matched against. */
     longLineLimit?: number;
 }
-/** JS-fallback grep: ignore-aware walk + per-line scan, honoring output_mode / context / head_limit. */
-export declare function jsGrep(env: ExecutionEnv, root: string, p: GrepParams, signal?: AbortSignal, guards?: JsGrepGuards): Promise<string>;
+/** design/199 件B — what a traversal withheld under the sensitive-path read deny list, structured
+ *  (the prose note is the model-facing twin). Three shapes (§3.1): `pruned_count` = the JS walker
+ *  counted its prune roots; `existence` = the rg leg's bounded probe CONFIRMED matching entries exist
+ *  under the scope (rg's own exclusions are silent, so the count is unknowable); `probe_failed` =
+ *  the probe itself failed — entries MAY have been withheld. */
+export interface ReadDenyWithheld {
+    kind: "pruned_count" | "existence" | "probe_failed";
+    count?: number;
+    patterns?: readonly string[];
+}
+/** The deny judge seam every search leg shares (structural subset of ReadDenyMatcher). */
+export interface ReadDenyJudge {
+    matchPath(path: string): {
+        pattern: string;
+    } | null;
+    rgExclusionGlobs: ReadonlyArray<{
+        flag: "--glob" | "--iglob";
+        glob: string;
+    }>;
+    rgProbeGlobs: ReadonlyArray<{
+        flag: "--glob" | "--iglob";
+        glob: string;
+    }>;
+}
+/** JS-fallback grep: ignore-aware walk + per-line scan, honoring output_mode / context / head_limit.
+ *  design/199 件B: `deny` prunes the walk (note appended to every output shape); `denyOut` is the
+ *  structured twin — a sink because this function's dozen error returns predate the facts (the sink
+ *  is written the moment the walk lands, whatever the scan then returns). */
+export declare function jsGrep(env: ExecutionEnv, root: string, p: GrepParams, signal?: AbortSignal, guards?: JsGrepGuards, deny?: ReadDenyJudge, denyOut?: {
+    withheld?: ReadDenyWithheld;
+}): Promise<string>;
 /** Detect ripgrep once per env (cached). */
 export declare function detectRipgrep(env: ExecutionEnv): Promise<boolean>;
 /** How a grep result was produced when the ripgrep leg could not complete normally. Either the
@@ -160,16 +204,19 @@ export type GrepDegradation = {
 export interface GrepRunResult {
     text: string;
     degraded?: GrepDegradation;
+    /** design/199 件B — deny-list withholding facts (see {@link ReadDenyWithheld}); absent = nothing
+     *  withheld / no deny judge in play. */
+    withheld?: ReadDenyWithheld;
 }
 /** ripgrep grep: build flags from params, run, normalize to the same output as {@link jsGrep}.
  *  Result-fidelity contract: output ripgrep DID produce is never silently replaced by a fallback
  *  rescan — partial results ship with a caveat; only a zero-output failure degrades to
  *  {@link jsGrep}, and that degradation is declared in both text and structure. An external abort
  *  propagates as the interruption it is (no fallback rerun). */
-export declare function rgGrepDetailed(env: ExecutionEnv, root: string, p: GrepParams, signal?: AbortSignal): Promise<GrepRunResult>;
+export declare function rgGrepDetailed(env: ExecutionEnv, root: string, p: GrepParams, signal?: AbortSignal, deny?: ReadDenyJudge): Promise<GrepRunResult>;
 /** grep dispatch: ripgrep when the env has it, else the hardened JS fallback (design/64 §10.3).
  *  Returns the degradation facts alongside the text so the tool layer can surface them structurally. */
-export declare function runGrepDetailed(env: ExecutionEnv, root: string, p: GrepParams, signal?: AbortSignal): Promise<GrepRunResult>;
+export declare function runGrepDetailed(env: ExecutionEnv, root: string, p: GrepParams, signal?: AbortSignal, deny?: ReadDenyJudge): Promise<GrepRunResult>;
 /** Text-only wrapper of {@link runGrepDetailed}. */
 export declare function runGrep(env: ExecutionEnv, root: string, p: GrepParams, signal?: AbortSignal): Promise<string>;
 /** glob: find files by name pattern, with optional sub-path scoping; returns RELATIVE paths (design/64 §10.4). */
@@ -193,6 +240,7 @@ export declare function runGlob(env: ExecutionEnv, root: string, pattern: string
 export declare function runGlobDetailed(env: ExecutionEnv, root: string, pattern: string, opts?: {
     path?: string;
     max?: number;
+    deny?: ReadDenyJudge;
 }, signal?: AbortSignal): Promise<{
     text: string;
     filenames: string[];
@@ -202,4 +250,5 @@ export declare function runGlobDetailed(env: ExecutionEnv, root: string, pattern
     totalMatches: number;
     countIsComplete: boolean;
     error?: string;
+    withheld?: ReadDenyWithheld;
 }>;