@sema-agent/core 7.33.8 → 7.34.0

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

@@ -1,21 +1,137 @@
 import { sliceHeadSafe, sliceTailSafe } from "../../core/surrogate-safe-slice.js";
+import { isAbsolutePathForm, normalizeAbsPathLexically, pathFamilyOf, pathIdentityOf, spellingOfIdentity } from "./safety.js";
 import { PROBE_REASON_MAX } from "../../core/untrusted-text.js";
+export const READ_DENY_HOME_WORD = "~";
+export function readDenyPatternRun(pattern) {
+    const segments = pattern.split("/").filter(Boolean);
+    return segments[0] === READ_DENY_HOME_WORD ? { homeAnchored: true, run: segments.slice(1).join("/") } : { homeAnchored: false, run: pattern };
+}
+export function readDenyRunHead(run) {
+    const segments = run.split("/").filter(Boolean);
+    const wild = segments.findIndex((seg) => seg.includes("*"));
+    return wild === -1 ? segments.length : wild;
+}
+export const DENY_FACES = ["read", "write"];
+export async function withRuleRowsWhereTheyLead(rows, leadsTo) {
+    const leads = new Map();
+    const partsOf = (head) => {
+        const family = pathFamilyOf({ root: head });
+        const id = pathIdentityOf(head, family, head);
+        if (!id.ok)
+            return [head];
+        const unc = id.identity.startsWith("//");
+        const segments = id.identity.split("/").filter((seg) => seg !== "");
+        const parts = [];
+        for (let k = unc ? 2 : 1; k <= segments.length; k++)
+            parts.push(spellingOfIdentity(`${unc ? "//" : "/"}${segments.slice(0, k).join("/")}`, family));
+        return parts.length > 0 ? parts : [head];
+    };
+    const partsByRow = rows.map((row) => (row.head === undefined ? [] : partsOf(row.head)));
+    for (const parts of partsByRow)
+        for (const part of parts)
+            if (!leads.has(part))
+                leads.set(part, leadsTo(part).catch(() => undefined));
+    const out = [];
+    for (const [i, row] of rows.entries()) {
+        out.push(row);
+        let parentLed;
+        let parentPart;
+        for (const part of partsByRow[i]) {
+            const led = await leads.get(part);
+            const extendsParent = led !== undefined && parentLed !== undefined && parentPart !== undefined && sameLocation(led, `${parentLed.replace(/[\\/]+$/, "")}/${part.slice(parentPart.replace(/[\\/]+$/, "").length).replace(/^[\\/]+/, "")}`);
+            const twin = extendsParent ? undefined : rowLedTo(row, part, led);
+            if (twin !== undefined)
+                out.push(twin);
+            parentLed = led;
+            parentPart = part;
+        }
+    }
+    return out;
+}
+function sameLocation(a, b) {
+    const family = pathFamilyOf({ root: a });
+    const x = pathIdentityOf(a, family, a);
+    const y = pathIdentityOf(b, family, b);
+    return x.ok && y.ok && x.identity === y.identity;
+}
+function rowLedTo(row, head, at) {
+    if (at === undefined)
+        return undefined;
+    const family = pathFamilyOf({ root: head });
+    const from = pathIdentityOf(at, family, head);
+    const to = pathIdentityOf(head, family, head);
+    if (!from.ok || !to.ok || from.identity === to.identity)
+        return undefined;
+    const base = from.identity;
+    const under = base.endsWith("/") ? base : `${base}/`;
+    const onto = to.identity.endsWith("/") ? to.identity.slice(0, -1) : to.identity;
+    return {
+        rule: row.rule,
+        tool: row.tool,
+        pattern: row.pattern,
+        faces: row.faces,
+        reaches: (absolutePath) => {
+            const id = pathIdentityOf(absolutePath, family, head);
+            if (!id.ok)
+                return false;
+            if (id.identity === base)
+                return row.reaches(to.identity);
+            return id.identity.startsWith(under) && row.reaches(`${onto}/${id.identity.slice(under.length)}`);
+        },
+    };
+}
+function ruleRowHit(rows, face, path) {
+    for (const r of rows)
+        if (r.faces.includes(face) && r.reaches(path))
+            return r;
+    return undefined;
+}
+export function compileWriteDeny(rules = []) {
+    const ruleRows = rules.filter((r) => r.faces.includes("write"));
+    const matchPath = (path) => {
+        const hit = ruleRowHit(ruleRows, "write", path);
+        return hit === undefined ? null : { pattern: hit.rule };
+    };
+    return { face: "write", ruleRows, matchPath, matchTarget: (canonicalKey, lexicalView, opts) => matchTargetOver(matchPath, canonicalKey, lexicalView, opts) };
+}
+function matchTargetOver(matchPath, canonicalKey, lexicalView, opts) {
+    const canonical = matchPath(canonicalKey, opts);
+    if (canonical !== null)
+        return { ...canonical, matchedView: canonicalKey };
+    if (lexicalView !== undefined) {
+        const lexical = matchPath(lexicalView);
+        if (lexical !== null)
+            return { ...lexical, matchedView: lexicalView };
+    }
+    for (const hop of opts?.hops ?? []) {
+        const viaHop = matchPath(hop);
+        if (viaHop !== null)
+            return { ...viaHop, matchedView: hop };
+    }
+    return null;
+}
 export function readDenySeat(matcher) {
-    const entries = (matcher?.entries ?? []).map((e) => e.pattern);
+    const entries = [...(matcher?.entries ?? []).map((e) => e.pattern), ...(matcher?.ruleRows ?? []).map((r) => r.rule)];
     if (matcher === undefined || entries.length === 0)
         return { denyEntries: entries };
-    return { denyMatch: (p) => matcher.matchPath(p)?.pattern ?? null, denyEntries: entries };
+    return {
+        denyMatch: (p, opts) => matcher.matchPath(p, opts)?.pattern ?? null,
+        denyAtOrBelow: (p) => (matcher.rowAtOrBelow !== undefined ? (matcher.rowAtOrBelow(p)?.pattern ?? null) : entries[0]),
+        denyEntries: entries,
+    };
 }
