@sema-agent/core 7.33.7 → 7.34.0

package/dist/tools/fs/file-read-check.js

@@ -0,0 +1,71 @@
+import { effectivePathSpellingOf } from "../../core/effective-path-target.js";
+import { pathTargetOf } from "../../core/tool-registry.js";
+import { fitMiddle, READ_DENY_SENTENCE_PART_MAX } from "./read-deny.js";
+import { resolveKey, violationDetails } from "./safety.js";
+import { grantOfferFor, parentDirLexically } from "./shell-read-judge.js";
+const ADMISSION_MAX = 1024;
+const VOUCH = { disposition: "vouch", finding: "none" };
+export function createFileReadStation(opts) {
+    const admissions = new Map();
+    const remember = (toolCallId, key) => {
+        if (admissions.size >= ADMISSION_MAX) {
+            const oldest = admissions.keys().next().value;
+            if (oldest !== undefined)
+                admissions.delete(oldest);
+        }
+        admissions.set(toolCallId, key);
+    };
+    const check = {
+        judge(toolName, args, cwd, signal, callOpts) {
+            if (!opts.tools.has(toolName))
+                return null;
+            const selection = effectivePathSpellingOf({ toolName, args }, pathTargetOf(toolName), { root: opts.rootCanonical, cwd });
+            if (selection === undefined || "refused" in selection || selection.spelled === undefined)
+                return null;
+            const spelled = selection.spelled;
+            return (async () => {
+                const extra = opts.roots();
+                const r = await resolveKey(opts.env, opts.rootCanonical, spelled, signal, selection.base, extra, undefined, opts.readDeny, opts.readFace);
+                if (r.ok || r.violation.code !== "path_not_in_root" || r.violation.target === undefined || opts.excluded?.(r.violation.target) === true || opts.exempt?.(r.violation.target) === true)
+                    return VOUCH;
+                const target = r.violation.target;
+                const toolCallId = callOpts.toolCallId;
+                const roots = [opts.rootCanonical, ...extra];
+                const details = violationDetails(r.violation);
+                const allowed = fitMiddle(roots.join(", "), READ_DENY_SENTENCE_PART_MAX);
+                if (callOpts.seat === "rejudge") {
+                    return { disposition: "refuse", finding: "outside_roots", sentence: `Error (${toolName}): the approved edit reads "${fitMiddle(target, READ_DENY_SENTENCE_PART_MAX)}", outside the directories allowed for this session (${allowed}) — re-submit it as a fresh call and answer its card.`, details };
+                }
+                const info = pathTargetOf(toolName)?.absent === "base" ? await opts.env.fileInfo(target, signal) : undefined;
+                const readsDirectory = info?.ok === true && info.value.kind === "directory";
+                const offer = grantOfferFor(readsDirectory ? target : parentDirLexically(target), target, { roots, ...(opts.homeDir !== undefined ? { homeDir: opts.homeDir } : {}) });
+                return {
+                    disposition: "ordinary",
+                    finding: "outside_roots",
+                    sentence: `reads outside the allowed directories for this session: "${fitMiddle(target, READ_DENY_SENTENCE_PART_MAX)}" is not under ${allowed}`,
+                    details,
+                    ...(offer !== undefined ? { readRootCandidate: { dir: offer.dir, ...(offer.covers !== undefined ? { covers: offer.covers } : {}), clearsThisAsk: true } } : {}),
+                    ...(toolCallId !== undefined ? { admit: () => remember(toolCallId, target) } : {}),
+                };
+            })();
+        },
+        unanswered: () => VOUCH,
+    };
+    const admitted = (toolCallId, key) => {
+        if (toolCallId === undefined || admissions.get(toolCallId) !== key)
+            return false;
+        admissions.delete(toolCallId);
+        return true;
+    };
+    return { check, tools: opts.tools, admitted };
+}
+export function composeReadChecks(stations) {
+    if (stations.length === 0)
+        return undefined;
+    if (stations.length === 1)
+        return stations[0].check;
+    return {
+        judge: (toolName, args, cwd, signal, callOpts) => stations.find((s) => s.tools.has(toolName))?.check.judge(toolName, args, cwd, signal, callOpts) ?? null,
+        unanswered: (toolName, cause) => (stations.find((s) => s.tools.has(toolName)) ?? stations[0]).check.unanswered(toolName, cause),
+    };
+}

package/dist/tools/fs/fs-bash.d.ts

