@sema-agent/core 7.50.2 → 7.51.0

package/dist/core/session-policy-store.d.ts

@@ -14,26 +14,37 @@
  *   (mirrors `steer.trusted`); core never adjudicates operator-ness, it only honors the flag.
  * - **CAS rev** (optimistic concurrency): a `putRules` with a stale `expectedRev` is rejected, so two replicas
  *   can't lose an update (mirrors the checkpoint store's `resolve` OCC).
- * - **structured fields only**: core interprets `toolAllow/Deny`, `allowDirs`, `commandAllow/Deny` (argv[0]
- *   names). A richer rule DSL is the service's/profile's job — core grows no rule interpreter.
- * - **NOT A SANDBOX**: command rules inherit the coarse argv[0] matching (wrappers like `sh -c`/`sudo` circumvention);
- *   the real isolation boundary is the executionEnv, never these rules.
+ * - **one grammar**: the two rule buckets hold rule ENTRIES — the grammar every entry list reads, through its one reader
+ *   (`readRuleEntry`, allow-entry.ts): a tool name, a protocol namespace, a shell command rule (`Bash(git push:*)`), a
+ *   path rule, a name or host rule. Entries are stored as written; every station that validates, compares, matches or
+ *   names one reads that reader's answer ({@link judgeSessionRulesWrite}, {@link loosenReasons}, the run-time layer).
+ * - **NOT A SANDBOX**: a shell command rule reads the command line the call carries (every program run in its connector
+ *   chain); the real isolation boundary is the executionEnv, never these rules.
  */
-import { type RuleToolNameVerdict } from "./tool-name-aliases.js";
-/** The structured per-session rules. All optional; an absent field imposes no constraint of that kind. */
+import { type AllowEntryInertDetail, type AllowEntryInertReason } from "./allow-entry.js";
+/** The per-session rules. All optional; an absent bucket imposes no constraint of that kind. */
 export interface SessionPermissionRules {
-    /** If set, ONLY these tool names are allowed (others denied). A narrowing allowlist. */
+    /** If set, ONLY the calls these entries admit are allowed — a narrowing allowlist: a call no entry admits is refused.
+     *  Rule entries read in the allow direction (`Read`, `mcp__srv`, `Bash(git:*)`, `Edit(src/**)`). */
     toolAllow?: string[];
-    /** Tool names always denied (deny wins). */
+    /** Entries whose calls are always refused (deny wins) — rule entries read in the deny direction (`Bash`, `Bash(rm:*)`,
+     *  `mcp__srv__delete_*`, `Read(//etc/**)`). */
     toolDeny?: string[];
     /** If set, WRITE tools (`Write`/`Edit`) may only target paths within these dirs; a write-capable
      *  tool that can't be path-confined (e.g. `Bash`) is denied while this is set. Stored RAW; resolved at run time. */
     allowDirs?: string[];
-    /** If set, ONLY these `Bash` command names (argv[0]) are allowed. */
-    commandAllow?: string[];
-    /** `Bash` command names (argv[0]) always denied. */
-    commandDeny?: string[];
 }
