@sema-agent/core 7.33.8 → 7.34.0

package/dist/core/tool-spec.d.ts

@@ -1113,7 +1113,7 @@ export interface ToolExecuteContext {
     /**
      * RB-201 FO-3 (form-one audit, CC 220 `Ipd`/`ein` parity) — the auto-mode classifier decider ARMED
      * for THIS task (auto-mode intent ∧ `RunnerDeps.autoMode` present ∧ `RuntimeCaps.autoMode !== false`
-     * — see {@link TaskSpec.autoModeRequested}; the same
+     * — see {@link TaskSpec.permissionMode}; the same
      * instance `runToolGate`'s per-call ask review already consults, carrying its own live breaker
      * state — not a fresh one built from raw config). Runner-filled, trusted, undefined when auto-mode
      * is not armed or the tool runs outside a Runner task.
@@ -1286,13 +1286,12 @@ export interface ToolExecuteContext {
      */
     requestStopAfterTurn?: () => void;
     /**
-     * design/108 — enter mid-run READ-ONLY plan mode: the rest of THIS run rejects write-effect tool calls
-     * (`effect !== "read"`), while read/research tools and `present_plan` still run. A run-local one-way flag
-     * (NOT durable — a later approve-resume re-prepares with it clear, so the approved plan can write). The
-     * first-party `enter_plan_mode` tool (CC `EnterPlanMode` parity) is the only caller; the engine enforces the
-     * read-only restriction in a dedicated plan-mode tool-call check (separate from the safety gate — plan mode
-     * is a FIDELITY mode, not a security boundary; the real safety gates apply independently). Idempotent; a
-     * no-op for tools that don't call it. The Runner fills it; not a tool arg. Absent outside a Runner.
+     * Enter plan mode mid-run: a steer of the leg's ONE permission-mode seat into `plan` — the same mode the spec's
+     * `permissionMode` and `TaskStream.setPermissionMode` set. For the rest of THIS run the mode gate asks before every
+     * covered write and every call to a tool the engine does not define that is not read-only (the plan sentence; refused
+     * where nobody can answer), while read tools and `ExitPlanMode` run. The word it left is recorded: an approve-resume
+     * returns to it; a rejected plan steers the resumed leg back into `plan`. The first-party `EnterPlanMode`
+     * tool is the only caller. Idempotent. The Runner fills it; not a tool arg. Absent outside a Runner.
      */
-    enterPlanMode?: () => void;
+    enterPlanMode?: () => Promise<void>;
 }

package/dist/core/trace.d.ts

