@sema-agent/core 7.33.7 → 7.34.0

package/dist/core/hooks.d.ts

@@ -1071,22 +1071,20 @@ export interface PersistedRuleHit {
     readonly rules: readonly PersistedRuleHitRule[];
 }
 /**
- * design/252 G-2 — the answer a lane gives when it could not READ its store.
+ * design/252 G-2 — the answer a lane gives when it could not READ its store (no `reason`; the CALL form is `reason`'s).
  *
- * Its DECISION meaning is identical to "no rule" — a loosening seam that cannot read its source fails
- * toward asking, and this shape changes no verdict anywhere. What it changes is the RECORD: without it,
- * an unreadable rule store and a store that genuinely holds no matching rule are the same answer
- * (`undefined`), and the ask's evidence has to report one of them as the other. The absence vocabulary
- * distinguishes "we looked and found nothing" (`"no_match"`) from "we could not look" (`"unavailable"`),
- * and this is how a lane says which one it means.
+ * The store form's DECISION meaning is identical to "no rule": the store's rows — allow, ask and deny alike — take
+ * no part in this call's decision (skipped, the way a settings file with errors is skipped whole; the lane announces
+ * it, and the rows apply again once a read succeeds). What it changes is the RECORD: without it, an unreadable store
+ * and a store that holds no matching rule are the same answer (`undefined`), and the ask's evidence would report one
+ * as the other — `"no_match"` ("we looked and found nothing") vs `"unavailable"` ("we could not look").
  */
 export interface PersistedRuleUnreadable {
     readonly unreadable: true;
-    /** WHY the lane could not read: absent for a store read failure; for a call the lane could not READ
-     *  against the person's standing deny/ask rows (an expansion where a rule reads a word, an unterminated
-     *  quote, a syntax error — `programRunReachOf`'s `unreadable` word), the lexer's reason. The DECISION
-     *  is the same fail-closed one either way (the question "does one of my rules forbid this?" is
-     *  unanswered); the reason is what the ask's message says instead of "the store could not be read". */
+    /** WHY the lane could not read: absent for a store read failure (its rows take no part); for a CALL the lane could
+     *  not read against the person's standing deny/ask rows (an expansion where a rule reads a word, an unterminated quote,
+     *  a syntax error — `programRunReachOf`'s `unreadable` word), the lexer's reason — the call then fails closed: an allow
+     *  tightens to a real-approval ask of origin `rule_store_unavailable`, the reason in its message. */
     readonly reason?: string;
 }
 /**
@@ -1349,8 +1347,8 @@ export interface ToolGateInput {
     onHookError?: (err: unknown) => void;
     /**
      * design/134 R5: true when this tool's `irreversibility` tier was installed by the ENGINE'S SHELL SEAT
-     * (the read-boundary judge under every doctrine, plus the `TaskSpec.shellGate` doctrine's residual-risk
-     * classifier — design/80 D-E; the seat's `shellGatedTools` membership), not an explicit per-tool mark —
+     * (the read-boundary judge on every shell face, plus the shape tier on every full shell and the
+     * `TaskSpec.shellGate: "always"` floor — design/80 D-E; the seat's `shellGatedTools` membership), not an explicit per-tool mark —
      * attributes a tighten-deny to `source:"shellGate"` instead of `"safety"`.
      */
     shellGated?: boolean;
