@sema-agent/core 7.49.4 → 7.50.0

package/dist/internal/llm.js

@@ -1 +1 @@
-export { createAssistantMessageEventStream, ensureToolTurnInvariants, MODEL_OUTPUT_INVALID_CAUSES, snapshotActorAssertion, stampStreamDrops, streamDropsOf, stripEngineMetadata, TOOL_TURN_INCOMPLETE_CAUSES, TOOL_TURN_REPAIR_DROPS } from "../engine/llm/index.js";
+export { createAssistantMessageEventStream, DATA_LABEL_UNSAFE, ensureToolTurnInvariants, isTextBlock, MODEL_OUTPUT_INVALID_CAUSES, quoteDataLabel, renderContentBlock, renderUserAttachmentView, snapshotActorAssertion, stampStreamDrops, streamDropsOf, stripEngineMetadata, TOOL_TURN_INCOMPLETE_CAUSES, TOOL_TURN_REPAIR_DROPS, userAttachmentOf } from "../engine/llm/index.js";

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/stores/file/permission-rule-store.d.ts

@@ -113,15 +113,23 @@ export type RuleAdoptionFile = {
 export declare function readRuleAdoptionFile(dir: string): RuleAdoptionFile | undefined;
 /** Atomically publish the adoption marker (same write-temp → fsync → rename discipline as the store). */
 export declare function writeRuleAdoptionFile(dir: string, content: RuleAdoptionFile): void;
+/** What a directory vetting reads from its host. Absent ⇒ this process's platform, and a skipped judgment goes unsaid. */
+interface DirVetting {
+    /** The platform whose permission bits are read (default: this process's — see {@link posixModeBitsMeaningful}). */
+    readonly platform?: NodeJS.Platform;
+    /** Said when the group/other-writable judgment was NOT made because the platform reports no permission bits. */
+    readonly modeBitsUnjudged?: (dir: string) => void;
+}
 /** One principal's rule file. */
 declare class FileDurableRulePartition implements WritableDurableRulePartition {
     private readonly dir;
     private readonly file;
     private readonly acquireWriteLock;
     private readonly onError?;
+    private readonly vetting?;
     readonly durability: StoreDurability;
     readonly fidelity: StoreFidelity;
-    constructor(dir: string, file: string, acquireWriteLock: () => void, onError?: ((message: string) => void) | undefined);
+    constructor(dir: string, file: string, acquireWriteLock: () => void, onError?: ((message: string) => void) | undefined, vetting?: DirVetting | undefined);
     /** Read and validate. Any refusal answers with an empty set AND says so — never a silent empty store. The answer's
      *  sentence names no location ({@link refusalText}); the disclosure that accompanies it does. */
     private read;
@@ -198,9 +206,13 @@ export declare class FileDurableRulePartitionProvider implements DurableRulePart
     private readonly onError?;
     private lock;
     private orgPersistence;
+    /** What every directory vetting of this instance reads; it says an unjudged mode check ONCE per instance. */
+    private readonly vetting;
     constructor(dir: string, onError?: ((message: string) => void) | undefined, opts?: {
         /** The data root whose adoption marker gates construction (design/183 I6). Absent ⇒ no root gate. */
         dataRoot?: string;
+        /** The platform whose permission bits the directory vetting reads. Absent ⇒ this process's platform. */
+        platform?: NodeJS.Platform;
     });
     /** The org partition's durable home in this directory (design/182 §7.4 contract; `org.json`). Shares
      *  this provider's writer lock — an install is a write. */

package/dist/stores/file/permission-rule-store.js

@@ -2,6 +2,7 @@ import { closeSync, constants as FS, existsSync, fsyncSync, lstatSync, mkdirSync
 import { join } from "node:path";
 import { createHash, randomBytes } from "node:crypto";
 import { isRuleBehavior } from "../../core/permission-rule-model.js";
+import { posixModeBitsMeaningful } from "../../core/posix-mode-face.js";
 import { PERMISSION_RULE_WRITER, applySyncJoin, applyTombstones, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, assertWriteDeltaScopeDurable, foldDelta, unknownRuleWriteDeltaError, } from "../../core/permission-rule-store.js";
 import { canonicalize } from "../../core/canonical-json.js";
 import { BootLock, FileStoreLockError } from "./fs-atomic.js";
@@ -118,13 +119,17 @@ const EMPTY_READ = { rules: [], tombstones: [], rev: 0 };
 function checksumOf(body) {
     return `sha256:${createHash("sha256").update(canonicalize(body), "utf8").digest("hex")}`;
 }
-function unsafeDirFault(dir) {
+function unsafeDirFault(dir, vetting) {
     mkdirSync(dir, { recursive: true, mode: 0o700 });
     const st = lstatSync(dir);
     if (st.isSymbolicLink() || !st.isDirectory())
         return "is a symlink or not a directory";
     if (typeof process.getuid === "function" && st.uid !== process.getuid())
         return "is owned by another user";
+    if (!posixModeBitsMeaningful(vetting?.platform)) {
+        vetting?.modeBitsUnjudged?.(dir);
+        return undefined;
+    }
     if ((st.mode & 0o022) !== 0)
         return `is writable by group or others (mode ${(st.mode & 0o777).toString(8)}) — anyone who can write there can grant themselves permissions`;
     return undefined;
@@ -135,15 +140,18 @@ function assertSafeDir(dir) {
         throw new Error(`permission-rule store directory ${dir} ${fault}; refusing to use it`);
 }
 function refusalText(onError, sentence, location) {
+    discloseTo(onError, `${sentence} (at ${location})`);
+    return `${sentence}. The location is reported to the store's error disclosure (onError), not in this message.`;
+}
+function discloseTo(onError, message) {
     try {
-        onError?.(`${sentence} (at ${location})`);
+        onError?.(message);
     }
     catch {
     }
-    return `${sentence}. The location is reported to the store's error disclosure (onError), not in this message.`;
 }
-function assertSafeDirAtRequest(dir, onError, act) {
-    const fault = unsafeDirFault(dir);
+function assertSafeDirAtRequest(dir, onError, act, vetting) {
+    const fault = unsafeDirFault(dir, vetting);
     if (fault !== undefined)
         throw new Error(refusalText(onError, `the permission-rule store directory ${fault}; refusing to ${act} it`, dir));
 }
@@ -171,13 +179,15 @@ class FileDurableRulePartition {
     file;
     acquireWriteLock;
     onError;
+    vetting;
     durability = "durable";
     fidelity = "json";
-    constructor(dir, file, acquireWriteLock, onError) {
+    constructor(dir, file, acquireWriteLock, onError, vetting) {
         this.dir = dir;
         this.file = file;
         this.acquireWriteLock = acquireWriteLock;
         this.onError = onError;
+        this.vetting = vetting;
     }
     read() {
         const bucket = "this owner's permission-rule bucket";
@@ -185,7 +195,7 @@ class FileDurableRulePartition {
         const unreadable = (sentence, location = this.file) => ({ unreadable: refusalText(this.onError, sentence, location) });
         let raw;
         try {
-            const dirFault = unsafeDirFault(this.dir);
+            const dirFault = unsafeDirFault(this.dir, this.vetting);
             if (dirFault !== undefined)
                 return unreadable(`the permission-rule store directory ${dirFault}; loading zero rules`, this.dir);
             const st = lstatSync(this.file);
@@ -228,11 +238,7 @@ class FileDurableRulePartition {
         return { file: parsed };
     }
     disclose(message) {
-        try {
-            this.onError?.(message);
-        }
-        catch {
-        }
+        discloseTo(this.onError, message);
     }
     screenDurableRows(file) {
         const isSession = (scope) => scope?.kind === "session";
@@ -246,7 +252,7 @@ class FileDurableRulePartition {
         return { rules, tombstones, quarantined };
     }
     write(next) {
-        assertSafeDirAtRequest(this.dir, this.onError, "write through");
+        assertSafeDirAtRequest(this.dir, this.onError, "write through", this.vetting);
         atomicPublish(this.dir, this.file, JSON.stringify({ ...next, checksum: checksumOf(next) }, null, 2));
     }
     async list() {
@@ -392,11 +398,22 @@ export class FileDurableRulePartitionProvider {
     onError;
     lock;
     orgPersistence;
+    vetting;
     constructor(dir, onError, opts) {
         this.dir = dir;
         this.onError = onError;
         if (opts?.dataRoot !== undefined)
             assertAdoptionBootGate(opts.dataRoot, "FileDurableRulePartitionProvider");
+        let said = false;
+        this.vetting = {
+            platform: opts?.platform,
+            modeBitsUnjudged: (where) => {
+                if (said)
+                    return;
+                said = true;
+                discloseTo(this.onError, `the permission-rule store directory is not checked for being writable by other accounts: this platform reports no POSIX permission bits, so who else can write there is not verified here (at ${where})`);
+            },
+        };
     }
     adoptionMarker() {
         const judged = judgeRuleAdoptionFile(this.dir);
@@ -410,13 +427,13 @@ export class FileDurableRulePartitionProvider {
         return this.fileOrgPersistence();
     }
     fileOrgPersistence() {
-        this.orgPersistence ??= new FileOrgRuleStatePersistence(this.dir, this.acquireWriteLock, this.onError);
+        this.orgPersistence ??= new FileOrgRuleStatePersistence(this.dir, this.acquireWriteLock, this.onError, this.vetting);
         return this.orgPersistence;
     }
     acquireWriteLock = () => {
         if (this.lock !== undefined)
             return;
-        assertSafeDirAtRequest(this.dir, this.onError, "write through");
+        assertSafeDirAtRequest(this.dir, this.onError, "write through", this.vetting);
         const lock = new BootLock(join(this.dir, "PERMISSION-RULES-WRITER-LOCK"));
         try {
             lock.acquire();
@@ -437,11 +454,11 @@ export class FileDurableRulePartitionProvider {
                 return this.readOnlySourceView(principalRuleFileName(principal), principalRuleFileName(rec.toPrincipal), "adopted" in adoption || adoption.marker.phase >= 4);
             }
         }
-        return new FileDurableRulePartition(this.dir, join(this.dir, principalRuleFileName(principal)), this.acquireWriteLock, this.onError);
+        return new FileDurableRulePartition(this.dir, join(this.dir, principalRuleFileName(principal)), this.acquireWriteLock, this.onError, this.vetting);
     }
     readOnlySourceView(sourceName, targetName, flipped) {
         const pick = flipped ? targetName : existsSync(join(this.dir, sourceName)) ? sourceName : targetName;
-        return readOnlyRuleStoreView(new FileDurableRulePartition(this.dir, join(this.dir, pick), this.acquireWriteLock, this.onError));
+        return readOnlyRuleStoreView(new FileDurableRulePartition(this.dir, join(this.dir, pick), this.acquireWriteLock, this.onError, this.vetting));
     }
     forLocalOwner() {
         const adoption = this.adoptionMarker();
@@ -451,7 +468,7 @@ export class FileDurableRulePartitionProvider {
                 return this.readOnlySourceView(LOCAL_OWNER_FILE, principalRuleFileName(rec.toPrincipal), "adopted" in adoption || adoption.marker.phase >= 4);
             }
         }
-        return new FileDurableRulePartition(this.dir, join(this.dir, LOCAL_OWNER_FILE), this.acquireWriteLock, this.onError);
+        return new FileDurableRulePartition(this.dir, join(this.dir, LOCAL_OWNER_FILE), this.acquireWriteLock, this.onError, this.vetting);
     }
     dispose() {
         this.lock?.release();
@@ -462,12 +479,14 @@ class FileOrgRuleStatePersistence {
     dir;
     acquireWriteLock;
     onError;
+    vetting;
     file;
     writeChain = Promise.resolve();
-    constructor(dir, acquireWriteLock, onError) {
+    constructor(dir, acquireWriteLock, onError, vetting) {
         this.dir = dir;
         this.acquireWriteLock = acquireWriteLock;
         this.onError = onError;
+        this.vetting = vetting;
         this.file = join(dir, ORG_STATE_FILE);
     }
     readSync() {
@@ -477,7 +496,7 @@ class FileOrgRuleStatePersistence {
         const ioFault = (err) => `could not be read (${err?.code ?? err?.name ?? "unknown"})`;
         let dirFault;
         try {
-            dirFault = unsafeDirFault(this.dir);
+            dirFault = unsafeDirFault(this.dir, this.vetting);
         }
         catch (err) {
             return refuse(`the permission-rule store directory ${ioFault(err)}`, `${this.dir}: ${thrownText(err)}`);
@@ -524,7 +543,7 @@ class FileOrgRuleStatePersistence {
     }
     installOrgStateSync(state) {
         this.acquireWriteLock();
-        assertSafeDirAtRequest(this.dir, this.onError, "write through");
+        assertSafeDirAtRequest(this.dir, this.onError, "write through", this.vetting);
         state = jsonForm(state);
         const cur = this.readSync();
         if (cur !== undefined && state.revisionHighWater < cur.revisionHighWater) {

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;