-export function sensitivePathDenyList(pattern) {
+export function sensitivePathDenyList(pattern, face = "read") {
     const rows = typeof pattern === "string" ? [pattern] : pattern;
-    return `the sensitive-path read deny list (pattern${rows.length === 1 ? "" : "s"} ${rows.map((p) => `"${p}"`).join(", ")})`;
+    return `the ${face === "write" ? "write" : "sensitive-path read"} deny list (pattern${rows.length === 1 ? "" : "s"} ${rows.map((p) => `"${p}"`).join(", ")})`;
 }
 export const SENSITIVE_PATH_DENY_SCOPE = "This list guards credential-class paths and applies regardless of the containment roots.";
+export const WRITE_DENY_SCOPE = "A write deny row holds regardless of the containment roots and of the permission mode.";
 export function readDenySentence(finding) {
+    const write = finding.face === "write";
     const canonicalNote = finding.canonical !== undefined && finding.canonical !== finding.target ? `(canonical target: "${fitMiddle(finding.canonical, READ_DENY_SENTENCE_PART_MAX)}") ` : "";
     const lexicalHit = finding.matchedView !== undefined && finding.matchedView !== (finding.canonical ?? finding.target);
     const judged = lexicalHit ? `the requested path's spelling ("${fitMiddle(finding.matchedView, READ_DENY_SENTENCE_PART_MAX)}") matches` : "the target matches";
-    return `${finding.action ?? "reading"} "${fitMiddle(finding.target, READ_DENY_SENTENCE_PART_MAX)}" ${canonicalNote}is refused: ${judged} ${sensitivePathDenyList(fitMiddle(finding.pattern, READ_DENY_SENTENCE_PART_MAX))}. ${SENSITIVE_PATH_DENY_SCOPE}`;
+    return `${finding.action ?? (write ? "writing" : "reading")} "${fitMiddle(finding.target, READ_DENY_SENTENCE_PART_MAX)}" ${canonicalNote}is refused: ${judged} ${sensitivePathDenyList(fitMiddle(finding.pattern, READ_DENY_SENTENCE_PART_MAX), write ? "write" : "read")}. ${write ? WRITE_DENY_SCOPE : SENSITIVE_PATH_DENY_SCOPE}`;
 }
 export const READ_DENY_SENTENCE_PART_MAX = PROBE_REASON_MAX;
 export function fitMiddle(s, budget) {
@@ -49,6 +165,7 @@ export const READ_FACE_BUILTIN_DENY_TABLE = [
     { pattern: ".local/share/keyrings", tier: "credentials" },
     { pattern: "Library/Keychains", tier: "credentials" },
     { pattern: ".credentials.json", tier: "credentials" },
+    { pattern: "credentials.env", tier: "credentials" },
     { pattern: ".codex/auth.json", tier: "credentials" },
     { pattern: ".config/github-copilot", tier: "credentials" },
     { pattern: ".gemini/oauth_creds.json", tier: "credentials" },
@@ -69,23 +186,23 @@ export const READ_FACE_BUILTIN_DENY_TABLE = [
     { pattern: "Library/Application Support/Exodus", tier: "wallet" },
     { pattern: "Library/Application Support/Ledger Live", tier: "wallet" },
     { pattern: "wallet.dat", tier: "wallet" },
-    { pattern: ".sema/settings.json", tier: "agent-config" },
-    { pattern: ".sema/settings.local.json", tier: "agent-config" },
-    { pattern: ".sema.*", tier: "agent-config" },
-    { pattern: ".claude/settings.json", tier: "agent-config" },
-    { pattern: ".claude/settings.local.json", tier: "agent-config" },
-    { pattern: ".claude.*", tier: "agent-config" },
-    { pattern: ".mcp.json", tier: "agent-config" },
-    { pattern: ".ai-agent/.env", tier: "agent-config" },
-    { pattern: ".sema/engine-data/.env", tier: "agent-config" },
-    { pattern: ".codex/config.toml", tier: "agent-config" },
-    { pattern: ".cursor/mcp.json", tier: "agent-config" },
-    { pattern: ".continue/config.json", tier: "agent-config" },
-    { pattern: ".continue/config.yaml", tier: "agent-config" },
-    { pattern: ".aider.conf.yml", tier: "agent-config" },
-    { pattern: ".gemini/settings.json", tier: "agent-config" },
+    { pattern: "~/.sema/settings.json", tier: "agent-config" },
+    { pattern: "~/.sema/settings.local.json", tier: "agent-config" },
+    { pattern: "~/.sema.*", tier: "agent-config" },
+    { pattern: "~/.claude/settings.json", tier: "agent-config" },
+    { pattern: "~/.claude/settings.local.json", tier: "agent-config" },
+    { pattern: "~/.claude.*", tier: "agent-config" },
+    { pattern: "~/.mcp.json", tier: "agent-config" },
+    { pattern: "~/.ai-agent/.env", tier: "agent-config" },
+    { pattern: "~/.sema/engine-data/.env", tier: "agent-config" },
+    { pattern: "~/.codex/config.toml", tier: "agent-config" },
+    { pattern: "~/.cursor/mcp.json", tier: "agent-config" },
+    { pattern: "~/.continue/config.json", tier: "agent-config" },
+    { pattern: "~/.continue/config.yaml", tier: "agent-config" },
+    { pattern: "~/.aider.conf.yml", tier: "agent-config" },
+    { pattern: "~/.gemini/settings.json", tier: "agent-config" },
 ];
-export const READ_DENY_DEFAULT_TIERS = [];
+export const READ_DENY_DEFAULT_TIERS = ["credentials", "agent-config"];
 export function resolveReadDenyBuiltins(config) {
     let activeTiers;
     if (config?.tiers === undefined) {
@@ -112,13 +229,21 @@ export function resolveReadDenyBuiltins(config) {
         }
         for (const name of config.exclude) {
             if (typeof name !== "string" || !READ_FACE_BUILTIN_DENY_TABLE.some((r) => r.pattern === name)) {
-                throw new Error(`readDenyBuiltinExclude: ${JSON.stringify(name)} names no built-in row — row names are the canonical pattern texts of READ_FACE_BUILTIN_DENY_TABLE (e.g. ".ssh", ".config/gcloud").`);
+                const anchored = typeof name === "string" ? READ_FACE_BUILTIN_DENY_TABLE.find((r) => r.pattern === `${READ_DENY_HOME_WORD}/${name}`) : undefined;
+                throw new Error(`readDenyBuiltinExclude: ${JSON.stringify(name)} names no built-in row — ${anchored !== undefined ? `the row is anchored at the home directory and is named ${JSON.stringify(anchored.pattern)}; ` : ""}row names are the canonical pattern texts of READ_FACE_BUILTIN_DENY_TABLE (e.g. ".ssh", ".config/gcloud", "~/.sema/settings.json").`);
             }
         }
         excluded = new Set(config.exclude);
     }
     return READ_FACE_BUILTIN_DENY_TABLE.filter((r) => activeTiers.has(r.tier) && !excluded.has(r.pattern));
 }
+export function readDenyBuiltinConfigOf(seats) {
+    resolveReadDenyBuiltins(seats);
+    return {
+        ...(seats.tiers !== undefined ? { tiers: [...seats.tiers] } : {}),
+        ...(seats.exclude !== undefined ? { exclude: [...seats.exclude] } : {}),
+    };
+}
 export function activeReadDenyBuiltinTiers(config) {
     const rows = resolveReadDenyBuiltins(config);
     return READ_DENY_BUILTIN_TIERS.filter((t) => rows.some((r) => r.tier === t));
@@ -145,6 +270,30 @@ export function compileSegmentPattern(raw, fold) {
     return { raw, segments, foldAscii: fold === "ascii" };
 }
 export function matchSegmentPatterns(path, compiled, opts) {
+    const views = segmentViewsOf(path, opts);
+    const rooted = isAbsolutePathForm(path);
+    const lowered = new Map();
+    for (const pat of compiled) {
+        for (const view of views) {
+            const segs = pat.foldAscii ? (lowered.get(view) ?? lowered.set(view, view.map(asciiLower)).get(view)) : view;
+            const n = pat.segments.length;
+            const runAt = (i) => i + n <= segs.length && pat.segments.every((re, j) => re.test(segs[i + j] ?? ""));
+            if (pat.anchors !== undefined && rooted) {
+                for (const anchor of pat.anchors)
+                    if (anchor.every((a, j) => segs[j] === a) && runAt(anchor.length))
+                        return pat.raw;
+                continue;
+            }
+            if (pat.rootedOnly === true)
+                continue;
+            for (let i = 0; i + n <= segs.length; i++)
+                if (runAt(i))
+                    return pat.raw;
+        }
+    }
+    return null;
+}
+function segmentViewsOf(path, opts) {
     const literalSegs = path.split(/[\\/]/).filter(Boolean);
     const win32Segs = [];
     for (const raw of literalSegs) {
@@ -164,20 +313,41 @@ export function matchSegmentPatterns(path, compiled, opts) {
     }
     const sameView = opts?.aliasResolved === true ||
         (win32Segs.length === literalSegs.length && win32Segs.every((s, i) => s === literalSegs[i]));
-    const views = sameView ? [literalSegs] : [literalSegs, win32Segs];
-    const lowered = new Map();
-    for (const pat of compiled) {
-        for (const view of views) {
-            const segs = pat.foldAscii ? (lowered.get(view) ?? lowered.set(view, view.map(asciiLower)).get(view)) : view;
-            const n = pat.segments.length;
-            for (let i = 0; i + n <= segs.length; i++) {
-                if (pat.segments.every((re, j) => re.test(segs[i + j] ?? "")))
-                    return pat.raw;
-            }
-        }
+    return sameView ? [literalSegs] : [literalSegs, win32Segs];
+}
+function rowMeetsPath(pat, segs, rooted) {
+    const n = pat.segments.length;
+    if (pat.anchors !== undefined && rooted) {
+        return pat.anchors.some((a) => {
+            const k = Math.min(segs.length, a.length + n);
+            for (let i = 0; i < k; i++)
+                if (i < a.length ? segs[i] !== a[i] : !pat.segments[i - a.length].test(segs[i]))
+                    return false;
+            return true;
+        });
+    }
+    if (pat.rootedOnly === true)
+        return false;
+    for (let i = 0; i < segs.length; i++) {
+        const m = Math.min(n, segs.length - i);
+        if (pat.segments.slice(0, m).every((re, j) => re.test(segs[i + j])))
+            return true;
+    }
+    return false;
+}
+function rowAtOrBelowOf(rows, path) {
+    const rooted = isAbsolutePathForm(path);
+    const views = segmentViewsOf(path);
+    for (const pat of rows) {
+        for (const view of views)
+            if (rowMeetsPath(pat, pat.foldAscii ? view.map(asciiLower) : view, rooted))
+                return pat.raw;
     }
     return null;
 }
+function homeAnchorSegments(home) {
+    return normalizeAbsPathLexically(home).split(/[\\/]/).filter(Boolean);
+}
 function rgGlobEscape(pattern) {
     return pattern.replace(/[?[\]{}]/g, (c) => `[${c}]`);
 }
@@ -193,9 +363,10 @@ function normalizeEntry(entry, layer) {
         throw new Error(`readDenyPatterns (${layer}): pattern ${JSON.stringify(shape.pattern)} contains a backslash — patterns are "/"-separated segment runs (both path families are matched); spell the segments with "/".`);
     }
     const segments = shape.pattern.split("/").filter(Boolean);
-    if (segments.length === 0) {
-        throw new Error(`readDenyPatterns (${layer}): pattern ${JSON.stringify(shape.pattern)} contains no path segments and would deny nothing. ` +
-            `Patterns are "/"-separated runs of path SEGMENTS (e.g. ".ssh", ".config/gcloud", "id_rsa*"); remove the entry or spell the segments.`);
+    const { homeAnchored, run } = readDenyPatternRun(segments.join("/"));
+    if (run.length === 0) {
+        throw new Error(`readDenyPatterns (${layer}): pattern ${JSON.stringify(shape.pattern)} contains no path segments${homeAnchored ? " below the home word" : ""} and would ${homeAnchored ? "name the whole home directory" : "deny nothing"}. ` +
+            `Patterns are "/"-separated runs of path SEGMENTS (e.g. ".ssh", ".config/gcloud", "id_rsa*", "~/.sema/settings.json"); remove the entry or spell the segments.`);
     }
     return { pattern: segments.join("/"), caseSensitive: shape.caseSensitive === true };
 }
@@ -211,13 +382,27 @@ export function persistedReadDenyEntryProblem(e) {
     if (pattern.includes("\\"))
         return "pattern contains a backslash";
     const segments = pattern.split("/").filter(Boolean);
-    if (segments.length === 0)
+    if (readDenyPatternRun(segments.join("/")).run.length === 0)
         return "pattern has no path segments";
     if (segments.join("/") !== pattern)
         return "pattern is not in canonical a/b form";
     return null;
 }
-export function compileReadDeny(additions = [], layer = "additions", builtin) {
+export function checkedReadDenyHomes(homes, seat = "readDenyHomes") {
+    if (!Array.isArray(homes) || !homes.every((h) => typeof h === "string" && isAbsolutePathForm(h))) {
+        let shown;
+        try {
+            shown = JSON.stringify(homes) ?? String(homes);
+        }
+        catch {
+            shown = String(homes);
+        }
+        throw new Error(`${seat}: expected an array of absolute ${seat === "readDenyHomes" ? "home paths" : "locations"}, got ${shown} — a home-anchored row ("~/…") is placed ${seat === "readDenyHomes" ? "under each" : "at each"}, so a relative or empty spelling would guard a place that is not the home's.`);
+    }
+    return homes;
+}
+export function compileReadDeny(additions = [], layer = "additions", builtin, rules = [], homes = [], linked = new Map()) {
+    const ruleRows = rules.filter((r) => r.faces.includes("read"));
     const normalized = [];
     const seen = new Set();
     const push = (e) => {
@@ -231,44 +416,66 @@ export function compileReadDeny(additions = [], layer = "additions", builtin) {
         push(normalizeEntry(row.pattern, "built-in"));
     for (const entry of additions)
         push(normalizeEntry(entry, layer));
+    const homeSegments = [...new Set(checkedReadDenyHomes(homes))].map(homeAnchorSegments);
     const compiled = normalized.map((e) => {
-        const c = compileSegmentPattern(e.pattern, e.caseSensitive ? "none" : "ascii");
+        const { homeAnchored, run } = readDenyPatternRun(e.pattern);
+        const fold = e.caseSensitive ? "none" : "ascii";
+        const c = compileSegmentPattern(run, fold);
         if (c === null)
             throw new Error(`readDenyPatterns: pattern ${JSON.stringify(e.pattern)} compiled to zero segments.`);
-        return c;
+        if (!homeAnchored || homeSegments.length === 0)
+            return { ...c, raw: e.pattern };
+        return { ...c, raw: e.pattern, anchors: homeSegments.map((segs) => (fold === "ascii" ? segs.map(asciiLower) : segs)) };
+    });
+    if (!(linked instanceof Map))
+        throw new Error(`readDenyHomeLinks: expected a Map from a row's pattern to its locations, got ${typeof linked}.`);
+    const linkedPlacements = [];
+    normalized.forEach((e, i) => {
+        const locations = linked.get(e.pattern);
+        const { homeAnchored, run } = readDenyPatternRun(e.pattern);
+        if (locations === undefined || !homeAnchored)
+            return;
+        const c = compiled[i];
+        const rest = c.segments.slice(readDenyRunHead(run));
+        for (const location of new Set(checkedReadDenyHomes(locations, "readDenyHomeLinks"))) {
+            const segs = homeAnchorSegments(location);
+            linkedPlacements.push({ raw: e.pattern, segments: rest, foldAscii: c.foldAscii, anchors: [c.foldAscii ? segs.map(asciiLower) : segs], rootedOnly: true });
+        }
     });
+    const judged = linkedPlacements.length === 0 ? compiled : [...compiled, ...linkedPlacements];
     const rgExclusionGlobs = [];
     const rgProbeGlobs = [];
-    for (const e of normalized) {
+    normalized.forEach((e, i) => {
+        if (compiled[i].anchors !== undefined)
+            return;
         const flag = e.caseSensitive ? "--glob" : "--iglob";
-        const g = rgGlobEscape(e.pattern);
+        const g = rgGlobEscape(readDenyPatternRun(e.pattern).run);
         rgExclusionGlobs.push({ flag, glob: `!**/${g}` }, { flag, glob: `!**/${g}/**` });
         rgProbeGlobs.push({ flag, glob: `**/${g}` }, { flag, glob: `**/${g}/**` });
-    }
+    });
+    const placed = judged.filter((c) => c.anchors !== undefined);
+    const unexcludableUnder = (scope) => placed.length > 0 && (!isAbsolutePathForm(scope) || rowAtOrBelowOf(placed, normalizeAbsPathLexically(scope)) !== null);
+    const rowAtOrBelow = (path) => {
+        const hit = rowAtOrBelowOf(judged, path);
+        if (hit !== null)
+            return { pattern: hit };
+        return ruleRows.length === 0 ? null : { pattern: ruleRows[0].rule };
+    };
     const matchPath = (path, opts) => {
-        const hit = matchSegmentPatterns(path, compiled, opts);
-        return hit === null ? null : { pattern: hit };
+        const hit = matchSegmentPatterns(path, judged, opts);
+        if (hit !== null)
+            return { pattern: hit };
+        const rule = ruleRows.length === 0 || opts?.walked === true ? undefined : ruleRowHit(ruleRows, "read", path);
+        return rule === undefined ? null : { pattern: rule.rule };
     };
     return {
         entries: normalized,
+        ...(ruleRows.length > 0 ? { ruleRows } : {}),
         matchPath,
-        matchTarget(canonicalKey, lexicalView, opts) {
-            const canonical = matchPath(canonicalKey, opts);
-            if (canonical !== null)
-                return { ...canonical, matchedView: canonicalKey };
-            if (lexicalView !== undefined) {
-                const lexical = matchPath(lexicalView);
-                if (lexical !== null)
-                    return { ...lexical, matchedView: lexicalView };
-            }
-            for (const hop of opts?.hops ?? []) {
-                const viaHop = matchPath(hop);
-                if (viaHop !== null)
-                    return { ...viaHop, matchedView: hop };
-            }
-            return null;
-        },
+        matchTarget: (canonicalKey, lexicalView, opts) => matchTargetOver(matchPath, canonicalKey, lexicalView, opts),
         rgExclusionGlobs,
         rgProbeGlobs,
+        unexcludableUnder,
+        rowAtOrBelow,
     };
 }

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

@@ -93,7 +93,7 @@ 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" | "read_path_denied";
+    code: "path_not_in_root" | "not_read" | "stale" | "ambiguous_edit" | "invalid" | "read_path_denied" | "write_path_denied";
     /** 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
@@ -378,6 +378,10 @@ export declare function isPathIdentity(s: string, family: PathFamily | undefined
 /** Is the identity a DIRECTORY a rule may speak for — anything but the tree's bare root (`/`, a drive root
  *  `/c`, a share root `//host/share`), which admits nothing? */
 export declare function isIdentityDir(identity: PathIdentity, family: PathFamily | undefined): boolean;
+/** A spelling of an identity that the environment resolves as a path of the family, and that reads as that family on its
+ *  own ({@link isWinFormPath}) — the one way back from the comparison form: posix, the identity; a win drive identity
+ *  `/c/rest` ⇒ `c:\rest`; a win UNC identity `//host/share/rest` ⇒ `\\host\share\rest`. */
+export declare function spellingOfIdentity(identity: PathIdentity, family: PathFamily | undefined): string;
 /** Does the spelling carry a `.` or `..` segment under the family's separators (a backslash is a name byte on
  *  POSIX)? A rule body with one admits nothing: folding it could make it name a second directory. */
 export declare function carriesDotSegment(spelled: string, family: PathFamily | undefined): boolean;
@@ -444,6 +448,7 @@ export type RootsSeat = readonly string[] | (() => readonly string[] | undefined
  * violation. Defense-in-depth at the tool layer; NOT a substitute for a sandboxed `executionEnv`.
  */
 export declare function resolveKey(env: ExecutionEnv, rootCanonical: string, path: string, signal?: AbortSignal, baseCwd?: string, additionalRoots?: RootsSeat, exactFileReadExemption?: (canonicalKey: string) => boolean, readDeny?: {
+    readonly face?: "write";
     matchTarget(canonicalKey: string, lexicalView?: string, opts?: {
         readonly aliasResolved?: boolean;
     }): {

package/dist/tools/fs/safety.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { readDenySentence } from "./read-deny.js";
+import { homeViewsOf } from "./read-deny-home.js";
 import { sliceHeadSafe } from "../../core/surrogate-safe-slice.js";
 import { pathTargetValue, protectivePathTargetOf } from "../../core/tool-registry.js";
 import { withGateTimeout, DEFAULT_GATE_AWAIT_TIMEOUT_MS } from "../../core/gate-bounded-await.js";
@@ -399,6 +400,13 @@ export function isIdentityDir(identity, family) {
         return identity !== "/";
     return identity.length > identityAnchorOf(identity).length;
 }
+export function spellingOfIdentity(identity, family) {
+    if (family !== "win")
+        return identity;
+    if (isUncIdentity(identity))
+        return identity.replace(/\//g, "\\");
+    return `${identity.slice(1, 2)}:${(identity.length > 2 ? identity.slice(2) : "/").replace(/\//g, "\\")}`;
+}
 export function carriesDotSegment(spelled, family) {
     return (family === "win" ? /(^|[\\/])\.{1,2}([\\/]|$)/ : /(^|\/)\.{1,2}(\/|$)/).test(spelled);
 }
@@ -458,15 +466,20 @@ export async function resolveKey(env, rootCanonical, path, signal, baseCwd, addi
         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), {
-            aliasResolved: canon.aliasResolved === true,
-        });
+        const judged = { aliasResolved: canon.aliasResolved === true };
+        let hit = readDeny.matchTarget(key, lexicalViewOf(path, baseCwd ?? rootCanonical), judged);
+        if (hit === null) {
+            const homeView = await homeViewsOf(env, signal).of(key);
+            if (homeView !== undefined)
+                hit = readDeny.matchTarget(key, homeView, judged);
+        }
         if (hit !== null) {
+            const write = readDeny.face === "write";
             return {
                 ok: false,
                 violation: {
-                    code: "read_path_denied",
-                    message: readDenySentence({ target: path, canonical: key, pattern: hit.pattern, ...(hit.matchedView !== undefined ? { matchedView: hit.matchedView } : {}) }),
+                    code: write ? "write_path_denied" : "read_path_denied",
+                    message: readDenySentence({ target: path, canonical: key, pattern: hit.pattern, ...(hit.matchedView !== undefined ? { matchedView: hit.matchedView } : {}), ...(write ? { face: "write" } : {}) }),
                     target: key,
                     pattern: hit.pattern,
                 },

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

@@ -170,6 +170,8 @@ export interface ReadDenyJudge {
         flag: "--glob" | "--iglob";
         glob: string;
     }>;
+    /** read-deny.ts `ReadDenyMatcher.unexcludableUnder`: a scope where an entry the rg globs cannot exclude may lie. */
+    unexcludableUnder?(scope: string): boolean;
 }
 /** JS-fallback grep: ignore-aware walk + per-line scan, honoring output_mode / context / head_limit.
  *  `deny` prunes the walk (note appended to every output shape); `denyOut` is the
@@ -286,6 +288,7 @@ type GrepOutputMode = "content" | "files_with_matches" | "count";
  */
 export declare function rgOutputDenyTripwire(stdout: string, mode: GrepOutputMode, judge: Pick<ReadDenyJudge, "matchPath">, opts?: {
     dropIncompleteTail?: boolean;
+    base?: string;
 }): {
     trip: false;
 } | {

package/dist/tools/fs/search.js

@@ -1,6 +1,7 @@
 import { delimitUntrusted } from "../../core/untrusted-text.js";
 import { MAX_EXEC_OUTPUT_BYTES } from "../../core/exec-output-tail.js";
 import { hasBinaryExtension, isAbsoluteForFamily, isWinFormPath, joinForFamily, pathFamilyOf } from "./safety.js";
+import { homeViewsOf } from "./read-deny-home.js";
 import { thrownText } from "../../core/thrown-value.js";
 const WALK_MAX_FILES = 5000;
 const WALK_MAX_DEPTH = 32;
@@ -227,8 +228,14 @@ export async function walk(env, root, start, ignore, signal, deny) {
     let aborted = false;
     let denyPruned = 0;
     const denyPatterns = [];
-    const denyHit = (path) => {
-        const hit = deny?.matchPath(path);
+    const views = deny !== undefined ? homeViewsOf(env, signal) : undefined;
+    const denyHit = async (path, leaf) => {
+        let hit = deny?.matchPath(path);
+        if (!hit && views !== undefined) {
+            const view = await views.of(path, leaf !== undefined ? { leaf } : undefined);
+            if (view !== undefined)
+                hit = deny.matchPath(view);
+        }
         if (!hit)
             return false;
         denyPruned++;
@@ -265,7 +272,7 @@ export async function walk(env, root, start, ignore, signal, deny) {
             if (info.kind === "directory") {
                 if (ignore(rel(info.path), true) || visited.has(info.path))
                     continue;
-                if (denyHit(info.path))
+                if (await denyHit(info.path))
                     continue;
                 if (depth < WALK_MAX_DEPTH)
                     stack.push({ dir: info.path, depth: depth + 1 });
@@ -275,7 +282,7 @@ export async function walk(env, root, start, ignore, signal, deny) {
             else if (info.kind === "file") {
                 if (ignore(rel(info.path), false))
                     continue;
-                if (denyHit(info.path))
+                if (await denyHit(info.path, "file"))
                     continue;
                 if (typeof info.mtimeMs === "number")
                     mtimes.set(info.path, info.mtimeMs);
@@ -1131,18 +1138,40 @@ function formatRgRecords(records, p, caveat = "") {
 export function rgOutputDenyTripwire(stdout, mode, judge, opts = {}) {
     if (stdout.length === 0)
         return { trip: false };
+    const absolute = rgRecordAbsolute(opts.base);
     for (const record of parseRgRecords(stdout, mode, opts.dropIncompleteTail === true)) {
         if (record.path === undefined) {
             if (record.text === "--")
                 continue;
             return { trip: true, reason: "ambiguous-record" };
         }
-        const hit = judge.matchPath(record.path);
+        const hit = judge.matchPath(absolute(record.path));
         if (hit !== null)
             return { trip: true, reason: "deny-hit", pattern: hit.pattern };
     }
     return { trip: false };
 }
+function rgRecordAbsolute(base) {
+    const family = base !== undefined ? pathFamilyOf({ root: base }) : undefined;
+    return (p) => (base === undefined || family === undefined || isAbsoluteForFamily(family, p) ? p : joinForFamily(family, base, p.replace(/^\.[\\/]/, "")));
+}
+async function rgOutputDenyTripwireAt(env, stdout, mode, deny, opts, signal) {
+    const views = homeViewsOf(env, signal);
+    const absolute = rgRecordAbsolute(opts.base);
+    const placed = new Map();
+    for (const record of parseRgRecords(stdout, mode, opts.dropIncompleteTail === true)) {
+        if (record.path === undefined)
+            continue;
+        const path = absolute(record.path);
+        if (placed.has(path))
+            continue;
+        const view = await views.of(path, { leaf: "file" });
+        if (view !== undefined)
+            placed.set(path, view);
+    }
+    const judge = placed.size === 0 ? deny : { matchPath: (p) => deny.matchPath(p) ?? (placed.has(p) ? deny.matchPath(placed.get(p)) : null) };
+    return rgOutputDenyTripwire(stdout, mode, judge, opts);
+}
 async function jsGrepDenyTripFallback(env, root, p, signal, trip, deny) {
     const denyOut = {};
     const { text, rows } = await jsGrepDetailed(env, root, p, signal, undefined, deny, denyOut);
@@ -1212,7 +1241,7 @@ export async function rgGrepDetailed(env, root, p, signal, deny) {
             const partial = err.partialStdout ?? "";
             if (partial.trim().length > 0) {
                 if (deny !== undefined) {
-                    const trip = rgOutputDenyTripwire(partial, mode, deny, { dropIncompleteTail: true });
+                    const trip = await rgOutputDenyTripwireAt(env, partial, mode, deny, { dropIncompleteTail: true, base: root }, signal);
                     if (trip.trip)
                         return jsGrepDenyTripFallback(env, root, p, signal, trip, deny);
                 }
@@ -1253,7 +1282,7 @@ export async function rgGrepDetailed(env, root, p, signal, deny) {
     if (exitCode >= 2) {
         if (stdout.trim().length > 0) {
             if (deny !== undefined) {
-                const trip = rgOutputDenyTripwire(stdout, mode, deny, { dropIncompleteTail: true });
+                const trip = await rgOutputDenyTripwireAt(env, stdout, mode, deny, { dropIncompleteTail: true, base: root }, signal);
                 if (trip.trip)
                     return jsGrepDenyTripFallback(env, root, p, signal, trip, deny);
             }
@@ -1268,7 +1297,7 @@ export async function rgGrepDetailed(env, root, p, signal, deny) {
         return jsGrepFallback(env, root, p, signal, `exited with code ${exitCode} and produced no output`, deny);
     }
     if (deny !== undefined) {
-        const trip = rgOutputDenyTripwire(stdout, mode, deny);
+        const trip = await rgOutputDenyTripwireAt(env, stdout, mode, deny, { base: root }, signal);
         if (trip.trip)
             return jsGrepDenyTripFallback(env, root, p, signal, trip, deny);
     }
@@ -1308,7 +1337,16 @@ async function rgDenyExistenceProbe(env, root, deny, target, signal) {
     }
 }
 export async function runGrepDetailed(env, root, p, signal, deny) {
-    if (await detectRipgrep(env))
+    const scope = p.path ? (isAbsoluteForFamily(pathFamilyOf({ root }), p.path) ? p.path : joinForFamily(pathFamilyOf({ root }), root, p.path)) : root;
+    const unexcludableUnder = async () => {
+        if (deny?.unexcludableUnder === undefined)
+            return false;
+        if (deny.unexcludableUnder(scope))
+            return true;
+        const view = await homeViewsOf(env, signal).of(scope);
+        return view !== undefined && deny.unexcludableUnder(view);
+    };
+    if (!(await unexcludableUnder()) && (await detectRipgrep(env)))
         return rgGrepDetailed(env, root, p, signal, deny);
     const denyOut = {};
     const { text, rows } = await jsGrepDetailed(env, root, p, signal, undefined, deny, denyOut);