@sema-agent/core 7.51.1 → 7.51.2

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

@@ -18,10 +18,13 @@
  *   (`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).
+ * - **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.
  * - **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 AllowEntryInertDetail, type AllowEntryInertReason } from "./allow-entry.js";
+import { compileAllowList, 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 the calls these entries admit are allowed — a narrowing allowlist: a call no entry admits is refused.
@@ -45,6 +48,14 @@ declare const SESSION_RULE_BUCKETS: {
 export type SessionRuleEntryField = {
     [K in keyof typeof SESSION_RULE_BUCKETS]: (typeof SESSION_RULE_BUCKETS)[K] extends "dirs" ? never : K;
 }[keyof typeof SESSION_RULE_BUCKETS];
+/**
+ * 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.
+ */
+export declare const SESSION_RULES_GRAMMAR = 1;
 /** {@link SessionPermissionRules} plus the monotonic `rev` the store stamps (the OCC key). */
 export interface StoredSessionRules extends SessionPermissionRules {
     rev: number;
@@ -53,7 +64,15 @@ export interface StoredSessionRules extends SessionPermissionRules {
      *  can tell a recreated row from a continuation of the one it enforces whatever `rev` the new row wears.
      *  Absent = generation 0 (a backend that predates the mark, or a row written before it). */
     gen?: number;
+    /** The rule grammar the row's entries are read in ({@link SESSION_RULES_GRAMMAR}), stamped by the write judge. Absent =
+     *  a row stored before the stamp: grammar 0. */
+    grammar?: number;
 }
+/** A rules value as the shape reading hands it on ({@link readSessionRulesShape}): its buckets, and the grammar its entries
+ *  are read in — resolved, so a store that serves it on beside its own counters serves the row's grammar with it. */
+export type SessionRulesInGrammar = SessionPermissionRules & {
+    grammar: number;
+};
 /** Options for {@link SessionPolicyStore.putRules}. */
 export interface PutRulesOptions {
     /** CAS: reject the write if the stored `rev` is not this (optimistic concurrency). Omit to skip the check. */
@@ -169,13 +188,14 @@ declare function lexWithin(root: string, p: string): boolean;
  * 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).
+ * 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,
+ * in the grammar the value is written in ({@link grammarOf}), handed on as `grammar`. The store's counters (`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;
+    rules: SessionRulesInGrammar;
 } | {
     fault: SessionRuleShapeRefusal;
     sentence: string;
@@ -185,15 +205,33 @@ 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 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`.
+ */
+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;
+/** 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;
 /**
  * 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}).
+ * `invalid_shape` ({@link normalizeRules}), `inert_entry` (an entry that reads as nothing in the grammar the rules are written
+ * in; 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. The rules to stamp carry `grammar` = {@link SESSION_RULES_GRAMMAR}: what passed
+ * the judge means the same in this engine's grammar, and THIS is the one place the stamp is minted, so every store that
+ * stores what the judge returns keeps it. `mountedToolNames` = the store's declaration ({@link SessionPolicyStoreOptions.mountedToolNames}).
  */
-export declare function judgeSessionRulesWrite(prior: StoredSessionRules | null, rules: unknown, opts: PutRulesOptions | undefined, mountedToolNames?: ReadonlySet<string>): SessionPermissionRules;
+export declare function judgeSessionRulesWrite(prior: StoredSessionRules | null, rules: unknown, opts: PutRulesOptions | undefined, mountedToolNames?: ReadonlySet<string>): SessionPermissionRules & {
+    grammar: number;
+};
 /**
  * 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
@@ -201,9 +239,11 @@ export declare function judgeSessionRulesWrite(prior: StoredSessionRules | null,
  * 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.
+ * 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
+ * nothing is in no effect, so writing it in this engine's grammar widens). 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(priorValue: SessionPermissionRules, nextValue: SessionPermissionRules, mountedToolNames?: ReadonlySet<string>): string[];
 /**

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

@@ -1,12 +1,13 @@
 import { posix } from "node:path";
 import { isWinFormPath } from "../tools/fs/safety.js";
 import { NAMESPACED_NAME_SHAPES, carriesNamespaceSeparator } from "./protocol-table.js";
-import { compileAllowList, inertEntryPhrase, readRuleEntry, renderListEntry } from "./allow-entry.js";
+import { compileAllowList, compiledEntryName, 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"]);
+const STORE_STAMPS = new Set(["rev", "gen", "grammar"]);
+export const SESSION_RULES_GRAMMAR = 1;
 export class SessionPolicyError extends Error {
     code;
     detail;
@@ -49,13 +50,32 @@ function lexWithin(root, p) {
         return true;
     return np === nr || np.startsWith(nr + "/");
 }
+function grammarOf(value) {
+    const stamp = value.grammar;
+    if (stamp === undefined)
+        return { grammar: value.rev !== undefined ? 0 : SESSION_RULES_GRAMMAR };
+    if (typeof stamp !== "number" || !Number.isInteger(stamp) || stamp < 0) {
+        const got = typeof stamp === "number" ? "a number that is not a whole number of 0 or more" : valueTypeLabel(stamp);
+        return { got, sentence: `session rules carry a grammar stamp that is ${got} — the stamp is the whole number of the rule grammar the rules were written in (this engine reads grammar ${SESSION_RULES_GRAMMAR})` };
+    }
+    if (stamp > SESSION_RULES_GRAMMAR) {
+        return {
+            got: `${stamp}, a grammar newer than this engine's (${SESSION_RULES_GRAMMAR})`,
+            sentence: `session rules were written in rule grammar ${stamp}, newer than this engine reads (grammar ${SESSION_RULES_GRAMMAR}) — refusing rather than read their entries in an older grammar; an engine that reads grammar ${stamp} reads them`,
+        };
+    }
+    return { grammar: stamp };
+}
 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}`);
     }
-    const rules = {};
+    const read = grammarOf(value);
+    if ("got" in read)
+        return fault("grammar", read.got, read.sentence);
+    const rules = { grammar: read.grammar };
     for (const [key, v] of Object.entries(value)) {
         if (STORE_STAMPS.has(key) || v === undefined)
             continue;
@@ -78,34 +98,76 @@ export function readSessionRulesShape(value) {
     return { rules };
 }
 export function normalizeRules(rules) {
+    return canonicalRules(shapeOrRefuse(rules));
+}
+function shapeOrRefuse(rules) {
     const read = readSessionRulesShape(rules);
     if ("fault" in read)
         throw new SessionPolicyError("invalid_shape", read.sentence, read.fault);
+    return read.rules;
+}
+function canonicalRules(read) {
     const out = {};
     for (const field of BUCKETS) {
-        const list = read.rules[field];
+        const list = read[field];
         if (list === undefined)
             continue;
         out[field] = SESSION_RULE_BUCKETS[field] === "dirs" ? list.map((d) => posix.normalize(d).replace(/\/+$/, "") || "/") : [...list];
     }
     return out;
 }
-function effectiveEntries(field, list, mountedToolNames) {
-    return compileAllowList(list ?? [], SESSION_RULE_BUCKETS[field], mountedToolNames).rows.map((r) => r.entry);
+function readsAsNothingIn(grammar, field, entry, compiled) {
+    return grammar === 0 && SESSION_RULE_BUCKETS[field] === "allow" && compiledEntryName(compiled) !== entry;
+}
+export function compileSessionRuleBucket(rules, field, roster) {
+    const list = compileAllowList(rules[field] ?? [], SESSION_RULE_BUCKETS[field], roster);
+    const rows = list.rows.filter((r) => !readsAsNothingIn(rules.grammar, field, r.entry, r.compiled));
+    if (rows.length === list.rows.length)
+        return list;
+    const earlier = list.rows.filter((r) => readsAsNothingIn(rules.grammar, field, r.entry, r.compiled)).map((r) => ({ entry: r.entry, reason: "earlier_grammar" }));
+    return { rows, inert: [...list.inert, ...earlier] };
+}
+const ADVISORY_ENTRIES_SHOWN = 5;
+export function earlierGrammarAdvisory(sessionId, entries) {
+    const one = entries.length === 1;
+    const shown = entries.slice(0, ADVISORY_ENTRIES_SHOWN).map(renderListEntry).join(", ");
+    const rest = entries.length > ADVISORY_ENTRIES_SHOWN ? ` and ${entries.length - ADVISORY_ENTRIES_SHOWN} more` : "";
+    return (`session permission rules of session ${JSON.stringify(sessionId)}: toolAllow ${shown}${rest} ${one ? "was" : "were"} stored before the rule grammar stamp, when session rules compared an entry as a tool name as written, so a parenthesized entry named no tool — ` +
+        `${one ? "it admits" : "they admit"} nothing, as when written. To make ${one ? "it an allow rule" : "them allow rules"}, write the session's rules afresh through this engine (an operator write of a value without the stored row's rev; the write stamps grammar ${SESSION_RULES_GRAMMAR}); left as stored, ${one ? "it keeps" : "they keep"} admitting nothing.`);
+}
+export function earlierGrammarAnnouncer(sink) {
+    const announced = new Set();
+    return (entries) => {
+        const key = JSON.stringify(entries);
+        if (sink === undefined || entries.length === 0 || announced.has(key))
+            return;
+        announced.add(key);
+        try {
+            sink(entries);
+        }
+        catch {
+        }
+    };
+}
+function effectiveEntries(rules, field, mountedToolNames) {
+    return compileSessionRuleBucket(rules, 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);
+            const reading = readRuleEntry(entry, SESSION_RULE_BUCKETS[field], mountedToolNames);
+            const read = reading.kind === "row" && readsAsNothingIn(rules.grammar, field, entry, reading.compiled) ? { kind: "inert", reason: "earlier_grammar" } : reading;
             if (read.kind === "row")
                 continue;
             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 way = why.reason === "earlier_grammar"
+                ? ` These rules are written in grammar ${rules.grammar} (a stored row from before the grammar stamp), in which this entry names no tool. To make it an allow rule, write the rules afresh — a value without the stored row's rev; the write stamps grammar ${SESSION_RULES_GRAMMAR} — or leave the entry out.`
+                : 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 });
         }