+/** Every bucket a rules object holds, and how its entries are read: a rule-entry list in one direction, or the write
+ *  confinement's directories. A key outside this table is no bucket ({@link readSessionRulesShape} refuses it). */
+declare const SESSION_RULE_BUCKETS: {
+    readonly toolAllow: "allow";
+    readonly toolDeny: "deny";
+    readonly allowDirs: "dirs";
+};
+/** A bucket that holds rule entries. */
+export type SessionRuleEntryField = {
+    [K in keyof typeof SESSION_RULE_BUCKETS]: (typeof SESSION_RULE_BUCKETS)[K] extends "dirs" ? never : K;
+}[keyof typeof SESSION_RULE_BUCKETS];
 /** {@link SessionPermissionRules} plus the monotonic `rev` the store stamps (the OCC key). */
 export interface StoredSessionRules extends SessionPermissionRules {
     rev: number;
@@ -52,58 +63,42 @@ export interface PutRulesOptions {
      *  this from a verified, role-checked principal (mirrors `steer.trusted`). */
     operator?: boolean;
 }
-/** The {@link SessionPolicyError.detail} of a tool-name refusal: which bucket, which entry, the judgment's word, the judgment's
- *  one-line sentence when it has one, and the spelling to write instead when the judgment has one (a retired name's 1:1
- *  successor, an unmintable segment's minted name). */
-export interface SessionRuleNameRefusal {
-    field: SessionRuleToolNameField;
-    name: string;
-    verdict: Exclude<RuleToolNameVerdict["kind"], "current">;
-    /** The `guidance` of the judgment ({@link judgeRuleToolName}), byte for byte — the same string the refusal's sentence quotes. Present for
-     *  `retired` and `unmintable_segment`, the two verdicts that carry one; absent for `unprefixed_namespace`, whose judgment has no sentence of its own. */
-    guidance?: string;
-    currentName?: string;
+/** The {@link SessionPolicyError.detail} of an `invalid_shape` refusal: which key, and what it holds — its TYPE, never its
+ *  value (`a string`, `null`, `an array holding an entry that is not a string`), or `not a rule bucket` for a key outside
+ *  the buckets. `field` is empty when the rules value itself is not an object. */
+export interface SessionRuleShapeRefusal {
+    field: string;
+    got: string;
+}
+/** The {@link SessionPolicyError.detail} of an `inert_entry` refusal: which bucket, which entry, and why it reads as nothing —
+ *  the entry reader's own answer (`readRuleEntry`), reason and facts unchanged. */
+export interface SessionRuleEntryRefusal extends AllowEntryInertDetail {
+    field: SessionRuleEntryField;
+    entry: string;
+    reason: AllowEntryInertReason;
 }
 /** Typed error from {@link SessionPolicyStore.putRules}. `conflict` = stale `expectedRev`; `loosen_forbidden`
- *  = a non-operator write tried to relax the rules; `corrupt` = a backend could not read the erase-surviving
- *  rev mark ({@link SessionPolicyStore.deleteBySession}) and refuses rather than stamp an unproven rev; the fourth
- *  code = a tool-name bucket names a retired name, a prefix-less `__` name or a segment no mint spells (an empty one, or a peer spelled otherwise)
- *  ({@link assertSessionRuleNamesCurrent}) — `detail` is present on that code and only on it. */
+ *  = a non-operator write tried to relax the rules; `corrupt` = a backend could not read what it stored (a row, or the
+ *  erase-surviving rev mark of {@link SessionPolicyStore.deleteBySession}) and refuses rather than read it as fewer rules or
+ *  stamp an unproven rev; `invalid_shape` = the rules value is not an object of buckets, each a list of strings
+ *  ({@link readSessionRulesShape}); `inert_entry` = a bucket holds an entry the entry reader reads as nothing. `detail` is
+ *  present on the last two codes and only on them ({@link SessionRuleShapeRefusal}, {@link SessionRuleEntryRefusal}). */
 export declare class SessionPolicyError extends Error {
-    readonly code: "conflict" | "loosen_forbidden" | "corrupt" | "legacy_tool_name";
-    readonly detail?: SessionRuleNameRefusal | undefined;
-    constructor(code: "conflict" | "loosen_forbidden" | "corrupt" | "legacy_tool_name", message: string, detail?: SessionRuleNameRefusal | undefined);
+    readonly code: "conflict" | "loosen_forbidden" | "corrupt" | "invalid_shape" | "inert_entry";
+    readonly detail?: (SessionRuleShapeRefusal | SessionRuleEntryRefusal) | undefined;
+    constructor(code: "conflict" | "loosen_forbidden" | "corrupt" | "invalid_shape" | "inert_entry", message: string, detail?: (SessionRuleShapeRefusal | SessionRuleEntryRefusal) | undefined);
 }
-/** Which buckets hold TOOL names (the ones a run's policy audit reads as names); a new bucket is given a role here. */
-declare const HOLDS_TOOL_NAMES: {
-    readonly toolAllow: true;
-    readonly toolDeny: true;
-    readonly allowDirs: false;
-    readonly commandAllow: false;
-    readonly commandDeny: false;
-};
-type SessionRuleToolNameField = {
-    [K in keyof typeof HOLDS_TOOL_NAMES]: (typeof HOLDS_TOOL_NAMES)[K] extends true ? K : never;
-}[keyof typeof HOLDS_TOOL_NAMES];
 /** Construction options both bundled stores take. */
 export interface SessionPolicyStoreOptions {
-    /** The names this deployment mounts its OWN tools under — the roster the store judges a rule's tool names against
-     *  ({@link judgeRuleToolName}): a retired name declared here is an ordinary name to the write and to the loosening
-     *  check alike. Absent = none. A name carrying `__` is refused, as it is for a deployment tool. */
+    /** The names this deployment mounts its OWN tools under — the roster the store reads a rule entry's tool name against
+     *  (`readRuleEntry`): a retired name declared here is an ordinary name to the write and to the loosening check alike.
+     *  Absent = none. A name carrying `__` is refused, as it is for a deployment tool. */
     mountedToolNames?: Iterable<string>;
 }
 /** A store's declared roster from {@link SessionPolicyStoreOptions.mountedToolNames} — the one reader both bundled stores
  *  (and so `FileStorageBackendOptions.sessionPolicy`) construct through, refusing loudly when it is not a list of plain
  *  tool names (a bare string would iterate by character). */
 export declare function readMountedToolNames(value: unknown): ReadonlySet<string>;
-/**
- * The write judge for session rules, against `mountedToolNames` (the store's declaration; empty when it has none): every
- * entry of a tool-name bucket must be `current` ({@link judgeRuleToolName}), or the write is refused (the fourth
- * {@link SessionPolicyError} code) — such a name matches no tool, and a run's policy audit refuses to start with it.
- * Operator writes included. Both bundled stores call it after normalizing and before {@link loosenReasons}; a durable
- * backend calls it at the same point. The message names the entry and the way out, never a storage location.
- */
-export declare function assertSessionRuleNamesCurrent(rules: SessionPermissionRules, mountedToolNames?: ReadonlySet<string>): void;
 /**
  * The seam a deployment implements for DURABLE, cross-replica per-session rules. Unset on `RunnerDeps` ⇒ the
  * feature is OFF (no rules read, zero behavior change). Keyed on `(sessionId, principal-owner)`: core passes
@@ -118,11 +113,9 @@ export interface SessionRulesRecord {
 }
 export interface SessionPolicyStore {
     getRules(sessionId: string, principal?: string): Promise<StoredSessionRules | null>;
-    /** Write the rules for a key: CAS on `expectedRev`, then the name judge ({@link assertSessionRuleNamesCurrent} —
-     *  operator writes included), then, for a non-operator write over an existing row, the
-     *  tighten-only check ({@link loosenReasons}) — both against the names the deployment declares it mounts its own
-     *  tools under. A bucket that is not a list of strings (a bare `"rm"` for `commandDeny`) throws a `TypeError` from
-     *  {@link normalizeRules} before any of those is judged, and nothing is written. */
+    /** Write the rules for a key through the one write judge ({@link judgeSessionRulesWrite}): CAS on `expectedRev`, the
+     *  shape, every entry's reading (operator writes included), then, for a non-operator write over an existing row, the
+     *  tighten-only check — each refusal a {@link SessionPolicyError}, and nothing is written. */
     putRules(sessionId: string, principal: string | undefined, rules: SessionPermissionRules, opts?: PutRulesOptions): Promise<StoredSessionRules>;
     /**
      * 2c session-sync: every (principal, rules) record for `sessionId` across ALL principals — `getRules`
@@ -172,21 +165,47 @@ export interface SessionPolicyStore {
  * backend should keep `allowDirs` to real directories; a future symlink-aware write-time canonicalize closes it.
  */
 declare function lexWithin(root: string, p: string): boolean;
-/** Normalize a rules object's `allowDirs` (lexical `posix.normalize`) so stored rules are `..`-free and the
- *  tighten diff compares the same canonical-ish form the runtime resolves. Every bucket must be a list of strings
- *  ({@link ruleList}); a bucket that is not one throws `TypeError`, so neither bundled store (nor a durable twin that
- *  normalizes through this function) can store a rule list the matcher would read differently from the one written. */
-export declare function normalizeRules(rules: SessionPermissionRules): SessionPermissionRules;
 /**
- * Pure tighten-only diff: the reasons `next` LOOSENS `prior` (empty ⇒ `next` is a pure tightening or no-op).
- * Direction per field — deny-lists: removing an entry loosens, except a `toolDeny` entry that is not `current` against
- * `mountedToolNames` ({@link judgeRuleToolName}: it matches no tool, so removing it relaxes nothing — the way a session's owner
- * takes out a stale entry that stops every run). allowlists: removing the list (→ everything allowed) or adding an
- * entry outside the prior set loosens; prior-undefined → any defined next only narrows. allowDirs: removing
- * confinement, or adding a dir not within some prior dir, loosens (coarse raw containment). `mountedToolNames` = the
- * store's declaration ({@link SessionPolicyStoreOptions.mountedToolNames}; empty when it has none) — the write judge's too.
+ * THE ONE SHAPE READING of a rules value — what every station that takes one reads it through: the write (incoming rules),
+ * a store's read-back of its own rows, the tighten comparison's prior, the run-time layer's served row. A rules value is an
+ * object whose keys are buckets ({@link SessionPermissionRules}); each bucket present is a list of strings (`allowDirs`: of
+ * non-blank strings — a directory is no blank). A bucket's TYPE is all this reads: what an entry means is the entry reader's.
+ * The store's own stamps (`rev`, `gen`) are passed over, and a key holding `undefined` holds nothing. Anything else is a fault,
+ * named by key and by TYPE, never by value — a bare string is never one rule and never its characters (`"rm"` spread into
+ * `["r","m"]`), and a key outside the buckets is never dropped (a dropped deny is a deny nobody enforces).
+ */
+export declare function readSessionRulesShape(value: unknown): {
+    rules: SessionPermissionRules;
+} | {
+    fault: SessionRuleShapeRefusal;
+    sentence: string;
+};
+/** The CANONICAL stored form of a rules value: its shape read ({@link readSessionRulesShape} — a fault refuses with
+ *  `invalid_shape`), every list copied (detached from the caller's arrays), and `allowDirs` lexically `posix.normalize`d so the
+ *  stored form is `..`-free and the tighten diff compares the form the runtime resolves. Both bundled stores and a durable twin
+ *  stamp exactly this, so a structuredClone and a JSON round-trip of it are byte-identical. */
+export declare function normalizeRules(rules: unknown): SessionPermissionRules;
+/**
+ * THE ONE WRITE JUDGE every store applies before it stamps a row (both bundled stores, and a durable backend at the same point):
+ * the rules to stamp, or a {@link SessionPolicyError}, in this order — `conflict` (a stale `expectedRev` against `prior`'s rev),
+ * `invalid_shape` ({@link normalizeRules}), `inert_entry` (an entry the reader reads as nothing; operator writes included — a
+ * rule that names nothing guards nothing whoever writes it), then, for a non-operator write over an existing row,
+ * `loosen_forbidden` ({@link loosenReasons}) — or `corrupt` when that prior cannot be read as rules, which the comparison never
+ * reads as fewer. `mountedToolNames` = the store's declaration ({@link SessionPolicyStoreOptions.mountedToolNames}).
+ */
+export declare function judgeSessionRulesWrite(prior: StoredSessionRules | null, rules: unknown, opts: PutRulesOptions | undefined, mountedToolNames?: ReadonlySet<string>): SessionPermissionRules;
+/**
+ * Pure tighten-only diff: the reasons `next` LOOSENS `prior` (empty ⇒ `next` is a pure tightening or no-op), over the EFFECTIVE
+ * entries of each rule bucket — the list as the run-time layer enforces it ({@link effectiveEntries}). An entry that reads as
+ * nothing is in neither side's effect, so removing one relaxes nothing and adding one widens nothing (the way a session's owner
+ * takes out an entry that names nothing); an allowlist a `*` voids admits nothing, so dropping the `*` widens. toolDeny: removing an effective entry loosens. toolAllow: removing the list
+ * (→ everything allowed) or adding an effective entry outside the prior set loosens; prior-undefined → any defined next only
+ * narrows. allowDirs: removing confinement, or adding a dir not within some prior dir, loosens (coarse raw containment).
+ * Entries compare as written. Both sides are read through {@link readSessionRulesShape} first: a side it cannot read (a key that
+ * is no bucket — a retired one included) throws `invalid_shape` rather than compare without it. `mountedToolNames` = the store's
+ * declaration ({@link SessionPolicyStoreOptions.mountedToolNames}; empty when it has none) — the write judge's too.
  */
-export declare function loosenReasons(prior: SessionPermissionRules, next: SessionPermissionRules, mountedToolNames?: ReadonlySet<string>): string[];
+export declare function loosenReasons(priorValue: SessionPermissionRules, nextValue: SessionPermissionRules, mountedToolNames?: ReadonlySet<string>): string[];
 /**
  * Does row `a` belong to the SAME lineage as row `b` — the one question every reader asks before it compares
  * two rows' `rev`, asked in ONE place so a `gen` that is ABSENT cannot mean three different things at three
@@ -205,8 +224,6 @@ export declare function continuesLineage(a: {
 }, b: {
     gen?: number;
 }): boolean;
-/** strip any caller-passed `rev` from a rules object so the store is the sole authority on it. */
-export declare function stripRev(rules: SessionPermissionRules): SessionPermissionRules;
 /**
  * In-process default {@link SessionPolicyStore} (single-replica). A deployment that needs cross-replica
  * durability supplies its own backend with the SAME CAS-rev + tighten-only semantics. Single-threaded JS makes

package/dist/core/session-policy-store.js

@@ -1,7 +1,12 @@
 import { posix } from "node:path";
 import { isWinFormPath } from "../tools/fs/safety.js";
 import { NAMESPACED_NAME_SHAPES, carriesNamespaceSeparator } from "./protocol-table.js";
-import { judgeRuleToolName } from "./tool-name-aliases.js";
+import { compileAllowList, inertEntryPhrase, readRuleEntry, renderListEntry } from "./allow-entry.js";
+import { valueTypeLabel } from "./tool-name-list.js";
+const SESSION_RULE_BUCKETS = { toolAllow: "allow", toolDeny: "deny", allowDirs: "dirs" };
+const BUCKETS = Object.keys(SESSION_RULE_BUCKETS);
+const ENTRY_FIELDS = BUCKETS.filter((f) => SESSION_RULE_BUCKETS[f] !== "dirs");
+const STORE_STAMPS = new Set(["rev", "gen"]);
 export class SessionPolicyError extends Error {
     code;
     detail;
@@ -12,8 +17,6 @@ export class SessionPolicyError extends Error {
         this.name = "SessionPolicyError";
     }
 }
-const HOLDS_TOOL_NAMES = { toolAllow: true, toolDeny: true, allowDirs: false, commandAllow: false, commandDeny: false };
-const TOOL_NAME_FIELDS = Object.keys(HOLDS_TOOL_NAMES).filter((f) => HOLDS_TOOL_NAMES[f]);
 const NO_DECLARED_TOOLS = new Set();
 export function readMountedToolNames(value) {
     if (value === undefined)
@@ -33,35 +36,6 @@ export function readMountedToolNames(value) {
     }
     return names;
 }
-export function assertSessionRuleNamesCurrent(rules, mountedToolNames = NO_DECLARED_TOOLS) {
-    for (const field of TOOL_NAME_FIELDS) {
-        for (const name of rules[field] ?? []) {
-            const verdict = judgeRuleToolName(name, mountedToolNames);
-            if (verdict.kind === "current")
-                continue;
-            const quoted = JSON.stringify(name);
-            const successor = verdict.kind === "unprefixed_namespace" ? undefined : verdict.currentName;
-            const guidance = verdict.kind === "unprefixed_namespace" ? undefined : verdict.guidance;
-            let message;
-            switch (verdict.kind) {
-                case "retired":
-                    message = `session rules ${field} names ${quoted}, a retired tool name (${verdict.guidance}) — with it in place no run of this session could start, so nothing was written.${successor !== undefined ? ` Use the current name ${JSON.stringify(successor)}.` : ""} If this deployment mounts its own tool under ${quoted}, declare it in the store's mountedToolNames.`;
-                    break;
-                case "unprefixed_namespace":
-                    message = `session rules ${field} names ${quoted}, which carries the "__" namespace separator but no protocol prefix — no tool is named that way (protocol tools are named ${NAMESPACED_NAME_SHAPES}), and with it in place no run of this session could start, so nothing was written.`;
-                    break;
-                case "unmintable_segment":
-                    message = `session rules ${field} names ${quoted}, which can match no tool (${verdict.guidance}) — with it in place no run of this session could start, so nothing was written.${successor !== undefined ? ` Write ${JSON.stringify(successor)}.` : ""}`;
-                    break;
-                default: {
-                    const exhaustive = verdict;
-                    return exhaustive;
-                }
-            }
-            throw new SessionPolicyError("legacy_tool_name", message, { field, name, verdict: verdict.kind, ...(guidance !== undefined ? { guidance } : {}), ...(successor !== undefined ? { currentName: successor } : {}) });
-        }
-    }
-}
 function lexWithin(root, p) {
     const fold = (x) => {
         let n = isWinFormPath(x) ? x.replace(/\\/g, "/") : x;
@@ -75,61 +49,109 @@ function lexWithin(root, p) {
         return true;
     return np === nr || np.startsWith(nr + "/");
 }
-function ruleList(field, value) {
-    if (value === undefined)
-        return undefined;
-    const refuse = (got) => {
-        throw new TypeError(`session rules ${field} must be an array of strings, got ${got} — a rule list is written as a list of names (["rm"], not "rm")`);
-    };
-    if (Array.isArray(value) && Array.from(value).every((entry) => typeof entry === "string")) {
-        if (value.some((entry) => entry.trim() === ""))
-            refuse("an array holding an empty or blank entry");
-        return value;
+export function readSessionRulesShape(value) {
+    const fault = (field, got, sentence) => ({ fault: { field, got }, sentence });
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        const got = Array.isArray(value) ? "an array" : valueTypeLabel(value);
+        return fault("", got, `session rules must be an object of rule buckets (${BUCKETS.join(", ")}), got ${got}`);
     }
-    return refuse(Array.isArray(value) ? "an array holding an entry that is not a string" : value === null ? "null" : `a ${typeof value}`);
+    const rules = {};
+    for (const [key, v] of Object.entries(value)) {
+        if (STORE_STAMPS.has(key) || v === undefined)
+            continue;
+        if (!Object.hasOwn(SESSION_RULE_BUCKETS, key)) {
+            return fault(key, "not a rule bucket", `session rules hold ${JSON.stringify(key)}, which is not a rule bucket — the buckets are ${BUCKETS.join(", ")}, and a shell command rule is a toolDeny / toolAllow entry written Bash(<command>) (Bash(rm:*) refuses every run of rm)`);
+        }
+        const field = key;
+        const listed = Array.isArray(v) ? Array.from(v) : undefined;
+        const got = listed === undefined
+            ? valueTypeLabel(v)
+            : !listed.every((e) => typeof e === "string")
+                ? "an array holding an entry that is not a string"
+                : SESSION_RULE_BUCKETS[field] === "dirs" && listed.some((e) => e.trim() === "")
+                    ? "an array holding an empty or blank entry"
+                    : undefined;
+        if (got !== undefined)
+            return fault(field, got, `session rules ${field} must be an array of ${SESSION_RULE_BUCKETS[field] === "dirs" ? "directory paths" : "rule entries"}, got ${got} — a bucket is written as a list (["Bash(rm:*)"], not "Bash(rm:*)")`);
+        rules[field] = listed;
+    }
+    return { rules };
 }
 export function normalizeRules(rules) {
+    const read = readSessionRulesShape(rules);
+    if ("fault" in read)
+        throw new SessionPolicyError("invalid_shape", read.sentence, read.fault);
     const out = {};
-    const toolAllow = ruleList("toolAllow", rules.toolAllow);
-    const toolDeny = ruleList("toolDeny", rules.toolDeny);
-    const commandAllow = ruleList("commandAllow", rules.commandAllow);
-    const commandDeny = ruleList("commandDeny", rules.commandDeny);
-    const allowDirs = ruleList("allowDirs", rules.allowDirs);
-    if (toolAllow !== undefined)
-        out.toolAllow = [...toolAllow];
-    if (toolDeny !== undefined)
-        out.toolDeny = [...toolDeny];
-    if (commandAllow !== undefined)
-        out.commandAllow = [...commandAllow];
-    if (commandDeny !== undefined)
-        out.commandDeny = [...commandDeny];
-    if (allowDirs !== undefined)
-        out.allowDirs = allowDirs.map((d) => posix.normalize(d).replace(/\/+$/, "") || "/");
+    for (const field of BUCKETS) {
+        const list = read.rules[field];
+        if (list === undefined)
+            continue;
+        out[field] = SESSION_RULE_BUCKETS[field] === "dirs" ? list.map((d) => posix.normalize(d).replace(/\/+$/, "") || "/") : [...list];
+    }
     return out;
 }
-export function loosenReasons(prior, next, mountedToolNames = NO_DECLARED_TOOLS) {
-    const reasons = [];
-    for (const field of ["toolDeny", "commandDeny"]) {
-        const n = new Set(next[field] ?? []);
-        for (const x of prior[field] ?? []) {
-            if (n.has(x) || (field === "toolDeny" && judgeRuleToolName(x, mountedToolNames).kind !== "current"))
+function effectiveEntries(field, list, mountedToolNames) {
+    return compileAllowList(list ?? [], SESSION_RULE_BUCKETS[field], mountedToolNames).rows.map((r) => r.entry);
+}
+function assertEntriesRead(rules, mountedToolNames) {
+    for (const field of ENTRY_FIELDS) {
+        for (const entry of rules[field] ?? []) {
+            const read = readRuleEntry(entry, SESSION_RULE_BUCKETS[field], mountedToolNames);
+            if (read.kind === "row")
                 continue;
-            reasons.push(`removed ${field} "${x}"`);
+            const { kind: _kind, ...why } = read;
+            void _kind;
+            const way = why.verdict === "retired"
+                ? ` If this deployment mounts its own tool under ${renderListEntry(entry)}, declare it in the store's mountedToolNames.`
+                : why.currentName === undefined
+                    ? ` An entry is a tool name (Read; a protocol tool is named ${NAMESPACED_NAME_SHAPES}), a protocol namespace (mcp__<server>), or a rule in its tool's own grammar (Bash(<command>), Edit(<path>), Skill(<name>), WebFetch(domain:<host>)).`
+                    : "";
+            const sentence = why.guidance !== undefined ? ` — ${why.guidance}` : "";
+            throw new SessionPolicyError("inert_entry", `session rules ${field} holds ${inertEntryPhrase({ entry, ...why })}, which ${SESSION_RULE_BUCKETS[field] === "deny" ? "refuses" : "admits"} nothing as written${sentence}; nothing was written.${way}`, { field, entry, ...why });
         }
     }
-    for (const field of ["toolAllow", "commandAllow"]) {
-        const p = prior[field];
-        if (p === undefined)
-            continue;
-        const n = next[field];
-        if (n === undefined) {
-            reasons.push(`removed ${field} allowlist (all allowed)`);
-            continue;
+}
+export function judgeSessionRulesWrite(prior, rules, opts, mountedToolNames = NO_DECLARED_TOOLS) {
+    if (opts?.expectedRev !== undefined && (prior?.rev ?? 0) !== opts.expectedRev) {
+        throw new SessionPolicyError("conflict", `session rules rev mismatch (expected ${opts.expectedRev}, have ${prior?.rev ?? 0})`);
+    }
+    const clean = normalizeRules(rules);
+    assertEntriesRead(clean, mountedToolNames);
+    if (prior !== null && opts?.operator !== true) {
+        const stored = readSessionRulesShape(prior);
+        if ("fault" in stored) {
+            throw new SessionPolicyError("corrupt", `the stored session rules cannot be read as rules (${stored.sentence}) — refusing to judge a non-operator write against them as fewer rules; an operator write replaces them`);
+        }
+        const loosens = loosenReasons(stored.rules, clean, mountedToolNames);
+        if (loosens.length > 0) {
+            throw new SessionPolicyError("loosen_forbidden", `a non-operator session-rule write may only tighten; refused: ${loosens.join("; ")}`);
+        }
+    }
+    return clean;
+}
+export function loosenReasons(priorValue, nextValue, mountedToolNames = NO_DECLARED_TOOLS) {
+    const shapeOf = (side, value) => {
+        const read = readSessionRulesShape(value);
+        if ("fault" in read)
+            throw new SessionPolicyError("invalid_shape", `the ${side} rules: ${read.sentence}`, read.fault);
+        return read.rules;
+    };
+    const prior = shapeOf("prior", priorValue);
+    const next = shapeOf("next", nextValue);
+    const reasons = [];
+    const keptDeny = new Set(effectiveEntries("toolDeny", next.toolDeny, mountedToolNames));
+    for (const x of effectiveEntries("toolDeny", prior.toolDeny, mountedToolNames))
+        if (!keptDeny.has(x))
+            reasons.push(`removed toolDeny ${renderListEntry(x)}`);
+    if (prior.toolAllow !== undefined) {
+        if (next.toolAllow === undefined)
+            reasons.push("removed toolAllow allowlist (all allowed)");
+        else {
+            const had = new Set(effectiveEntries("toolAllow", prior.toolAllow, mountedToolNames));
+            for (const x of effectiveEntries("toolAllow", next.toolAllow, mountedToolNames))
+                if (!had.has(x))
+                    reasons.push(`widened toolAllow with ${renderListEntry(x)}`);
         }
-        const ps = new Set(p);
-        for (const x of n)
-            if (!ps.has(x))
-                reasons.push(`widened ${field} with "${x}"`);
     }
     const pd = prior.allowDirs;
     if (pd !== undefined && pd.length > 0) {
@@ -146,11 +168,6 @@ export function loosenReasons(prior, next, mountedToolNames = NO_DECLARED_TOOLS)
 export function continuesLineage(a, b) {
     return (a.gen ?? 0) === (b.gen ?? 0);
 }
-export function stripRev(rules) {
-    const { ...rest } = rules;
-    delete rest.rev;
-    return rest;
-}
 export class InMemorySessionPolicyStore {
     map = new Map();
     mountedToolNames;
@@ -168,17 +185,7 @@ export class InMemorySessionPolicyStore {
     async putRules(sessionId, principal, rules, opts) {
         const key = this.key(sessionId, principal);
         const prior = this.map.get(key);
-        if (opts?.expectedRev !== undefined && (prior?.rev ?? 0) !== opts.expectedRev) {
-            throw new SessionPolicyError("conflict", `session rules rev mismatch (expected ${opts.expectedRev}, have ${prior?.rev ?? 0})`);
-        }
-        const clean = normalizeRules(stripRev(rules));
-        assertSessionRuleNamesCurrent(clean, this.mountedToolNames);
-        if (prior && opts?.operator !== true) {
-            const loosens = loosenReasons(prior, clean, this.mountedToolNames);
-            if (loosens.length > 0) {
-                throw new SessionPolicyError("loosen_forbidden", `a non-operator session-rule write may only tighten; refused: ${loosens.join("; ")}`);
-            }
-        }
+        const clean = judgeSessionRulesWrite(prior ?? null, rules, opts, this.mountedToolNames);
         const mark = this.highWater.get(key) ?? { rev: 0, gen: 0 };
         const floor = Math.max(prior?.rev ?? 0, mark.rev);
         const gen = prior?.gen ?? mark.gen;

package/dist/core/shell-read-silence.d.ts

@@ -1,6 +1,40 @@
 import type { ShellReadVerdict } from "../tools/fs/shell-read-check.js";
+import { type ShellReadDisposition } from "../tools/fs/shell-read-judge.js";
 import type { GatePass } from "./runner/gate-exit.js";
 import type { AskGuard } from "./tool-policy.js";
+/** One station answer, received and read: what a reader acts on (`kind`) and the answer it acts on (`verdict` — the engine's own
+ *  copy, received once). `unbelieved`: the station's answer was not received or contradicted its own finding, and `verdict` is the
+ *  engine's refusal of it (its sentence names the station's words only where they are words of the closed sets — nothing a station
+ *  spelled reaches the model), reported once on the call's lane ({@link StationAnswerCall.report}). */
+export interface StationAnswerReading {
+    readonly kind: ShellReadDisposition | "silence";
+    readonly verdict: ShellReadVerdict;
+    readonly unbelieved?: true;
+}
+/** The call a reader reads an answer for: its name (the refusal names it), its id, and the lane a station's failure is reported on
+ *  (absent ⇒ unreported — the resumed leg reads the engine's own stations). */
+export interface StationAnswerCall {
+    readonly toolName: string;
+    readonly toolCallId?: string;
+    readonly report?: (err: Error) => void;
+}
+/**
+ * Receive and read a station's answer — the ONE reading for every reader. The answer is received whole ({@link receivedAnswer}:
+ * the engine's one receipt for a caller's object, then each member by its kind — none of the caller's code runs) into the engine's
+ * copy every later read is of; an answer that is not received (an accessor, a member its prototype or a non-enumerable property
+ * supplies, a Proxy anywhere in it, a word that is no string, a mark that is not `true`, not an object) is not believed. Then, in order:
+ *  · `refuse` stands, whatever beside it: no reading is stricter;
+ *  · the station's SILENCE — the finding `unanswered`, or nothing found (`none`) beside a silence mark (`environmentSilent`,
+ *    `rowsUnread`): the station made no finding, whatever disposition it spelled beside it (the engine's own station spells a
+ *    vouch beside unread rows as `unanswered`);
+ *  · a disposition the decision table does not give the finding on any seat, under any form of the question
+ *    ({@link dispositionsOfRow}) — a `vouch` beside a deny hit, an ask beside one, a word outside the closed sets — is NOT believed:
+ *    the station's answer contradicts its own finding, and the reader refuses the call;
+ *  · otherwise the disposition, as the table gives it.
+ * A silence mark beside a finding the station DID make is not the silence: it classes that finding's question
+ * ({@link silencedBy}).
+ */
+export declare function readStationAnswer(answer: ShellReadVerdict, call: StationAnswerCall): StationAnswerReading;
 /** Whose silence a station's answer carries, each its own class on the question it keeps or mints: unread rows are a rule that could
  *  not be read (the rule lane's class); the finding `unanswered` is, unless rows are unread, the environment's silence — shell text the
  *  engine cannot read (a guard) — and the marks only pick whose. Either is a question only a person answers; `probe` follows the finding. */
@@ -12,10 +46,10 @@ export declare function silencedBy(verdict: ShellReadVerdict, d: {
     guards?: readonly AskGuard[];
     requiresRealApproval?: true;
 };
-/** The finding `unanswered` IS the silence, applied once, before any disposition arm: a station — a host-mounted one included — may
- *  spell `vouch` or `mandated` beside it, and neither word vouches for what nobody judged. A deny stands; an ask keeps its words and
- *  gains the silence's class; an allow becomes the silence's question (`ask.message`), one only a person answers. Nothing is admitted,
- *  no `probe` is stamped and no grant is offered — the station made no finding. */
+/** The station's SILENCE ({@link readStationAnswer}), applied once, before any disposition arm: a station — a host-mounted one
+ *  included — may spell `vouch`, `mandated` or `ordinary` beside it, and no word vouches for what nobody judged. A deny stands; an
+ *  ask keeps its words and gains the silence's class; an allow becomes the silence's question (`ask.message`), one only a person
+ *  answers. Nothing is admitted, no `probe` is stamped and no grant is offered — the station made no finding. */
 export declare function applyUnansweredSilence(pass: GatePass, verdict: ShellReadVerdict, ask: {
     readonly message: string;
     readonly account: string | undefined;