@@ -4,8 +4,8 @@ import { type CwdRef } from "./fs-shared.js";
 import type { ReversibilityVerdict } from "../../core/types.js";
 import type { ShellReadAdmission } from "./shell-read-check.js";
 /**
- * The classify doctrine's SHAPE classifier for the `bash` tool, exposed as a `ToolSpec.reversibilityProbe`
- * (the "maybe" tier's probe under `shellGate:"classify"`). A command is reversible ONLY if every connected
+ * The full shell face's SHAPE classifier for the `bash` tool, exposed as a `ToolSpec.reversibilityProbe`
+ * (the "maybe" tier's probe, installed on every full shell). A command is reversible ONLY if every connected
  * segment is a bare command whose program is on the reversible allowlist (default
  * {@link bashClassifyDefaultAllow} — curated to commands with NO write/mutation mode under ANY args) and whose
  * SHAPE the compound classifier accepts (no redirects, substitutions, subshells, escapes or backgrounding; no
@@ -17,7 +17,7 @@ import type { ShellReadAdmission } from "./shell-read-check.js";
  *
  * WHERE a command reads is not this probe's question. The read boundary — deny rows, containment, symlinks,
  * patterns, traversals, the working directory a `cd` moves — is the gate's shell READ STATION
- * (`shell-read-check.ts`), judged on every shell call under every doctrine, ahead of this probe; a call the
+ * (`shell-read-check.ts`), judged on every shell call under every mode, ahead of this probe; a call the
  * station refused never reaches it, and a call the station asks about is asked about whatever this probe
  * says. `boundary` supplies only the environment's declared home, so the `$HOME`/`~` spellings fold here the
  * way the station folds them; nothing else of it is read. A caller-supplied `allow` is honored verbatim, so a

package/dist/tools/fs/fs-read.d.ts

@@ -6,4 +6,5 @@ import { type ReminderDisclosureCounts } from "../../core/reminder-disclosure.js
 export declare function createReadFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: RootsSeat, imageDownsampler?: ReadImageDownsamplerOption, pdfCapabilities?: PdfModelCapabilities, bgOutputReadExemption?: (canonicalKey: string, ctx: {
     taskId?: string;
     principal?: string;
+    toolCallId?: string;
 }) => boolean, readCyberReminder?: boolean, readDeny?: import("./read-deny.js").ReadDenyMatcher, readFace?: import("./containment-face.js").ContainmentFace, reminderMark?: string, reminderDisclosureCounts?: ReminderDisclosureCounts): AgentTool;

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

@@ -12,5 +12,5 @@ import type { CwdRef } from "./fs-shared.js";
  * honesty boundary.
  */
 export declare function grepDetailFields(text: string, mode: "files_with_matches" | "content" | "count", offset?: number, structuredRows?: readonly import("./search.js").GrepRow[]): Record<string, unknown>;
-export declare function createGrepTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: RootsSeat, readDeny?: ReadDenyMatcher, readFace?: ContainmentFace, cwdRef?: CwdRef): AgentTool;
-export declare function createGlobTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: RootsSeat, readDeny?: ReadDenyMatcher, readFace?: ContainmentFace, cwdRef?: CwdRef): AgentTool;
+export declare function createGrepTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: RootsSeat, readDeny?: ReadDenyMatcher, readFace?: ContainmentFace, cwdRef?: CwdRef, readAdmission?: (toolCallId: string | undefined, canonicalKey: string) => boolean): AgentTool;
+export declare function createGlobTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: RootsSeat, readDeny?: ReadDenyMatcher, readFace?: ContainmentFace, cwdRef?: CwdRef, readAdmission?: (toolCallId: string | undefined, canonicalKey: string) => boolean): AgentTool;

package/dist/tools/fs/fs-search-tools.js

@@ -74,7 +74,7 @@ export function grepDetailFields(text, mode, offset, structuredRows) {
     }
     return detailFields;
 }
