@sema-agent/core 7.51.2 → 7.53.0

package/dist/core/secret-env.js

@@ -1,6 +1,9 @@
-import { CREDENTIAL_VOCABULARY, envNameView, splitCamelCase } from "./credential-vocabulary.js";
+import { createHash } from "node:crypto";
+import { types } from "node:util";
+import { CREDENTIAL_MIN_CHARS, CREDENTIAL_VOCABULARY, envNameView, isSensitiveHeaderName, splitCamelCase } from "./credential-vocabulary.js";
 import { DEFAULT_INHERITED_ENV_VARS } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { deliverEngineNotice } from "./engine-notice.js";
+import { receiveOwnProperties } from "./own-property-receipt.js";
 const GIT_CONFIG_ENV_RE = /^GIT_CONFIG_(?:COUNT|PARAMETERS|(?:KEY|VALUE)_[0-9]+)$/;
 const PROXY_ENV_RE = /^(?:(?:https?|ftp|all|no)_proxy|npm_config_(?:https?_)?proxy|npm_config_noproxy|yarn_proxy|(?:yarn|global_agent|docker|claude_code)_(?:https?|no)_proxy|cloudsdk_proxy_[a-z]+|electron_get_use_proxy)$/i;
 function isExemptEnvName(name) {
@@ -66,13 +69,14 @@ function carriesSchemelessUserinfo(text) {
     const at = text.lastIndexOf("@", text.search(/\s|$/));
     return !isHostPortPathBeforeAt(text.slice(0, at), text.slice(at + 1)) && !/^(?:mailto|sips?|xmpp|im|acct):/i.test(text);
 }
-const CREDENTIAL_ASSIGNMENT_RE = /(?:(?:^|[;&?#,{]|\/:)\s*|\s)["']?(?!-*jobserver-auth\s*[=:])(?:[a-z0-9_.-]{0,64}(?:password|passwd|pwd|secret|token|(?:account|access|api|private|subscription)[-_]?key|signature|sig|credential)|[a-z0-9_.-]{0,63}[_.-]auth)["']?\s*[=:]\s*["']?(?!(?:true|false|none|null|yes|no|on|off|enabled|disabled|required|optional)(?:$|[;&,\s"']))[^;&,\s"']+/i;
+const FLAG_WORDS = ["true", "false", "none", "null", "yes", "no", "on", "off", "enabled", "disabled", "required", "optional"];
+const CREDENTIAL_ASSIGNMENT_RE = new RegExp(String.raw `(?:(?:^|[;&?#,{]|\/:)\s*|\s)["']?(?!-*jobserver-auth\s*[=:])(?:[a-z0-9_.-]{0,64}(?:password|passwd|pwd|secret|token|(?:account|access|api|private|subscription)[-_]?key|signature|sig|credential)|[a-z0-9_.-]{0,63}[_.-]auth)["']?\s*[=:]\s*["']?(?!(?:${FLAG_WORDS.join("|")})(?:$|[;&,\s"']))[^;&,\s"']+`, "i");
 const WEBHOOK_URL_RE = /https:\/\/(?:hooks\.slack\.com\/(?:services|workflows|triggers)\/|(?:ptb\.|canary\.)?discord(?:app)?\.com\/api\/webhooks\/\d+\/|[\w.-]+\.webhook\.office\.com\/webhookb2\/)[\w\/@.~-]{16,}/i;
-const SONAR_LOGIN_RE = /["']?sonar\.login["']?\s*[:=]\s*["']?[^\s"',}]{8,}/;
+const SONAR_LOGIN_RE = new RegExp(String.raw `["']?sonar\.login["']?\s*[:=]\s*["']?[^\s"',}]{${CREDENTIAL_MIN_CHARS},}`);
 const PRIVATE_KEY_HEADER_RE = /-----BEGIN [A-Z ]*PRIVATE KEY(?: BLOCK)?-----/;
-const AUTHORIZATION_HEADER_RE = /\bauthorization\s*[:=]\s*["']?[a-z][a-z0-9_-]*\s+[A-Za-z0-9._~+\/=-]{8,}/i;
+const AUTHORIZATION_HEADER_RE = new RegExp(String.raw `\bauthorization\s*[:=]\s*["']?[a-z][a-z0-9_-]*\s+[A-Za-z0-9._~+\/=-]{${CREDENTIAL_MIN_CHARS},}`, "i");
 const TOKEN_WORD_RE = /\b(?:[Tt]oken|TOKEN)\s+(?=[A-Za-z0-9_~+=-]*[0-9])(?=[A-Za-z0-9_~+=-]*[A-Z])(?=([A-Za-z0-9_~+=-]{20,}))\1(?![\/.])/;
-const BEARER_BASIC_RE = /\b(?:Bearer|Basic)\s+(?=[A-Za-z._~+\/=-]*[0-9]|(?:[A-Za-z0-9._~+\/=-]*?[a-z][A-Z](?![a-z])){2}|[A-Za-z0-9.-]*[_~+\/=])[A-Za-z0-9._~+\/=-]{8,}/;
+const BEARER_BASIC_RE = new RegExp(String.raw `\b(?:Bearer|Basic)\s+(?=[A-Za-z._~+\/=-]*[0-9]|(?:[A-Za-z0-9._~+\/=-]*?[a-z][A-Z](?![a-z])){2}|[A-Za-z0-9.-]*[_~+\/=])[A-Za-z0-9._~+\/=-]{${CREDENTIAL_MIN_CHARS},}`);
 export function looksLikeCredentialValue(value) {
     const text = value.length > VALUE_SCAN_LIMIT ? value.slice(0, VALUE_SCAN_LIMIT) : value;
     for (let at = text.indexOf("://"); at !== -1; at = text.indexOf("://", at + 3)) {
@@ -149,39 +153,188 @@ const WINDOWS_REQUIRED_ENV = Object.freeze(["HOMEDRIVE", "HOMEPATH", "LOGONSERVE
 function runtimeSuppliedEnv() {
     return ["NODE_V8_COVERAGE", ...DEFAULT_INHERITED_ENV_VARS, ...(process.platform === "win32" ? WINDOWS_REQUIRED_ENV : [])];
 }
-const WITHHELD_ENV = Symbol.for("sema.core.withheldEnv");
-const NOTHING_WITHHELD = Object.freeze([]);
-const withheldEnvOf = () => {
-    const held = Reflect.get(globalThis, WITHHELD_ENV);
-    return Array.isArray(held) ? held : NOTHING_WITHHELD;
+const valueDigest = (value) => createHash("sha256").update(value, "utf16le").digest("base64");
+const indexHas = (index, value) => {
+    const digests = index.get(value.length);
+    return digests !== undefined && digests.has(valueDigest(value));
+};
+const indexAdd = (index, value) => {
+    const digests = index.get(value.length);
+    if (digests === undefined)
+        index.set(value.length, new Set([valueDigest(value)]));
+    else
+        digests.add(valueDigest(value));
 };
-const setWithheldEnv = (names) => {
-    Reflect.set(globalThis, WITHHELD_ENV, Object.freeze([...names]));
+const WITHHELD_ENV = Symbol.for("sema.core.withheldEnvTable");
+const NOTHING_NAMED = Object.freeze([]);
+const isWithheldEnvTable = (t) => typeof t === "object" && t !== null && Array.isArray(t.names) && t.declared instanceof Map && t.held instanceof Map;
+const withheldEnvOf = () => {
+    const slot = Reflect.get(globalThis, WITHHELD_ENV);
+    if (isWithheldEnvTable(slot))
+        return slot;
+    const fresh = { names: NOTHING_NAMED, declared: new Map(), held: new Map() };
+    Reflect.set(globalThis, WITHHELD_ENV, fresh);
+    return fresh;
 };
-export function declareWithheldEnv(names) {
-    const value = names;
-    if (!Array.isArray(value))
-        throw new Error(`declareWithheldEnv: the list must be an array of variable names (got ${typeof value === "string" ? JSON.stringify(value) : value === null ? "null" : typeof value})`);
-    const problem = variableNameListProblem("names", value);
+const kindOf = (v) => (v === null ? "null" : Array.isArray(v) ? "an array" : typeof v);
+function listCopy(label, list) {
+    if (types.isProxy(list))
+        throw new Error(`declareWithheldEnv: ${label} must be a plain array, not a Proxy`);
+    const copy = [];
+    try {
+        for (let i = 0, n = list.length; i < n; i++)
+            copy[i] = list[i];
+    }
+    catch {
+        throw new Error(`declareWithheldEnv: an element of ${label} threw while it was read — refused`);
+    }
+    return Object.freeze(copy);
+}
+const CANNOT_BE_WITHHELD = "which a child is handed from this process's environment whatever the spawn passes (by Node, the MCP stdio transport or Windows) — it cannot be withheld";
+function runtimeSuppliedHolderOf(value) {
+    const supplied = policyArm([...runtimeSuppliedEnv()]);
+    return Object.keys(supplied).find((k) => supplied[k] === value);
+}
+const PLACEHOLDER_KEY_WORDS = new Set([...FLAG_WORDS, "undefined", "placeholder", "lm-studio", "not-needed", "sk-no-key-required"]);
+const ONE_REPEATED_CHARACTER_RE = /^(\S)\1{2,}$/u;
+function notACredentialReason(value) {
+    const text = value.trim();
+    if (text === "")
+        return "white space only, which every blank variable equals";
+    if (text.length < CREDENTIAL_MIN_CHARS)
+        return `a string of fewer than ${CREDENTIAL_MIN_CHARS} characters, which names no secret`;
+    if (PLACEHOLDER_KEY_WORDS.has(text.toLowerCase()))
+        return "a flag or placeholder word, which names no secret";
+    if (ONE_REPEATED_CHARACTER_RE.test(text.replace(CREDENTIAL_VOCABULARY.tokenPrefix, "")))
+        return "one character repeated, which names no secret";
+    return undefined;
+}
+function credentialValueProblem(v) {
+    if (typeof v !== "string")
+        return kindOf(v);
+    if (v === "")
+        return "an empty string, which every variable set to nothing equals";
+    if (v.includes("\0") || UNPAIRED_SURROGATE_RE.test(v))
+        return `a value holding ${v.includes("\0") ? "a NUL" : "an unpaired surrogate"}, which no variable can hold`;
+    return notACredentialReason(v);
+}
+function credentialValueListProblem(value) {
+    for (const [i, v] of value.entries()) {
+        const why = credentialValueProblem(v);
+        if (why !== undefined)
+            return `values[${i}] is not a credential value (got ${why})`;
+    }
+    return undefined;
+}
+export function declareWithheldEnv(table) {
+    const given = table;
+    if (given === null || typeof given !== "object" || Array.isArray(given)) {
+        throw new Error(`declareWithheldEnv: the declaration must be a table { names, values } (got ${Array.isArray(given) ? "an array — a names-only list is no longer a declaration: pass { names, values }" : kindOf(given)})`);
+    }
+    const received = receiveOwnProperties(given, { subject: "declareWithheldEnv's table", unit: "member", moment: "at the declaration" });
+    const stray = Object.keys(received).find((k) => k !== "names" && k !== "values");
+    if (stray !== undefined)
+        throw new Error(`declareWithheldEnv: the table has a member ${JSON.stringify(stray.slice(0, 64))} — it holds names and values only`);
+    const givenNames = received.names;
+    if (!Array.isArray(givenNames))
+        throw new Error(`declareWithheldEnv: names must be an array of variable names (got ${kindOf(givenNames)})`);
+    const names = listCopy("names", givenNames);
+    const problem = variableNameListProblem("names", names);
     if (problem !== undefined)
         throw new Error(`declareWithheldEnv: ${problem}`);
     const supplied = new Set(runtimeSuppliedEnv().map(envNameKey));
-    const unwithholdable = value.findIndex((k) => supplied.has(envNameKey(k)));
+    const unwithholdable = names.findIndex((k) => supplied.has(envNameKey(k)));
     if (unwithholdable !== -1)
-        throw new Error(`declareWithheldEnv: names[${unwithholdable}] is ${value[unwithholdable]}, which a child is handed from this process's environment whatever the spawn passes (by Node, the MCP stdio transport or Windows) — it cannot be withheld`);
-    setWithheldEnv(value);
+        throw new Error(`declareWithheldEnv: names[${unwithholdable}] is ${String(names[unwithholdable])}, ${CANNOT_BE_WITHHELD}`);
+    const givenValues = received.values;
+    if (!Array.isArray(givenValues))
+        throw new Error(`declareWithheldEnv: values must be an array of credential values (got ${kindOf(givenValues)})`);
+    const values = listCopy("values", givenValues);
+    const valueProblem = credentialValueListProblem(values);
+    if (valueProblem !== undefined)
+        throw new Error(`declareWithheldEnv: ${valueProblem}`);
+    for (const [i, v] of values.entries()) {
+        const holder = runtimeSuppliedHolderOf(v);
+        if (holder !== undefined)
+            throw new Error(`declareWithheldEnv: values[${i}] is the value of ${holder}, ${CANNOT_BE_WITHHELD}`);
+    }
+    const declared = new Map();
+    for (const v of values)
+        indexAdd(declared, v);
+    Reflect.set(globalThis, WITHHELD_ENV, { names: names, declared, held: withheldEnvOf().held });
+}
+export function holdOwnCredentialValues(values, onNotice) {
+    const given = [...values].filter((v) => typeof v === "string" && v.length > 0);
+    const taken = given.filter((v) => {
+        const why = notACredentialReason(v);
+        if (why !== undefined)
+            sayNotTaken(v, why, onNotice);
+        return why === undefined;
+    });
+    for (const v of taken) {
+        const holder = runtimeSuppliedHolderOf(v);
+        if (holder !== undefined)
+            throw Object.assign(new Error(`a credential the engine was handed is the value of ${holder}, ${CANNOT_BE_WITHHELD}; the credential is refused`), { code: "config.invalid_argument" });
+    }
+    const { held } = withheldEnvOf();
+    for (const v of taken)
+        indexAdd(held, v);
+}
+const AUTH_SCHEME_VALUE_RE = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+ +(\S[\s\S]*)$/;
+const SCHEMED_HEADER_RE = /^(?:proxy-)?authorization$/i;
+export function isCredentialHeaderName(name) {
+    return isSensitiveHeaderName(name);
+}
+export function isSchemedCredentialHeader(name) {
+    return SCHEMED_HEADER_RE.test(name);
+}
+export function credentialHeaderValues(headers) {
+    const out = [];
+    for (const [name, value] of Object.entries(headers ?? {})) {
+        if (typeof value !== "string" || !(isCredentialHeaderName(name) || looksLikeCredentialValue(value)))
+            continue;
+        const credentials = AUTH_SCHEME_VALUE_RE.exec(value)?.[1];
+        if (credentials !== undefined && isSchemedCredentialHeader(name) && notACredentialReason(credentials) !== undefined) {
+            out.push(credentials);
+            continue;
+        }
+        out.push(value);
+        if (credentials !== undefined)
+            out.push(credentials);
+    }
+    return out;
+}
+const intakeSaid = new Set();
+function sayNotTaken(value, why, onNotice) {
+    const key = valueDigest(value.trim());
+    if (intakeSaid.has(key))
+        return;
+    intakeSaid.add(key);
+    try {
+        deliverEngineNotice(onNotice, {
+            code: "config.credential_not_withheld",
+            message: `a credential the engine was handed is ${why} — it is used as given, but a variable holding the same string is not withheld from a spawned child (said once per value; the value is not repeated)`,
+            detail: { reason: why },
+        });
+    }
+    catch {
+    }
 }
 export function __resetWithheldEnv() {
-    setWithheldEnv([]);
+    Reflect.set(globalThis, WITHHELD_ENV, { names: NOTHING_NAMED, declared: new Map(), held: new Map() });
+    intakeSaid.clear();
 }
 function withholdOwnCredentials(inherited, findings) {
-    if (withheldEnvOf().length === 0)
+    const table = withheldEnvOf();
+    if (table.names.length === 0 && table.declared.size === 0 && table.held.size === 0)
         return inherited;
-    const own = new Set(withheldEnvOf().map(envNameKey));
+    const own = new Set(table.names.map(envNameKey));
     const kept = [];
     for (const key of Object.keys(inherited)) {
-        if (!own.has(envNameKey(key)))
-            kept.push([key, inherited[key]]);
+        const value = inherited[key];
+        const ownValue = typeof value === "string" && (indexHas(table.declared, value) || indexHas(table.held, value));
+        if (!own.has(envNameKey(key)) && !ownValue)
+            kept.push([key, value]);
         else
             findings?.push({ key, kind: "own-credential", confidence: SECRET_ENV_KIND_CONFIDENCE["own-credential"], source: "secret-env" });
     }
@@ -198,24 +351,25 @@ export function inheritedHostEnv(policy, findings) {
     const problem = inheritEnvPolicyProblem(policy);
     if (problem !== undefined)
         throw new Error(problem);
-    let arm;
+    return withholdOwnCredentials(policyArm(policy, findings), findings);
+}
+function policyArm(policy, findings) {
     if (policy === "all")
-        arm = { ...process.env };
-    else if (Array.isArray(policy)) {
-        arm = {};
-        for (const k of policy)
-            if (process.env[k] !== undefined)
-                arm[k] = process.env[k];
-    }
-    else
-        arm = scrubSecretEnv(process.env, findings);
-    return withholdOwnCredentials(arm, findings);
+        return { ...process.env };
+    if (!Array.isArray(policy))
+        return scrubSecretEnv(process.env, findings);
+    const arm = {};
+    for (const k of policy)
+        if (process.env[k] !== undefined)
+            arm[k] = process.env[k];
+    return arm;
 }
 export function inheritEnvPolicyProblem(value) {
     const shape = policyShapeProblem(value);
-    if (shape !== undefined || !Array.isArray(value) || withheldEnvOf().length === 0)
+    const { names } = withheldEnvOf();
+    if (shape !== undefined || !Array.isArray(value) || names.length === 0)
         return shape;
-    const own = new Set(withheldEnvOf().map(envNameKey));
+    const own = new Set(names.map(envNameKey));
     const named = value.findIndex((k) => own.has(envNameKey(k)));
     return named === -1 ? undefined : `inheritEnv[${named}] names ${value[named]}, which is this deployment's own credential and cannot be inherited by a child (a configuration error: no retry succeeds until the policy or the declaration changes)`;
 }

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

@@ -21,10 +21,13 @@
  * - **a row keeps its grammar**: the write judge stamps the grammar it read the entries in ({@link SESSION_RULES_GRAMMAR}), and
  *   every station reads a row's entries in the grammar the row carries ({@link readSessionRulesShape}) — a row stored before
  *   the stamp keeps the reading it was written under, so an upgrade never turns a stored entry into a grant.
+ * - **rules are read as rules or not at all**: rules whose shape cannot be read, or whose toolDeny holds an entry no grammar
+ *   reads ({@link unreadableDenyEntries}), refuse every call until an operator writes them afresh — never read as fewer.
  * - **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 { compileAllowList, type AllowEntryInertDetail, type AllowEntryInertReason } from "./allow-entry.js";
+import { compileAllowList, type AllowEntryInert, type AllowEntryInertDetail, type AllowEntryInertReason } from "./allow-entry.js";
+import type { EngineNotice } from "./engine-notice.js";
 /** The per-session rules. All optional; an absent bucket imposes no constraint of that kind. */
 export interface SessionPermissionRules {
     /** If set, ONLY the calls these entries admit are allowed — a narrowing allowlist: a call no entry admits is refused.
@@ -51,11 +54,16 @@ export type SessionRuleEntryField = {
 /**
  * The rule grammar this engine reads a session's rule entries in: the `grammar` the write judge stamps on every rules value it
  * judges ({@link judgeSessionRulesWrite}), so every store that writes through it keeps the stamp on the row. It counts
- * revisions of what an entry MEANS and moves only when that changes. Grammar 0 is the reading before the one entry reader:
- * a bucket's entries were tool names compared as written, so an allow entry the reader now reads as speaking for another name
- * (`Bash(rm:*)`, `Bash(*)`) named no tool and admitted nothing.
+ * revisions of what an entry MEANS and moves only when that changes:
+ *  - 0, the reading before the one entry reader: a bucket's entries were tool names compared as written, so an allow entry the
+ *    reader now reads as speaking for another name (`Bash(rm:*)`, `Bash(*)`) named no tool and admitted nothing — and so did
+ *    `*`, one more name no tool carried, which voided nothing beside it;
+ *  - 1, the one entry reader taking its tool name from the lenient rule parser (trimmed before a `(`, any character but a
+ *    blank, a parenthesis or a control / format character);
+ *  - 2, the rule syntax's tool-name head (`ruleSpellingOf`): a name is read as written, in the characters names are minted in.
+ * An entry this grammar reads as no rule in a row an earlier grammar wrote reads as `earlier_grammar` ({@link compileSessionRuleBucket}).
  */
-export declare const SESSION_RULES_GRAMMAR = 1;
+export declare const SESSION_RULES_GRAMMAR = 2;
 /** {@link SessionPermissionRules} plus the monotonic `rev` the store stamps (the OCC key). */
 export interface StoredSessionRules extends SessionPermissionRules {
     rev: number;
@@ -111,7 +119,8 @@ export declare class SessionPolicyError extends Error {
 export interface SessionPolicyStoreOptions {
     /** 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. */
+     *  Absent = none. Each name keeps the caller tool name contract a deployment tool's name keeps at the mount
+     *  (`callerToolNameProblem`: a name a rule can name, no `__`); one that does not is refused at construction. */
     mountedToolNames?: Iterable<string>;
 }
 /** A store's declared roster from {@link SessionPolicyStoreOptions.mountedToolNames} — the one reader both bundled stores
@@ -205,20 +214,64 @@ export declare function readSessionRulesShape(value: unknown): {
  *  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 ANSWER to "can these rules' denies be read?": the `toolDeny` entries the list reading ({@link compileSessionRuleBucket},
+ * in the rules' own grammar) reads as no rule at all. Rules whose deny bucket holds one cannot be read, and rules that cannot be
+ * read are never read as fewer: they refuse every call (the run-time layer) and a non-operator write over them is a loosening
+ * ({@link loosenReasons}) — until an operator writes them afresh, and the write judge refuses such an entry. Unlike a definition
+ * file a plugin ships, which its user cannot edit, a session's rules are written by the session's own operator and can be
+ * rewritten, so a deny nobody can read costs one write instead of quietly guarding nothing. An entry the grammar reads that names
+ * no mounted tool (or `*`) is not here: it names nothing and refuses nothing, the rest of the bucket refusing as written.
+ * `roster` as in {@link compileSessionRuleBucket}; it never changes this answer (a spelling is read before a name is judged).
+ */
+export declare function unreadableDenyEntries(rules: SessionRulesInGrammar, roster?: ReadonlySet<string>): AllowEntryInert[];
 /**
  * THE LIST READING of one rule bucket of a rules value the shape reading read — what the run-time layer enforces, the tighten
  * comparison compares and the write judge refuses on: `compileAllowList` over the one entry reader, in the bucket's direction,
- * against `roster` when given, in the grammar the value is written in. An entry its grammar reads as nothing that the reader
- * reads as a row ({@link readsAsNothingIn}) is moved to the entries that read as nothing, reason `earlier_grammar`.
+ * against `roster` when given, in the grammar the value is written in. An entry its grammar reads as nothing
+ * ({@link earlierGrammarReads}) is moved to the entries that read as nothing, reason `earlier_grammar`, before the list is
+ * compiled: it is one entry that reads as nothing, and the list beside it is read as written. The move is an ENTRY's reading and
+ * never the list's: an allow list a `*` voids (in any spelling the voiding test reads as `*`, `* (*)` included) is voided in
+ * every grammar from 1 on, so in such a row the list is read whole, as written — only grammar 0, where `*` was one more name, takes
+ * it out alone.
  */
 export declare function compileSessionRuleBucket(rules: SessionRulesInGrammar, field: SessionRuleEntryField, roster?: ReadonlySet<string>): ReturnType<typeof compileAllowList>;
-/** The advisory for allow entries a stored row's earlier grammar reads as nothing ({@link compileSessionRuleBucket}): the session,
- *  the entries as written, what they do and the way to make them the rules they now spell. */
-export declare function earlierGrammarAdvisory(sessionId: string, entries: readonly string[]): string;
+/**
+ * The advisory for the entries of one bucket a stored row's earlier grammar reads as nothing ({@link compileSessionRuleBucket},
+ * `earlier_grammar`; `grammar` = the row's): the session, the bucket, the entries as written, what they do and the way out. An
+ * entry this engine's grammar reads as no rule is named with the reader's word — in `toolAllow` it admits nothing, in `toolDeny`
+ * the rules cannot be read and every call is refused ({@link unreadableDenyEntries}); the way out is a rewrite leaving it out
+ * (the write judge refuses an entry it cannot read). A grammar-0 allow entry that named no tool there is told as it always was:
+ * to make a parenthesized one the rule it now spells, or (`*`, which is no allow rule in any grammar) to leave it out.
+ */
+export declare function earlierGrammarAdvisory(sessionId: string, entries: readonly string[], field: SessionRuleEntryField, grammar: number): string;
+/** The reader's word for one entry an earlier grammar reads as nothing: `no_rule` — this engine's rule grammar reads it as no
+ *  rule; `named_no_tool` — a grammar-0 allow entry the bare-name comparison of its day read as naming no tool. */
+export type EarlierGrammarReader = "no_rule" | "named_no_tool";
+/**
+ * The notice for the entries of one bucket a stored row's earlier grammar reads as nothing (`config.session_rules_earlier_grammar`,
+ * audience `user` — the session's rules are what the person's calls are judged by): the message is {@link earlierGrammarAdvisory}
+ * verbatim, and `detail` carries the same facts for a machine — `bucket` (the field), `storedGrammar` (the row's), `entries` (every
+ * entry, each as `noticeRuleText` hands rule text to a notice, with its reader's word), `rewrite` (the way out: an operator write of
+ * a new value without the stored row's rev, which stamps `stampsGrammar`), `rulesSessionId` (whose rules — an ancestor's on a
+ * delegated child's inherited layer) and `sessionId` (the run that read them).
+ */
+export declare function earlierGrammarNotice(input: {
+    rulesSessionId: string;
+    sessionId: string;
+    entries: readonly string[];
+    field: SessionRuleEntryField;
+    grammar: number;
+}): EngineNotice;
+/** The clause a run-time refusal carries when the allowlist it judged by holds entries its earlier grammar reads as nothing
+ *  ({@link compileSessionRuleBucket}; `grammar` = the row's): the grammar the rules are stored in, then which entries name no tool
+ *  there (grammar 0: `*` by its spelling, the parenthesized ones counted) and how many this engine's grammar reads as no rule —
+ *  counted, since a stored entry's own text is data and never reaches a sentence the model reads. Empty when none. */
+export declare function earlierGrammarRefusalClause(entries: readonly string[], grammar: number): string;
 /** A layer's delivery of the entries its snapshots' earlier grammar reads as nothing ({@link compileSessionRuleBucket},
- *  `earlier_grammar`) to `sink`: once per distinct set per layer (the ledger is this closure's), an empty set is no news, and a
- *  throwing sink never changes what the snapshot enforces. */
-export declare function earlierGrammarAnnouncer(sink: ((entries: readonly string[]) => void) | undefined): (entries: readonly string[]) => void;
+ *  `earlier_grammar`), one bucket at a time with the grammar its row is written in, to `sink`: once per distinct set per layer
+ *  (the ledger is this closure's), an empty set is no news, and a throwing sink never changes what the snapshot enforces. */
+export declare function earlierGrammarAnnouncer(sink: ((entries: readonly string[], field: SessionRuleEntryField, grammar: number) => void) | undefined): (entries: readonly string[], field: SessionRuleEntryField, grammar: number) => void;
 /**
  * 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),
@@ -234,9 +287,11 @@ export declare function judgeSessionRulesWrite(prior: StoredSessionRules | null,
 };
 /**
  * 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
+ * entries of each rule bucket — the list as the run-time layer enforces it ({@link effectiveEntries}). Rules whose toolDeny holds
+ * an entry no grammar reads ({@link unreadableDenyEntries}) refuse every call: as `next` they loosen nothing, and as `prior`
+ * every readable `next` loosens them (one reason, naming the entries). Any other 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
+ * takes out an entry that names nothing); an allowlist a `*` voids (in this engine's grammar; in grammar 0 a `*` is one such entry beside the rest) 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, each side's in the grammar that side is written in (a stored row's entry that its grammar reads as