@@ -115,8 +177,9 @@ export function judgeSessionRulesWrite(prior, rules, opts, mountedToolNames = NO
     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);
+    const read = shapeOrRefuse(rules);
+    const clean = canonicalRules(read);
+    assertEntriesRead(read, mountedToolNames);
     if (prior !== null && opts?.operator !== true) {
         const stored = readSessionRulesShape(prior);
         if ("fault" in stored) {
@@ -127,7 +190,7 @@ export function judgeSessionRulesWrite(prior, rules, opts, mountedToolNames = NO
             throw new SessionPolicyError("loosen_forbidden", `a non-operator session-rule write may only tighten; refused: ${loosens.join("; ")}`);
         }
     }
-    return clean;
+    return { ...clean, grammar: SESSION_RULES_GRAMMAR };
 }
 export function loosenReasons(priorValue, nextValue, mountedToolNames = NO_DECLARED_TOOLS) {
     const shapeOf = (side, value) => {
@@ -139,16 +202,16 @@ export function loosenReasons(priorValue, nextValue, mountedToolNames = NO_DECLA
     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))
+    const keptDeny = new Set(effectiveEntries(next, "toolDeny", mountedToolNames));
+    for (const x of effectiveEntries(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))
+            const had = new Set(effectiveEntries(prior, "toolAllow", mountedToolNames));
+            for (const x of effectiveEntries(next, "toolAllow", mountedToolNames))
                 if (!had.has(x))
                     reasons.push(`widened toolAllow with ${renderListEntry(x)}`);
         }

