@sema-agent/core 7.49.4 → 7.50.0

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

@@ -4,17 +4,22 @@ import { sha256, resolveKey, violationText, violationDetails, binaryMagicFormat,
 import { decodeTextBytes } from "./encoding.js";
 import { isNotebookPath, parseNotebookCells, renderNotebookCells, stripNotebookImageData, NOTEBOOK_IMAGE_BASE64_BUDGET } from "./notebook.js";
 import { MCP_IMAGE_MAX_BASE64, IMAGE_TARGET_RAW_SIZE } from "../../core/mcp.js";
-import { PDF_MAX_PAGES_PER_READ, pdfMagicMatches } from "./pdf.js";
+import { countPdfPagesFromBytes, PDF_MAX_PAGES_PER_READ, PDF_TARGET_RAW_SIZE, pdfMagicMatches } from "./pdf.js";
 import { MAX_READ_BYTES, SLICED_READ_MAX_BYTES, NO_DOWNSAMPLER_IMAGE_CAP_HINT, resolveAutoDownsampler, MAX_READ_OUTPUT_CHARS, FILE_PATH_PARAMS, countLines, seededFileUnchangedReminder, enoentMessage, } from "./fs-shared.js";
 import { readPdfFile } from "./fs-pdf.js";
-import { openSystemReminder } from "../../core/reminder-mint.js";
+import { seatForCall, seatReady } from "./read-deny.js";
+import { thrownText } from "../../core/thrown-value.js";
+import { MARKED_BLOCK_AFTER_DATA, openSystemReminder } from "../../core/reminder-mint.js";
 import { planReminderDisclosure, commitReminderDisclosureEffects, renderReminderDisclosureTrailer, } from "../../core/reminder-disclosure.js";
 import { toolFace } from "../../core/tool-catalog-entries.js";
 import { admitImageBytes, imageReadCap } from "./image-admission.js";
+import { createEntryDenyJudge, enumerateDirectory } from "./dir-entries.js";
+import { FileError } from "../../internal/harness.js";
 export const READ_OUTCOMES = Object.freeze(["attached", "partial", "unchanged", "not_attached"]);
+const UNBINDABLE = "this environment cannot bind a read to the file that was checked, so it was not read";
 const NO_EFFECTS = () => ({ disclosure: [] });
 export function createModelFileReader(opts) {
-    const { env, state, rootCanonical, cwdRef, additionalRoots, imageDownsampler, pdfCapabilities, bgOutputReadExemption, readDeny, readFace, reminderMark } = opts;
+    const { env, state, rootCanonical, cwdRef, imageDownsampler, pdfCapabilities, bgOutputReadExemption, readFace, reminderMark, readDeny: readDenySeat, additionalRoots: rootsSeat } = opts;
     const windows = opts.disclosureWindows ?? new Map();
     const refuse = (envelope, kind) => ({
         outcome: "not_attached",
@@ -29,7 +34,13 @@ export function createModelFileReader(opts) {
         const verdict = plan.verdict;
         return { ...(verdict.reminder !== undefined || verdict.envelopeTags !== undefined ? { note: { kind: "disclosure", verdict } } : {}), effects: plan.effects };
     };
-    const readForModel = async (args, ctx) => {
+    const resolve = async (path, ctx) => {
+        if (ctx.toolCallId === undefined)
+            await seatReady(rootsSeat, ctx.signal);
+        return resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, seatForCall(rootsSeat, ctx.toolCallId), bgOutputReadExemption === undefined ? undefined : (key) => bgOutputReadExemption(key, ctx), seatForCall(readDenySeat, ctx.toolCallId), readFace);
+    };
+    const readForModel = async (args, ctx, opts) => {
+        const readDeny = seatForCall(readDenySeat, ctx.toolCallId);
         const { offset, limit, pages } = (args ?? {});
         const path = fileArgPath(args);
         if (path === undefined)
@@ -42,29 +53,35 @@ export function createModelFileReader(opts) {
             details: { type: "file_unchanged", reason, file: { filePath: path, startLine, endLine, totalLines } },
             effects: NO_EFFECTS(),
         });
-        const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots, bgOutputReadExemption === undefined ? undefined : (key) => bgOutputReadExemption(key, ctx), readDeny, readFace);
+        const r = await resolve(path, ctx);
         if (!r.ok)
             return refuse(errorResult(violationText("Read", r.violation), violationDetails(r.violation)));
+        if (opts?.bound !== undefined && r.key !== opts.bound.key) {
+            return refuse(errorResult(`Error (Read): "${path.slice(0, 300)}" resolved to a different file while it was being checked, so it was not read.`));
+        }
+        const bound = opts?.bound;
+        const readBytes = (key, laneCap) => bound === undefined ? env.readBinaryFile(key, ctx.signal) : bound.object.readBytes(laneCap, ctx.signal);
+        const info = bound === undefined ? await env.fileInfo(r.key, ctx.signal) : await bound.object.size().then((s) => (s.ok ? { ok: true, value: { kind: bound.object.kind, size: s.value } } : s));
+        if (info.ok && info.value.kind === "directory") {
+            return refuse(errorResult(`Error (Read): "${path}" is a directory, not a file; use glob/grep or list it with the shell.`), "directory");
+        }
         const isNb = isNotebookPath(r.key);
         const imageMime = imageMimeForRead(r.key);
         if (imageMime !== undefined) {
-            const meta = await env.fileInfo(r.key, ctx.signal);
+            const meta = info;
             if (!meta.ok) {
                 const ex = await env.exists(r.key, ctx.signal);
                 if (ex.ok && !ex.value)
                     return refuse(errorResult(`Error (Read): ${await enoentMessage(env, r.key, cwdRef?.current ?? rootCanonical, ctx.signal, readDeny)}`), "image");
                 return refuse(errorResult(`Error (Read): cannot stat image "${path}" to verify its size before reading: ${meta.error.message}`), "image");
             }
-            if (meta.value.kind === "directory") {
-                return refuse(errorResult(`Error (Read): "${path}" is a directory, not a file; use glob/grep or list it with the shell.`), "image");
-            }
             const downsampler = imageDownsampler === false ? undefined : (imageDownsampler ?? (await resolveAutoDownsampler()));
             const readCap = imageReadCap(downsampler);
             const tooLargeToRead = (bytes) => `Error (Read): image "${path}" is too large to read (${bytes} bytes > ${readCap}-byte cap).` +
                 (downsampler ? "" : ` ${NO_DOWNSAMPLER_IMAGE_CAP_HINT}`);
             if (meta.value.size > readCap)
                 return refuse(errorResult(tooLargeToRead(meta.value.size)), "image");
-            const bin = await env.readBinaryFile(r.key, ctx.signal);
+            const bin = await readBytes(r.key, readCap);
             if (!bin.ok)
                 return refuse(errorResult(`Error (Read): cannot read image "${path}": ${bin.error.message}`), "image");
             const admitted = await admitImageBytes(bin.value, imageMime, downsampler);
@@ -96,6 +113,25 @@ export function createModelFileReader(opts) {
             };
         }
         const pdfOf = async (preRead) => {
+            if (bound !== undefined) {
+                if (!info.ok)
+                    return refuse(errorResult(`Error (Read): cannot size PDF "${path.slice(0, 300)}": ${info.error.message.slice(0, 200)}`), "pdf");
+                let held = preRead;
+                if (held === undefined && info.value.size <= PDF_TARGET_RAW_SIZE) {
+                    const got = await readBytes(r.key, PDF_TARGET_RAW_SIZE);
+                    if (!got.ok)
+                        return refuse(errorResult(`Error (Read): cannot read PDF "${path.slice(0, 300)}": ${got.error.message.slice(0, 200)}`), "pdf");
+                    held = got.value;
+                }
+                const pageCount = held !== undefined ? countPdfPagesFromBytes(held) : undefined;
+                return {
+                    outcome: "attached",
+                    kind: "pdf",
+                    data: [],
+                    notes: [{ kind: "pdf_reference", bytes: info.value.size, ...(pageCount !== undefined ? { pages: pageCount } : {}) }],
+                    effects: NO_EFFECTS(),
+                };
+            }
             const effects = [];
             const out = await readPdfFile(env, path, r.key, pages, ctx.signal, imageDownsampler, cwdRef?.current ?? rootCanonical, preRead, pdfCapabilities, readDeny, {
                 mark: reminderMark,
@@ -113,11 +149,7 @@ export function createModelFileReader(opts) {
             return pdfOf(undefined);
         const binaryExt = hasBinaryExtension(r.key);
         const binaryExtRefusal = () => refuse(errorResult(`Error (Read): "${path}" appears to be a binary file (by extension); this tool reads UTF-8 text only.`), "text");
-        const info = await env.fileInfo(r.key, ctx.signal);
         if (info.ok) {
-            if (info.value.kind === "directory") {
-                return refuse(errorResult(`Error (Read): "${path}" is a directory, not a file; use glob/grep or list it with the shell.`), "text");
-            }
             if (info.value.size > SLICED_READ_MAX_BYTES) {
                 if (binaryExt)
                     return binaryExtRefusal();
@@ -137,7 +169,7 @@ export function createModelFileReader(opts) {
                 return refuse(errorResult(`Error (Read): ${await enoentMessage(env, r.key, cwdRef?.current ?? rootCanonical, ctx.signal, readDeny)}`), "text");
             return refuse(errorResult(`Error (Read): cannot determine the type of "${path.slice(0, 300)}" (stat failed: ${info.error.message.slice(0, 200)}); refusing to open it — if it is a FIFO/socket/device, reading it would hang. Retry if this was transient, or inspect it with Bash (e.g. \`file\`, \`ls -l\`).`), "text");
         }
-        const readBin = await env.readBinaryFile(r.key, ctx.signal);
+        const readBin = await readBytes(r.key, !isNb && limit === undefined ? MAX_READ_BYTES : SLICED_READ_MAX_BYTES);
         if (!readBin.ok)
             return refuse(errorResult(`Error (Read): cannot read "${path}": ${readBin.error.message}`), "text");
         const readSize = readBin.value.byteLength;
@@ -302,6 +334,16 @@ export function createModelFileReader(opts) {
     const committed = new WeakSet();
     return {
         readForModel,
+        async resolveTarget(path, ctx) {
+            const r = await resolve(path, ctx).catch((err) => ({ ok: false, violation: { code: "invalid", message: thrownText(err) } }));
+            return r.ok ? { ok: true, key: r.key } : { ok: false, refusal: errorResult(violationText("Read", r.violation), violationDetails(r.violation)) };
+        },
+        openBound: (key, signal) => (env.openBound !== undefined ? env.openBound(key, signal) : Promise.resolve({ ok: false, error: new FileError("not_supported", UNBINDABLE, key) })),
+        listDirectory: (bound, signal) => enumerateDirectory(env, bound.key, readDenySeat !== undefined ? createEntryDenyJudge(env, readDenySeat, signal) : undefined, signal, () => bound.object.list(signal)),
+        planDisclosure(segments, throttleKey) {
+            const d = disclosureOf(segments, "read", throttleKey);
+            return { ...(d.note !== undefined ? { note: d.note } : {}), effects: d.effects };
+        },
         commit(result, at) {
             if (committed.has(result))
                 throw new Error("ModelFileReader.commit: this read result was already committed — a delivery commits its read once");
@@ -348,6 +390,8 @@ export function renderReadNoteForTool(note, mark) {
         }
         case "disclosure":
             return renderReminderDisclosureTrailer(note.verdict, mark) ?? "";
+        case "pdf_reference":
+            return `[PDF not read: ${note.bytes !== undefined ? `${note.bytes} bytes` : "size unknown"}, ${note.pages !== undefined ? `${note.pages} page${note.pages === 1 ? "" : "s"}` : "page count unknown"}. Read it with the pages parameter, at most ${PDF_MAX_PAGES_PER_READ} pages per request.]`;
     }
 }
 export function renderReadToolResult(r, mark) {
@@ -373,7 +417,7 @@ export function renderReadToolResult(r, mark) {
             return {
                 content: [
                     ...(noCells !== undefined ? [{ type: "text", text: renderReadNoteForTool(noCells, mark) }] : r.data),
-                    ...(trailer !== undefined ? [{ type: "text", text: trailer }] : []),
+                    ...(trailer !== undefined ? [{ type: "text", text: `${MARKED_BLOCK_AFTER_DATA}${trailer}` }] : []),
                 ],
                 details: r.details,
             };
@@ -383,14 +427,14 @@ export function renderReadToolResult(r, mark) {
             const header = noteOf("partial_page") ?? noteOf("partial_chars") ?? noteOf("range");
             const body = r.data[0]?.text ?? "";
             return {
-                content: `${fallback !== undefined ? renderReadNoteForTool(fallback, mark) : ""}${header !== undefined ? renderReadNoteForTool(header, mark) : ""}${body}${trailer !== undefined ? `\n${trailer}` : ""}`,
+                content: `${fallback !== undefined ? renderReadNoteForTool(fallback, mark) : ""}${header !== undefined ? renderReadNoteForTool(header, mark) : ""}${body}${trailer !== undefined ? `${MARKED_BLOCK_AFTER_DATA}${trailer}` : ""}`,
                 details: r.details,
             };
         }
     }
 }
-export function createReadFileTool(env, state, rootCanonical, cwdRef, additionalRoots, imageDownsampler, pdfCapabilities, bgOutputReadExemption, readDeny, readFace, reminderMark, reminderDisclosureCounts) {
-    const reader = createModelFileReader({
+export function createReadFileTool(env, state, rootCanonical, cwdRef, additionalRoots, imageDownsampler, pdfCapabilities, bgOutputReadExemption, readDeny, readFace, reminderMark, reminderDisclosureCounts, sharedReader) {
+    const reader = sharedReader ?? createModelFileReader({
         env,
         state,
         rootCanonical,

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

@@ -1,6 +1,6 @@
 import type { AgentTool, ExecutionEnv } from "../../internal/harness-types.js";
 import { type RootsSeat } from "./safety.js";
-import type { ReadDenyMatcher } from "./read-deny.js";
+import { type ReadDenyMatcher } from "./read-deny.js";
 import type { ContainmentFace } from "./containment-face.js";
 import type { CwdRef } from "./fs-shared.js";
 /**
@@ -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, 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;
+export declare function createGrepTool(env: ExecutionEnv, rootCanonical: string, rootsSeat?: RootsSeat, denySeat?: ReadDenyMatcher, readFace?: ContainmentFace, cwdRef?: CwdRef, readAdmission?: (toolCallId: string | undefined, canonicalKey: string) => boolean): AgentTool;
+export declare function createGlobTool(env: ExecutionEnv, rootCanonical: string, rootsSeat?: RootsSeat, denySeat?: ReadDenyMatcher, readFace?: ContainmentFace, cwdRef?: CwdRef, readAdmission?: (toolCallId: string | undefined, canonicalKey: string) => boolean): AgentTool;

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

@@ -2,6 +2,7 @@ import { Type } from "typebox";
 import { defineTool, errorResult } from "../../core/tools.js";
 import { clipSpelling, pathFamilyOf, resolveKey, violationText, violationDetails, WIN32_NAMESPACE_REFUSAL_TEXT } from "./safety.js";
 import { runGrepDetailed, runGlobDetailed, invalidGlobTokens } from "./search.js";
+import { seatForCall } from "./read-deny.js";
 import { toolFace } from "../../core/tool-catalog-entries.js";
 import { pathTargetBaseOf, splitAbsoluteGlobPattern } from "../../core/effective-path-target.js";
 import { pathTargetValue } from "../../core/tool-registry.js";
@@ -74,7 +75,7 @@ export function grepDetailFields(text, mode, offset, structuredRows) {
     }
     return detailFields;
 }
-export function createGrepTool(env, rootCanonical, additionalRoots, readDeny, readFace, cwdRef, readAdmission) {
+export function createGrepTool(env, rootCanonical, rootsSeat, denySeat, readFace, cwdRef, readAdmission) {
     const declaredTarget = toolFace("grep").pathTarget;
     return defineTool({
         name: "Grep",
@@ -112,6 +113,8 @@ export function createGrepTool(env, rootCanonical, additionalRoots, readDeny, re
             offset: Type.Optional(Type.Number({ description: "Skip the first N output lines (pagination partner of head_limit)." })),
         }),
         execute: async (args, ctx) => {
+            const readDeny = seatForCall(denySeat, ctx.toolCallId);
+            const additionalRoots = seatForCall(rootsSeat, ctx.toolCallId);
             const retired = args;
             for (const [name, repair] of [
                 ["regex", "the `pattern` is ALWAYS evaluated as a regular expression (ripgrep semantics) — drop the key; to match text literally, escape the regex metacharacters in `pattern`"],
@@ -177,7 +180,7 @@ export function createGrepTool(env, rootCanonical, additionalRoots, readDeny, re
         },
     });
 }
-export function createGlobTool(env, rootCanonical, additionalRoots, readDeny, readFace, cwdRef, readAdmission) {
+export function createGlobTool(env, rootCanonical, rootsSeat, denySeat, readFace, cwdRef, readAdmission) {
     const declaredTarget = toolFace("glob").pathTarget;
     return defineTool({
         name: "Glob",
@@ -201,6 +204,8 @@ export function createGlobTool(env, rootCanonical, additionalRoots, readDeny, re
             max_results: Type.Optional(Type.Number({ description: "Cap results (default 500)." })),
         }),
         execute: async (args, ctx) => {
+            const readDeny = seatForCall(denySeat, ctx.toolCallId);
+            const additionalRoots = seatForCall(rootsSeat, ctx.toolCallId);
             let pattern = args.pattern;
             let path = declaredTarget === undefined ? undefined : pathTargetValue(args, declaredTarget);
             const { max_results } = args;

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

@@ -2,7 +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 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

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

@@ -3,6 +3,7 @@ import { Type } from "typebox";
 import { defineTool, errorResult } from "../../core/tools.js";
 import { sha256, resolveKey, violationText, violationDetails, requireRead, checkStale, checkEditMatch, checkNoChange, fileArgPath, resolveQuoteMatch, adaptNewStringQuotes, resolveEscapeMatch, adaptNewStringEscapes, escapeMatchWasAttempted, ESCAPE_MATCH_MISS_NOTE, deletionOldString, countOccurrences, READ_REFUSED_ESCAPE_HINT, } from "./safety.js";
 import { decodeTextBytes, encodeTextForFile, normalizeEditText, normalizeFileText } from "./encoding.js";
+import { seatForCall } from "./read-deny.js";
 import { MAX_EDIT_BYTES, decodeEditBytes, tooLargeToEditMessage, truncatedUtf16BodyMessage, persistedTextOf, notReadRefusalText, enoentMessage, FILE_STATE_TRAILER, FILE_PATH_PARAMS, coerceWriteArguments, ipynbRedirect, countLines, applyRecordedEdit, } from "./fs-shared.js";
 import { toolFace } from "../../core/tool-catalog-entries.js";
 import { thrownText } from "../../core/thrown-value.js";
@@ -112,7 +113,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, writeDeny, writeFace?.());
+            const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots, undefined, seatForCall(writeDeny, ctx.toolCallId), writeFace?.());
             if (!r.ok)
                 return { ok: true };
             if (a.old_string === a.new_string)
@@ -150,7 +151,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, writeDeny, writeFace?.());
+            const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots, undefined, seatForCall(writeDeny, ctx.toolCallId), writeFace?.());
             if (!r.ok)
                 return errorResult(violationText("Edit", r.violation), violationDetails(r.violation));
             if (!batch && a.old_string === a.new_string) {
@@ -344,7 +345,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, writeDeny, writeFace?.());
+            const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots, undefined, seatForCall(writeDeny, ctx.toolCallId), writeFace?.());
             if (!r.ok)
                 return { ok: true };
             const exists = await env.exists(r.key, ctx.signal);
@@ -363,7 +364,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, writeDeny, writeFace?.());
+            const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots, undefined, seatForCall(writeDeny, ctx.toolCallId), writeFace?.());
             if (!r.ok)
                 return errorResult(violationText("Write", r.violation), violationDetails(r.violation));
             const exists = await env.exists(r.key, ctx.signal);
@@ -460,7 +461,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, writeDeny, writeFace?.());
+            const r = await resolveKey(env, rootCanonical, a.notebook_path, ctx.signal, cwdRef?.current, additionalRoots, undefined, seatForCall(writeDeny, ctx.toolCallId), writeFace?.());
             if (!r.ok)
                 return { ok: true };
             const notRead = requireRead(state, r.key);
@@ -480,7 +481,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, writeDeny, writeFace?.());
+            const r = await resolveKey(env, rootCanonical, notebook_path, ctx.signal, cwdRef?.current, additionalRoots, undefined, seatForCall(writeDeny, ctx.toolCallId), 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

@@ -57,7 +57,7 @@ export interface HandsToolkitOptions {
      *  (`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
+     *  Glob / RepoMap: 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
@@ -245,6 +245,12 @@ export interface HandsToolkitOptions {
      *  mount may pass its own object or omit it (counting off — and the whole disclosure pipeline
      *  is off anyway when `reminderMark` is absent). */
     reminderDisclosureCounts?: import("../../core/reminder-disclosure.js").ReminderDisclosureCounts;
+    /** Where the band hands out the leg's ONE file reader — the reader its Read tool reads through, with the same read
+     *  state, throttle windows and counters — for the run's other carriers of a file to the model (a user's attachment).
+     *  Written once at mount; absent ⇒ the reader stays the Read tool's own. */
+    modelFileReaderSeat?: {
+        current?: import("./fs-read.js").ModelFileReader;
+    };
 }
 /** Whether the band's WRITE half (Edit / Write / NotebookEdit, and the full `bash`) mounts for these options — the ONE
  *  predicate {@link createHandsToolkit} branches on and prepare-task plans by (the memory phase must know, before the

package/dist/tools/fs/index.js

@@ -16,11 +16,11 @@ import { BASH_READONLY_DEFAULT_ALLOW } from "./bash-readonly-classifier.js";
 export { BASH_CLASSIFY_EXTRA_ALLOW, bashClassifyDefaultAllow } from "./bash-readonly-classifier.js";
 import { checkedReadDenyHomes, compileReadDeny, compileWriteDeny, isRootedReadDenyPattern, readDenyBuiltinConfigOf, readDenyPatternRun } from "./read-deny.js";
 import { withGateTimeout } from "../../core/gate-bounded-await.js";
-import { carryHomeViews, homeViewsAt, placeReadDenyAtHome, placementViewsOf, readDenyPlacedLater, sayPlacementLost } from "./read-deny-home.js";
+import { carriedReadFaceOf, carryHomeViews, homeViewsAt, placeReadDenyAtHome, placementViewsOf, readDenyPlacedLater, sayPlacementLost } from "./read-deny-home.js";
 import { deploymentFaceClampNotice, resolveContainmentFace } from "./containment-face.js";
 export * from "./containment-face.js";
 import {} from "./fs-shared.js";
-import { createReadFileTool } from "./fs-read.js";
+import { createModelFileReader, createReadFileTool } from "./fs-read.js";
 import { createEditFileTool, createWriteFileTool, createNotebookEditTool } from "./fs-write.js";
 import { createGrepTool, createGlobTool } from "./fs-search-tools.js";
 import { createBashTool, createBashReadonlyTool, createEnvTaskOutputTool, createEnvTaskStopTool } from "./fs-bash.js";
@@ -34,42 +34,15 @@ export function backgroundOutputReadExemption(registry, seat, 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 carriedFace = opts.readDenyHomes !== undefined ? carriedReadFaceOf(opts.readDenyHomes) : undefined;
+    const readFaceRoots = carriedFace?.readRoots ?? (additionalReadRoots === undefined ? additionalRoots : () => (additionalReadRoots.length === 0 ? additionalRoots : [...(additionalRoots ?? []), ...additionalReadRoots]));
     const cwdRef = opts.cwdRef ?? { current: rootCanonical };
     const bgOutput = backgroundOutputReadExemption(opts.taskRegistry, opts, env);
     const readAdmission = opts.readAdmission;
     const bgOutputReadExemption = bgOutput === undefined && readAdmission === undefined
         ? undefined
         : (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 carriedViews = carried ? placementViewsOf(opts.readDenyHomes) : undefined;
-    if (carried && carriedViews === undefined)
-        sayPlacementLost();
-    const placesNothing = !unplaced.entries.some((e) => readDenyPatternRun(e.pattern).homeAnchored || isRootedReadDenyPattern(e.pattern));
-    const late = carried || placesNothing ? undefined : readDenyPlacedLater(carryHomeViews(unplaced, homeViewsAt(env, [])), () => placeReadDenyAtHome(env, compileAt, readDenyHomes));
-    const readDeny = late?.matcher ??
-        (carried
-            ? carriedViews !== undefined
-                ? carryHomeViews(compileAt(readDenyHomes, opts.readDenyHomeLinks), carriedViews)
-                : carryHomeViews(unplaced, homeViewsAt(env, []))
-            : carryHomeViews(unplaced, homeViewsAt(env, readDenyHomes ?? [])));
-    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 ? carryHomeViews(writeDenyCompiled, readDeny.homeViews) : undefined;
+    const { readDeny, writeDeny, afterPlacement } = carriedFace !== undefined ? { readDeny: carriedFace.readDeny, writeDeny: carriedFace.writeDeny, afterPlacement: (tool) => tool } : bandOwnTables(env, opts);
     const readFace = resolveContainmentFace({
         kind: "read",
         depsFace: opts.readFace,
@@ -87,13 +60,30 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
         onDeploymentClamp: () => deliverEngineNotice(opts.onNotice, deploymentFaceClampNotice("write")),
     });
     const writeFaceOf = opts.writeFaceLive ?? (() => writeFace);
+    const readCwd = readOnly ? undefined : cwdRef;
+    const reader = createModelFileReader({
+        env,
+        state: readFileState,
+        rootCanonical,
+        ...(readCwd !== undefined ? { cwdRef: readCwd } : {}),
+        ...(readFaceRoots !== undefined ? { additionalRoots: readFaceRoots } : {}),
+        imageDownsampler: opts.readImageDownsampler,
+        ...(opts.pdfModelCapabilities !== undefined ? { pdfCapabilities: opts.pdfModelCapabilities } : {}),
+        ...(bgOutputReadExemption !== undefined ? { bgOutputReadExemption } : {}),
+        ...(readDeny !== undefined ? { readDeny } : {}),
+        ...(readFace !== undefined ? { readFace } : {}),
+        ...(opts.reminderMark !== undefined ? { reminderMark: opts.reminderMark } : {}),
+        ...(opts.reminderDisclosureCounts !== undefined ? { reminderDisclosureCounts: opts.reminderDisclosureCounts } : {}),
+    });
+    if (opts.modelFileReaderSeat !== undefined)
+        opts.modelFileReaderSeat.current = reader;
     const tools = [
-        afterPlacement(createReadFileTool(env, readFileState, rootCanonical, readOnly ? undefined : cwdRef, readFaceRoots, opts.readImageDownsampler, opts.pdfModelCapabilities, bgOutputReadExemption, readDeny, readFace, opts.reminderMark, opts.reminderDisclosureCounts)),
+        afterPlacement(createReadFileTool(env, readFileState, rootCanonical, readCwd, readFaceRoots, opts.readImageDownsampler, opts.pdfModelCapabilities, bgOutputReadExemption, readDeny, readFace, opts.reminderMark, opts.reminderDisclosureCounts, reader)),
     ];
     if (handsWriteHalfMounts({ readOnly })) {
         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(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)));
+    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, cwdRef, readAdmission)));
     if (includeShell) {
         tools.push(readOnly
             ? createBashReadonlyTool(env, rootCanonical, new Set(bashReadonlyAllow ?? BASH_READONLY_DEFAULT_ALLOW), {
@@ -141,3 +131,35 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
     }
     return tools;
 }
+function bandOwnTables(env, opts) {
+    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 carriedViews = carried ? placementViewsOf(opts.readDenyHomes) : undefined;
+    if (carried && carriedViews === undefined)
+        sayPlacementLost();
+    const placesNothing = !unplaced.entries.some((e) => readDenyPatternRun(e.pattern).homeAnchored || isRootedReadDenyPattern(e.pattern));
+    const late = carried || placesNothing ? undefined : readDenyPlacedLater(carryHomeViews(unplaced, homeViewsAt(env, [])), () => placeReadDenyAtHome(env, compileAt, readDenyHomes));
+    const readDeny = late?.matcher ??
+        (carried
+            ? carriedViews !== undefined
+                ? carryHomeViews(compileAt(readDenyHomes, opts.readDenyHomeLinks), carriedViews)
+                : carryHomeViews(unplaced, homeViewsAt(env, []))
+            : carryHomeViews(unplaced, homeViewsAt(env, readDenyHomes ?? [])));
+    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 ? carryHomeViews(writeDenyCompiled, readDeny.homeViews) : undefined;
+    return { readDeny, writeDeny, afterPlacement };
+}

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

@@ -1,6 +1,6 @@
 import type { ExecutionEnv } from "../../internal/harness-types.js";
 import { type PathFamily } from "./safety.js";
-import { type ReadDenyMatcher } from "./read-deny.js";
+import { type ReadDenyMatcher, type WriteDenyMatcher } from "./read-deny.js";
 /** The one bound every probe of an AUXILIARY home shares within one placement (see the module head): long enough for a
  *  local directory's canonical spelling, its chain of identities and its rows' heads, short enough that a hung home
  *  costs a placement seconds, not the gate's bound. */
@@ -116,11 +116,29 @@ export interface HomeViewsCarrier {
 export type PlacedReadDenyMatcher = ReadDenyMatcher & {
     readonly homeViews: HomeViewSource;
 };
+/** The Runner's read face as its tool band takes it: the run's read and write deny tables — each judgment reads the run's
+ *  latest, `forCall` hands a call its own — and the read face's root set, read per judgment (a call's own through
+ *  `forCall`). A band handed one judges with it and compiles no table of its own. */
+export interface CarriedReadFace {
+    readonly readDeny: PlacedReadDenyMatcher;
+    readonly writeDeny: WriteDenyMatcher & {
+        readonly homeViews: HomeViewSource;
+    };
+    readonly readRoots: () => readonly string[];
+}
 /** The views of the placement that returned `homes` — the very list object, as the engine hands it on (the Runner's
  *  tool band). `undefined` for any other list: a copy, or a host's own. A mount that was handed the engine's placement
  *  and cannot find its views has lost it: an engine defect, which the mount names ({@link sayPlacementLost}) and answers
  *  by holding its home-anchored rows at every location — never by reading the homes a second time. */
 export declare function placementViewsOf(homes: readonly string[]): HomeViewSource | undefined;
+/** The run's read face a home list carries ({@link carryReadFace}); `undefined` for any other list. */
+export declare function carriedReadFaceOf(homes: readonly string[]): CarriedReadFace | undefined;
+/** A home list (a fresh frozen copy of `homes`) that hands the Runner's read face to its band: the band judges with the
+ *  face's tables and roots instead of compiling its own from the rows it is handed. */
+export declare function carryReadFace(homes: readonly string[], face: CarriedReadFace): readonly string[];
+/** A judge that reads `current` at every judgment — the table a placement in flight will replace, or the run's tables of
+ *  which each judgment takes the latest — with the home views `homeViews` (default: the current judge's). */
+export declare function readDenyOver(current: () => PlacedReadDenyMatcher, homeViews?: HomeViewSource): PlacedReadDenyMatcher;
 /** The line a mount says when the engine handed it a home list that is not its placement's (an engine defect, said every
  *  time: no latch). */
 export declare function sayPlacementLost(): void;

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

@@ -348,11 +348,40 @@ function homeViewSourceOver(env, auxiliary) {
 const PLACEMENT_VIEWS = new WeakMap();
 function placementOf(matcher, homes, linked, whole) {
     const list = Object.freeze([...homes]);
-    PLACEMENT_VIEWS.set(list, matcher.homeViews);
+    PLACEMENT_VIEWS.set(list, { views: matcher.homeViews });
     return { matcher, homes: list, linked, whole };
 }
 export function placementViewsOf(homes) {
-    return PLACEMENT_VIEWS.get(homes);
+    return PLACEMENT_VIEWS.get(homes)?.views;
+}
+export function carriedReadFaceOf(homes) {
+    return PLACEMENT_VIEWS.get(homes)?.face;
+}
+export function carryReadFace(homes, face) {
+    const list = Object.freeze([...homes]);
+    PLACEMENT_VIEWS.set(list, { views: face.readDeny.homeViews, face });
+    return list;
+}
+export function readDenyOver(current, homeViews) {
+    return {
+        get entries() {
+            return current().entries;
+        },
+        get ruleRows() {
+            return current().ruleRows;
+        },
+        matchPath: (path, opts) => current().matchPath(path, opts),
+        matchTarget: (canonicalKey, lexicalView, opts) => current().matchTarget(canonicalKey, lexicalView, opts),
+        get rgExclusionGlobs() {
+            return current().rgExclusionGlobs;
+        },
+        get rgProbeGlobs() {
+            return current().rgProbeGlobs;
+        },
+        unexcludableUnder: (scope) => current().unexcludableUnder?.(scope) ?? false,
+        rowAtOrBelow: (path) => current().rowAtOrBelow?.(path) ?? null,
+        homeViews: homeViews ?? { views: (signal) => current().homeViews.views(signal) },
+    };
 }
 export function sayPlacementLost() {
     try {
@@ -447,24 +476,5 @@ export function readDenyPlacedLater(unplaced, place) {
             };
         },
     };
-    const matcher = {
-        get entries() {
-            return current.entries;
-        },
-        get ruleRows() {
-            return current.ruleRows;
-        },
-        matchPath: (path, opts) => current.matchPath(path, opts),
-        matchTarget: (canonicalKey, lexicalView, opts) => current.matchTarget(canonicalKey, lexicalView, opts),
-        get rgExclusionGlobs() {
-            return current.rgExclusionGlobs;
-        },
-        get rgProbeGlobs() {
-            return current.rgProbeGlobs;
-        },
-        unexcludableUnder: (scope) => current.unexcludableUnder?.(scope) ?? false,
-        rowAtOrBelow: (path) => current.rowAtOrBelow?.(path) ?? null,
-        homeViews,
-    };
-    return { matcher, ready };
+    return { matcher: readDenyOver(() => current, homeViews), ready };
 }

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

@@ -142,6 +142,8 @@ export interface WriteDenyMatcher {
         readonly aliasResolved?: boolean;
         readonly hops?: readonly string[];
     }): ReadDenyHit | null;
+    /** The table ONE call judges with ({@link ReadDenyMatcher.forCall}). */
+    forCall?(toolCallId: string | undefined): WriteDenyMatcher;
 }
 /** Compile the write face over the rule rows (the rows not on it are dropped here, once). */
 export declare function compileWriteDeny(rules?: readonly PathRuleDenyRow[]): WriteDenyMatcher;
@@ -197,7 +199,19 @@ export interface ReadDenyMatcher {
      *  path from its own segments ({@link rowMeetsPath}) — so moving, copying or removing the path changes what the row
      *  covers. A rule row's reach below a path is not enumerable: any rule row answers. */
     rowAtOrBelow?(path: string): ReadDenyHit | null;
+    /** The table ONE call judges with — the Runner's tables are one per read of the person's rules, and a call judges with
+     *  the read it was pinned to (an unknown or released call: the run's latest). Absent on a table compiled once: it is
+     *  every call's ({@link seatForCall}). */
+    forCall?(toolCallId: string | undefined): ReadDenyMatcher;
 }
+/** A seat the run's tables back — a deny table, a read-root set — as ONE call takes it: the call's own where the seat
+ *  carries `forCall`, the seat itself otherwise (a table compiled once, a host's own list) and for a reader that is no
+ *  call (no id: the seat's own reading of the run's latest, with every refusal it carries). Taken once, where the call's
+ *  judgment starts, so every judgment of the call reads one table. */
+export declare function seatForCall<T>(seat: T, toolCallId: string | undefined): T;
+/** Settles once the tables a seat the run's tables back stands on are ready for a reader that is no call (the seat's
+ *  `ready`); any other seat is ready. Never rejects. */
+export declare function seatReady(seat: unknown, signal?: AbortSignal): Promise<void>;
 /** The DENY HALF of a shell read boundary, in the shape `BashReadonlyRootBoundary` declares it (structural:
  *  this module is the leaf every face depends on). `denyMatch` judges one LEXICALLY RESOLVED operand,
  *  returning the matched pattern or null; PRESENT-IFF there is something to judge. */

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

@@ -153,6 +153,14 @@ export function compileWriteDeny(rules = []) {
     };
     return { face: "write", ruleRows, matchPath, matchTarget: (canonicalKey, lexicalView, opts) => denyTableHit(rows, denyTargetViews(canonicalKey, lexicalView, opts)) };
 }
+export function seatForCall(seat, toolCallId) {
+    const forCall = seat?.forCall;
+    return typeof forCall === "function" && toolCallId !== undefined ? forCall.call(seat, toolCallId) : seat;
+}
+export function seatReady(seat, signal) {
+    const ready = seat?.ready;
+    return typeof ready === "function" ? Promise.resolve(ready.call(seat, signal)) : Promise.resolve();
+}
 export function readDenySeat(matcher) {
     const entries = [...(matcher?.entries ?? []).map((e) => e.pattern), ...(matcher?.ruleRows ?? []).map((r) => r.rule)];
     if (matcher === undefined || entries.length === 0)