@sema-agent/core 5.29.0 → 5.30.0

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,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").

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;
@@ -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,46 @@ 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);
+    if (unc)
+        return "\\\\" + rest.slice(unc[0].length);
+    return 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;
+        }
+        out.push(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 +318,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 +326,32 @@ 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) {
+            return {
+                ok: false,
+                violation: {
+                    code: "read_path_denied",
+                    message: `reading "${path}" ${key !== path ? `(canonical target: "${key}") ` : ""}is refused: the target matches 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 +369,18 @@ 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 (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 = path.startsWith("//") ? path.replace(/^\/+/, "/") : path;
+    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 +462,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 +472,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;
 }>;

package/dist/tools/fs/search.js

@@ -218,7 +218,7 @@ export async function buildIgnore(env, root, signal) {
 export function walkIsPartial(w) {
     return w.incomplete || w.skippedUnreadable > 0 || w.aborted;
 }
-export async function walk(env, root, start, ignore, signal) {
+export async function walk(env, root, start, ignore, signal, deny) {
     const out = [];
     const nameOnly = [];
     const mtimes = new Map();
@@ -226,6 +226,17 @@ export async function walk(env, root, start, ignore, signal) {
     let skippedLarge = 0;
     let skippedUnreadable = 0;
     let aborted = false;
+    let denyPruned = 0;
+    const denyPatterns = [];
+    const denyHit = (path) => {
+        const hit = deny?.matchPath(path);
+        if (!hit)
+            return false;
+        denyPruned++;
+        if (!denyPatterns.includes(hit.pattern))
+            denyPatterns.push(hit.pattern);
+        return true;
+    };
     const rootPrefix = root.replace(/[\\/]+$/, "") + (root.includes("\\") ? "\\" : "/");
     const rel = (abs) => (abs.startsWith(rootPrefix) ? abs.slice(rootPrefix.length) : abs);
     const stack = [{ dir: start, depth: 0 }];
@@ -255,6 +266,8 @@ export async function walk(env, root, start, ignore, signal) {
             if (info.kind === "directory") {
                 if (ignore(rel(info.path), true) || visited.has(info.path))
                     continue;
+                if (denyHit(info.path))
+                    continue;
                 if (depth < WALK_MAX_DEPTH)
                     stack.push({ dir: info.path, depth: depth + 1 });
                 else
@@ -263,6 +276,8 @@ export async function walk(env, root, start, ignore, signal) {
             else if (info.kind === "file") {
                 if (ignore(rel(info.path), false))
                     continue;
+                if (denyHit(info.path))
+                    continue;
                 if (typeof info.mtimeMs === "number")
                     mtimes.set(info.path, info.mtimeMs);
                 if (hasBinaryExtension(info.path)) {
@@ -290,7 +305,12 @@ export async function walk(env, root, start, ignore, signal) {
     }
     if (stack.length > 0 && out.length >= WALK_MAX_FILES)
         incomplete = true;
-    return { files: out, nameOnly, incomplete, skippedLarge, skippedUnreadable, aborted, mtimes };
+    return { files: out, nameOnly, incomplete, skippedLarge, skippedUnreadable, aborted, mtimes, denyPruned, denyPatterns };
+}
+export function denyWithheldNote(w) {
+    if (w.denyPruned <= 0)
+        return "";
+    return `\n[note: ${w.denyPruned} entr${w.denyPruned === 1 ? "y" : "ies"} matching the sensitive-path read deny list ${w.denyPruned === 1 ? "was" : "were"} withheld from this traversal (pruned entries' descendants not counted; patterns: ${w.denyPatterns.join(", ")})]`;
 }
 function walkCaveat(w, forContentSearch) {
     const parts = [];
@@ -737,7 +757,7 @@ function multilineSpans(content, p, captureText = false, deadline = Infinity) {
     }
     return spans;
 }
-export async function jsGrep(env, root, p, signal, guards) {
+export async function jsGrep(env, root, p, signal, guards, deny, denyOut) {
     const analysis = analyzeRedos(p.pattern, p.ignore_case === true);
     if (analysis.risk)
         return redosRejection(analysis.risk);
@@ -773,16 +793,21 @@ export async function jsGrep(env, root, p, signal, guards) {
                 skippedUnreadable: 0,
                 aborted: false,
                 mtimes: typeof info.value.mtimeMs === "number" ? new Map([[start, info.value.mtimeMs]]) : new Map(),
+                denyPruned: 0,
+                denyPatterns: [],
             };
         }
         else {
-            walked = await walk(env, root, start, ignore, signal);
+            walked = await walk(env, root, start, ignore, signal, deny);
         }
     }
     else {
-        walked = await walk(env, root, start, ignore, signal);
+        walked = await walk(env, root, start, ignore, signal, deny);
+    }
+    if (denyOut !== undefined && walked.denyPruned > 0) {
+        denyOut.withheld = { kind: "pruned_count", count: walked.denyPruned, patterns: walked.denyPatterns };
     }
-    let caveat = walkCaveat(walked, true);
+    let caveat = walkCaveat(walked, true) + denyWithheldNote(walked);
     let files = walked.files;
     files.sort();
     const cap = p.head_limit === 0 ? Infinity : Math.max(1, Math.floor(p.head_limit ?? GREP_DEFAULT_CAP));
@@ -1016,16 +1041,18 @@ function formatRgStdout(stdout, p, caveat = "") {
         (off > 0 ? `\n[offset ${off}]` : "") +
         caveat);
 }
-async function jsGrepFallback(env, root, p, signal, reason) {
-    const text = await jsGrep(env, root, p, signal);
+async function jsGrepFallback(env, root, p, signal, reason, deny) {
+    const denyOut = {};
+    const text = await jsGrep(env, root, p, signal, undefined, deny, denyOut);
     return {
         text: text.startsWith("Error (grep)")
             ? text
             : `${text}\n[note: ripgrep failed (${reason}); results are from a fallback scanner]`,
         degraded: { fallback: "js-scan", reason: `ripgrep failed (${reason})` },
+        ...(denyOut.withheld !== undefined ? { withheld: denyOut.withheld } : {}),
     };
 }
-export async function rgGrepDetailed(env, root, p, signal) {
+export async function rgGrepDetailed(env, root, p, signal, deny) {
     const mode = p.output_mode ?? "files_with_matches";
     const flags = ["--no-messages", "--no-require-git", "--hidden"];
     for (const d of VCS_DIRS)
@@ -1055,6 +1082,9 @@ export async function rgGrepDetailed(env, root, p, signal) {
             flags.push("--glob", shellQuote(g));
     if (p.type)
         flags.push("--type", shellQuote(p.type));
+    if (deny !== undefined)
+        for (const g of deny.rgExclusionGlobs)
+            flags.push(g.flag, shellQuote(g.glob));
     const target = p.path ? shellQuote(p.path) : ".";
     const cmd = `rg ${flags.join(" ")} -e ${shellQuote(p.pattern)} -- ${target}`;
     const res = await env.exec(cmd, { cwd: root, timeout: 60, abortSignal: signal });
@@ -1070,13 +1100,26 @@ export async function rgGrepDetailed(env, root, p, signal) {
                     degraded: { partial: true, reason: "ripgrep timed out" },
                 };
             }
-            return jsGrepFallback(env, root, p, signal, "timed out with no output");
+            return jsGrepFallback(env, root, p, signal, "timed out with no output", deny);
         }
-        return jsGrepFallback(env, root, p, signal, `could not run: ${err.code}`);
+        return jsGrepFallback(env, root, p, signal, `could not run: ${err.code}`, deny);
     }
     const { exitCode, stdout } = res.value;
-    if (exitCode === 1)
-        return { text: NO_MATCHES };
+    const denyDisclosure = async () => {
+        if (deny === undefined || deny.rgExclusionGlobs.length === 0)
+            return { note: "" };
+        const withheld = await rgDenyExistenceProbe(env, root, deny, target, signal);
+        if (withheld === undefined)
+            return { note: "" };
+        const note = withheld.kind === "existence"
+            ? "\n[note: entries matching the sensitive-path read deny list exist under this scope and were excluded (readDenyPatterns)]"
+            : "\n[note: entries matching the sensitive-path read deny list may have been excluded (deny-existence probe failed)]";
+        return { note, withheld };
+    };
+    if (exitCode === 1) {
+        const d = await denyDisclosure();
+        return { text: NO_MATCHES + d.note, ...(d.withheld !== undefined ? { withheld: d.withheld } : {}) };
+    }
     if (exitCode >= 2) {
         if (stdout.trim().length > 0) {
             return {
@@ -1084,15 +1127,45 @@ export async function rgGrepDetailed(env, root, p, signal) {
                 degraded: { partial: true, reason: `ripgrep exited with code ${exitCode}` },
             };
         }
-        return jsGrepFallback(env, root, p, signal, `exited with code ${exitCode} and produced no output`);
+        return jsGrepFallback(env, root, p, signal, `exited with code ${exitCode} and produced no output`, deny);
     }
     const orderedStdout = mode === "files_with_matches" ? await sortRgFilesByMtime(env, root, stdout, signal) : stdout;
-    return { text: formatRgStdout(orderedStdout, p) };
+    const d = await denyDisclosure();
+    return { text: formatRgStdout(orderedStdout, p) + d.note, ...(d.withheld !== undefined ? { withheld: d.withheld } : {}) };
 }
-export async function runGrepDetailed(env, root, p, signal) {
+async function rgDenyExistenceProbe(env, root, deny, target, signal) {
+    const probeFlags = ["--files", "--hidden", "--no-require-git", "--no-messages"];
+    for (const d of VCS_DIRS)
+        probeFlags.push("--glob", `!${d}`);
+    for (const g of deny.rgProbeGlobs)
+        probeFlags.push(g.flag, shellQuote(g.glob));
+    try {
+        const res = await env.exec(`( rg ${probeFlags.join(" ")} -- ${target}; echo "__RG_PROBE_EXIT_$?" 1>&2 ) | head -n 1`, { cwd: root, timeout: 10, abortSignal: signal });
+        if (!res.ok)
+            return { kind: "probe_failed" };
+        const first = res.value.stdout.split("\n").find((l) => l.trim().length > 0);
+        if (first !== undefined) {
+            const hit = deny.matchPath(first.trim());
+            return { kind: "existence", ...(hit !== null ? { patterns: [hit.pattern] } : {}) };
+        }
+        const marker = /__RG_PROBE_EXIT_(\d+)/.exec(res.value.stderr ?? "");
+        const rgExit = marker === null ? undefined : Number(marker[1]);
+        if (rgExit === 1)
+            return undefined;
+        if (rgExit === 0)
+            return undefined;
+        return { kind: "probe_failed" };
+    }
+    catch {
+        return { kind: "probe_failed" };
+    }
+}
+export async function runGrepDetailed(env, root, p, signal, deny) {
     if (await detectRipgrep(env))
-        return rgGrepDetailed(env, root, p, signal);
-    return { text: await jsGrep(env, root, p, signal) };
+        return rgGrepDetailed(env, root, p, signal, deny);
+    const denyOut = {};
+    const text = await jsGrep(env, root, p, signal, undefined, deny, denyOut);
+    return { text, ...(denyOut.withheld !== undefined ? { withheld: denyOut.withheld } : {}) };
 }
 export async function runGrep(env, root, p, signal) {
     return (await runGrepDetailed(env, root, p, signal)).text;
@@ -1180,8 +1253,8 @@ export async function runGlobDetailed(env, root, pattern, opts = {}, signal) {
         }
         return ig;
     };
-    const walked = await walk(env, root, start, ignore, signal);
-    const caveat = walkCaveat(walked, false);
+    const walked = await walk(env, root, start, ignore, signal, opts.deny);
+    const caveat = walkCaveat(walked, false) + denyWithheldNote(walked);
     const files = [...walked.files, ...walked.nameOnly];
     const rel = (abs) => (abs.startsWith(rootPrefix) ? abs.slice(rootPrefix.length) : abs);
     const cap = Math.max(1, Math.floor(opts.max ?? 500));
@@ -1212,5 +1285,14 @@ export async function runGlobDetailed(env, root, pattern, opts = {}, signal) {
         ? `\n[note: the file-walk budget (${WALK_MAX_FILES} files / ${WALK_MAX_DEPTH} directory levels) ran out before the whole tree was scanned — this empty result is NOT proof the file is absent; scope the search with \`path\`, or use a root-anchored pattern (e.g. "src/**/*.ts") so the walk is pruned toward it, then retry]`
         : "";
     const text = matched.length === 0 ? "No files matched." + ignoreNote + ignoredFileNote + budgetNote + caveat : matched.join("\n") + capNote + caveat;
-    return { text, filenames: matched, numFiles: matched.length, truncated, durationMs: Date.now() - t0, totalMatches, countIsComplete };
+    return {
+        text,
+        filenames: matched,
+        numFiles: matched.length,
+        truncated,
+        durationMs: Date.now() - t0,
+        totalMatches,
+        countIsComplete,
+        ...(walked.denyPruned > 0 ? { withheld: { kind: "pruned_count", count: walked.denyPruned, patterns: walked.denyPatterns } } : {}),
+    };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "5.29.0",
+  "version": "5.30.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",