package/dist/core/types.d.ts

@@ -18,7 +18,8 @@ export type { PermissionMode } from "./ask-origin.js";
 export type { ToolEffect, ToolContentOrigin, ReversibilityVerdict, ReadRootGrantCandidate, ToolSpec, ToolReturn, NestedUsage, NestedUsageAccum, ToolExecuteContext } from "./tool-spec.js";
 export type { BeforeWriteRequest, BeforeWriteResult, BeforeWriteHook, TrackEditRequest, TrackEditResult, TrackFileEditHook, FileEditedNotice, FileEditedHook, HandsBandOptions } from "./hands-band.js";
 export type { AgentDefinition, SkillSpec } from "./agent-definition.js";
-export type { McpServerSpec, A2aServerSpec, McpElicitRequest, McpElicitResponse, OnElicit, McpRevocationLedger, McpMountIdentity } from "./mcp-server-spec.js";
+export type { McpServerSpec, A2aServerSpec, McpElicitRequest, McpElicitResponse, OnElicit, McpRevocationLedger, McpMountIdentity, McpToolAxesRead } from "./mcp-server-spec.js";
+export { readMcpToolAxes } from "./mcp-server-spec.js";
 export type { TaskLimits } from "./task-limits.js";
 export type { TaskStatus, RemoteEnvFailureNote, EffectiveMemoryScopes, TaskResult, HumanReviewGateRow } from "./task-result.js";
 export type { TerminalCause, PausedCause } from "./terminal-cause.js";

