@sema-agent/core 7.49.5 → 7.50.0

package/dist/orchestration/workflow.d.ts

@@ -436,11 +436,10 @@ export interface RunWorkflowOptions {
     parentCwd?: string;
     /**
      * The SPAWNING tool call's id (`run_workflow`'s own `ToolExecuteContext.toolCallId`) — threaded into every
-     * spawned agent's trusted internals (`RunInternals.parentToolCallId`) so each child runs AS a sub-agent:
-     * its per-turn `task_progress` ticks actually EMIT (the runner gates them on `parentToolCallId`) and carry
-     * this id for attribution, the same contract as a `createSubagentTool` delegation. Set by the `run_workflow`
-     * tool wiring; a directly-started workflow (no launching tool call) leaves it unset — children then emit no
-     * progress ticks (status quo), and no id is ever fabricated.
+     * spawned agent's trusted internals (`RunInternals.parentToolCallId`) so each child's frames carry this id
+     * for attribution, the same contract as a `createSubagentTool` delegation. Set by the `run_workflow` tool
+     * wiring; a directly-started workflow (no launching tool call) leaves it unset — its children's row frames
+     * (start, ticks, terminal tick) still go out, without the attribution, and no id is ever fabricated.
      */
     parentToolCallId?: string;
     /** The HOST task's taskId — threaded as every spawned agent's `RunInternals.parentTaskId` so its

package/dist/orchestration/workflow.js

@@ -1648,7 +1648,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 const runSpec = await reviewSpawnBeforeLaunch("ctx.agent", label, callKey, preReviewSpec, effectiveSignal);
                 const enrichedForward = opts.onForwardEvent !== undefined
                     ? (e) => {
-                        opts.onForwardEvent(e.type === "task_progress" ? { ...e, workflowRunId: runId, workflowAgentLabel: label } : e);
+                        opts.onForwardEvent(e.type === "task_progress" || e.type === "task_started" ? { ...e, workflowRunId: runId, workflowAgentLabel: label } : e);
                     }
                     : undefined;
                 const baseInternals = { ...(agentOpts.isolation ? { isolation: agentOpts.isolation } : {}), ...(opts.parentCwd !== undefined ? { parentCwd: opts.parentCwd, callerRoot: opts.parentCwd } : {}), ...spawnAttribution, ...(await captureFloorSeatsNow()), ...(enrichedForward !== undefined ? { onForwardEvent: enrichedForward } : {}), delegationTaskType: "workflow", agentName: label, onWorkspaceResolved: createWorkspaceObserver(rec) };
@@ -2013,7 +2013,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 const runSpec = await reviewSpawnBeforeLaunch("ctx.agentStream", label, callKey, preReviewSpec, effectiveSignal);
                 const enrichedForwardS = opts.onForwardEvent !== undefined
                     ? (e) => {
-                        opts.onForwardEvent(e.type === "task_progress" ? { ...e, workflowRunId: runId, workflowAgentLabel: label } : e);
+                        opts.onForwardEvent(e.type === "task_progress" || e.type === "task_started" ? { ...e, workflowRunId: runId, workflowAgentLabel: label } : e);
                     }
                     : undefined;
                 const runInternals = {

package/dist/prompts/default.d.ts

@@ -255,7 +255,7 @@ export declare const PROJECT_CONTEXT_FRAMING = "# Project context\nThe `<user_me
  *    relation to the specific tool results or user messages in which they appear."
  *  - LEAN (`wMy` @596743, heading **`# Harness`**) → "`<system-reminder>` tags in messages and tool
  *    results are injected by the harness, not the user."
- *  - THIRD ARM (`itp`'s `otp(model)` short-circuit → `gMy` @597111 (cli250.js:44459)): "The system may send updates,
+ *  - THIRD ARM (`itp`'s `otp(model)` short-circuit → `gMy` @597111 (cli250.js:44486)): "The system may send updates,
  *    reminders, or modifications to rules via mid-conversation system turns. These are
  *    system-controlled, unlike function results." sema has NO counterpart and does not need one — the
  *    arm is selected by a per-model latch (`otp` @597208) over CC's own model registry, which a BYOM

package/dist/tools/artifact/artifact-tool.js

@@ -321,7 +321,7 @@ export function createArtifactTool(opts) {
         if (sharedReadApproved.has(url))
             return Promise.resolve({ ok: true });
         if (permissionMode !== undefined) {
-            const verdict = arbitrateByMode(permissionMode(), classifyAsk({ action: "ask", requiresRealApproval: true, guard: "artifact_shared_read" }, { contentQuestion: false, markedUnresolvable: false, org: undefined, tightened: undefined, mandateMarks: {} }));
+            const verdict = arbitrateByMode(permissionMode(), classifyAsk({ action: "ask", requiresRealApproval: true, guards: ["artifact_shared_read"] }, { contentQuestion: false, markedUnresolvable: false, org: undefined, tightened: undefined, mandateMarks: {} }));
             if (verdict.kind === "released") {
                 if (!releaseAnnounced && onNotice !== undefined) {
                     releaseAnnounced = true;

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

@@ -19,7 +19,7 @@ import { type ProgramRow } from "./program-read-model.js";
  * auto-allow an irreversible clock jump on the full shell face).
  *
  * Rows 3-4 are the CC-anchored expansion — the members of CC's safe-command
- * set (pretty223.js:420513-420565 `e6s`; identical in the 220 corpus; the 220→245 campaign diff records
+ * set (2.1.296 `v3e` (cli296.js:249645); `e6s` in the 223 corpus, identical in 220; the 220→245 campaign diff records
  * no change on this face) that satisfy THIS list's curation bar (no write/mutation mode under any args)
  * without new stdin-floor/option-value modeling: pure status/computation printers (`cal`…`sleep` — none
  * reads stdin when bare, none takes a path it READS except realpath/readlink, which stay boundary-judged)

package/dist/tools/fs/dir-entries.d.ts

@@ -22,7 +22,7 @@
  * judging was cut short by an abort — the listing is a prefix, not the directory).
  */
 import type { ExecutionEnv } from "../../internal/harness-types.js";
-import type { FileError, FileKind, Result } from "../../internal/harness.js";
+import type { FileError, FileInfo, FileKind, Result } from "../../internal/harness.js";
 import { type HomeViewEnv, type HomeViewsCarrier } from "./read-deny-home.js";
 /** The upstream at-mention's cap on listed entries. */
 export declare const DIRECTORY_LISTING_MAX_ENTRIES = 1000;
@@ -55,15 +55,9 @@ export interface DirectoryListing {
     /** An abort cut the judging short: `entries` / `more` / `omitted` describe a prefix of the directory. */
     incomplete: boolean;
 }
-/** List one level of `dir` (a canonical directory path). A listing the environment refuses is the error. */
-export declare function enumerateDirectory(env: ExecutionEnv, dir: string, judge: EntryDenyJudge | undefined, signal?: AbortSignal): Promise<Result<DirectoryListing, FileError>>;
-/**
- * A data label (a path, a file name) as a JSON string literal with every C0/C1 control, format character
- * and line / paragraph separator written as `\uXXXX` — lossless (JSON.parse gives the original back), and
- * one line whatever the name holds. JSON's own escaping alone leaves U+2028 / U+2029 / U+0085 and the
- * format characters raw.
- */
-export declare function quoteDataLabel(label: string): string;
+/** List one level of `dir` (a canonical directory path). A listing the environment refuses is the error. `list` is how the
+ *  entries are read (default: the environment's `listDir`; a carrier bound to a judged directory passes its bound listing). */
+export declare function enumerateDirectory(env: ExecutionEnv, dir: string, judge: EntryDenyJudge | undefined, signal?: AbortSignal, list?: (dir: string) => Promise<Result<FileInfo[], FileError>>): Promise<Result<DirectoryListing, FileError>>;
 /** The listing as text: one entry per line (a directory with a trailing "/"; a name that could break or
  *  hide in its line is written as {@link quoteDataLabel}), then "… and N more entries" when capped. */
 export declare function renderDirectoryListing(l: DirectoryListing): string;

package/dist/tools/fs/dir-entries.js

@@ -1,4 +1,5 @@
 import { homeViewsOf } from "./read-deny-home.js";
+import { DATA_LABEL_UNSAFE, quoteDataLabel } from "../../internal/llm.js";
 export const DIRECTORY_LISTING_MAX_ENTRIES = 1000;
 export function createEntryDenyJudge(env, deny, signal) {
     const views = homeViewsOf(env, deny, signal);
@@ -10,8 +11,8 @@ export function createEntryDenyJudge(env, deny, signal) {
         return view !== undefined ? deny.matchPath(view) : null;
     };
 }
-export async function enumerateDirectory(env, dir, judge, signal) {
-    const listing = await env.listDir(dir, signal);
+export async function enumerateDirectory(env, dir, judge, signal, list = (d) => env.listDir(d, signal)) {
+    const listing = await list(dir);
     if (!listing.ok)
         return listing;
     const infos = [...listing.value].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
@@ -44,16 +45,8 @@ export async function enumerateDirectory(env, dir, judge, signal) {
         },
     };
 }
-const LABEL_UNSAFE = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u;
-export function quoteDataLabel(label) {
-    let out = "";
-    for (const ch of JSON.stringify(label)) {
-        out += LABEL_UNSAFE.test(ch) ? `\\u${ch.codePointAt(0).toString(16).padStart(4, "0")}` : ch;
-    }
-    return out;
-}
 export function renderDirectoryListing(l) {
-    const lines = l.entries.map((e) => `${LABEL_UNSAFE.test(e.name) ? quoteDataLabel(e.name) : e.name}${e.kind === "directory" ? "/" : ""}`);
+    const lines = l.entries.map((e) => `${DATA_LABEL_UNSAFE.test(e.name) ? quoteDataLabel(e.name) : e.name}${e.kind === "directory" ? "/" : ""}`);
     if (l.more > 0)
         lines.push(`… and ${l.more} more entries`);
     return lines.join("\n");

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

@@ -1,6 +1,6 @@
 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 { fitMiddle, READ_DENY_SENTENCE_PART_MAX, seatForCall } from "./read-deny.js";
 import { resolveKey, violationDetails } from "./safety.js";
 import { readStationMemberOf } from "./shell-read-check.js";
 import { grantOfferFor, parentDirLexically } from "./shell-read-judge.js";
@@ -27,8 +27,8 @@ export function createFileReadStation(opts) {
                 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);
+                const extra = seatForCall(opts.roots, callOpts.toolCallId)();
+                const r = await resolveKey(opts.env, opts.rootCanonical, spelled, signal, selection.base, extra, undefined, seatForCall(opts.readDeny, callOpts.toolCallId), 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;

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

@@ -3,13 +3,14 @@ import { MCP_IMAGE_MAX_BASE64 } from "../../core/mcp.js";
 import { PDF_FALLBACK_RENDER_PAGES, PDF_INLINE_PAGE_THRESHOLD, PDF_MAX_EXTRACT_SIZE, PDF_MAX_PAGES_PER_READ, PDF_TARGET_RAW_SIZE, extractPdfPagesAsImages, extractPdfTextLayer, getPdfPageCount, parsePdfPageRange, pdfMagicMatches, } from "./pdf.js";
 import { resolveAutoDownsampler, enoentMessage, MAX_READ_BYTES } from "./fs-shared.js";
 import { planReminderDisclosure, renderReminderDisclosureTrailer } from "../../core/reminder-disclosure.js";
+import { MARKED_BLOCK_AFTER_DATA } from "../../core/reminder-mint.js";
 function pdfDisclosureTrailer(body, d) {
     if (d === undefined)
         return "";
     const plan = planReminderDisclosure({ segments: [body], mark: d.mark, outlet: "pdf", defuseExactMark: false, throttle: { key: d.key, windows: d.windows } });
     d.effects.push(plan.effects);
     const trailer = renderReminderDisclosureTrailer(plan.verdict, d.mark);
-    return trailer !== undefined ? `\n${trailer}` : "";
+    return trailer !== undefined ? `${MARKED_BLOCK_AFTER_DATA}${trailer}` : "";
 }
 export { pdfModelCapabilitiesOf } from "./pdf.js";
 async function pdfPagesToImageBlocks(pages, path, downsamplerOpt) {
@@ -47,9 +48,6 @@ export async function readPdfFile(env, path, key, pages, signal, downsamplerOpt,
             return `Error (Read): ${await enoentMessage(env, key, cwd, signal, readDeny)}`;
         return `Error (Read): cannot stat PDF "${path}" to verify its size before reading: ${meta.error.message}`;
     }
-    if (meta.value.kind === "directory") {
-        return `Error (Read): "${path}" is a directory, not a file; use glob/grep or list it with the shell.`;
-    }
     const size = preRead ? preRead.byteLength : meta.value.size;
     if (size > PDF_MAX_EXTRACT_SIZE) {
         return `Error (Read): PDF "${path}" exceeds the maximum size for PDF reading (${size} bytes > ${PDF_MAX_EXTRACT_SIZE}-byte / 100 MB cap).`;

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

@@ -7,6 +7,8 @@ import { type ImageDimensions } from "../../core/mcp.js";
 import { type PdfModelCapabilities } from "./pdf.js";
 import { type ReadImageDownsamplerOption, type CwdRef } from "./fs-shared.js";
 import { type ReminderDisclosureCounts, type ReminderDisclosureEffects, type ReminderDisclosureVerdict } from "../../core/reminder-disclosure.js";
+import { type DirectoryListing } from "./dir-entries.js";
+import { FileError, type BoundFileObject, type Result } from "../../internal/harness.js";
 /**
  * The Read tool, and the ONE read of a file for the model it is built on, split into three steps so every
  * carrier shares it:
@@ -42,8 +44,9 @@ import { type ReminderDisclosureCounts, type ReminderDisclosureEffects, type Rem
 export declare const READ_OUTCOMES: readonly ["attached", "partial", "unchanged", "not_attached"];
 export type ReadOutcome = (typeof READ_OUTCOMES)[number];
 /** The lane the read took. Absent on a refusal raised before the lane was known. A corrupt notebook served
- *  as raw text is `text` (with the `notebook_fallback` note). */
-export type ReadKind = "text" | "notebook" | "image" | "pdf";
+ *  as raw text is `text` (with the `notebook_fallback` note). `directory`: the path is a directory — judged in one
+ *  place, before the lanes; the Read tool refuses it, a carrier that lists directories reads the kind. */
+export type ReadKind = "text" | "notebook" | "image" | "pdf" | "directory";
 /** The engine's statements about one read, as data. The Read carrier's rendering is
  *  {@link renderReadNoteForTool}; the frame carrier renders the same members its own way. */
 export type ReadNote = {
@@ -105,6 +108,12 @@ export type ReadNote = {
  | {
     kind: "disclosure";
     verdict: ReminderDisclosureVerdict;
+}
+/** A PDF read as a reference only (a bound read, {@link ReadForModelOptions.bound}): its size and page count, when known. */
+ | {
+    kind: "pdf_reference";
+    bytes?: number;
+    pages?: number;
 };
 /** The read-state entry a delivery records, minus the delivery's own facts (when, which transmission). */
 export interface ReadObservation {
@@ -136,6 +145,17 @@ export interface ReadForModelContext {
     taskId?: string;
     principal?: string;
 }
+/** How a carrier other than the Read tool asks for the read. Absent members ⇒ exactly the Read tool's read. */
+export interface ReadForModelOptions {
+    /** A BOUND read: the canonical key the carrier resolved and the object it holds open there ({@link ModelFileReader.openBound}),
+     *  the one it had judged. A path that resolves to another key is refused; the kind, the size and every byte come from the
+     *  held object, never from the path. A PDF is a reference only: its size from the held object, its page count from its
+     *  bytes up to the whole-send size (`pdf_reference` note). */
+    bound?: {
+        key: string;
+        object: BoundFileObject;
+    };
+}
 export interface ModelFileReaderOptions {
     env: ExecutionEnv;
     state: ReadFileState;
@@ -159,7 +179,30 @@ export interface ModelFileReaderOptions {
     disclosureWindows?: Map<string, number>;
 }
 export interface ModelFileReader {
-    readForModel(args: unknown, ctx: ReadForModelContext): Promise<ReadForModelResult>;
+    readForModel(args: unknown, ctx: ReadForModelContext, opts?: ReadForModelOptions): Promise<ReadForModelResult>;
+    /** The path's resolution alone — the same step `readForModel` opens with (the read-deny table, the roots, the device
+     *  and UNC refusals): its canonical key, or the Read tool's refusal. */
+    resolveTarget(path: string, ctx: ReadForModelContext): Promise<{
+        ok: true;
+        key: string;
+    } | {
+        ok: false;
+        refusal: ReadRefusal;
+    }>;
+    /** Open the object at a resolved key and hold it, for a carrier that judges and then reads that same object (the
+     *  environment's `openBound`; an environment without it cannot bind, and the answer says so). The carrier closes it. */
+    openBound(key: string, signal?: AbortSignal): Promise<Result<BoundFileObject, FileError>>;
+    /** One level of a held directory, every entry through the walk's per-entry read-deny judge. */
+    listDirectory(bound: {
+        key: string;
+        object: BoundFileObject;
+    }, signal?: AbortSignal): Promise<Result<DirectoryListing, FileError>>;
+    /** Plan the disclosure over external text this reader did not read (the same pipeline, throttle windows and
+     *  counters); the effects commit with the result that carries them. */
+    planDisclosure(segments: string[], throttleKey: string): {
+        note?: ReadNote;
+        effects: ReminderDisclosureEffects;
+    };
     /** Apply the result's effects: the read-state entry (stamped `lastReadAt` and the transmission that
      *  carried it) and the disclosure windows / counters. Once per result: a second commit throws. */
     commit(result: ReadForModelResult, at?: {
@@ -178,4 +221,4 @@ export declare function createReadFileTool(env: ExecutionEnv, state: ReadFileSta
     taskId?: string;
     principal?: string;
     toolCallId?: string;
-}) => boolean, readDeny?: import("./read-deny.js").ReadDenyMatcher, readFace?: import("./containment-face.js").ContainmentFace, reminderMark?: string, reminderDisclosureCounts?: ReminderDisclosureCounts): AgentTool;
+}) => boolean, readDeny?: import("./read-deny.js").ReadDenyMatcher, readFace?: import("./containment-face.js").ContainmentFace, reminderMark?: string, reminderDisclosureCounts?: ReminderDisclosureCounts, sharedReader?: ModelFileReader): AgentTool;

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