@@ -253,11 +253,12 @@ export type TraceEvent = {
     taskId: string;
     /** Which spec field the skipped entry came from. Absent = `additionalDirectories` (the
      *  original face, kept implicit for existing readers); `"additionalReadDirectories"` = the
-     *  read-only whitelist arm (ruled 2026-08-05). */
-    field?: "additionalReadDirectories";
+     *  read-only whitelist arm (ruled 2026-08-05); `"persistedReadRule"` = a person's persisted `Read(//dir/**)` allow row. */
+    field?: "additionalReadDirectories" | "persistedReadRule";
     /** The spec entry as written (raw, not canonical — canonicalization is what failed). */
     entry: string;
-    /** The canonicalization failure, `code: message` form. */
+    /** Why the entry was skipped, `code: message` form: the canonicalization failure, or (a persisted row only)
+     *  `admits_artifact_store` — the in-flight grant's store rule. */
     reason: string;
     ts: number;
 } | {
@@ -442,9 +443,9 @@ export type TraceEvent = {
     ts: number;
 } | {
     /**
-     * design/179 — the persisted allow-rule store could not be read, so this call was adjudicated with
-     * ZERO rules (it asks, rather than silently behaving like an empty store). A loosening face that
-     * fails must say so.
+     * design/179 — the person's persisted rule store could not be read (at prepare, or for one call), so
+     * that read's rows took no part: the decision it served was made with ZERO persisted rows. The operator's
+     * per-read record; the person hears it once per run (`permission.rule_store_unavailable`).
      */
     kind: "permission.rule_store_unreadable";
     version: 1;

package/dist/core/types.d.ts

@@ -13,7 +13,8 @@ import type { AgentTool, ThinkingLevel, ToolInputValidationContext, ToolInputVer
 import type { Model, StreamFn } from "../internal/llm.js";
 export type { ModelRef, ModelRole, RoleSpec, ModelRoles, Brain } from "./model-seat.js";
 export { MODEL_ROLES } from "./model-seat.js";
-export type { StaleToolResultOffloadOptions, ImageInput, TaskSpec, ShellGateDoctrine, ApproverPosture } from "./task-spec.js";
+export type { StaleToolResultOffloadOptions, ImageInput, TaskSpec, ShellGateDoctrine } from "./task-spec.js";
+export type { PermissionMode } from "./ask-origin.js";
 export type { ToolEffect, ToolContentOrigin, ReversibilityVerdict, ReadRootGrantCandidate, ToolSpec, ToolReturn, NestedUsage, NestedUsageAccum, ToolExecuteContext } from "./tool-spec.js";
 export type { BeforeWriteRequest, BeforeWriteResult, BeforeWriteHook, TrackEditRequest, TrackEditResult, TrackFileEditHook, FileEditedNotice, FileEditedHook, HandsBandOptions } from "./hands-band.js";
 export type { AgentDefinition, SkillManifest, SkillSpec } from "./agent-definition.js";

package/dist/core/wiring-manifest.d.ts

@@ -64,8 +64,8 @@ export type ParkLaneReason = "no_checkpoint_store" | "no_durable_approval_opt_in
  * The closed set of auto-mode ARMING outcomes a leg's manifest reports
  * ({@link WiringManifest.autoMode}). Minted from the arming predicate's own three-arm read, as the
  * FIRST failing arm in predicate order:
- *  - `no_intent`      — no `TaskSpec.autoModeRequested` seat and no intent inherited on the chain /
- *                       recorded on the resumed checkpoint (a non-auto run; byte-identical arming).
+ *  - `no_intent`      — the declared permission mode is not `auto` (no `permissionMode: "auto"` seat, none
+ *                       inherited on the chain / recorded on the resumed checkpoint; a non-auto run).
  *  - `no_face`        — intent, but no `RunnerDeps.autoMode` deployment face (the trust gate).
  *  - `denied`         — intent + face, but the organization's deny bit (`RuntimeCaps.autoMode:false`)
  *                       as the resolver STATED it.
@@ -306,7 +306,8 @@ export interface WiringManifest {
      * classifier decider was minted for this leg), and `reason` names the first arm that failed
      * otherwise — see {@link AUTO_MODE_ARM_REASONS}. A serving layer that used to infer the mode from
      * spec shape reads it here instead. The classifier's availability is a per-CALL fact (an unavailable
-     * round is a deny that says so, and the next round is classified afresh), so there is no session-level
+     * round goes on to the approval seat or is refused with a sentence that says so, and the next round is
+     * classified afresh), so there is no session-level
      * breaker face here and nothing about availability enters {@link configFingerprint}.
      */
     autoMode?: AutoModeArmFact;
@@ -369,6 +370,17 @@ export interface WiringManifest {
         mounted: boolean;
         reason?: HandsUnmountedReason;
     };
+    /**
+     * EFFECTIVE half only, ALWAYS present on an engine-minted effective manifest: the leg's PERMISSION MODE as the engine
+     * resolved it — `requested` (the caller's word; absent = declared nothing), `effective` (the mode the leg runs under:
+     * the request clamped under a parent's ceiling, then folded to `default` where the deployment denies it or the
+     * classifier face is absent), `foldedBy` (present iff the two differ: `operator_deny` / `face_absent` /
+     * `inherited_ceiling`). The same three members answer every steer of the mode (`TaskStream.setPermissionMode`) and
+     * ride the fold notice's detail. A shell renders its mode indicator from `effective`, never from what it sent.
+     * ABSENT = an older mint, never a state. Leg-local (excluded from {@link configFingerprint}: a child clamped under its
+     * parent legitimately differs from it).
+     */
+    permissionMode?: import("./mode-policy.js").PermissionModeReceipt;
     /**
      * EFFECTIVE half only, PRESENT IFF this leg compiled a write-protection judge — a deployment that
      * replaced the table with `[]` opted the layer out entirely, and reports nothing here rather than a
@@ -407,8 +419,8 @@ export interface WiringManifest {
      * of one assembly agree.
      *
      * @contract read_deny.builtin_activation_disclosed — WHETHER the built-in sensitive-path read deny
-     * table judges a leg is DISCLOSED, never inferred: the table is a deployment opt-in whose default
-     * selection is empty, the leg that compiles the judge relays the tiers its own resolution materially
+     * table judges a leg is DISCLOSED, never inferred: the tier selection is the deployment's (absent = the default
+     * tiers, an explicit `[]` = none), the leg that compiles the judge relays the tiers its own resolution materially
      * activated, and the manifest carries that section iff at least one built-in row is active (absence
      * = no built-in row judges; an empty array is never emitted — "off" and "on to nothing" are one
      * fact). The disclosure changes no verdict.
@@ -524,6 +536,9 @@ export interface WiringFacts {
         mounted: boolean;
         reason?: HandsUnmountedReason;
     };
+    /** Effective half only — the leg's permission-mode receipt ({@link WiringManifest.permissionMode}); the engine always passes it.
+     *  Screened: `effective` a mode word, `requested` a mode word or absent, `foldedBy` a fold reason or absent. */
+    permissionMode?: import("./mode-policy.js").PermissionModeReceipt;
     /** Effective half only — the compiled write-protection judge's OWN target-view word
      *  ({@link WiringManifest.writeProtection}); absent ⇒ this leg compiled no judge (an emptied table). */
     writeProtectionTargetView?: WriteProtectionTargetView;
@@ -596,6 +611,17 @@ export declare function resolveSubagentTranscriptTier(agentStoreWired: boolean,
  *    else the headless degrade `auto_deny`.
  */
 export declare function deriveAskEffective(form: AskSeamForm, parkEffective: boolean | "unresolved"): AskEffective;
+/**
+ * Does an ask this leg hands on carrying `requiresRealApproval` reach a PERSON — never an automatic yes? The leg's
+ * APPROVAL SEAT, read off the ONE ask derivation above, never re-derived: `human_reachable` (a live approver) and
+ * `park_only` (the durable park; where the park cannot take the ask, a blanket seat behind it refuses the bit) are a
+ * person; `auto_allow`, `auto_deny` and `unresolved` are nobody (the last the fail-closed reading). The auto-mode
+ * classifier stations read it to decide where a classification that could not rule goes: to that person (the ask
+ * carrying the bit), or refused.
+ */
+export declare function askReachesPerson(ask: {
+    readonly effective?: AskEffective;
+}): boolean;
 export declare function deriveWiringManifest(facts: WiringFacts): WiringManifest;
 /** The one ask-seat resolution (`spec` wins over `deps`), shared with the effective half so the
  *  form/provenance read cannot fork. Junk values (a JS caller passing something outside the OnAsk

package/dist/core/wiring-manifest.js

@@ -1,3 +1,5 @@
+import { isPermissionMode } from "./ask-origin.js";
+import { PERMISSION_MODE_FOLD_REASONS } from "./mode-policy.js";
 import { createHash } from "node:crypto";
 import { canonicalize } from "./canonical-json.js";
 import { resolveCheckpointStore } from "./checkpoint-store.js";
@@ -57,6 +59,23 @@ export function deriveAskEffective(form, parkEffective) {
         }
     }
 }
+export function askReachesPerson(ask) {
+    const effective = ask.effective ?? "unresolved";
+    switch (effective) {
+        case "human_reachable":
+        case "park_only":
+            return true;
+        case "auto_allow":
+        case "auto_deny":
+        case "unresolved":
+            return false;
+        default: {
+            const _exhaustive = effective;
+            void _exhaustive;
+            throw new Error(`unreachable ask effective ${String(effective)}`);
+        }
+    }
+}
 function deriveParkLane(facts) {
     if (!facts.parkCapable) {
         return { capable: false, effective: false, reasons: ["no_checkpoint_store"] };
@@ -87,6 +106,13 @@ function readAutoModeFact(fact) {
     }
     return { armed, reason, ...(deniedSource !== undefined ? { deniedSource } : {}) };
 }
+function readPermissionModeFact(fact) {
+    const { requested, effective, foldedBy } = typeof fact === "object" && fact !== null ? fact : { requested: undefined, effective: undefined, foldedBy: undefined };
+    if (!isPermissionMode(effective) || (requested !== undefined && !isPermissionMode(requested)) || (foldedBy !== undefined && !PERMISSION_MODE_FOLD_REASONS.includes(foldedBy))) {
+        throw new Error(`the permission-mode wiring fact is inconsistent (${JSON.stringify(fact)}) — effective must be a permission mode, requested one or absent, foldedBy one of ${PERMISSION_MODE_FOLD_REASONS.join("|")} or absent`);
+    }
+    return { ...(requested !== undefined ? { requested } : {}), effective, ...(foldedBy !== undefined ? { foldedBy } : {}) };
+}
 function readHandsFact(fact) {
     const { mounted, reason } = typeof fact === "object" && fact !== null ? fact : { mounted: undefined, reason: undefined };
     if (typeof mounted !== "boolean" || (mounted ? reason !== undefined : reason !== "no_execution_env")) {
@@ -157,6 +183,7 @@ export function deriveWiringManifest(facts) {
         ...(facts.half === "effective" && facts.hooks !== undefined && facts.hooks.length > 0 ? { hooks: facts.hooks.map((h) => ({ ...h })) } : {}),
         ...(facts.half === "effective" && facts.lsp !== undefined ? { lsp: { ...facts.lsp } } : {}),
         ...(facts.half === "effective" && facts.hands !== undefined ? { hands: readHandsFact(facts.hands) } : {}),
+        ...(facts.half === "effective" && facts.permissionMode !== undefined ? { permissionMode: readPermissionModeFact(facts.permissionMode) } : {}),
         ...(facts.half === "effective" && facts.writeProtectionTargetView !== undefined ? { writeProtection: { targetView: facts.writeProtectionTargetView } } : {}),
         ...(facts.half === "effective" && facts.readDenyBuiltinTiersActive !== undefined && facts.readDenyBuiltinTiersActive.length > 0
             ? { readDeny: { builtinTiers: [...facts.readDenyBuiltinTiersActive] } }
@@ -169,7 +196,7 @@ export function deriveWiringManifest(facts) {
             : {}),
     };
     if (facts.half === "effective") {
-        const { leg: _leg, mcp: _mcp, tools: _tools, lsp: _lsp, hooks: _hooks, teamRole: _teamRole, peerPresence: _peerPresence, fileHistory: _fileHistory, ...assembly } = manifest;
+        const { leg: _leg, mcp: _mcp, tools: _tools, lsp: _lsp, hooks: _hooks, teamRole: _teamRole, peerPresence: _peerPresence, fileHistory: _fileHistory, permissionMode: _permissionMode, ...assembly } = manifest;
         const { provenance: _askSeat, ...askForHash } = assembly.ask;
         const { provenance: _questionSeat, ...questionForHash } = assembly.question;
         manifest.configFingerprint = createHash("sha256")

package/dist/core/write-protect.d.ts

@@ -20,7 +20,7 @@ export interface WriteProtectedRow {
  * String shorthand: a bare name ≡ `{ name, kind: "segment" }` (the WIDER single-segment kind —
  * over-matching is the fail-safe direction for a tighten); a name containing `/` ≡
  * `{ name, kind: "segment-run" }`. Spell `kind: "basename"` explicitly when last-segment-only
- * matching is the intent.
+ * matching is the intent. A name opening with the home word (`~/…`) refuses: the table places no row at a home.
  */
 export type WriteProtectedEntry = string | WriteProtectedRow;
 /** A table hit: which row matched (the row's canonical name + kind). */
@@ -108,6 +108,13 @@ export interface WriteProtectionJudgeContext {
     readonly base?: string;
     /** Bounds the filesystem probes of the target view. */
     readonly signal?: AbortSignal;
+    /** The path is a CANONICAL key the caller already resolved at the seat its program writes it (the shell read station's
+     *  established write target: where the path lands, or — for a removal or a rename — the entry itself, its canonical
+     *  parent joined with the last name, a link there not followed). It is judged where a key is judged — the readings and
+     *  the canonical data-root exemption — never as a spelling (the lexical passthrough reads a spelling, and a key reached
+     *  through a linked data root does not spell itself inside it) and never followed: no link chain is walked from it, as
+     *  the program walks none from where it writes. Without an environment the key is judged as a spelling (the absence law). */
+    readonly canonical?: true;
 }
 /**
  * WHICH reading of a write's TARGET a compiled judge has — its own word, and the vocabulary the wiring
@@ -258,3 +265,6 @@ export interface WriteProtectionMount {
  * `deny > ask > allow` fold, which is what makes the missing seat cost nothing.
  */
 export declare function createWriteProtectionCheck(entries?: readonly WriteProtectedEntry[], opts?: WriteProtectionCompileOptions): WriteProtectionMount | undefined;
+/** {@link createWriteProtectionCheck} over a judge already compiled — the engine's leg compiles once and hands the same
+ *  judge to the call check and to the shell station (engine-internal; not re-exported from the package root). */
+export declare function writeProtectionMountOver(matcher: WriteProtectionMatcher, rootPath: string | undefined): WriteProtectionMount;

package/dist/core/write-protect.js

@@ -3,6 +3,7 @@ import { protectivePathTargetOf } from "./tool-registry.js";
 import { pathTargetBaseOf } from "./effective-path-target.js";
 import { canonicalDataRootKeys, dataRootSpellings, relativeUnderRoot } from "./sensitive-path-policy.js";
 import { symlinkChainHops } from "./path-identity.js";
+import { readDenyPatternRun } from "../tools/fs/read-deny.js";
 import { thrownText } from "./thrown-value.js";
 const freezeTable = (rows) => Object.freeze(rows.map((r) => Object.freeze(r)));
 export const WRITE_PROTECTED_DEFAULT_TABLE = freezeTable([
@@ -57,6 +58,7 @@ export const WRITE_PROTECTED_DEFAULT_TABLE = freezeTable([
     { name: ".gnupg", kind: "segment" },
     { name: ".sema.json", kind: "basename" },
     { name: ".sema", kind: "segment" },
+    { name: "credentials.env", kind: "basename" },
 ]);
 export function foldWriteProtectSegment(s) {
     const cased = s.toLowerCase().replace(/ı/g, "i").replace(/ſ/g, "s");
@@ -91,6 +93,11 @@ function normalizeWriteProtectedEntry(entry) {
         throw new Error(`writeProtectedPaths: entry ${describeEntryValue(entry)} has kind ${describeEntryValue(shape.kind)} — known kinds: ${KINDS.join(", ")}.`);
     }
     const kind = shape.kind;
+    const { homeAnchored, run } = readDenyPatternRun(name);
+    if (homeAnchored) {
+        throw new Error(`writeProtectedPaths: entry ${describeEntryValue(name)} opens with the home word "~", which this table does not place — its names are matched wherever their segments appear. ` +
+            (run.length > 0 ? `Spell the name without it (${describeEntryValue(run)}), which covers the home's file and every same-named one.` : "The home directory itself is not a row; spell the name of what it holds."));
+    }
     if (name.includes("*") || name.includes("?")) {
         throw new Error(`writeProtectedPaths: entry ${describeEntryValue(name)} contains a wildcard metacharacter — this table speaks LITERAL names only (a silently-literal "*" would guard less than it reads); pattern semantics live in createSensitivePathPolicy.`);
     }
@@ -254,7 +261,8 @@ export function compileWriteProtection(entries, opts) {
             return judgeSpelling(path, cwd);
         },
         async judge(path, ctx = {}) {
-            const bySpelling = judgeSpelling(path, ctx.cwd);
+            const givenKey = ctx.canonical === true && env !== undefined;
+            const bySpelling = givenKey ? null : judgeSpelling(path, ctx.cwd);
             if (bySpelling !== null)
                 return { kind: "hit", hit: bySpelling, via: "spelling" };
             if (env === undefined)
@@ -268,16 +276,18 @@ export function compileWriteProtection(entries, opts) {
                 noted = true;
                 opts?.onViewAbsent?.({ cause, unresolvedSymlink });
             };
-            let canonKey;
-            try {
-                const canon = await canonicalizeTarget(env, path, ctx.signal, family, base);
-                if (canon.ok)
-                    canonKey = canon.key;
-                else
-                    noteAbsence(canon.message, canon.unresolvedSymlink === true);
-            }
-            catch (err) {
-                noteAbsence(thrownText(err), false);
+            let canonKey = givenKey ? path : undefined;
+            if (!givenKey) {
+                try {
+                    const canon = await canonicalizeTarget(env, path, ctx.signal, family, base);
+                    if (canon.ok)
+                        canonKey = canon.key;
+                    else
+                        noteAbsence(canon.message, canon.unresolvedSymlink === true);
+                }
+                catch (err) {
+                    noteAbsence(thrownText(err), false);
+                }
             }
             try {
                 if (canonKey !== undefined) {
@@ -295,7 +305,7 @@ export function compileWriteProtection(entries, opts) {
                         return { kind: "hit", hit: byTarget, via: "target" };
                     }
                 }
-                for (const hop of await symlinkChainHops(env, path, ctx.signal, family, base, (cause) => noteAbsence(cause, false))) {
+                for (const hop of givenKey ? [] : await symlinkChainHops(env, path, ctx.signal, family, base, (cause) => noteAbsence(cause, false))) {
                     const byHop = judgeSpelled(hop);
                     if (byHop === null)
                         continue;
@@ -346,8 +356,9 @@ export function writeProtectionUnresolved(verdict) {
 }
 export function createWriteProtectionCheck(entries, opts) {
     const matcher = compileWriteProtection(entries, opts);
-    if (matcher === undefined)
-        return undefined;
+    return matcher === undefined ? undefined : writeProtectionMountOver(matcher, opts?.rootPath);
+}
+export function writeProtectionMountOver(matcher, rootPath) {
     const check = (toolName, args, face, cwd, signal) => {
         const call = { toolName, args, ...(face !== undefined ? { face } : {}) };
         const protective = protectivePathTargetOf(call);
@@ -356,7 +367,7 @@ export function createWriteProtectionCheck(entries, opts) {
         const path = writeTargetPath(call, protective);
         if (typeof path !== "string" || path.length === 0)
             return null;
-        return matcher.judge(path, { ...(cwd !== undefined ? { cwd } : {}), ...(signal !== undefined ? { signal } : {}), ...(() => { const b = pathTargetBaseOf(protective, { root: opts?.rootPath, cwd }); return b !== undefined ? { base: b } : {}; })() });
+        return matcher.judge(path, { ...(cwd !== undefined ? { cwd } : {}), ...(signal !== undefined ? { signal } : {}), ...(() => { const b = pathTargetBaseOf(protective, { root: rootPath, cwd }); return b !== undefined ? { base: b } : {}; })() });
     };
     return { check, targetView: matcher.targetView };
 }

package/dist/engine/execution-env/node-execution-env.d.ts

@@ -187,6 +187,9 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
     setFileMode(path: string, mode: number, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
     listDir(path: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;
     canonicalPath(path: string): Promise<Result<string, FileError>>;
+    /** {@link FileSystem.fileIdentity}: `stat` (links followed) read as BIGINT — an inode past 2^53 (an APFS volume root)
+     *  is not exact as a number, and two inodes that collapse to one number would name two directories as one. */
+    fileIdentity(path: string): Promise<Result<string, FileError>>;
     readLink(path: string): Promise<Result<string, FileError>>;
     /**
      * The LEAF symlink chain ({@link FileSystem.canonicalChain}): `readlink` on the whole spelling, then on each

package/dist/engine/execution-env/node-execution-env.js

@@ -1,7 +1,7 @@
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { closeSync, constants, createReadStream, mkdtempSync, openSync, readSync, statSync, truncateSync, unlinkSync } from "node:fs";
-import { access, appendFile, lstat, mkdir, mkdtemp, open, readdir, readFile, readlink, rename, rm, unlink, writeFile, } from "node:fs/promises";
+import { access, appendFile, lstat, mkdir, mkdtemp, open, readdir, readFile, readlink, rename, rm, stat, unlink, writeFile, } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { createInterface } from "node:readline";
@@ -1010,6 +1010,16 @@ export class NodeExecutionEnv {
             return err(toFileError(error, resolved));
         }
     }
+    async fileIdentity(path) {
+        const resolved = resolvePath(this.cwd, path);
+        try {
+            const s = await stat(resolved, { bigint: true });
+            return ok(`${s.dev}:${s.ino}`);
+        }
+        catch (error) {
+            return err(toFileError(error, resolved));
+        }
+    }
     async readLink(path) {
         const resolved = resolvePath(this.cwd, path);
         try {

package/dist/engine/harness/types.d.ts

@@ -397,16 +397,15 @@ export interface FileSystem {
     listDir(path: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;
     /** Return the canonical path for an existing path, resolving symlinks where supported. */
     canonicalPath(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
-    /**
-     * VENDORED EDIT (design/72 §2.1, additive/backward-compatible): read a symlink's raw target (one
-     * hop, NOT followed). Optional — an env that omits it falls back to best-effort canonicalization
-     * for a DANGLING leaf symlink (a symlink whose target doesn't exist yet, which `canonicalPath`'s
-     * `realpath` can't resolve). Needed so a sensitive-path guard / containment check sees the real
-     * target of `write_file innocent.txt` where `innocent.txt -> .git/hooks/payload`.
-     */
+    /** OPTIONAL: a symlink's raw target, one hop, not followed — so a path guard sees where `innocent.txt -> .git/hooks/payload`
+     *  writes although the target does not exist yet (`canonicalPath`'s `realpath` cannot resolve a DANGLING leaf link).
+     *  Omitted ⇒ such a leaf is canonicalized best-effort. */
     readLink?(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
     /** OPTIONAL: the LEAF symlink chain of `path` ({@link SymlinkChain}). Omitted, or `ok: false` ⇒ the path judges read the spelling and the canonical terminal only (the reach they had before this seat); a remote adapter answers in one `readlink` round trip and a caller never emulates it through {@link readLink}; bounded (64 hops, a cycle ends it), a network hop kept unprobed. */
     canonicalChain?(path: string, abortSignal?: AbortSignal): Promise<Result<SymlinkChain, FileError>>;
+    /** OPTIONAL: the identity of the object `path` names, links followed (`<device>:<inode>` on POSIX, exact): equal answers name one object, where
+     *  a firmlink or bind mount keeps its own {@link canonicalPath}. Home-anchored deny rows are placed by it; omitted ⇒ by spelling only. */
+    fileIdentity?(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
     /** Return false for missing paths. Other errors, such as permission failures, return a {@link FileError}. */
     exists(path: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;
     /** Create a directory. Defaults: `recursive: true`, no abort signal. */

package/dist/engine/llm/types.d.ts

@@ -144,10 +144,8 @@ export interface StreamOptions {
      * (see BrainTimeoutConfig.firstTokenTimeoutMs, design/17 O5).
      */
     stallTimeouts?: StallTimeouts;
-    /**
-     * Maximum retry attempts for providers/SDKs that support client-side retries.
-     * For example, OpenAI and Anthropic SDK clients default to 2.
-     */
+    /** Per-call cap on the brain's transient retry budget: this call retries at most this many times, never more than
+     *  the brain is configured for. */
     maxRetries?: number;
     /**
      * Maximum delay in milliseconds to wait for a retry when the server requests a long wait.

package/dist/engine/loop/types.d.ts

@@ -765,6 +765,13 @@ export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = unk
      * keyed by the folded-away spelling must stay inert rather than land on the other tool. Absent on non-MCP tools.
      */
     mcpRemoteName?: string;
+    /**
+     * The MCP server's own read-only declaration (`annotations.readOnlyHint === true` on its tools/list entry), set by
+     * the MCP materializer. It answers ONE question: whether the `plan` mode leaves the tool to run (the reference's
+     * `isReadOnly` for a server's tool). It is never the tool's effect — a server's self-claim does not lower the
+     * repeat-safety effect below its fail-closed `write` default (only the caller's `toolAxes` does). Absent on non-MCP tools.
+     */
+    mcpReadOnlyHint?: true;
     /**
      * design/120 P1.5 (CC `isConcurrencySafe(parsedInput)` parity): INPUT-level concurrency refinement
      * for a tool whose safety depends on its arguments — CC's only real consumer is

package/dist/index.d.ts

@@ -62,6 +62,12 @@ export { probeMcpServers, type McpProbeResult } from "./core/mcp-probe.js";
 export { MCP_FAILURE_KINDS, MCP_DELIVERY_VERDICTS, MCP_LIVENESS_STATES, classifyMcpFailure, type McpFailure, type McpFailureKind, type McpDelivered, type McpLivenessState, type McpServerLiveness } from "./core/mcp-failure.js";
 export { MCP_INJECTION_DROP_REASONS, MCP_INJECTION_DROP_TEXT, mcpInjectionDroppedNotice, type McpInjectionDropReason, type McpInjectionDropFacts } from "./core/mcp-injection-drop.js";
 export { askUnresolvableNotice, type AskUnresolvableFacts } from "./core/ask-unresolvable-notice.js";
+export { ASK_UNRESOLVABLE_CAUSES } from "./core/ask-unresolvable-notice.js";
+export { DURABLE_MANDATE_SOURCES } from "./core/tool-policy.js";
+export { TERMINAL_CAUSE_IS_REPLAYABLE } from "./core/terminal-cause.js";
+export { RESERVED_AGENT_NAMES } from "./agents/subagent.js";
+export { WORKFLOW_SIZE_GUIDELINE_AGENT_CAPS } from "./orchestration/workflow-size-guideline.js";
+export { ENGINE_AUTHORITY_ENVELOPE_TAGS } from "./core/untrusted-text.js";
 export { materializeA2aTools, A2aRpcError, type MaterializedA2a, type A2aPeerStatus, type A2aRefreshResult, type A2aToolAxis } from "./core/a2a.js";
 export { PROTOCOL_TABLE, MCP_NAMESPACE, A2A_NAMESPACE, protocolOf, type ProtocolNamespace, type ProtocolId } from "./core/protocol-table.js";
 export { InMemorySessionPolicyStore, SessionPolicyError, loosenReasons, normalizeRules, stripRev, type SessionPolicyStore, type SessionPermissionRules, type StoredSessionRules, type SessionRulesRecord, type PutRulesOptions, } from "./core/session-policy-store.js";
@@ -104,7 +110,7 @@ export type { InvariantKind, FunctionContract, Invariant, InvariantViolation, Ch
 export { bashReversibilityProbe, BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName, classifyCompoundReadonly, MAX_EDIT_BYTES } from "./tools/fs/index.js";
 export { classifyCompoundReadonlyDetailed, formatOutOfRootReadApprovalOption, type BashReadonlyRootBoundary, type CompoundReadonlyVerdict, } from "./tools/fs/index.js";
 export { resolveBashTimeoutCaps } from "./tools/fs/index.js";
-export { READ_FACE_DEFAULT_DENY_ENTRIES, READ_FACE_BUILTIN_DENY_TABLE, READ_DENY_BUILTIN_TIERS, READ_DENY_DEFAULT_TIERS, resolveReadDenyBuiltins, compileReadDeny, type ReadDenyEntry, type ReadDenyMatcher, type NormalizedReadDenyEntry, type ReadDenyBuiltinTier, type ReadDenyBuiltinRow, type ReadDenyBuiltinConfig, } from "./tools/fs/index.js";
+export { READ_FACE_DEFAULT_DENY_ENTRIES, READ_FACE_BUILTIN_DENY_TABLE, READ_DENY_BUILTIN_TIERS, READ_DENY_DEFAULT_TIERS, resolveReadDenyBuiltins, compileReadDeny, READ_DENY_HOME_WORD, readDenyPatternRun, readDenyHomesOf, compileWriteDeny, DENY_FACES, type DenyFace, type PathRuleDenyRow, type WriteDenyMatcher, type ReadDenyEntry, type ReadDenyMatcher, type NormalizedReadDenyEntry, type ReadDenyBuiltinTier, type ReadDenyBuiltinRow, type ReadDenyBuiltinConfig, } from "./tools/fs/index.js";
 export { deploymentFaceClampNotice, resolveContainmentFace, type ContainmentFace, type ContainmentFaceInputs, type ContainmentFaceKind, type ContainmentFaceLayer, } from "./tools/fs/index.js";
 export { WRITE_PROTECTED_DEFAULT_TABLE, resolveWriteProtectedTable, compileWriteProtection, type WriteProtectedEntry, type WriteProtectedRow, type WriteProtectedKind, type WriteProtectedHit, type WriteProtectionMatcher, type WriteProtectionVerdict, type WriteProtectionViewAbsence, type WriteProtectionJudgeContext, type WriteProtectionCompileOptions, type WriteProtectionCheck, WRITE_PROTECTION_TARGET_VIEWS, type WriteProtectionTargetView, type WriteProtectionMount, } from "./core/write-protect.js";
 export { InMemoryToolResultStore, OFFLOAD_TOOL_NAME, DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, assertSafeToolResultRef, buildToolResultRef, toolResultContentSegment, MAX_MINTED_TOOL_RESULT_REF_CHARS, type ToolResultProvenance, assertToolResultProvenanceMatch, normalizeToolResultProvenance, toolResultProvenanceOf, ToolResultRefConflictError, TOOL_RESULT_REF_CONFLICT_CODE, type ToolResultStore, type ToolResultSlice, type ToolResultDeletionReport, } from "./core/tool-result-store.js";
@@ -183,14 +189,18 @@ export { createAllowDenyPolicy, createApprovalPolicy,
  *  members that seat has no lane for (`"unavailable"`, a routing answer; `updatedInput`, an operator edit a
  *  policy verdict cannot get re-adjudicated). Exported so a host can NAME it instead of deriving it through
  *  `Parameters<typeof createApprovalPolicy>[0]["approve"]`. */
-type ApprovalSeatOutcome, COARSE_SHELL_TOOLS, createCoarseCommandNamePolicy, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, findUnverifiableRecursiveDelete, combinePolicies, decisionText, resolveAsk, toolPolicyNameSets, type ToolPolicyNameSets, type NamedToolPolicy, type ToolPolicyProjection, type ToolPolicyProjectionComponent, type ConstraintChainEntry, checkToolPolicyProjection, constraintChainEntryOf, constraintChainDigest, type ToolPolicy, type ToolCallRequest, type PermissionResult, type DecisionReason, screenApproverAttribution, APPROVER_ATTRIBUTION_MAX_CHARS, type OnAsk, type AskOutcome, type ResolvedAsk, type AskRequest, type AskDelegationProvenance, type AskRuleEvidence, type AskEvidenceAbsence, ASK_EVIDENCE_ABSENCE_VALUES, } from "./core/tool-policy.js";
+type ApprovalSeatOutcome, COARSE_SHELL_TOOLS, createCoarseCommandNamePolicy, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, findUnverifiableRecursiveDelete, combinePolicies, decisionText, resolveAsk, toolPolicyNameSets, toolPolicyPathDenyRules, type ToolPolicyNameSets, type NamedToolPolicy, type ToolPolicyProjection, type ToolPolicyProjectionComponent, type ConstraintChainEntry, checkToolPolicyProjection, constraintChainEntryOf, constraintChainDigest, type ToolPolicy, type ToolCallRequest, type PermissionResult, type DecisionReason, screenApproverAttribution, APPROVER_ATTRIBUTION_MAX_CHARS, type OnAsk, type AskOutcome, type ResolvedAsk, type AskRequest, type AskDelegationProvenance, type AskRuleEvidence, type AskEvidenceAbsence, ASK_EVIDENCE_ABSENCE_VALUES, } from "./core/tool-policy.js";
 export { type ReadRootGrantScreen } from "./core/read-root-grant-screen.js";
-export { type AskOrigin, ASK_ORIGINS, isAskOrigin, classifierMayAnswer, ORIGIN_IMPLIES_REAL_APPROVAL, RULE_STORE_UNREADABLE_KINDS, type RuleStoreUnreadable, isRuleStoreUnreadable, PERSISTED_RULE_MANDATES, type PersistedRuleMandate, isPersistedRuleMandate } from "./core/ask-origin.js";
+export { type AskOrigin, ASK_ORIGINS, isAskOrigin, ORIGIN_IMPLIES_REAL_APPROVAL, PERSISTED_RULE_MANDATES, type PersistedRuleMandate, isPersistedRuleMandate } from "./core/ask-origin.js";
+export { PERMISSION_MODES, type PermissionMode, isPermissionMode, PERMISSION_MODE_RANK, clampPermissionMode, ASK_CLASSES, type AskClass, isAskClass, MODE_ARBITRATION, type ModeArbitrationRow, RELEASABLE_ASK_CLASSES, RRA_EXPLAINERS, classifyAsk, foldArbitrationRow, type AskClassification, type AskClassFacts, type ToolMarkSource, arbitrateByMode, type Arbitration, fileCommandOptionsSentence } from "./core/ask-origin.js";
+export { modePolicyOf, type ModePolicy, PERMISSION_MODE_FOLD_REASONS, type PermissionModeFoldReason, type PermissionModeReceipt, ACCEPT_EDITS_FILE_COMMANDS, modeAcceptsFileCommand } from "./core/mode-policy.js";
+export { readDenyClassifierRules, renderClassifierDenyRules, type DerivedDenyRule } from "./core/auto-mode-prompt.js";
 export { AUTO_MODE_DENY_SOURCES, isAutoModeDenySource, type AutoModeDenySource } from "./core/runtime-caps.js";
-export { SETTLEMENT_KINDS, type SettlementKind, isSettlementKind, type Settlement, SETTLEMENT_IS_REFUSAL, DENIED_BY_VALUES, type DeniedBy, isDeniedBy, DENIED_BY_MAY_VETO, CLASSIFIER_DENY_CAUSES, type ClassifierDenyCause, isClassifierDenyCause, DENIED_BY_MAY_CARRY_CAUSE, type GateDisposition, type GateOutcome, screenGateOutcome } from "./core/gate-outcome.js";
+export { SETTLEMENT_KINDS, type SettlementKind, isSettlementKind, type Settlement, SETTLEMENT_IS_REFUSAL, DENIED_BY_VALUES, type DeniedBy, isDeniedBy, DENIED_BY_MAY_VETO, CLASSIFIER_DENY_CAUSES, type ClassifierDenyCause, isClassifierDenyCause, DENIED_BY_MAY_CARRY_CAUSE, type GateDisposition, type GateOutcome, type ModeRelease, type ModeRefusal, screenGateOutcome } from "./core/gate-outcome.js";
 export { type AskCarry } from "./core/hooks.js";
 export { SWAPPABLE_DEP_SEATS, SWAP_SEAT_NOTICE, isSwappableDepSeat, screenSwappableDeps, type SwappableDepSeat, type SwappableDeps } from "./core/swappable-deps.js";
 export { parseAutoModeResponse, createAutoModeDecider, AUTO_MODE_UNAVAILABLE_CAUSES, isAutoModeUnavailableCause, classifierUnavailableDenyMessage, classifierParseFailureDenyMessage, AUTO_MODE_PARSE_FAILURES, isAutoModeParseFailure, type AutoModeParseFailure, type AutoModeUnavailableCause, AUTO_MODE_CLASSIFIER_FALLBACKS, isAutoModeClassifierFallback, AUTO_MODE_FALLBACK_CAUSES, isAutoModeFallbackCause, type AutoModeClassifierFallback, type AutoModeFallbackCause, type AutoModeClassifierRound, type AutoModeLadderRung, type AutoModeVerdict, type AutoModeDecider, type AutoModeDeciderOptions, type AutoModeClassified, type AutoModeClassifyFn, type AutoModeClassifyInput, createAutoModeDenialTracker, denialLimitFallbackMessage, denialLimitSentence, unarmedWindow, type AutoModeDenialTracker, type AutoModeDenialLimitOptions, type DenialLimitCounts, type DenialLimitFallbackFace, type UnarmedDenialLimitFallback, type DenialLimitFallback, type DenialLimitVerdict, } from "./core/auto-mode.js";
+export type { ClassifierUnavailableSeat, ClassifierUnavailableInfo, ClassifierUnavailableDisposition, ClassifierUnavailableObserver } from "./core/classifier-unavailable-arm.js";
 export { AUTO_MODE_DENIAL_LIMIT_DEFAULTS, AUTO_MODE_DENIAL_AUTO_DENY_DEFAULT_MS, AUTO_MODE_CLASSIFIER_MAX_TOKENS } from "./core/auto-mode-defaults.js";
 export { classifierSeatModel, type ClassifierSeat } from "./core/runner/classifier-ladder.js";
 export { buildAutoModePrompt, renderAutoModeWindow, renderAutoModeAction, AUTO_MODE_DEFAULTS_SENTINEL, type AutoModeRules, type BuildAutoModePromptOptions, type AutoModeWindowOptions, } from "./core/auto-mode-prompt.js";
@@ -352,7 +362,7 @@ export { ROUTE_ADJUDICATION_CONFORMANCE_CORPUS, type RouteAdjudicationVector } f
 export { type BrainTimeoutConfig } from "./brain/timeout.js";
 export { createAssistantMessageEventStream } from "./internal/llm.js";
 export type { AssistantMessage, AssistantMessageEvent, CompleteSimpleFn, Context, DocumentContent, ImageContent, Message, StopReason, StreamFn, TextContent, ThinkingContent, ToolCall, ToolResultMessage, Usage, UserMessage, } from "./internal/llm.js";
-export type { AgentDefinition, BeforeWriteHook, BeforeWriteRequest, BeforeWriteResult, TrackFileEditHook, TrackEditRequest, TrackEditResult, FileEditedHook, FileEditedNotice, HandsBandOptions, Brain, BrainStatus, BrainStatusPhase, BrainRetryErrClass, ImageInput, McpElicitRequest, McpElicitResponse, McpServerSpec, A2aServerSpec, OnElicit, Model, ModelRef, ProjectMemoryLoad, RunnerDeps, ResumePreflightInfo, ResumePreflightVerdict, EngineNotice, RuntimeCaps, BackgroundChildEvent, DelegationLifecycleEvent, SkillManifest, SkillSpec, TaskEvent, TaskEventIdentity, ToolActivity, TaskLimits, StaleToolResultOffloadOptions, TaskResult, TerminalCause, PausedCause, EffectiveMemoryScopes, RemoteEnvFailureNote, TaskSpec, ShellGateDoctrine, ApproverPosture, TaskStatus, TaskStream, CompactOutcome, ThinkingLevel, ToolExecuteContext, ToolReturn, ToolSpec, ToolInputVerdict, ToolInputValidationContext, ReversibilityVerdict, ReadRootGrantCandidate, ToolEffect, ToolContentOrigin, WorkflowGovernanceBaseline, DelegationTaskType, } from "./core/types.js";
+export type { AgentDefinition, BeforeWriteHook, BeforeWriteRequest, BeforeWriteResult, TrackFileEditHook, TrackEditRequest, TrackEditResult, FileEditedHook, FileEditedNotice, HandsBandOptions, Brain, BrainStatus, BrainStatusPhase, BrainRetryErrClass, ImageInput, McpElicitRequest, McpElicitResponse, McpServerSpec, A2aServerSpec, OnElicit, Model, ModelRef, ProjectMemoryLoad, RunnerDeps, ResumePreflightInfo, ResumePreflightVerdict, EngineNotice, RuntimeCaps, BackgroundChildEvent, DelegationLifecycleEvent, SkillManifest, SkillSpec, TaskEvent, TaskEventIdentity, ToolActivity, TaskLimits, StaleToolResultOffloadOptions, TaskResult, TerminalCause, PausedCause, EffectiveMemoryScopes, RemoteEnvFailureNote, TaskSpec, ShellGateDoctrine, TaskStatus, TaskStream, CompactOutcome, ThinkingLevel, ToolExecuteContext, ToolReturn, ToolSpec, ToolInputVerdict, ToolInputValidationContext, ReversibilityVerdict, ReadRootGrantCandidate, ToolEffect, ToolContentOrigin, WorkflowGovernanceBaseline, DelegationTaskType, } from "./core/types.js";
 export { Type } from "typebox";
 export type { TSchema, Static } from "typebox";
 export { explainPromptAssembly, describeDefaultPack, type DefaultPackDescription, type ExplainInput } from "./prompt-assembly/explain.js";

package/dist/index.js

@@ -48,6 +48,12 @@ export { probeMcpServers } from "./core/mcp-probe.js";
 export { MCP_FAILURE_KINDS, MCP_DELIVERY_VERDICTS, MCP_LIVENESS_STATES, classifyMcpFailure } from "./core/mcp-failure.js";
 export { MCP_INJECTION_DROP_REASONS, MCP_INJECTION_DROP_TEXT, mcpInjectionDroppedNotice } from "./core/mcp-injection-drop.js";
 export { askUnresolvableNotice } from "./core/ask-unresolvable-notice.js";
+export { ASK_UNRESOLVABLE_CAUSES } from "./core/ask-unresolvable-notice.js";
+export { DURABLE_MANDATE_SOURCES } from "./core/tool-policy.js";
+export { TERMINAL_CAUSE_IS_REPLAYABLE } from "./core/terminal-cause.js";
+export { RESERVED_AGENT_NAMES } from "./agents/subagent.js";
+export { WORKFLOW_SIZE_GUIDELINE_AGENT_CAPS } from "./orchestration/workflow-size-guideline.js";
+export { ENGINE_AUTHORITY_ENVELOPE_TAGS } from "./core/untrusted-text.js";
 export { materializeA2aTools, A2aRpcError } from "./core/a2a.js";
 export { PROTOCOL_TABLE, MCP_NAMESPACE, A2A_NAMESPACE, protocolOf } from "./core/protocol-table.js";
 export { InMemorySessionPolicyStore, SessionPolicyError, loosenReasons, normalizeRules, stripRev, } from "./core/session-policy-store.js";
@@ -82,7 +88,7 @@ export { deriveInvariants, checkInvariants } from "./core/property-harness.js";
 export { bashReversibilityProbe, BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName, classifyCompoundReadonly, MAX_EDIT_BYTES } from "./tools/fs/index.js";
 export { classifyCompoundReadonlyDetailed, formatOutOfRootReadApprovalOption, } from "./tools/fs/index.js";
 export { resolveBashTimeoutCaps } from "./tools/fs/index.js";
-export { READ_FACE_DEFAULT_DENY_ENTRIES, READ_FACE_BUILTIN_DENY_TABLE, READ_DENY_BUILTIN_TIERS, READ_DENY_DEFAULT_TIERS, resolveReadDenyBuiltins, compileReadDeny, } from "./tools/fs/index.js";
+export { READ_FACE_DEFAULT_DENY_ENTRIES, READ_FACE_BUILTIN_DENY_TABLE, READ_DENY_BUILTIN_TIERS, READ_DENY_DEFAULT_TIERS, resolveReadDenyBuiltins, compileReadDeny, READ_DENY_HOME_WORD, readDenyPatternRun, readDenyHomesOf, compileWriteDeny, DENY_FACES, } from "./tools/fs/index.js";
 export { deploymentFaceClampNotice, resolveContainmentFace, } from "./tools/fs/index.js";
 export { WRITE_PROTECTED_DEFAULT_TABLE, resolveWriteProtectedTable, compileWriteProtection, WRITE_PROTECTION_TARGET_VIEWS, } from "./core/write-protect.js";
 export { InMemoryToolResultStore, OFFLOAD_TOOL_NAME, DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, assertSafeToolResultRef, buildToolResultRef, toolResultContentSegment, MAX_MINTED_TOOL_RESULT_REF_CHARS, assertToolResultProvenanceMatch, normalizeToolResultProvenance, toolResultProvenanceOf, ToolResultRefConflictError, TOOL_RESULT_REF_CONFLICT_CODE, } from "./core/tool-result-store.js";
@@ -148,9 +154,12 @@ export { hasScheduler, isValidCronExpr, SchedulerError } from "./core/scheduler.
 export { createSchedulerTools, SCHEDULE_WAKEUP_TOOL_NAME, AUTONOMOUS_LOOP_SENTINEL, AUTONOMOUS_LOOP_DYNAMIC_SENTINEL, } from "./tools/scheduler-tools.js";
 export { resolveAutonomousLoopPrompt, AUTONOMOUS_LOOP_PREAMBLE, AUTONOMOUS_LOOP_PREAMBLE_PERSISTENT, } from "./tools/loop-tick.js";
 export { tightenTaskSpec, TaskSpecTightenError } from "./core/tighten-task-spec.js";
-export { createAllowDenyPolicy, createApprovalPolicy, COARSE_SHELL_TOOLS, createCoarseCommandNamePolicy, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, findUnverifiableRecursiveDelete, combinePolicies, decisionText, resolveAsk, toolPolicyNameSets, checkToolPolicyProjection, constraintChainEntryOf, constraintChainDigest, screenApproverAttribution, APPROVER_ATTRIBUTION_MAX_CHARS, ASK_EVIDENCE_ABSENCE_VALUES, } from "./core/tool-policy.js";
+export { createAllowDenyPolicy, createApprovalPolicy, COARSE_SHELL_TOOLS, createCoarseCommandNamePolicy, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, findUnverifiableRecursiveDelete, combinePolicies, decisionText, resolveAsk, toolPolicyNameSets, toolPolicyPathDenyRules, checkToolPolicyProjection, constraintChainEntryOf, constraintChainDigest, screenApproverAttribution, APPROVER_ATTRIBUTION_MAX_CHARS, ASK_EVIDENCE_ABSENCE_VALUES, } from "./core/tool-policy.js";
 export {} from "./core/read-root-grant-screen.js";
-export { ASK_ORIGINS, isAskOrigin, classifierMayAnswer, ORIGIN_IMPLIES_REAL_APPROVAL, RULE_STORE_UNREADABLE_KINDS, isRuleStoreUnreadable, PERSISTED_RULE_MANDATES, isPersistedRuleMandate } from "./core/ask-origin.js";
+export { ASK_ORIGINS, isAskOrigin, ORIGIN_IMPLIES_REAL_APPROVAL, PERSISTED_RULE_MANDATES, isPersistedRuleMandate } from "./core/ask-origin.js";
+export { PERMISSION_MODES, isPermissionMode, PERMISSION_MODE_RANK, clampPermissionMode, ASK_CLASSES, isAskClass, MODE_ARBITRATION, RELEASABLE_ASK_CLASSES, RRA_EXPLAINERS, classifyAsk, foldArbitrationRow, arbitrateByMode, fileCommandOptionsSentence } from "./core/ask-origin.js";
+export { modePolicyOf, PERMISSION_MODE_FOLD_REASONS, ACCEPT_EDITS_FILE_COMMANDS, modeAcceptsFileCommand } from "./core/mode-policy.js";
+export { readDenyClassifierRules, renderClassifierDenyRules } from "./core/auto-mode-prompt.js";
 export { AUTO_MODE_DENY_SOURCES, isAutoModeDenySource } from "./core/runtime-caps.js";
 export { SETTLEMENT_KINDS, isSettlementKind, SETTLEMENT_IS_REFUSAL, DENIED_BY_VALUES, isDeniedBy, DENIED_BY_MAY_VETO, CLASSIFIER_DENY_CAUSES, isClassifierDenyCause, DENIED_BY_MAY_CARRY_CAUSE, screenGateOutcome } from "./core/gate-outcome.js";
 export {} from "./core/hooks.js";

package/dist/orchestration/workflow-governance.js

@@ -298,7 +298,7 @@ function pickWhitelist(scriptSpec) {
         if (!Array.isArray(readDenyPatternsRaw)) {
             throw new WorkflowScriptError('agent(spec): `readDenyPatterns` must be an array of deny entries (a "/"-separated segment run such as ".ssh", or { pattern, caseSensitive? })');
         }
-        const entries = mapUntrustedArray(readDenyPatternsRaw, "agent(spec): `readDenyPatterns`", MAX_SCRIPT_DENY_ENTRIES, "Every entry is judged against every path the child reads, for the child's whole run; the deployment's own entries, and whichever built-in tiers the deployment switched on (none by default), are in force on top of these.", pickReadDenyEntry);
+        const entries = mapUntrustedArray(readDenyPatternsRaw, "agent(spec): `readDenyPatterns`", MAX_SCRIPT_DENY_ENTRIES, "Every entry is judged against every path the child reads, for the child's whole run; the deployment's own entries, and whichever built-in tiers the deployment has on (by default the credentials and home agent-config tiers), are in force on top of these.", pickReadDenyEntry);
         try {
             compileReadDeny(entries, "agent(spec).readDenyPatterns");
         }

package/dist/orchestration/workflow-primitives.d.ts

@@ -52,7 +52,7 @@ parentReadFace?: () => TaskSpec["readFace"],
  *  stricter-wins into every spawned child on its own seat (the two seats never read each other). */
 parentWriteFace?: () => TaskSpec["writeFace"], 
 /** Twin of the above for the deny-set additions (the extra entries the host's own deployment/task
- *  layers stacked on; the built-in rows the DEPLOYMENT switched on — none by default — apply beside them). */
+ *  layers stacked on; the built-in rows the DEPLOYMENT's tier selection activates apply beside them). */
 parentReadDenyPatterns?: () => TaskSpec["readDenyPatterns"], 
 /** #345 ③ — the HOST task's write-hands clamp is ON (`spec.handsReadOnly === true`). Injected
  *  tighten-only into every spawned child, like the read-face clamp above; see the injection

package/dist/orchestration/workflow-size-guideline.js

@@ -1,10 +1,10 @@
 export const WORKFLOW_SIZE_GUIDELINES = ["unrestricted", "small", "medium", "large"];
 export const WORKFLOW_SIZE_GUIDELINE_DEFAULT = "medium";
-export const WORKFLOW_SIZE_GUIDELINE_AGENT_CAPS = {
+export const WORKFLOW_SIZE_GUIDELINE_AGENT_CAPS = Object.freeze({
     small: 5,
     medium: 15,
     large: 50,
-};
+});
 export function normalizeWorkflowSizeGuideline(value) {
     return WORKFLOW_SIZE_GUIDELINES.includes(value) ? value : undefined;
 }

package/dist/tools/artifact/artifact-tool.d.ts

@@ -1,3 +1,12 @@
+/**
+ * The `Artifact` tool: one tool, `action`-multiplexed, assembled from the host's capability declaration.
+ * The action enum, the parameter set and the description are all functions of `capabilities` — the
+ * implementation behind the seam is never inspected. Session state (the version tracked per URL and the
+ * local-path → URL binding that makes "same file path ⇒ same page" hold) lives in this factory's closure,
+ * fresh per run, never checkpointed.
+ */
+import { type PermissionMode } from "../../core/ask-origin.js";
+import { type EngineNotice } from "../../core/engine-notice.js";
 import { type ArtifactHost, type ArtifactHostCapabilities } from "../../core/artifact-host.js";
 import { type OnAsk } from "../../core/tool-policy.js";
 import type { ToolSpec } from "../../core/types.js";
@@ -42,6 +51,14 @@ export interface ArtifactToolOptions {
      *  = the run has no ask face, and a shared read is then REFUSED fail-closed (`artifact.refused`, content withheld) —
      *  never silently delivered. */
     onAsk?: OnAsk;
+    /** The run's effective permission mode, read at each shared-read consent (a steer moves it). The consent ask is
+     *  arbitrated as the gate's asks are (class `artifact_shared_read`): `bypassPermissions` RELEASES the read — delivered,
+     *  announced once per run through `onNotice`, and NOT remembered as an approval (a mode release is not a person's
+     *  nod; a later `default` leg asks) — `dontAsk` refuses it, every other mode asks the approver. Absent ⇒ no arbitration
+     *  (the approver decides, or the read is withheld with none). */
+    permissionMode?: () => PermissionMode;
+    /** The notice sink the release account rides (`permission.ask_released_by_mode`, once per run for this class). */
+    onNotice?: (notice: EngineNotice) => void;
 }
 /** Supporting files per publish (upstream cap); enforced in the schema AND in the body, for callers that bypass the schema. */
 export declare const MAX_FILES_PER_PUBLISH = 255;