package/dist/core/types.js

@@ -1,4 +1,5 @@
 export { MODEL_ROLES } from "./model-seat.js";
+export { readMcpToolAxes } from "./mcp-server-spec.js";
 export { AUTO_MODE_DENY_SOURCES, isAutoModeDenySource } from "./runtime-caps.js";
 export { __resetMalformedDelegationSeatAnnouncement, backgroundChildTerminal, deliverDelegationLifecycle, emitsChildRowFrames, taskStartedFrame } from "./delegation-frames.js";
 export { __resetMalformedNoticeSeatAnnouncement, deliverEngineNotice, owedUserInputCounts, parentLegIds, settleOwedUserInput, undrainedUserInputNotices, USER_INPUT_UNDRAINED_CAUSES, USER_INPUT_UNDRAINED_FAMILIES } from "./engine-notice.js";

package/dist/index.d.ts

@@ -76,7 +76,7 @@ export { WORKFLOW_SIZE_GUIDELINE_AGENT_CAPS } from "./orchestration/workflow-siz
 export { ENGINE_AUTHORITY_ENVELOPE_TAGS } from "./core/untrusted-text.js";
 export { materializeA2aTools, A2aRpcError, type MaterializedA2a, type A2aPeerStatus, type A2aRefreshResult, type A2aToolAxis } from "./core/a2a.js";
 export { PROTOCOL_TABLE, MCP_NAMESPACE, A2A_NAMESPACE, protocolOf, type ProtocolNamespace, type ProtocolId } from "./core/protocol-table.js";
-export { InMemorySessionPolicyStore, SessionPolicyError, loosenReasons, normalizeRules, judgeSessionRulesWrite, readSessionRulesShape, type SessionPolicyStoreOptions, type SessionRuleShapeRefusal, type SessionRuleEntryRefusal, type SessionRuleEntryField, type SessionPolicyStore, type SessionPermissionRules, type StoredSessionRules, type SessionRulesRecord, type PutRulesOptions, } from "./core/session-policy-store.js";
+export { InMemorySessionPolicyStore, SessionPolicyError, loosenReasons, normalizeRules, judgeSessionRulesWrite, readSessionRulesShape, SESSION_RULES_GRAMMAR, compileSessionRuleBucket, type SessionRulesInGrammar, type SessionPolicyStoreOptions, type SessionRuleShapeRefusal, type SessionRuleEntryRefusal, type SessionRuleEntryField, type SessionPolicyStore, type SessionPermissionRules, type StoredSessionRules, type SessionRulesRecord, type PutRulesOptions, } from "./core/session-policy-store.js";
 export { SAFETY_MERGE_CONFORMANCE_CORPUS, type SafetyMergeVector } from "./core/safety-merge-corpus.js";
 export { SAFETY_AXIS_VOCABULARY } from "./core/safety-axis-vocab.js";
 export { createSessionRulePolicy } from "./core/runner/session-rule-policy.js";