-export function createGrepTool(env, rootCanonical, additionalRoots, readDeny, readFace, cwdRef) {
+export function createGrepTool(env, rootCanonical, additionalRoots, readDeny, readFace, cwdRef, readAdmission) {
     const declaredTarget = toolFace("grep").pathTarget;
     return defineTool({
         name: "Grep",
@@ -143,7 +143,7 @@ export function createGrepTool(env, rootCanonical, additionalRoots, readDeny, re
             const scopeSpelling = declaredTarget === undefined ? undefined : pathTargetValue(a, declaredTarget);
             let scoped = scopeSpelling;
             if (scopeSpelling !== undefined) {
-                const r = await resolveKey(env, rootCanonical, scopeSpelling, ctx.signal, baseCwd, additionalRoots, undefined, readDeny, readFace);
+                const r = await resolveKey(env, rootCanonical, scopeSpelling, ctx.signal, baseCwd, additionalRoots, readAdmission && ((key) => readAdmission(ctx.toolCallId, key)), readDeny, readFace);
                 if (!r.ok)
                     return errorResult(violationText("Grep", r.violation), violationDetails(r.violation));
                 scoped = r.key;
@@ -177,7 +177,7 @@ export function createGrepTool(env, rootCanonical, additionalRoots, readDeny, re
         },
     });
 }
-export function createGlobTool(env, rootCanonical, additionalRoots, readDeny, readFace, cwdRef) {
+export function createGlobTool(env, rootCanonical, additionalRoots, readDeny, readFace, cwdRef, readAdmission) {
     const declaredTarget = toolFace("glob").pathTarget;
     return defineTool({
         name: "Glob",
@@ -217,7 +217,7 @@ export function createGlobTool(env, rootCanonical, additionalRoots, readDeny, re
             const baseCwd = pathTargetBaseOf(declaredTarget, { root: rootCanonical, cwd: cwdRef?.current });
             let scoped = path;
             if (path !== undefined) {
-                const r = await resolveKey(env, rootCanonical, path, ctx.signal, baseCwd, additionalRoots, undefined, readDeny, readFace);
+                const r = await resolveKey(env, rootCanonical, path, ctx.signal, baseCwd, additionalRoots, readAdmission && ((key) => readAdmission(ctx.toolCallId, key)), readDeny, readFace);
                 if (!r.ok)
                     return errorResult(violationText("Glob", r.violation), violationDetails(r.violation));
                 scoped = r.key;

package/dist/tools/fs/fs-shared.js

@@ -4,6 +4,7 @@ import { normalizeAbsPathLexically, sha256, similarNameSuggestion, OVERSIZE_READ
 import { decodeTextBytes, normalizeFileText } from "./encoding.js";
 import { shellQuote } from "./search.js";
 import { isNotebookPath } from "./notebook.js";
+import { homeViewsOf } from "./read-deny-home.js";
 import { sharpImageDownsampler } from "../../core/mcp.js";
 import { deliverEngineNotice } from "../../core/types.js";
 import { resolveEnvBudget } from "../../core/env-budget.js";
@@ -344,24 +345,37 @@ export function applyContextShrinkToReadFileState(state, shrink) {
 export async function enoentMessage(env, key, cwd, signal, readDeny) {
     let msg = `File does not exist. Note: your current working directory is ${cwd}.`;
     const sep = Math.max(key.lastIndexOf("/"), key.lastIndexOf("\\"));
+    const views = readDeny !== undefined ? homeViewsOf(env, signal) : undefined;
+    const denied = async (path, leaf) => {
+        if (readDeny === undefined || views === undefined)
+            return false;
+        if (readDeny.matchPath(path) != null)
+            return true;
+        const view = await views.of(path, leaf !== undefined ? { leaf } : undefined);
+        return view !== undefined && readDeny.matchPath(view) != null;
+    };
     if (sep > 0) {
         const parent = key.slice(0, sep);
         const name = key.slice(sep + 1);
-        if (readDeny?.matchPath(parent) != null)
+        if (await denied(parent))
             return msg;
         const cwdSepped = cwd.replace(/[\\/]+$/, "");
         const cwdCandidate = `${cwdSepped}${cwd.includes("\\") ? "\\" : "/"}${name}`;
-        if (cwdCandidate !== key && readDeny?.matchPath(cwdCandidate) == null) {
+        if (cwdCandidate !== key && !(await denied(cwdCandidate))) {
             const hit = await env.exists(cwdCandidate, signal).catch(() => undefined);
             if (hit?.ok && hit.value)
                 return `${msg} Did you mean ${cwdCandidate}?`;
         }
         const listing = await env.listDir(parent, signal).catch(() => undefined);
         if (listing?.ok) {
-            const names = listing.value
-                .filter((e) => e.kind !== "directory")
-                .map((e) => e.path.slice(Math.max(e.path.lastIndexOf("/"), e.path.lastIndexOf("\\")) + 1))
-                .filter((n2) => readDeny?.matchPath(`${parent}/${n2}`) == null);
+            const names = [];
+            for (const e of listing.value) {
+                if (e.kind === "directory")
+                    continue;
+                const n2 = e.path.slice(Math.max(e.path.lastIndexOf("/"), e.path.lastIndexOf("\\")) + 1);
+                if (!(await denied(`${parent}/${n2}`, "file")))
+                    names.push(n2);
+            }
             const suggestion = similarNameSuggestion(names, name);
             if (suggestion)
                 msg += ` Did you mean ${suggestion}?`;

package/dist/tools/fs/fs-write.d.ts

@@ -2,6 +2,7 @@ import type { AgentTool, ExecutionEnv } from "../../internal/harness-types.js";
 import type { BeforeWriteHook, FileEditedHook, TrackFileEditHook } from "../../core/types.js";
 import { type ReadFileState } from "./safety.js";
 import type { ContainmentFace } from "./containment-face.js";
+import type { WriteDenyMatcher } from "./read-deny.js";
 import { type CwdRef } from "./fs-shared.js";
 /**
  * The `beforeWrite` CONTENT hook, mounted here rather than in ToolPolicy because only this band sees
@@ -13,8 +14,8 @@ import { type CwdRef } from "./fs-shared.js";
  * Absent hook ⇒ byte-identical behavior.
  */
 export type { BeforeWriteRequest, BeforeWriteResult, BeforeWriteHook, TrackEditRequest, TrackEditResult, TrackFileEditHook } from "../../core/types.js";
-export declare function createEditFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook, onEdited?: FileEditedHook, writeFace?: ContainmentFace): AgentTool;
-export declare function createWriteFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook, onEdited?: FileEditedHook, writeFace?: ContainmentFace): AgentTool;
+export declare function createEditFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook, onEdited?: FileEditedHook, writeFace?: () => ContainmentFace, writeDeny?: WriteDenyMatcher): AgentTool;
+export declare function createWriteFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook, onEdited?: FileEditedHook, writeFace?: () => ContainmentFace, writeDeny?: WriteDenyMatcher): AgentTool;
 /**
  * design v1.163 — NotebookEdit: replace/insert/delete a single cell in a .ipynb. CC-parity tool over the SAME hand-band
  * safety skeleton as Edit/Write (resolveKey containment → requireRead read-before-edit → checkStale content-hash
@@ -22,4 +23,4 @@ export declare function createWriteFileTool(env: ExecutionEnv, state: ReadFileSt
  * .ipynb as the cell projection but records read state (hash/totalLines) in the RAW notebook-text
  * coordinate — that raw-coordinate read record is what this tool's freshness check depends on.
  */
-export declare function createNotebookEditTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook, onEdited?: FileEditedHook, writeFace?: ContainmentFace): AgentTool;
+export declare function createNotebookEditTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook, onEdited?: FileEditedHook, writeFace?: () => ContainmentFace, writeDeny?: WriteDenyMatcher): AgentTool;

package/dist/tools/fs/fs-write.js

@@ -87,7 +87,7 @@ async function gateToolWrite(hook, tool, path, key, content) {
         return `Error (${tool}): write rejected by the write gate (${res.code}): ${clipHookText(res.reason)}`;
     return undefined;
 }
-export function createEditFileTool(env, state, rootCanonical, cwdRef, additionalRoots, beforeWrite, trackEdit, onEdited, writeFace) {
+export function createEditFileTool(env, state, rootCanonical, cwdRef, additionalRoots, beforeWrite, trackEdit, onEdited, writeFace, writeDeny) {
     return defineTool({
         name: "Edit",
         ...toolFace("edit"),
@@ -112,7 +112,7 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
             const path = fileArgPath(args);
             if (path === undefined)
                 return { ok: true };
-            const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots, undefined, undefined, writeFace);
+            const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots, undefined, writeDeny, writeFace?.());
             if (!r.ok)
                 return { ok: true };
             if (a.old_string === a.new_string)
@@ -150,7 +150,7 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
             const path = fileArgPath(args);
             if (path === undefined)
                 return errorResult(`Error (Edit): file_path is required.`);
-            const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots, undefined, undefined, writeFace);
+            const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots, undefined, writeDeny, writeFace?.());
             if (!r.ok)
                 return errorResult(violationText("Edit", r.violation), violationDetails(r.violation));
             if (!batch && a.old_string === a.new_string) {
@@ -325,7 +325,7 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
         },
     });
 }
-export function createWriteFileTool(env, state, rootCanonical, cwdRef, additionalRoots, beforeWrite, trackEdit, onEdited, writeFace) {
+export function createWriteFileTool(env, state, rootCanonical, cwdRef, additionalRoots, beforeWrite, trackEdit, onEdited, writeFace, writeDeny) {
     return defineTool({
         name: "Write",
         ...toolFace("write"),
@@ -344,7 +344,7 @@ export function createWriteFileTool(env, state, rootCanonical, cwdRef, additiona
                 return { ok: true };
             if (ipynbRedirect("Write", path))
                 return { ok: true };
-            const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots, undefined, undefined, writeFace);
+            const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots, undefined, writeDeny, writeFace?.());
             if (!r.ok)
                 return { ok: true };
             const exists = await env.exists(r.key, ctx.signal);
@@ -363,7 +363,7 @@ export function createWriteFileTool(env, state, rootCanonical, cwdRef, additiona
             const ipynb = ipynbRedirect("Write", path);
             if (ipynb)
                 return errorResult(ipynb);
-            const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots, undefined, undefined, writeFace);
+            const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots, undefined, writeDeny, writeFace?.());
             if (!r.ok)
                 return errorResult(violationText("Write", r.violation), violationDetails(r.violation));
             const exists = await env.exists(r.key, ctx.signal);
@@ -424,7 +424,7 @@ export function createWriteFileTool(env, state, rootCanonical, cwdRef, additiona
 const notebookNotIpynbMessage = (notebookPath) => `Error (NotebookEdit): "${notebookPath}" is not a .ipynb file; use Edit for other file types.`;
 const NOTEBOOK_CELL_TYPE_REQUIRED_MESSAGE = `Error (NotebookEdit): Cell type is required when using edit_mode=insert.`;
 const NOTEBOOK_CELL_ID_REQUIRED_MESSAGE = `Error (NotebookEdit): cell_id is required for replace/delete.`;
-export function createNotebookEditTool(env, state, rootCanonical, cwdRef, additionalRoots, beforeWrite, trackEdit, onEdited, writeFace) {
+export function createNotebookEditTool(env, state, rootCanonical, cwdRef, additionalRoots, beforeWrite, trackEdit, onEdited, writeFace, writeDeny) {
     return defineTool({
         name: "NotebookEdit",
         ...toolFace("notebook-edit"),
@@ -458,7 +458,7 @@ export function createNotebookEditTool(env, state, rootCanonical, cwdRef, additi
                 return { ok: false, code: "invalid", message: NOTEBOOK_CELL_TYPE_REQUIRED_MESSAGE };
             if (mode !== "insert" && !a.cell_id)
                 return { ok: false, code: "invalid", message: NOTEBOOK_CELL_ID_REQUIRED_MESSAGE };
-            const r = await resolveKey(env, rootCanonical, a.notebook_path, ctx.signal, cwdRef?.current, additionalRoots, undefined, undefined, writeFace);
+            const r = await resolveKey(env, rootCanonical, a.notebook_path, ctx.signal, cwdRef?.current, additionalRoots, undefined, writeDeny, writeFace?.());
             if (!r.ok)
                 return { ok: true };
             const notRead = requireRead(state, r.key);
@@ -478,7 +478,7 @@ export function createNotebookEditTool(env, state, rootCanonical, cwdRef, additi
                 return errorResult(NOTEBOOK_CELL_TYPE_REQUIRED_MESSAGE);
             if (mode !== "insert" && !cell_id)
                 return errorResult(NOTEBOOK_CELL_ID_REQUIRED_MESSAGE);
-            const r = await resolveKey(env, rootCanonical, notebook_path, ctx.signal, cwdRef?.current, additionalRoots, undefined, undefined, writeFace);
+            const r = await resolveKey(env, rootCanonical, notebook_path, ctx.signal, cwdRef?.current, additionalRoots, undefined, writeDeny, writeFace?.());
             if (!r.ok)
                 return errorResult(violationText("NotebookEdit", r.violation), violationDetails(r.violation));
             const notRead = requireRead(state, r.key);

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

@@ -11,6 +11,7 @@ export * from "./fs-search-tools.js";
 export * from "./bash-readonly-classifier.js";
 export * from "./fs-bash.js";
 export * from "./read-deny.js";
+export { readDenyHomesOf } from "./read-deny-home.js";
 import type { ShellReadAdmission } from "./shell-read-check.js";
 export { BASH_CLASSIFY_EXTRA_ALLOW, bashClassifyDefaultAllow } from "./bash-readonly-classifier.js";
 import { type ReadDenyEntry } from "./read-deny.js";
@@ -55,6 +56,10 @@ export interface HandsToolkitOptions {
      *  consumer mounting the read-only band outside the Runner must run `runToolGate` with a station of its own
      *  (`createShellReadStation`). */
     shellReadAdmission?: ShellReadAdmission;
+    /** The gate's file read station's ADMISSION (`FileReadStation.admitted`, file-read-check.ts), handed to Read / Grep /
+     *  Glob: an out-of-root target the gate put to a question and then let through is read once, on the canonical key the
+     *  station judged. ABSENT ⇒ no station (a library-direct toolkit): the tools refuse every out-of-root target. */
+    readAdmission?: (toolCallId: string | undefined, canonicalKey: string) => boolean;
     /** Commit-message attribution trailer for the `bash` git protocol. Default NONE — attribution is a
      *  deployment identity asset, so the branded deployment sets it; pass `"Name <email>"` to advertise
      *  one, `false` (≡ unset) for no trailer section. */
@@ -167,11 +172,10 @@ export interface HandsToolkitOptions {
      *  time. The write faces are untouched (their guard is createSensitivePathPolicy). */
     readDenyPatterns?: readonly ReadDenyEntry[];
     /** The deployment's built-in-table TIER selection ({@link import("./read-deny.js").ReadDenyBuiltinConfig}
-     *  `tiers` key) — the ON/OFF switch for the built-in table, OFF unless this seat says otherwise:
+     *  `tiers` key) — the switch for the built-in table:
      *  EXACTLY the listed tiers of {@link import("./read-deny.js").READ_FACE_BUILTIN_DENY_TABLE}
      *  are active (`[]` = none — explicit and legal); absent = the default selection
-     *  ({@link import("./read-deny.js").READ_DENY_DEFAULT_TIERS}), which is EMPTY — an unconfigured
-     *  mount activates no built-in row.
+     *  ({@link import("./read-deny.js").READ_DENY_DEFAULT_TIERS}: `credentials` and the home-anchored `agent-config`).
      *  Composes with {@link readDenyBuiltinExclude} (tier selection first, then row removal) and never
      *  touches the additions seats. Unknown tier names throw at wiring time. Deployment seat ONLY —
      *  deliberately not a TaskSpec key, so no task can widen below its deployment. */
@@ -181,6 +185,22 @@ export interface HandsToolkitOptions {
      *  of an inactive tier is a satisfied intent (no-op); a name matching NO table row throws at wiring
      *  time (never silently ignored). Deployment seat ONLY, same clamp argument as the tiers key. */
     readDenyBuiltinExclude?: readonly string[];
+    /** The spellings of the execution environment's home a home-anchored deny row (`~/…`) is placed under
+     *  ({@link import("./read-deny-home.js").readDenyHomesOf}: the declared home and its canonical spelling). Absolute path
+     *  strings only — any other shape throws at wiring time, naming the seat. The Runner passes the spellings its own judge
+     *  was compiled with. */
+    readDenyHomes?: readonly string[];
+    /** Where each home-anchored row's literal head leads beyond the home's spellings
+     *  ({@link import("./read-deny-home.js").readDenyHomeLinksOf}, keyed by the row's pattern) — the Runner passes the
+     *  locations its own judge was compiled with, so the band and the gate judge one placement.
+     *  Unless a mount carries both, the band resolves the placement itself the way the Runner does (the homes it carries
+     *  are used as given; {@link import("./read-deny-home.js").placeReadDenyAtHome}), and its read tools (Read / Grep /
+     *  Glob / RepoMap) wait for that placement before they judge anything. A placement that fails leaves the home-anchored
+     *  rows held anywhere. */
+    readDenyHomeLinks?: ReadonlyMap<string, readonly string[]>;
+    /** The permission-rule rows of the deny table ({@link import("./read-deny.js").PathRuleDenyRow}, `ToolPolicy.pathDenyRules`):
+     *  the read-face rows join the structured read faces' judge beside the segment rows. The Runner passes the leg's own. */
+    pathDenyRules?: readonly import("./read-deny.js").PathRuleDenyRow[];
     /** The READ-face containment state for the structured read faces
      *  ({@link import("./containment-face.js").ContainmentFace}; resolved through the SAME
      *  {@link import("./containment-face.js").resolveContainmentFace} order prepare-task uses). Absent ⇒ the
@@ -202,6 +222,10 @@ export interface HandsToolkitOptions {
      *  wins the same way the read seat's does (that mount carries no write faces at all), announced as
      *  `config.write_face_deployment_clamped`. Never affects the read faces. */
     writeFace?: ContainmentFace;
+    /** A runner's LIVE write face — its resolution, which reads the permission mode's face on every call. Present ⇒
+     *  the write tools read it per call and {@link writeFace} is not consulted (the runner resolved and screened the
+     *  seats itself); absent ⇒ the toolkit's own resolution of {@link writeFace}, fixed at creation. */
+    writeFaceLive?: () => ContainmentFace;
     /** The session's reminder provenance mark: the band's engine-minted
      *  `<system-reminder>` open tags (the Read cyber/dedup/offset/empty reminders and the gh
      *  rate-limit hint) carry it as `mark="…"`, matching the system-prompt declaration the Runner
@@ -224,6 +248,18 @@ export interface HandsToolkitOptions {
  *  predicate {@link createHandsToolkit} branches on and prepare-task plans by (the memory phase must know, before the
  *  band exists, whether the instruction-taught write channel will be there). `readOnly` is the verifier boundary. */
 export declare function handsWriteHalfMounts(opts: Pick<HandsToolkitOptions, "readOnly">): boolean;
+/** The engine's background-output read exemption over one toolkit's seats: the exact registered output file of a
+ *  background command, visible to the caller's own owner / scope / session, on THIS execution env — the file the
+ *  launch receipt tells the model to Read. Shared by the Read tool's fence and the file read station, so the station
+ *  puts no question where the fence would admit. */
+export declare function backgroundOutputReadExemption(registry: TaskRegistry | undefined, seat: {
+    readonly taskOwner?: string;
+    readonly taskScope?: string;
+    readonly sessionId?: string;
+}, env: ExecutionEnv): ((canonicalKey: string, c?: {
+    taskId?: string;
+    principal?: string;
+}) => boolean) | undefined;
 /**
  * Build the per-task hand tool band over an injected env + fresh per-task read state.
  * `rootCanonical` is the already-canonicalized containment root (prepare-task resolves it once). Normal

package/dist/tools/fs/index.js

@@ -11,9 +11,12 @@ export * from "./fs-search-tools.js";
 export * from "./bash-readonly-classifier.js";
 export * from "./fs-bash.js";
 export * from "./read-deny.js";
+export { readDenyHomesOf } from "./read-deny-home.js";
 import { BASH_READONLY_DEFAULT_ALLOW } from "./bash-readonly-classifier.js";
 export { BASH_CLASSIFY_EXTRA_ALLOW, bashClassifyDefaultAllow } from "./bash-readonly-classifier.js";
-import { compileReadDeny } from "./read-deny.js";
+import { checkedReadDenyHomes, compileReadDeny, compileWriteDeny, readDenyBuiltinConfigOf, readDenyPatternRun } from "./read-deny.js";
+import { withGateTimeout } from "../../core/gate-bounded-await.js";
+import { placeReadDenyAtHome, readDenyPlacedLater } from "./read-deny-home.js";
 import { deploymentFaceClampNotice, resolveContainmentFace } from "./containment-face.js";
 export * from "./containment-face.js";
 import {} from "./fs-shared.js";
@@ -24,22 +27,41 @@ import { createBashTool, createBashReadonlyTool, createEnvTaskOutputTool, create
 export function handsWriteHalfMounts(opts) {
     return opts.readOnly !== true;
 }
+export function backgroundOutputReadExemption(registry, seat, env) {
+    if (registry === undefined)
+        return undefined;
+    return (canonicalKey, c) => registry.isBackgroundOutputFile(canonicalKey, { owner: c?.taskId ?? seat.taskOwner, scope: c?.principal ?? seat.taskScope, ...(seat.sessionId !== undefined ? { sessionId: seat.sessionId } : {}) }, env);
+}
 export function createHandsToolkit(env, readFileState, rootCanonical, opts = {}) {
     const { includeShell = false, readOnly = false, bashReadonlyAllow, commitCoAuthor = false, mountBackgroundTaskTools = true, additionalRoots, additionalReadRoots, } = opts;
     const readFaceRoots = additionalReadRoots === undefined ? additionalRoots : () => (additionalReadRoots.length === 0 ? additionalRoots : [...(additionalRoots ?? []), ...additionalReadRoots]);
     const cwdRef = opts.cwdRef ?? { current: rootCanonical };
-    const bgReadRegistry = opts.taskRegistry;
-    const bgOutputReadExemption = bgReadRegistry === undefined
+    const bgOutput = backgroundOutputReadExemption(opts.taskRegistry, opts, env);
+    const readAdmission = opts.readAdmission;
+    const bgOutputReadExemption = bgOutput === undefined && readAdmission === undefined
         ? undefined
-        : (canonicalKey, c) => bgReadRegistry.isBackgroundOutputFile(canonicalKey, {
-            owner: c.taskId ?? opts.taskOwner,
-            scope: c.principal ?? opts.taskScope,
-            ...(opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {}),
-        }, env);
-    const readDeny = compileReadDeny(opts.readDenyPatterns ?? [], "HandsToolkitOptions.readDenyPatterns", {
-        ...(opts.readDenyBuiltinTiers !== undefined ? { tiers: opts.readDenyBuiltinTiers } : {}),
-        ...(opts.readDenyBuiltinExclude !== undefined ? { exclude: opts.readDenyBuiltinExclude } : {}),
-    });
+        : (canonicalKey, c) => readAdmission?.(c.toolCallId, canonicalKey) === true || (bgOutput?.(canonicalKey, c) ?? false);
+    const readDenyAdditions = (opts.readDenyPatterns ?? []).map((e) => (typeof e === "object" && e !== null ? { ...e } : e));
+    const readDenyRules = opts.pathDenyRules === undefined ? undefined : [...opts.pathDenyRules];
+    const readDenyBuiltinCfg = readDenyBuiltinConfigOf({ tiers: opts.readDenyBuiltinTiers, exclude: opts.readDenyBuiltinExclude });
+    const readDenyHomes = opts.readDenyHomes === undefined ? undefined : [...checkedReadDenyHomes(opts.readDenyHomes)];
+    const compileAt = (homes, linked) => compileReadDeny(readDenyAdditions, "HandsToolkitOptions.readDenyPatterns", readDenyBuiltinCfg, readDenyRules, homes, linked);
+    const unplaced = compileAt([]);
+    const carried = readDenyHomes !== undefined && opts.readDenyHomeLinks !== undefined;
+    const placesNothing = !unplaced.entries.some((e) => readDenyPatternRun(e.pattern).homeAnchored);
+    const late = carried || placesNothing ? undefined : readDenyPlacedLater(unplaced, () => placeReadDenyAtHome(env, compileAt, readDenyHomes));
+    const readDeny = late?.matcher ?? (carried ? compileAt(readDenyHomes, opts.readDenyHomeLinks) : unplaced);
+    const afterPlacement = (tool) => late === undefined
+        ? tool
+        : {
+            ...tool,
+            execute: async (...args) => {
+                await withGateTimeout(late.ready(), undefined, args[2], "readDenyPlacement").catch(() => undefined);
+                return await tool.execute(...args);
+            },
+        };
+    const writeDenyCompiled = compileWriteDeny(readDenyRules);
+    const writeDeny = writeDenyCompiled.ruleRows.length > 0 ? writeDenyCompiled : undefined;
     const readFace = resolveContainmentFace({
         kind: "read",
         depsFace: opts.readFace,
@@ -56,13 +78,14 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
         fullShellReachable: includeShell && !readOnly,
         onDeploymentClamp: () => deliverEngineNotice(opts.onNotice, deploymentFaceClampNotice("write")),
     });
+    const writeFaceOf = opts.writeFaceLive ?? (() => writeFace);
     const tools = [
-        createReadFileTool(env, readFileState, rootCanonical, readOnly ? undefined : cwdRef, readFaceRoots, opts.readImageDownsampler, opts.pdfModelCapabilities, bgOutputReadExemption, opts.readCyberReminder, readDeny, readFace, opts.reminderMark, opts.reminderDisclosureCounts),
+        afterPlacement(createReadFileTool(env, readFileState, rootCanonical, readOnly ? undefined : cwdRef, readFaceRoots, opts.readImageDownsampler, opts.pdfModelCapabilities, bgOutputReadExemption, opts.readCyberReminder, readDeny, readFace, opts.reminderMark, opts.reminderDisclosureCounts)),
     ];
     if (handsWriteHalfMounts({ readOnly })) {
-        tools.push(createEditFileTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite, opts.trackFileEdit, opts.onFileEdited, writeFace), createWriteFileTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite, opts.trackFileEdit, opts.onFileEdited, writeFace), createNotebookEditTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite, opts.trackFileEdit, opts.onFileEdited, writeFace));
+        tools.push(createEditFileTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite, opts.trackFileEdit, opts.onFileEdited, writeFaceOf, writeDeny), createWriteFileTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite, opts.trackFileEdit, opts.onFileEdited, writeFaceOf, writeDeny), createNotebookEditTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite, opts.trackFileEdit, opts.onFileEdited, writeFaceOf, writeDeny));
     }
-    tools.push(createGrepTool(env, rootCanonical, readFaceRoots, readDeny, readFace, cwdRef), createGlobTool(env, rootCanonical, readFaceRoots, readDeny, readFace, cwdRef), createRepoMapTool(env, rootCanonical, readFaceRoots, readDeny, readFace));
+    tools.push(afterPlacement(createGrepTool(env, rootCanonical, readFaceRoots, readDeny, readFace, cwdRef, readAdmission)), afterPlacement(createGlobTool(env, rootCanonical, readFaceRoots, readDeny, readFace, cwdRef, readAdmission)), afterPlacement(createRepoMapTool(env, rootCanonical, readFaceRoots, readDeny, readFace)));
     if (includeShell) {
         tools.push(readOnly
             ? createBashReadonlyTool(env, rootCanonical, new Set(bashReadonlyAllow ?? BASH_READONLY_DEFAULT_ALLOW), {

package/dist/tools/fs/read-deny-home.d.ts

@@ -0,0 +1,93 @@
+import type { ExecutionEnv } from "../../internal/harness-types.js";
+import { type PathFamily } from "./safety.js";
+import { type ReadDenyMatcher } from "./read-deny.js";
+/** The environment's DECLARED home as an anchor list: `[homeDir]` when it declares an absolute one, else `[]` (no
+ *  home — a home-anchored row then holds its run anywhere, see `compileReadDeny`). */
+export declare function declaredReadDenyHomes(env: Pick<ExecutionEnv, "homeDir">): string[];
+/** The declared home and, where the environment's canonical spelling of it differs (a home reached through a
+ *  symlink), that spelling too: the faces judge canonical keys beside the spelled views, so a row placed only at
+ *  the spelled home would never meet a canonical key. A home the environment cannot resolve keeps its spelling. */
+export declare function readDenyHomesOf(env: Pick<ExecutionEnv, "homeDir" | "canonicalPath">, signal?: AbortSignal): Promise<string[]>;
+/**
+ * Where the home-anchored rows of a table LEAD beyond the home's own spellings, keyed by the row's pattern — the
+ * `linked` argument of `compileReadDeny`. For each row, its LITERAL HEAD (`readDenyRunHead`: the run's segments before
+ * the first one carrying `*`) is spelled under each home and resolved the way the read faces mint their keys
+ * (`canonicalizeTarget`: the longest existing prefix resolved, the rest rejoined); a location that differs from every
+ * home's own spelling of the head is where one of the head's segments is a link, and the row is placed there too.
+ *  · a head that resolves to its own spelling under a home adds nothing (the row is already placed there);
+ *  · a head that cannot be resolved (an unanswered or refused probe, a probe that throws) adds nothing, and the answer
+ *    is not WHOLE (`whole: false`): the row stays placed at the home's spellings until the mount places again;
+ *  · a row whose head is empty (`~/.sema.*`) has no location to resolve and adds nothing;
+ *  · the heads are resolved together, so one placement waits at most one probe bound;
+ *  · read per placement — a link created afterwards is followed from the next placement on.
+ */
+export declare function readDenyHomeLinksOf(env: ExecutionEnv, entries: readonly {
+    readonly pattern: string;
+    readonly caseSensitive?: boolean;
+}[], homes: readonly string[], signal?: AbortSignal): Promise<{
+    readonly linked: Map<string, string[]>;
+    readonly whole: boolean;
+}>;
+/** Where an absolute location LEADS in one environment — resolved the way the read and write faces mint their keys
+ *  (`canonicalizeTarget`: the longest existing prefix resolved, the rest rejoined). `undefined` when the environment
+ *  does not answer (a refused or failed probe, one that throws). The one resolution a deny row's placement reads: a
+ *  home-anchored row's head ({@link readDenyHomeLinksOf}) and a rule row's head ({@link whereItsAnsweredPrefixLeads}). */
+export declare function whereItLeads(env: ExecutionEnv, at: string, family?: PathFamily, signal?: AbortSignal): Promise<string | undefined>;
+/** {@link whereItLeads} with a floor: where the environment does not answer for `at` (a probe that fails), the longest
+ *  prefix it does answer for is resolved and the rest rejoined — a rule row's head below a base that resolves is never
+ *  placed narrower than that base's own canonical spelling. The whole walk waits at most one bounded-await deadline.
+ *  `undefined` when no prefix answers in time. */
+export declare function whereItsAnsweredPrefixLeads(env: ExecutionEnv, at: string, family?: PathFamily, signal?: AbortSignal): Promise<string | undefined>;
+/** One mount's read-deny judge with its home-anchored rows placed: at the home's spellings (`homes` when the mount
+ *  carries them, else {@link readDenyHomesOf}, under the tree's bounded-await deadline — an environment that cannot
+ *  answer rejects the placement instead of holding it open) and where their heads lead ({@link readDenyHomeLinksOf}).
+ *  `whole` says whether the home and every head answered. A home the environment did not answer for places nothing:
+ *  the rows are held anywhere (`compile([])`, the rule for a row that cannot be placed) rather than at a spelling that
+ *  may miss the home's canonical one. `compile` is the mount's own compile over the two; the rows' patterns are read
+ *  off its compile at the homes alone. */
+export declare function placeReadDenyAtHome(env: ExecutionEnv, compile: (homes: readonly string[], linked?: ReadonlyMap<string, readonly string[]>) => ReadDenyMatcher, homes?: readonly string[], signal?: AbortSignal): Promise<{
+    readonly matcher: ReadDenyMatcher;
+    readonly homes: readonly string[];
+    readonly linked: ReadonlyMap<string, readonly string[]>;
+    readonly whole: boolean;
+}>;
+/**
+ * A judge for a mount that is built before its placement settles (the hands band is built synchronously): the table as
+ * `unplaced` compiles it — home-anchored rows held anywhere, the rule for a row that cannot be placed — until a
+ * placement settles, then the placed table. `place` starts at once; `ready()` settles when the latest placement has
+ * (either way) and, while no placement has come back WHOLE (a failed one, or one with a head that did not answer),
+ * places again first — an unanswered lookup is never kept as the answer. A failed placement leaves the table it
+ * replaced (the rows held anywhere, or an earlier placement), never unplaced-and-narrow. The mount holds its read faces
+ * until `ready()`.
+ */
+export declare function readDenyPlacedLater(unplaced: ReadDenyMatcher, place: () => Promise<{
+    readonly matcher: ReadDenyMatcher;
+    readonly whole: boolean;
+}>): {
+    readonly matcher: ReadDenyMatcher;
+    readonly ready: () => Promise<void>;
+};
+/** The environment surface a home view reads. */
+export type HomeViewEnv = Pick<ExecutionEnv, "homeDir" | "canonicalPath" | "fileIdentity">;
+/**
+ * A path's HOME VIEW — the one reader every face that judges a deny row by location uses (the structured read and
+ * write tools' target judgment, the shell station's establishment, the search walker, the ripgrep leg's output check
+ * and its scope choice). The view of a path is the path itself when it IS a directory on the home's chain (the
+ * canonical home and each of its ancestors, matched by {@link ExecutionEnv.fileIdentity}) — that directory's
+ * canonical spelling — and otherwise its parent's view with its own name rejoined. `of` answers the view only where
+ * it differs from the path as spelled; `undefined` otherwise, and wherever it cannot be read:
+ *  · the environment declares no home, no `fileIdentity`, or its home does not resolve ⇒ no view (the spelling form);
+ *    a home, or a level of its chain, that could not be read is asked again by the next judgment — an unanswered
+ *    lookup is never kept as the answer;
+ *  · a level that does not exist (a write's missing tail) has no identity of its own and takes its parent's view;
+ *  · any other failure at a level stops the view there: the path is judged as spelled, never wider.
+ * `leaf: "file"` skips the path's own identity (a file is never a directory on the chain).
+ */
+export interface HomeViews {
+    of(path: string, opts?: {
+        readonly leaf?: "file";
+    }): Promise<string | undefined>;
+}
+/** The home views of one judgment (a tool call, a command's establishment, one search): a view per directory is read
+ *  once and shared by every path below it. */
+export declare function homeViewsOf(env: HomeViewEnv, signal?: AbortSignal): HomeViews;