@@ -1386,7 +1384,8 @@ export interface ToolGateInput {
      * POLICY-class member of the fold: a deny-listed read is REFUSED (`deniedBy: "read_boundary"`, composing
      * under `deny > ask > allow`), an out-of-root or unestablishable read tightens a surviving allow to a
      * MANDATED ask (or marks an existing ask mandated), a read the station declined to judge tightens to an
-     * ordinary ask on the classify seat and a mandated one on the off seat, and a vouched call is untouched.
+     * ordinary ask on the full shell face (under `auto` the classifier answers it, shown the read-deny table) and
+     * is refused on the read-only face, and a vouched call is untouched.
      * `null` SYNCHRONOUSLY for a call it does not cover (no suspension point there), a promise for a shell
      * call. Absent ⇒ no station (no shell mounted) and the decision path is byte-identical.
      */
@@ -1395,10 +1394,9 @@ export interface ToolGateInput {
      * design/143 批2 (A, CC 2.1.207 auto mode): when present, a surviving `ask` is routed to the
      * small-model policy CLASSIFIER before any human/durable resolution:
      *  - verdict `allow` → the ask resolves to allow (`decisionReason:"classifier"`) — no suspend, no onAsk;
-     *  - verdict `block` → deny (`decisionReason:"classifier"`, `source:"classifier"`; CC `automode-blocked`);
-     *  - `unavailable`/`parse_error` → FAIL-CLOSED: the ask continues down the ORIGINAL chain
-     *    (durable suspend / onAsk / headless auto-deny) exactly as if auto mode were absent
-     *    (CC `automode-unavailable`/`automode-parsing-error` — "NOT a policy decision").
+     *  - verdict `block` → deny (`decisionReason:"classifier"`, `source:"classifier"`; CC `automode-blocked`); `parse_error` too;
+     *  - `unavailable` → where `unavailable.approvalSeat` (a person, live or parked) the ask goes on, its text saying why;
+     *    else CC's refusal (`cause: "unavailable"`). Never counted by the denial limit (`classifierUnavailableArm`).
      * SCOPE (declared semantic): this covers every surviving ask INCLUDING the deterministic egress/
      * irreversibility safety tightens — auto mode is the deployment's explicit choice to let the
      * classifier be the "explicit ask-resolution" for this session (its rule set covers exactly those
@@ -1425,7 +1423,32 @@ export interface ToolGateInput {
          * `RunnerDeps.autoMode.denialLimit`; a host driving the gate directly may hand its own.
          */
         denialTracking?: AutoModeDenialTracker;
+        unavailable?: import("./classifier-unavailable-arm.js").ClassifierUnavailableSeat;
     };
+    /**
+     * The leg's EFFECTIVE permission mode, read at every arbitration (a steer changes the next call's answer). The
+     * gate's one mode read point sits after the classifier and the sandbox leg and before the park / resolution:
+     * `bypassPermissions` releases every non-immune class (`GateDisposition.released`), `dontAsk` refuses every ask
+     * but a hook's or an operator authority's (`deniedBy: "mode"`), the other modes hand the ask on. ABSENT ⇒ no
+     * arbitration (a host driving the gate directly keeps the pre-mode chain); the classifier station then reads
+     * `autoMode` presence alone as the arming fact.
+     */
+    permissionMode?: () => import("./ask-origin.js").PermissionMode;
+    /** WHO put the tool's egress / irreversibility marks on the seat ({@link import("./ask-origin.js").ToolMarkSource});
+     *  absent or empty with a mark present reads as the deployment's own (fail-closed: an operator's mandate). */
+    toolMarkSources?: ReadonlySet<import("./ask-origin.js").ToolMarkSource>;
+    /** The deployment's A2A peer-isolation switch: a set switch makes the A2A egress default an operator mandate. */
+    a2aIsolatePeers?: boolean;
+    /** Observe a mode RELEASE (fired before the released allow leaves the arbitration point; `readUnestablished`: the read station could not establish what the call reads). Observe-only. */
+    onModeReleased?: (info: {
+        toolName: string;
+        toolCallId: string;
+        release: import("./gate-outcome.js").ModeRelease;
+        readUnestablished?: true;
+    }) => void;
+    /** An ancestor station's arbitration of this call (the inherited lane arbitrates inside the fold and records
+     *  here); the exit reads it onto the disposition when the gate's own point did not arbitrate. */
+    ancestorArbitrationOf?: (toolCallId: string) => import("./ask-origin.js").Arbitration | undefined;
     /**
      * The HEADLESS arm of the denial-limit fallback: the fallback ask was resolved by a deny no
      * person made (no approver wired; a blanket `"allow"` refused as no approver; an approver that
@@ -1456,6 +1479,7 @@ export interface ToolGateInput {
         toolCallId: string;
         cause: import("./ask-unresolvable-notice.js").AskUnresolvableCause;
         parkLaneExisted: boolean;
+        remedy?: string;
     }) => void;
     /**
      * design/153 §2/§7.4 (件4 复审, MED): true means this call's ask is MARKED — an inherited ancestor
@@ -1506,7 +1530,7 @@ export interface ToolGateInput {
      *  · #502: an ask the call's own reversibility probe declared STRUCTURAL (`probeMandated`) joins that
      *    family. It is the one PER-CALL member of it, and the reason there has to be one: the built-in
      *    shell probe raises it for a read outside the session's allowed directories, which is a boundary
-     *    the deployment declared but which arrives wearing the classify doctrine's own "maybe" tier —
+     *    the deployment declared but which arrives wearing the shape tier's own "maybe" —
      *    the very tier the bullet below keeps as this lane's home turf. Without a per-call member, a
      *    compound was cleared segment-wise by the conjunction arm and an out-of-root read plus a sender
      *    ran on two ordinary standing rules with no question asked.
@@ -1521,12 +1545,11 @@ export interface ToolGateInput {
      */
     persistedRules?: {
         /** The lane's verdict for this call — a {@link PersistedRuleHit} naming the behavior that spoke and
-         *  the rule set it stands on, a coverage-carrying clean negative, an unreadable-store report, or
+         *  the rule set it stands on, a coverage-carrying clean negative, an unreadable report, or
          *  `undefined` (the store was READ and no rule speaks). Must not throw — and a store that cannot be
-         *  read answers `{ unreadable: true }`, NEVER `undefined`: the gate reads the unreadable report as
-         *  fail-closed (an allow tightens to a real-approval ask of origin `rule_store_unavailable`), while
-         *  `undefined` is a successful no-match that leaves an allow standing. An adapter that answers
-         *  `undefined` on a read failure silently disarms every deny/ask row it holds.
+         *  read answers `{ unreadable: true }`, not `undefined`: the DECISION is the same (its rows take no part, as
+         *  for a thrown or timed-out lane) but the evidence records `"unavailable"`, not `"no_match"`; the lane owns
+         *  announcing the skip. A call unreadable against the rows answers `{ unreadable: true, reason }` (fails closed).
          *
          *  For an ALLOW the set is the COVERAGE SET — each member's canonical text plus its add DOTS. A
          *  single rule admitting the whole command is a one-element set; a compound admitted by the
@@ -1708,14 +1731,13 @@ export interface AskCarry {
     /** The surviving ask's engine-stamped origin word ({@link import("./ask-origin.js").AskOrigin}), persisted
      *  on the row so a durable card is rendered by the same word the synchronous card is. */
     readonly origin?: import("./ask-origin.js").AskOrigin;
-    /** #688 C3: the mechanism behind an `origin: "rule_store_unavailable"` (`store` / `call`), persisted on the row
-     *  so a durable card says the same thing the synchronous card does. */
-    readonly ruleStoreUnreadable?: import("./ask-origin.js").RuleStoreUnreadable;
     /** The stamped mandate ({@link import("./tool-policy.js").AskRequest.mandated}) — the park site's
      *  rule-offer facts read it, so a parked mandated ask offers no rule, like the live card. */
     readonly mandated?: true;
     /** The table word stamped beside it ({@link import("./tool-policy.js").AskRequest.mandate}), for the row's twin. */
     readonly mandate?: import("./ask-origin.js").PersistedRuleMandate;
+    /** The deployment's authorship ({@link import("./tool-policy.js").AskRequest.authoredBy}), for the row's twin. */
+    readonly authoredBy?: "deployment";
 }
 /** What a durable row persists of an {@link AskCarry}: the fallback member COPIED (the row never aliases
  *  the gate's object; its window is already `0` — the gate's carry mint is the one writer of that
@@ -1724,7 +1746,6 @@ export interface AskCarry {
 export declare function askCarryRowMembers(carry: AskCarry | undefined): {
     denialLimitFallback?: import("./auto-mode.js").DenialLimitFallback;
     origin?: import("./ask-origin.js").AskOrigin;
-    ruleStoreUnreadable?: import("./ask-origin.js").RuleStoreUnreadable;
 };
 /**
  * The design/37 **two-phase tool gate** — the single chokepoint that makes the load-bearing invariant

package/dist/core/hooks.js

@@ -7,7 +7,7 @@ import { runGateLanes } from "./gate-lanes.js";
 export { normalizeOrgGateVerdict, normalizePersistedRuleHit } from "./gate-lanes.js";
 export { cloneObserverInput } from "./runner/gate-exit.js";
 import { brandPolicyAskClass } from "./ask-class.js";
-import { isAskOrigin, isRuleStoreUnreadable } from "./ask-origin.js";
+import { isAskOrigin } from "./ask-origin.js";
 import { inlineUntrusted } from "./untrusted-text.js";
 export { formatHookFeedback } from "./reminder-mint.js";
 import { createSafeNotifier } from "./safe-notify.js";
@@ -238,11 +238,9 @@ export function askCarryRowMembers(carry) {
     if (carry === undefined)
         return {};
     const origin = carry.origin;
-    const ruleStoreUnreadable = carry.ruleStoreUnreadable;
     return {
         ...(carry.denialLimitFallback !== undefined ? { denialLimitFallback: { ...carry.denialLimitFallback } } : {}),
         ...(isAskOrigin(origin) ? { origin } : {}),
-        ...(isRuleStoreUnreadable(ruleStoreUnreadable) ? { ruleStoreUnreadable } : {}),
     };
 }
 export async function runToolGate(input) {

package/dist/core/mcp.js

@@ -1671,7 +1671,7 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
             parameters: (effectiveInputSchema ?? { type: "object" }),
             ...(mcpMaxResultSizeChars !== undefined ? { mcpMaxResultSizeChars } : {}),
             ...(mcpAlwaysLoad ? { mcpAlwaysLoad: true } : {}),
-            mcpRemoteName: remoteName,
+            mcpRemoteName: remoteName, ...(t.annotations?.readOnlyHint === true ? { mcpReadOnlyHint: true } : {}),
             execute: async (_toolCallId, params, signal) => {
                 const what = `The call to tool ${inlineUntrusted(remoteName)}`;
                 if (isServerRevoked?.(spec.name) === true) {

package/dist/core/mode-policy.d.ts

@@ -0,0 +1,182 @@
+/**
+ * The permission MODE's two derivations, beside the arbitration that reads it (`ask-origin.ts`):
+ *
+ *  - {@link modePolicyOf} — what a mode INSTALLS on the leg: the plan pair and the mode's own write gate (the
+ *    reference implementation's per-mode defaults: `plan` keeps every tool mounted and ASKS at the call for a write
+ *    and for a tool it did not define that is not read-only, `acceptEdits` writes inside the root without asking,
+ *    `default` / `auto` / `dontAsk` ask on every covered write — auto's classifier and dontAsk's refusal then act on
+ *    that ask — and `bypassPermissions` installs no gate). One writer of the mode (the caller, the steer verb, the
+ *    model's `EnterPlanMode`), one interpreter (this engine): a library embedder's `plan` is not a word a serving
+ *    layer has to translate first.
+ *  - {@link PermissionModeController} — the one RESOLUTION of a leg's effective mode, read live by every mode
+ *    consumer (the gate's arbitration, the mode gate policy, the manifest, the children's ceiling): the
+ *    requested word, clamped under the parent's live ceiling, folded back to `default` where the deployment
+ *    denies it or the arming face is absent. A steer rewrites the requested word; nothing caches the answer.
+ */
+import type { AgentTool, ExecutionEnv } from "../internal/harness-types.js";
+import type { ContainmentFace } from "../tools/fs/containment-face.js";
+import type { ToolCallRequest, ToolPolicy } from "./tool-policy.js";
+import { type ToolRoster } from "./tool-roster.js";
+import { type PermissionMode } from "./ask-origin.js";
+import type { RuntimeCaps } from "./runtime-caps.js";
+/** WHY an effective mode is not the requested one: the deployment's deny bit (`RuntimeCaps.bypassPermissions` /
+ *  `RuntimeCaps.autoMode`), a requested `auto` with no classifier face wired, or a child's declaration folded under
+ *  its parent's ceiling. */
+export declare const PERMISSION_MODE_FOLD_REASONS: readonly ["operator_deny", "face_absent", "inherited_ceiling"];
+export type PermissionModeFoldReason = (typeof PERMISSION_MODE_FOLD_REASONS)[number];
+/** The mode's seats on a leg. `writeGate`: `none` — no mode write gate; `ask` — every covered write asks;
+ *  `accept_root` — writes inside the leg's write roots (the task root and every additional working directory) are allowed,
+ *  writes outside them ask; `plan` — every write {@link planRefusesWrite} names is the mode's OWN question (the plan
+ *  sentence, `decisionReason: "mode"`: a person may say yes, no rule and no automatic lane answers it). `fileCommands`: the
+ *  shell commands whose ordinary question the mode answers itself ({@link modeAcceptsFileCommand}) — the reference
+ *  implementation's `acceptEdits` set ("auto-approve file edits and common file commands"); empty for every other mode.
+ *  `writeFace`: the write face the mode states where no seat declared one (the mode row of {@link import("../tools/fs/containment-face.js").resolveContainmentFace}) —
+ *  `bypassPermissions` writes outside the write roots (`open`); every other mode states nothing and the default fence stands. */
+export interface ModePolicy {
+    readonly enablePlanMode: boolean;
+    readonly writeGate: "none" | "ask" | "accept_root" | "plan";
+    readonly fileCommands: readonly string[];
+    readonly writeFace: ContainmentFace | undefined;
+}
+/** The `acceptEdits` file commands, verbatim from the reference implementation (2.1.280): a closed set. */
+export declare const ACCEPT_EDITS_FILE_COMMANDS: readonly ["mkdir", "touch", "rm", "rmdir", "mv", "cp", "sed"];
+/** The mode → seats table, total over {@link PermissionMode}. */
+export declare function modePolicyOf(mode: PermissionMode): ModePolicy;
+/**
+ * Is this call a shell command the mode's {@link ModePolicy.fileCommands} cover — every segment a SIMPLE command
+ * whose command word is, as written, one of them? The reference implementation's reading (it compares the first
+ * word of each command against its list): no redirection, no pipe or background, no substitution, no leading
+ * assignment, no wrapper in front, a literal unquoted command word — `/bin/rm` and `"rm"` are not `rm`. The answer
+ * is only ever a license for the mode to answer the call's ORDINARY question: the gate's arbitration reads it beside
+ * the class set and the read station's `writesPlaced` fact (every write target established inside the write roots, no
+ * removal of a root, every program in the text), so a deny rule, an ask rule, the delete guard, a read-boundary finding
+ * or a write the station could not place still stands. A `run_in_background` call is not accepted (as a `&` is not).
+ */
+export declare function modeAcceptsFileCommand(mode: PermissionMode, toolName: string, args: unknown): boolean;
+/** What the mode gate policy resolves paths against. `acceptDirs` = the leg's WRITE ROOTS (the task root plus every additional
+ *  working directory), the set `acceptEdits` allows writes inside — absent ⇒ the root alone; `exemptDirs` = the task's scratchpad,
+ *  never asked about; `roster` = the leg's live tool roster (who defined the called tool and its effect) and `readOnlyDeclared` =
+ *  whether the mounted tool of that name declares itself read-only, both read per call by {@link planRefusesWrite}. */
+export interface ModeGateSeats {
+    env: ExecutionEnv;
+    rootPath: string;
+    acceptDirs?: readonly string[];
+    exemptDirs?: readonly string[];
+    roster?: {
+        readonly current: ToolRoster | undefined;
+    };
+    readOnlyDeclared?: (toolName: string) => boolean;
+}
+/** Does the LAST mounted instance of this name (the one a call dispatches to) declare itself read-only — an MCP server's
+ *  `readOnlyHint` ({@link AgentTool.mcpReadOnlyHint})? The mode gate's `readOnlyDeclared` seat over the leg's live tools. */
+export declare function mountedToolDeclaresReadOnly(tools: readonly AgentTool[], toolName: string): boolean;
+/**
+ * Is this call a WRITE the `plan` mode asks about? Two faces, one question — does the call write by its declaration:
+ *  · a covered path write (the catalog's protective floor: a file-write tool, or a same-name tool wearing its slot), and
+ *  · a call to a tool the engine does not define (a caller's, an MCP server's, an A2A peer's) that is not read-only — the
+ *    reference implementation's plan arm for a tool it did not write (`!isReadOnly` ⇒ the mode). Read-only is the tool's
+ *    effect on the leg's roster being `read`, or — only where that effect is the fail-closed default (nobody declared one)
+ *    — the mounted tool's own read-only declaration (`readOnlyDeclared`: an MCP server's `readOnlyHint`, which the
+ *    reference reads for this question). A declared effect (the tool's own, or the deployment's `toolAxes`) always
+ *    outranks the server's claim; the effect is the repeat-safety axis a server's self-claim never lowers.
+ * The engine's own tools answer through their own seats: a child a delegation spawns inherits `plan` as its ceiling, and
+ * the shell station and the tool marks raise their own questions, which reach a person under `plan` as under `default`.
+ * A name the roster does not carry dispatches nowhere and is not judged here.
+ */
+export declare function planRefusesWrite(req: ToolCallRequest, roster: ToolRoster | undefined, readOnlyDeclared?: (toolName: string) => boolean): boolean;
+/**
+ * The mode's WRITE GATE as one live policy layer: every call reads the mode ref and dispatches to the gate the
+ * table names for it, so a steer changes the next call's gate without re-composing the chain. The three gates are
+ * built once (their root / exemption screens run at construction). The plan gate is the ask gate with the plan
+ * sentence in place of the ordinary write question: the same structural exemptions (the scratchpad, the advertised
+ * writable roots — the reference exempts its scratchpad and agent-memory files under plan too) admit a write, everything
+ * else the mode names asks.
+ */
+export declare function createModeGatePolicy(modeRef: {
+    readonly current: PermissionMode;
+}, seats: ModeGateSeats): ToolPolicy;
+/**
+ * The mode a resumed leg REQUESTS: the re-passed spec's word, else the word the checkpoint row recorded — except where the
+ * resume approves or edits a `plan_review` over a row recorded in `plan`: the plan exits to the word the leg had before it
+ * (`prePlanMode`, the reference implementation's ExitPlanMode: `prePlanMode ?? "default"`; absent ⇒ the leg's own default),
+ * unless the resume names another mode — the approver's choice. A re-passed `plan` does not keep an approved plan open.
+ */
+export declare function modeRequestAfterResume(seat: PermissionMode | undefined, recorded: {
+    readonly permissionMode?: PermissionMode;
+    readonly prePlanMode?: PermissionMode;
+}, outcome: {
+    readonly gate: string;
+    readonly decision?: string;
+} | undefined): PermissionMode | undefined;
+/** The three-member answer every mode question gets — the manifest member, the steer verb's return value and the
+ *  fold notice's detail share it. `requested` is absent when the caller declared nothing (a root inherits `default`,
+ *  a child inherits its parent). */
+export interface PermissionModeReceipt {
+    readonly requested?: PermissionMode;
+    readonly effective: PermissionMode;
+    readonly foldedBy?: PermissionModeFoldReason;
+}
+/** The arming facts the controller folds a declared mode against, bound once the deployment's caps resolved. */
+export interface PermissionModeArming {
+    readonly caps: Pick<RuntimeCaps, "bypassPermissions" | "autoMode"> | undefined;
+    readonly autoFacePresent: boolean;
+    /** Arm the classifier for a leg whose effective mode became `auto` after prepare (a steer, a parent's live ceiling);
+     *  idempotent. A failed arming leaves no classifier: a steer is rolled back and rejects with the failure; an arming a
+     *  read started (no caller awaits it) reports it through {@link onArmFault}. */
+    readonly armAuto?: () => Promise<void> | void;
+    /** Where an arming a read of {@link PermissionModeController.current} started reports its failure. Observe-only: a throw
+     *  or a rejection from it is contained. */
+    readonly onArmFault?: (error: unknown) => void;
+}
+/** A live ceiling: the parent leg's own controller (`current` tracks the parent's steers), or a recorded word. */
+export type PermissionModeCeiling = {
+    readonly current: PermissionMode;
+} | PermissionMode;
+/**
+ * The one resolution of a leg's effective mode. `current` is derived on every read from three inputs —
+ * the requested word (the spec's, or the newest steer's whose arming has not failed), the ceiling (a parent's live controller, or the
+ * word a checkpoint recorded) and the arming facts — so a parent's steer reaches a running child on the
+ * child's next read with no forwarding, and nothing holds a stale answer.
+ */
+export declare class PermissionModeController {
+    private readonly requestedBySpec;
+    private readonly ceiling;
+    /** The steers that still count, oldest first: each is pending (its arming running) or took effect. A steer whose
+     *  arming fails leaves the list; one that takes effect drops the older ones (a newer steer that took effect outranks
+     *  them whatever they do next). */
+    private readonly steers;
+    private arming;
+    private readonly onFold;
+    private prePlan;
+    constructor(requestedBySpec: PermissionMode | undefined, ceiling: PermissionModeCeiling | undefined, opts?: {
+        onFold?: (receipt: PermissionModeReceipt) => void;
+        prePlanMode?: PermissionMode;
+    });
+    /** The declared word the leg had when a steer (or the model's `EnterPlanMode`) last moved it into `plan`, while it is
+     *  there; a leg that started in plan has none, and a steer out of plan clears it. A checkpoint row records it. */
+    get prePlanMode(): PermissionMode | undefined;
+    /** The word the caller asked for right now: the newest steer that still counts, else the spec's. */
+    get requested(): PermissionMode | undefined;
+    private ceilingNow;
+    /** The declared mode after the ceiling clamp — what a checkpoint records and what the leg's children inherit. */
+    get declared(): PermissionMode;
+    private declaration;
+    private armedForAuto;
+    /** Contains the fault observer: its synchronous throw and its rejection both stop here. */
+    private readonly faultSeat;
+    /** The effective mode: declared, then folded against the arming facts. A read that finds the leg in `auto` with its
+     *  classifier not yet armed (a parent's steer reached this child through the live ceiling) starts the arming — idempotent,
+     *  not awaited: the call that observed the transition may still meet the person, the next one meets the classifier. A
+     *  failure goes to {@link PermissionModeArming.onArmFault}; the leg then has no classifier, so its asks go on to the
+     *  approval seat as under `default`. */
+    get current(): PermissionMode;
+    /** The three-member answer as it stands right now. */
+    receipt(): PermissionModeReceipt;
+    /** Bind the deployment's arming facts (once, after the caps resolved); announces a fold-back if one results. */
+    bindArming(arming: PermissionModeArming): PermissionModeReceipt;
+    /** A steer: the requested word changes; the arming fold is re-judged; a leg that became `auto` arms its classifier.
+     *  When that arming fails the steer rejects with the failure, stops counting (the requested word is again the newest
+     *  steer's that still counts, else the spec's — a failed arming never undoes another steer, and never leaves the leg
+     *  in `auto` on its own word), and the arming may start again on the leg's next move into `auto`. */
+    steer(mode: PermissionMode): Promise<PermissionModeReceipt>;
+}

package/dist/core/mode-policy.js

@@ -0,0 +1,179 @@
+import { createFsWriteGatePolicy } from "./fs-write-gate-policy.js";
+import { isProtectedWrite } from "./tool-registry.js";
+import { rosterEntryNamed } from "./tool-roster.js";
+import { clampPermissionMode } from "./ask-origin.js";
+import { argvOf, lexShellText } from "../shell/lex.js";
+import { COMMAND_RULE_TOOL } from "./permission-rule-model.js";
+import { createSafeNotifier } from "./safe-notify.js";
+export const PERMISSION_MODE_FOLD_REASONS = ["operator_deny", "face_absent", "inherited_ceiling"];
+export const ACCEPT_EDITS_FILE_COMMANDS = ["mkdir", "touch", "rm", "rmdir", "mv", "cp", "sed"];
+const MODE_POLICY_TABLE = {
+    plan: { enablePlanMode: true, writeGate: "plan", fileCommands: [], writeFace: undefined },
+    acceptEdits: { enablePlanMode: false, writeGate: "accept_root", fileCommands: ACCEPT_EDITS_FILE_COMMANDS, writeFace: undefined },
+    default: { enablePlanMode: false, writeGate: "ask", fileCommands: [], writeFace: undefined },
+    auto: { enablePlanMode: false, writeGate: "ask", fileCommands: [], writeFace: undefined },
+    dontAsk: { enablePlanMode: false, writeGate: "ask", fileCommands: [], writeFace: undefined },
+    bypassPermissions: { enablePlanMode: false, writeGate: "none", fileCommands: [], writeFace: "open" },
+};
+export function modePolicyOf(mode) {
+    return MODE_POLICY_TABLE[mode];
+}
+export function modeAcceptsFileCommand(mode, toolName, args) {
+    const commands = modePolicyOf(mode).fileCommands;
+    if (commands.length === 0 || toolName !== COMMAND_RULE_TOOL)
+        return false;
+    const command = args?.command;
+    if (typeof command !== "string" || args.run_in_background === true)
+        return false;
+    const lexed = lexShellText(command);
+    if ("reject" in lexed || lexed.segments.length === 0 || lexed.substitutions.length > 0)
+        return false;
+    return lexed.segments.every((segment) => {
+        if (segment.connector === "|" || segment.connector === "&" || segment.tokens.some((t) => t.kind !== "word"))
+            return false;
+        const head = argvOf(segment)[0];
+        return head !== undefined && head.assignment === undefined && head.expansions.length === 0 && head.raw === head.folded && commands.includes(head.raw);
+    });
+}
+export function mountedToolDeclaresReadOnly(tools, toolName) {
+    return tools.findLast((t) => t.name === toolName)?.mcpReadOnlyHint === true;
+}
+const ENGINE_ROSTER_SOURCES = new Set(["builtin", "synthetic"]);
+export function planRefusesWrite(req, roster, readOnlyDeclared) {
+    if (isProtectedWrite(req))
+        return true;
+    const row = roster === undefined ? undefined : rosterEntryNamed(roster, req.toolName);
+    return row !== undefined && !ENGINE_ROSTER_SOURCES.has(row.source) && row.effect !== "read" && !(row.effectProvenance === "default" && readOnlyDeclared?.(row.name) === true);
+}
+const planAsk = (message) => ({ action: "ask", message, decisionReason: "mode" });
+export function createModeGatePolicy(modeRef, seats) {
+    const exemptDirs = seats.exemptDirs !== undefined && seats.exemptDirs.length > 0 ? { exemptDirs: seats.exemptDirs } : {};
+    const askGate = createFsWriteGatePolicy({ env: seats.env, rootPath: seats.rootPath, ...exemptDirs, defaultWrite: "ask" });
+    const acceptRootGate = createFsWriteGatePolicy({ env: seats.env, rootPath: seats.rootPath, acceptDirs: seats.acceptDirs !== undefined && seats.acceptDirs.length > 0 ? [...seats.acceptDirs] : [seats.rootPath], ...exemptDirs, defaultWrite: "ask" });
+    const planGate = createFsWriteGatePolicy({ env: seats.env, rootPath: seats.rootPath, ...exemptDirs, defaultWrite: "ask", defaultAsk: (path, note) => planAsk(`Cannot write to ${path} while in plan mode.${note ?? ""}`) });
+    return {
+        async check(req, signal) {
+            const gate = modePolicyOf(modeRef.current).writeGate;
+            if (gate === "none")
+                return { action: "allow" };
+            if (gate === "plan") {
+                if (!planRefusesWrite(req, seats.roster?.current, seats.readOnlyDeclared))
+                    return { action: "allow" };
+                if (!isProtectedWrite(req))
+                    return planAsk(`Cannot call ${req.toolName} while in plan mode.`);
+                return planGate.check(req, signal);
+            }
+            return (gate === "ask" ? askGate : acceptRootGate).check(req, signal);
+        },
+    };
+}
+export function modeRequestAfterResume(seat, recorded, outcome) {
+    const exitsPlan = outcome?.gate === "plan_review" && outcome.decision !== "reject" && recorded.permissionMode === "plan";
+    if (!exitsPlan)
+        return seat ?? recorded.permissionMode;
+    return seat !== undefined && seat !== "plan" ? seat : recorded.prePlanMode;
+}
+export class PermissionModeController {
+    requestedBySpec;
+    ceiling;
+    steers = [];
+    arming;
+    onFold;
+    prePlan;
+    constructor(requestedBySpec, ceiling, opts) {
+        this.requestedBySpec = requestedBySpec;
+        this.ceiling = ceiling;
+        this.onFold = opts?.onFold;
+        if (requestedBySpec === "plan")
+            this.prePlan = opts?.prePlanMode;
+    }
+    get prePlanMode() {
+        return this.declared === "plan" ? this.prePlan : undefined;
+    }
+    get requested() {
+        return this.steers.at(-1)?.word ?? this.requestedBySpec;
+    }
+    ceilingNow() {
+        return this.ceiling === undefined ? undefined : typeof this.ceiling === "string" ? this.ceiling : this.ceiling.current;
+    }
+    get declared() {
+        return this.declaration().effective;
+    }
+    declaration() {
+        const ceiling = this.ceilingNow();
+        if (ceiling === undefined)
+            return { effective: this.requested ?? "default", clamped: false };
+        return clampPermissionMode(this.requested, ceiling);
+    }
+    armedForAuto = false;
+    faultSeat = createSafeNotifier();
+    get current() {
+        const effective = this.receipt().effective;
+        const arming = this.arming;
+        if (effective === "auto" && !this.armedForAuto && arming?.armAuto !== undefined) {
+            this.armedForAuto = true;
+            void new Promise((resolve) => resolve(arming.armAuto?.())).catch((e) => this.faultSeat.notifyAsync(() => arming.onArmFault?.(e), "permissionMode.onArmFault"));
+        }
+        return effective;
+    }
+    receipt() {
+        const { effective: declared, clamped } = this.declaration();
+        const requested = this.requested;
+        const base = requested !== undefined ? { requested } : {};
+        const a = this.arming;
+        const armingFold = a === undefined
+            ? undefined
+            : declared === "bypassPermissions" && a.caps?.bypassPermissions === false
+                ? "operator_deny"
+                : declared === "auto" && !a.autoFacePresent
+                    ? "face_absent"
+                    : declared === "auto" && a.caps?.autoMode === false
+                        ? "operator_deny"
+                        : undefined;
+        if (armingFold !== undefined)
+            return { ...base, effective: "default", foldedBy: armingFold };
+        if (clamped)
+            return { ...base, effective: declared, foldedBy: "inherited_ceiling" };
+        return { ...base, effective: declared };
+    }
+    bindArming(arming) {
+        const before = this.receipt();
+        this.arming = arming;
+        const receipt = this.receipt();
+        if (receipt.foldedBy !== undefined && receipt.foldedBy !== before.foldedBy)
+            this.onFold?.(receipt);
+        return receipt;
+    }
+    async steer(mode) {
+        const entry = { word: mode };
+        const before = this.declared;
+        this.steers.push(entry);
+        const receipt = this.receipt();
+        const arming = this.arming;
+        if (receipt.effective === "auto" && arming?.armAuto !== undefined) {
+            this.armedForAuto = true;
+            try {
+                await arming.armAuto();
+            }
+            catch (e) {
+                this.armedForAuto = false;
+                const at = this.steers.indexOf(entry);
+                if (at >= 0)
+                    this.steers.splice(at, 1);
+                throw e;
+            }
+        }
+        const at = this.steers.indexOf(entry);
+        if (at > 0)
+            this.steers.splice(0, at);
+        if (this.steers.at(-1) === entry) {
+            if (mode !== "plan")
+                this.prePlan = undefined;
+            else if (before !== "plan")
+                this.prePlan = before;
+        }
+        if (receipt.foldedBy !== undefined)
+            this.onFold?.(receipt);
+        return receipt;
+    }
+}

package/dist/core/oracle-isolation.d.ts

@@ -10,7 +10,7 @@
  *   checks), and the {@link OracleIsolationVerdict}.isolationClass tiering that CAPS a non-isolated grader at
  *   `candidate_only` (never auto-accept).
  * - SERVICE: the actually-isolated grader env (E2B microVM with `capabilities.isolation === true`), minted by
- *   the trusted control plane through {@link import("./types.js").RunnerDeps.graderEnvFactory}.
+ *   the trusted control plane and handed to the repair loop as its grader env (the engine has no seat for it).
  *
  * 🔴 **Honest residual (design/77 §1 Residual + §9):** the bash write-probe is point-in-time and
  * necessary-not-sufficient — core, running *inside the worker*, cannot prove a mount is truly immutable (it
@@ -37,8 +37,8 @@ export interface OracleIsolationVerdict {
     reason?: string;
 }
 /**
- * The isolated grader environment, provisioned by the trusted control plane. `provenance` is settable ONLY at
- * the {@link import("./types.js").RunnerDeps.graderEnvFactory} call site — it is NEVER reconstructed from
+ * The isolated grader environment, provisioned by the trusted control plane. `provenance` is settable ONLY by
+ * the trusted control plane that mints the grader env — it is NEVER reconstructed from
  * worker-visible state (a worker that could mint a `{provenance:'control_plane'}` object would defeat the whole
  * gate). `immutableOraclePaths` are the paths the oracle/spec is supposed to live behind (e.g. a hidden held-out
  * test dir) that the worker must not be able to corrupt; the bash write-probe (check C) targets them.

package/dist/core/permission-rule-model.d.ts

@@ -558,6 +558,18 @@ export declare function isUsablePathBase(base: string | undefined, family: PathF
  * no root reached nothing at all).
  */
 export declare function pathRuleReachOf(rule: Pick<PersistedRule, "match" | "command" | "behavior">, target: PathIdentity, bases: PathRuleBases): ProgramRunReachOutcome;
+/**
+ * Where a path rule's reach STARTS under the call's bases — its HEAD: the location the resolved pattern names before
+ * its first segment carrying `*` (the whole path when none does), or a directory rule's directory. Everything the rule
+ * reaches lies at or below the head, so a spelling of the head that the environment resolves elsewhere (a link, a
+ * firmlink, `/var` → `/private/var`) is a second spelling of everything the rule reaches — the deny tables judge the
+ * rule at both ({@link import("../tools/fs/read-deny.js").withRuleRowsWhereTheyLead}; the reference's "physical twin"
+ * of a rule prefix, cli280.js 9766583). The head may be the bare anchor (`/`, a drive or share root — `Read(/**)` at a
+ * drive root): an environment can resolve a drive or share root elsewhere. `undefined`: the pattern needs a base the
+ * call does not supply (the rule then reads `unreadable`, a reach, everywhere), or a directory rule names the bare
+ * anchor (it admits nothing).
+ */
+export declare function pathRuleHeadOf(rule: Pick<PersistedRule, "match" | "command" | "behavior">, bases: PathRuleBases): PathIdentity | undefined;
 /**
  * Does this rule's command pattern admit `command`?
  *
@@ -793,7 +805,8 @@ export declare function eligiblePersisted(rule: PersistedRule, call: {
  *     found BEFORE any conjunction: reporting one rule is narrower than reporting a set;
  *  3. the conjunction arm, compounds only: every segment must be admitted by some eligible rule under
  *     the MATCH reading (the allow side's own under-approximating instrument — never the deny side's
- *     wider PROGRAM_RUNS reading). Per segment the FIRST table-order admitting rule is selected, and
+ *     wider PROGRAM_RUNS reading), or be a read-only segment that allows itself ({@link readsOnlyAsSegment});
+ *     at least one rule must speak. Per segment the FIRST table-order admitting rule is selected, and
  *     the coverage set is those selections in segment order, de-duplicated — the same command against
  *     the same rule table always names the same set (reporting-order determinism, the historical
  *     "order is defined only for reporting" contract extended to sets).
@@ -832,8 +845,8 @@ export interface PersistedRuleVerdict {
     readonly rules: readonly PersistedRule[];
     /** The call could not be READ against the person's deny/ask rows (see {@link programRunReachOf}):
      *  `behavior` is `ask`, `rules` names the first tightening row that could not be judged, and this is
-     *  the lexer's reason. The lane projects it as an UNREADABLE answer — the same fail-closed shape an
-     *  unreadable store takes — never as a matched ask rule. */
+     *  the lexer's reason. The lane projects it as an UNREADABLE answer carrying that reason (it fails closed)
+     *  — never as a matched ask rule. */
     readonly unreadable?: string;
 }
 /**