@@ -348,7 +348,8 @@ export { CONFIG_CATALOG_VERSION, describeConfigCatalog, resolveEffectiveConfig,
 export { normalizeAgentName } from "./core/task-registry.js";
 export { DELEGATION_MAX_CONCURRENT_DEFAULT, DELEGATION_MAX_PER_SESSION_DEFAULT, SUBAGENT_TRANSCRIPT_RETENTION_DAYS_DEFAULT, } from "./config/defaults.js";
 export { COORDINATOR_ROLE_PROMPT, TEAMMATE_COMMUNICATION_ADDENDUM } from "./prompts/coordinator.js";
-export { createSubagentTool, FORK_SUBAGENT_TYPE, GENERAL_PURPOSE_SUBAGENT_TYPE, agentWhenToUseText, FORK_DIRECTIVE_FRAME, SUBAGENT_SYSTEM_NOTE, type SubagentToolOptions, resolveDelegationEntryCaps, type ResolvedDelegationEntryCaps, type SubagentSpawnContext, type SubagentSteerHandle, type SubagentStep, type SubagentEditedFile, } from "./agents/subagent.js";
+export type { BuiltinSubagentType } from "./agents/subagent.js";
+export { createSubagentTool, FORK_SUBAGENT_TYPE, BUILTIN_SUBAGENT_TYPES, GENERAL_PURPOSE_SUBAGENT_TYPE, agentWhenToUseText, FORK_DIRECTIVE_FRAME, SUBAGENT_SYSTEM_NOTE, type SubagentToolOptions, resolveDelegationEntryCaps, type ResolvedDelegationEntryCaps, type SubagentSpawnContext, type SubagentSteerHandle, type SubagentStep, type SubagentEditedFile, } from "./agents/subagent.js";
 export { getSessionRetainLedger, releaseSessionRetainLedger, } from "./agents/retain-ledger.js";
 export { createSendMessageTool, createAgentContinuationVerb, SEND_MESSAGE_TOOL_NAME, type SendMessageToolOptions, type AgentContinuationReceipt } from "./agents/send-message-tool.js";
 export { createPeerAdmission, peerAdmissionFor, judgePeerAdmission, resolvePeerLaneConfig, PEER_LANE_DEFAULTS, PEER_HOP_CHAIN_WINDOW, PEER_MESSAGE_NOTICE, createPeerSelfRef, createPeerInboundChainRef, peerAxisToken, appendHopToken, type PeerAdmission, type PeerLaneConfig, type PeerAdmissionOptions, type PeerAdmissionRequest, type PeerAdmissionVerdict, type PeerAdmissionRefusal, type PeerRefusalCode, type PeerAxisTag, type PeerIdentity, type PeerSelfRef, type PeerInboundChainRef, } from "./agents/peer-admission.js";
@@ -400,3 +401,5 @@ export { RULE_OFFERS_ABSENCES, type RuleOffersAbsence } from "./core/ask-origin.
 export { BOUND_GRANT_ABSENCES, type BoundGrantAbsence } from "./core/skill-grant-binding.js";
 export { DISPOSABLE_PROMPT_SECTIONS, type DisposablePromptSection, type PromptSectionEntry, type PromptSectionDisposition, type PromptSectionAuthor, type McpInstructionsEntry } from "./core/prompt-section-seat.js";
 export type { McpRevocationLedger, McpMountIdentity } from "./core/mcp-server-spec.js";
+export { readMcpToolAxes } from "./core/mcp-server-spec.js";
+export type { McpToolAxesRead } from "./core/mcp-server-spec.js";

package/dist/index.js

@@ -62,7 +62,7 @@ export { WORKFLOW_SIZE_GUIDELINE_AGENT_CAPS } from "./orchestration/workflow-siz
 export { ENGINE_AUTHORITY_ENVELOPE_TAGS } from "./core/untrusted-text.js";
 export { materializeA2aTools, A2aRpcError } from "./core/a2a.js";
 export { PROTOCOL_TABLE, MCP_NAMESPACE, A2A_NAMESPACE, protocolOf } from "./core/protocol-table.js";
-export { InMemorySessionPolicyStore, SessionPolicyError, loosenReasons, normalizeRules, judgeSessionRulesWrite, readSessionRulesShape, } from "./core/session-policy-store.js";
+export { InMemorySessionPolicyStore, SessionPolicyError, loosenReasons, normalizeRules, judgeSessionRulesWrite, readSessionRulesShape, SESSION_RULES_GRAMMAR, compileSessionRuleBucket, } from "./core/session-policy-store.js";
 export { SAFETY_MERGE_CONFORMANCE_CORPUS } from "./core/safety-merge-corpus.js";
 export { SAFETY_AXIS_VOCABULARY } from "./core/safety-axis-vocab.js";
 export { createSessionRulePolicy } from "./core/runner/session-rule-policy.js";
@@ -285,7 +285,7 @@ export { CONFIG_CATALOG_VERSION, describeConfigCatalog, resolveEffectiveConfig,
 export { normalizeAgentName } from "./core/task-registry.js";
 export { DELEGATION_MAX_CONCURRENT_DEFAULT, DELEGATION_MAX_PER_SESSION_DEFAULT, SUBAGENT_TRANSCRIPT_RETENTION_DAYS_DEFAULT, } from "./config/defaults.js";
 export { COORDINATOR_ROLE_PROMPT, TEAMMATE_COMMUNICATION_ADDENDUM } from "./prompts/coordinator.js";
-export { createSubagentTool, FORK_SUBAGENT_TYPE, GENERAL_PURPOSE_SUBAGENT_TYPE, agentWhenToUseText, FORK_DIRECTIVE_FRAME, SUBAGENT_SYSTEM_NOTE, resolveDelegationEntryCaps, } from "./agents/subagent.js";
+export { createSubagentTool, FORK_SUBAGENT_TYPE, BUILTIN_SUBAGENT_TYPES, GENERAL_PURPOSE_SUBAGENT_TYPE, agentWhenToUseText, FORK_DIRECTIVE_FRAME, SUBAGENT_SYSTEM_NOTE, resolveDelegationEntryCaps, } from "./agents/subagent.js";
 export { getSessionRetainLedger, releaseSessionRetainLedger, } from "./agents/retain-ledger.js";
 export { createSendMessageTool, createAgentContinuationVerb, SEND_MESSAGE_TOOL_NAME } from "./agents/send-message-tool.js";
 export { createPeerAdmission, peerAdmissionFor, judgePeerAdmission, resolvePeerLaneConfig, PEER_LANE_DEFAULTS, PEER_HOP_CHAIN_WINDOW, PEER_MESSAGE_NOTICE, createPeerSelfRef, createPeerInboundChainRef, peerAxisToken, appendHopToken, } from "./agents/peer-admission.js";
@@ -332,3 +332,4 @@ export { SHADOW_REASON, allowRuleShadowSentence, cardDisclosureOf } from "./core
 export { RULE_OFFERS_ABSENCES } from "./core/ask-origin.js";
 export { BOUND_GRANT_ABSENCES } from "./core/skill-grant-binding.js";
 export { DISPOSABLE_PROMPT_SECTIONS } from "./core/prompt-section-seat.js";
+export { readMcpToolAxes } from "./core/mcp-server-spec.js";

package/dist/stores/file/session-policy-store.d.ts

@@ -102,9 +102,9 @@ export declare function judgeSessionPolicyRowObject(raw: string): {
  *
  * Required: `rev` >= 1 (a rev-0 row would read as the live reader's SYNTHETIC empty seed); `gen`, when present, a
  * whole number (a STRING `rev` poisons the CAS arithmetic); the rules themselves read by the ONE shape reading
- * (`readSessionRulesShape` — every key a bucket, every bucket a list of strings), so a row this engine cannot read as
- * rules (a key that is no bucket) is refused like any malformed row, never read as fewer rules. The `__sid`/`__principal`
- * metadata is STRIPPED so the value is byte-identical to the in-memory twin's.
+ * (`readSessionRulesShape` — every key a bucket, every bucket a list of strings, a `grammar` this engine reads), so a row it
+ * cannot read as rules (a key that is no bucket, a later grammar) is refused like any malformed row, never read as fewer rules.
+ * The `__sid`/`__principal` metadata is STRIPPED so the value is byte-identical to the in-memory twin's.
  */
 export declare function judgeSessionPolicyRowShape(row: Record<string, unknown>): {
     rules: StoredSessionRules;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "7.51.1",
+  "version": "7.51.2",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",

package/test/export-surface.snapshot.json

@@ -1,7 +1,7 @@
 {
   "_comment": "design/87 L3 — frozen public export surface of src/index.ts (name -> kind). DO NOT edit by hand to silence a red test. A removed/changed entry = a BREAKING change: name every removed entry in the CHANGELOG's BREAKING lines (what was removed / who is hurt / what to read instead) and update this fixture in the SAME commit. Regenerate via REGEN in test/export-surface.test.ts.",
   "_tierComment": "#435 v1 — machine-readable layering of the public surface: stable = demonstrated by README.md / src/examples; internal = an `Internal`-marked name or a runner/engine deep-subtree declaration (the model seam src/engine/llm is excluded — it is the BYOM contract, not an engine internal); advanced = a supported export the front door does not walk you through. THIS IS AN INITIAL HEURISTIC, derived mechanically and expected to be refined ticket by ticket: no human reviewed these 1700+ entries one by one, and nothing here claims otherwise. Known bias: a short or English-word export name (ok, err, Result, Usage) can match ordinary prose in README.md and land `stable` on a coincidence. Every export MUST carry a tier — a new export with no row fails the gate in export-surface.test.ts.",
-  "count": 2679,
+  "count": 2686,
   "exports": {
     "A2ATaskState": "type",
     "A2ATaskStateReversal": "type",
@@ -199,6 +199,7 @@
     "BOUND_GRANT_ABSENCES": "variable",
     "BUILTIN_COMPLIANCE_DENIES": "variable",
     "BUILTIN_READONLY_DENY_TOOLS": "variable",
+    "BUILTIN_SUBAGENT_TYPES": "variable",
     "BackgroundAgentQuery": "interface",
     "BackgroundAgentRecord": "interface",
     "BackgroundAgentRowSummary": "interface",
@@ -236,6 +237,7 @@
     "BreakerState": "interface",
     "BudgetAxis": "type",
     "BuildAutoModePromptOptions": "interface",
+    "BuiltinSubagentType": "type",
     "BundleChallengeRow": "interface",
     "BundleLineageRow": "interface",
     "BundlePollutedSession": "interface",
@@ -794,6 +796,7 @@
     "McpServerLiveness": "interface",
     "McpServerSpec": "interface",
     "McpServerStatus": "interface",
+    "McpToolAxesRead": "type",
     "McpToolFace": "type",
     "MediaDescriptor": "type",
     "MediaStripInfo": "interface",
@@ -1391,6 +1394,7 @@
     "SESSION_BOX_PREFIX": "variable",
     "SESSION_CAPTURE_OPTOUT_DIR": "variable",
     "SESSION_LOG_DIGEST_SCHEME": "variable",
+    "SESSION_RULES_GRAMMAR": "variable",
     "SETTLEMENT_IS_REFUSAL": "variable",
     "SETTLEMENT_KINDS": "variable",
     "SETTLEMENT_PARTIES": "variable",
@@ -1472,6 +1476,7 @@
     "SessionRuleEntryRefusal": "interface",
     "SessionRulePartition": "interface",
     "SessionRuleShapeRefusal": "interface",
+    "SessionRulesInGrammar": "type",
     "SessionRulesRecord": "interface",
     "SessionStorage": "interface",
     "SessionStore": "interface",
@@ -1959,6 +1964,7 @@
     "compactableToolNames": "function",
     "compileAllowList": "function",
     "compileReadDeny": "function",
+    "compileSessionRuleBucket": "function",
     "compileWriteDeny": "function",
     "compileWriteProtection": "function",
     "complianceCallDenial": "function",
@@ -2437,6 +2443,7 @@
     "readIntentCredentials": "function",
     "readJsonlRecords": "function",
     "readMailboxPeerMeta": "function",
+    "readMcpToolAxes": "function",
     "readOnlyShellVerdict": "function",
     "readPeerSessionRecord": "function",
     "readPendingSteerQueue": "function",
@@ -2880,6 +2887,7 @@
     "BOUND_GRANT_ABSENCES": "advanced",
     "BUILTIN_COMPLIANCE_DENIES": "advanced",
     "BUILTIN_READONLY_DENY_TOOLS": "advanced",
+    "BUILTIN_SUBAGENT_TYPES": "advanced",
     "BackgroundAgentQuery": "advanced",
     "BackgroundAgentRecord": "advanced",
     "BackgroundAgentRowSummary": "advanced",
@@ -2917,6 +2925,7 @@
     "BreakerState": "stable",
     "BudgetAxis": "internal",
     "BuildAutoModePromptOptions": "advanced",
+    "BuiltinSubagentType": "advanced",
     "BundleChallengeRow": "advanced",
     "BundleLineageRow": "advanced",
     "BundlePollutedSession": "advanced",
@@ -3475,6 +3484,7 @@
     "McpServerLiveness": "advanced",
     "McpServerSpec": "advanced",
     "McpServerStatus": "advanced",
+    "McpToolAxesRead": "advanced",
     "McpToolFace": "internal",
     "MediaDescriptor": "advanced",
     "MediaStripInfo": "advanced",
@@ -4072,6 +4082,7 @@
     "SESSION_BOX_PREFIX": "advanced",
     "SESSION_CAPTURE_OPTOUT_DIR": "advanced",
     "SESSION_LOG_DIGEST_SCHEME": "internal",
+    "SESSION_RULES_GRAMMAR": "advanced",
     "SETTLEMENT_IS_REFUSAL": "advanced",
     "SETTLEMENT_KINDS": "advanced",
     "SETTLEMENT_PARTIES": "advanced",
@@ -4153,6 +4164,7 @@
     "SessionRuleEntryRefusal": "advanced",
     "SessionRulePartition": "advanced",
     "SessionRuleShapeRefusal": "advanced",
+    "SessionRulesInGrammar": "advanced",
     "SessionRulesRecord": "advanced",
     "SessionStorage": "internal",
     "SessionStore": "advanced",
@@ -4640,6 +4652,7 @@
     "compactableToolNames": "advanced",
     "compileAllowList": "advanced",
     "compileReadDeny": "advanced",
+    "compileSessionRuleBucket": "advanced",
     "compileWriteDeny": "advanced",
     "compileWriteProtection": "advanced",
     "complianceCallDenial": "advanced",
@@ -5118,6 +5131,7 @@
     "readIntentCredentials": "advanced",
     "readJsonlRecords": "advanced",
     "readMailboxPeerMeta": "advanced",
+    "readMcpToolAxes": "advanced",
     "readOnlyShellVerdict": "advanced",
     "readPeerSessionRecord": "advanced",
     "readPendingSteerQueue": "advanced",

package/wire-changes/core@7.51.1.json

@@ -53,7 +53,7 @@
       "kind": "function",
       "tier": "advanced",
       "at": [
-        "src/core/secret-env.ts:273",
+        "src/core/secret-env.ts:278",
         "src/index.ts:515"
       ],
       "criteriaCovered": false,
@@ -75,7 +75,7 @@
       "kind": "function",
       "tier": "advanced",
       "at": [
-        "src/core/secret-env.ts:336",
+        "src/core/secret-env.ts:341",
         "src/index.ts:515"
       ],
       "criteriaCovered": false,
@@ -86,7 +86,7 @@
       "kind": "function",
       "tier": "advanced",
       "at": [
-        "src/core/secret-env.ts:321",
+        "src/core/secret-env.ts:326",
         "src/index.ts:515"
       ],
       "criteriaCovered": false,
@@ -251,9 +251,9 @@
       "SecretEnvFindingKind"
     ],
     "sdk": [],
-    "note": "scanned cli@80e061c0 server@3c0e175c sdk@304339d — a name listed is MENTIONED there today, which is evidence of consumption, not proof of it"
+    "note": "scanned cli@d742f6fd server@52b73a9c sdk@304339d — a name listed is MENTIONED there today, which is evidence of consumption, not proof of it. Ledger files (**/docs/core-consumption/**, **/docs/wire-consumption/**, **/*LEDGER*.json) are not evidence of use — server: 8 name(s) matched ONLY in bookkeeping files and were set aside (ENGINE_CAPABILITIES, EngineCapability, ProtocolHttpAuth, declareWithheldEnv, headerOwnershipCollision, inheritEnvPolicyProblem, inheritedHostEnv, toolOutputBlockChars)"
   },
   "breakingCount": 0,
   "breakingItems": [],
-  "toResolvedAt": "cedf0606eb8b5b488d394a01b5f0a632019d1692"
+  "toResolvedAt": "a5c7c33244f7b139e674093f35159037fdfb63da"
 }