@sema-agent/core 5.28.0 → 5.30.0

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/dist/tools/scheduler-tools.d.ts

@@ -27,7 +27,7 @@ export declare const AUTONOMOUS_LOOP_DYNAMIC_SENTINEL = "<<autonomous-loop-dynam
 /** Runner-held 上下文 + run-stop 出口，工具工厂闭包捕获（模型触不到）。 */
 export interface SchedulerToolContext {
     /**
-     * **会话腿**的越权隔离键（Runner 填 sessionId ?? principal ?? taskId）。durable 腿不用这条链——它的键由
+     * **会话腿**的越界隔离键（Runner 填 sessionId ?? principal ?? taskId）。durable 腿不用这条链——它的键由
      * {@link durableScopeOf} 从 principal 独立铸（ruled 2026-08-03，见该函数注释）。
      */
     scope: string;

package/dist/tools/task-list.d.ts

@@ -74,7 +74,7 @@ export interface TaskListStore {
  *
  * The in-memory store rejected such a row incidentally: its snapshot helper spreads `t.blocks`, so a
  * missing array threw "blocks is not iterable" at write. The file store had no such accident and wrote the
- * row to disk, where it survived until `TaskUpdate` reached `t.blocks.includes(...)` — a poisoned row that
+ * row to disk, where it survived until `TaskUpdate` reached `t.blocks.includes(...)` — a contaminated row that
  * passes the write and detonates at an unrelated later call, in a different session, with no trace of where
  * it came from. Two backends disagreeing about what a valid row is means a test written against one has
  * different semantics on the other.

package/dist/tools/web.d.ts

@@ -21,7 +21,7 @@ export interface WebFetchConfig {
      *
      *  Pre-2.13 review F1 (additive): the object return form lets a summarizer report that its own OUTPUT
      *  was cut (`truncated: true` — e.g. the sub-model hit max_tokens) as structured fact. The tool then
-     *  renders the disclosure OUTSIDE the untrusted fence (a page must not be able to forge it) and stamps
+     *  renders the disclosure OUTSIDE the untrusted fence (a page must not be able to self-declare it) and stamps
      *  `details.truncated`. A plain-string return still works and claims a complete summary.
      *
      *  ruled 2026-08-05 (grounding contract): the object form additionally carries `inputTruncated` — the
@@ -126,7 +126,7 @@ export declare const WEBFETCH_SUMMARY_INPUT_HEADROOM = 0.8;
  * reservation still gets a small excerpt rather than a computation that lands at or below zero and feeds
  * the summarizer an empty page — a call that cannot possibly answer is strictly worse than one that might.
  *
- * Honest scope (adversarial review round 1): this is a FLOOR, not a proof of fit. With the output
+ * Honest scope (falsification review round 1): this is a FLOOR, not a proof of fit. With the output
  * reservation bounded at window/4 (see `resolveSummaryInputChars`), the floor now fires only on genuinely
  * tiny windows (roughly under 3k tokens at the default chars-per-token) — a model whose declared
  * dimensions leave no room gets a small excerpt whose attempt often succeeds anyway, and a failure is
@@ -139,7 +139,7 @@ export declare const WEBFETCH_SUMMARY_MIN_CONTENT = 4000;
  * Resolve the page-content budget for {@link createWebFetchSummarizer} against `model`'s window.
  * An explicit `override` wins outright (a deployment that measured its own model beats an estimate).
  *
- * Fail-loud on every non-finite input, same posture as {@link resolveWebMaxBytes} (adversarial review
+ * Fail-loud on every non-finite input, same posture as {@link resolveWebMaxBytes} (falsification review
  * round 1): a `NaN` anywhere in the model's declared dimensions propagates through the arithmetic and out
  * through `Math.min`/`Math.max` unchanged, and a `NaN` budget makes `content.length > budget` false — so
  * the clip silently stops happening and the whole oversize page is fed to the model, which is the failure

package/package.json

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