@sema-agent/core 7.51.1 → 7.51.2

package/CHANGELOG.md

@@ -1,3 +1,49 @@
+## 7.51.2 — 2026-10-14
+
+### A stored session-rules row carries the rule grammar it was written in; a row from before keeps the reading it had (#1761; security; behavior narrowing open to veto; hard-breaking: none; closed sets: +1 member `AllowEntryInertReason` `earlier_grammar`; exports: +1 const, +1 function, +1 type) (@server)
+
+**Behavior narrowing (open to veto).** A rules row written before this version has no grammar stamp. In such a row, a parenthesized `toolAllow` entry **no longer admits anything**. That covers `Tool(content)` (`Bash(rm:*)`, `Edit(src/**)`, `WebFetch(domain:x)`) and also `Tool(*)` / `Tool()`, which the entry reader reads as the bare tool. That was the entry's meaning when it was written (7.50.x compared session entries as tool names as written, so `Bash(rm:*)` and `Bash(*)` named no tool), and since 7.51.0 the same stored string had been read as an allow rule, or for `Bash(*)` as the whole shell. Upgrading turned it into a grant with no signal: the real Runner lane ran `rm` under a 7.50.x row whose allowlist admitted nothing. Rows written by 7.51.0 / 7.51.1 carry no stamp either, so they read the same way until rewritten.
+
+- **What changed.**
+  - **The stamp.** `judgeSessionRulesWrite` is the one write judge every store calls. It now returns the rules with `grammar: SESSION_RULES_GRAMMAR` (`1`). Both bundled stores, and a durable twin that stores what the judge returns, keep the stamp on the row with no change of their own. `StoredSessionRules.grammar?: number` is new.
+  - **The reading.** `readSessionRulesShape` is the one shape reading, and every station reads through it: the write, a store's read-back, the tighten comparison's prior, the run-time layer and a parked checkpoint's ancestor snapshot. It now also answers the grammar, as `rules.grammar`, always present. A value carrying a store's `rev` and no stamp is grammar 0. A value no store stamped (no `rev`) is written now, in this engine's grammar.
+  - **Grammar 0.** An allow-direction entry whose row the one entry reader reads as speaking for a name other than the entry as written reads as nothing, with reason `earlier_grammar`. That is a `Tool(content)` rule, or `Tool(*)` / `Tool()` read as the bare tool; the test is the reader's own `compiledEntryName(row) !== entry`. A **deny** entry of that form refuses in every grammar, because reading it as the rule it spells only ever refuses more than the name it was. Bare names, namespaces and `allowDirs` read the same in both grammars.
+  - **The announcement.** The engine announces grammar-0 entries once per distinct set per layer, through `onError` with code `config.session_rules_earlier_grammar` (phase `config`, the same channel as `config.session_rules_unreadable`). The message names the session and the entries, and how to rewrite them.
+  - **Refusals.** A stamp above the engine's, or one that is not a whole number ≥ 0, is a shape fault (field `grammar`). The file store refuses that row as `corrupt` (the existing damaged-row path). The run-time layer refuses every call. A write refuses it as `invalid_shape`.
+  - **New list reading.** `compileSessionRuleBucket(rules, field, roster?)` is the list reading of one bucket in its row's grammar. The run-time layer and the tighten comparison both read through it.
+- **The way out (the rewrite).** An operator write of the rules **afresh** stamps them. That means a value without the stored row's `rev`, through `putRules`. After it, the entry is the allow rule it spells. A non-operator write of the same entry is a widening (`loosen_forbidden`, `widened toolAllow with "Bash(rm:*)"`), because the stored entry admitted nothing. A stored row handed back to a write is refused by name (`inert_entry`, reason `earlier_grammar`, nothing written). That covers a read-modify-write and a session-sync replay of an export, so neither can turn the entry into a grant.
+- **Who breaks.**
+  - Rows written before this version whose `toolAllow` holds a parenthesized entry. 7.51.0 / 7.51.1 rows meant as allow rules are included. They admit less until an operator rewrites them; the advisory names each.
+  - Exact-equality on rule rows. `getRules` / `putRules` / `listBySession` values and `readSessionRulesShape(…).rules` now carry `grammar`.
+  - A switch over `AllowEntryInertReason` has one more word.
+  - Rollback or a mixed-version fleet (KL-1761-c). 7.51.1 and earlier read `grammar` as a key that is no bucket, so every row this version writes is a malformed row there: the file store refuses it as `corrupt`, the layer refuses every call, and the SQL twin judges it the same way. The way out on such an engine is to delete the row. A fleet should not let an older replica read a stamped row (server: take this in the same version as M17).
+  - *server*: the SQL twin stores `JSON.stringify(judge result)` and serves `{ ...readSessionRulesShape(body).rules, rev, gen }`, so the stamp rides both ways with no code change. A body read through the shape reading carries no `rev`, so the twin's rows read in this grammar. The twin's own one-column-one-grammar migration (M17) remains its fence for rows written before 7.51.0. A session-sync import of an export holding an unstamped row is now refused by name (400 `rules.inert_entry`, reason `earlier_grammar`) instead of granting. Pins that deep-equal the judge's or the shape reading's output gain `grammar: 1`.
+- **How to migrate.** For each entry the advisory names, either write the session's rules afresh as an operator (the entry becomes the allow rule it spells) or leave it (it keeps admitting nothing). Nothing to do for rows without such entries.
+- **Pins.** `test/backlog1761-rule-row-grammar-version.test.ts` (P0 red on 7.51.1: the lane ran `rm`). It covers the real-lane refusal and advisory, the operator rewrite (stamped; `rm` then runs), the non-operator widening, the handed-back row and the export → import replay refused, an old row's deny still refusing, a later stamp and malformed stamps refused at the store, the layer and the write, a stamped row read as written (and, over the published safety-merge corpus, every tighten verdict and bucket compile unchanged by the stamp), `Bash(*)` / `Bash()` / `Read(*)` / `mcp__srv(*)` read as nothing in grammar 0 (lane, write, widening), and the checkpoint face: a parked unstamped ancestor snapshot resumes in grammar 0, and a parking leg records the stamped row it enforces. Re-pinned: the row key set in `backlog1003-1000` / `file-session-policy-store` (+ `grammar`) and the reason-set arrays in `backlog1358` / `backlog1352` (+ `earlier_grammar`).
+
+### `BUILTIN_SUBAGENT_TYPES` is exported from the package root (#1771; additive; hard-breaking: none; closed sets: +1 set `BuiltinSubagentType`; exports: +1 constant, +1 type) (@client-core @cli @desktop)
+
+- **What changed.** The `subagent_type` words a default deployment accepts without defining an agent of its own — the two built-in definitions `Explore` / `Plan` and the two built-in routes `fork` / `general-purpose` — are one closed set on the root, `BUILTIN_SUBAGENT_TYPES` (frozen; type `BuiltinSubagentType`; registered in `docs/CLOSED-SETS.md`). A deployment definition of the same name shadows the built-in, as before; the Agent tool's accepted domain per deployment is this set ∪ the roster, less shadowed built-ins.
+- **Who breaks.** No one: additive. client-core's generated table (CC-748) and desktop's / cli's local copies retire onto it.
+- **How to migrate.** `import { BUILTIN_SUBAGENT_TYPES } from "@sema-agent/core"`; render pickers from it and keep no copy. `worker` is not a core word (an agent-teams role name lives with the shells).
+
+### `McpServerSpec.toolAxes` has one reader, `readMcpToolAxes`, exported from the package root; the preparation door asks it of every MCP entry (#1763; additive export; behavior narrowing at the door, open to veto; hard-breaking: none; closed sets: none; exports: +1 function, +1 type; members: none) (@server @web-admin)
+
+**Behavior narrowing (open to veto).** (1) **What changed:** a task whose `mcp[i].toolAxes` does not fit now fails at prepare with `config.invalid_argument`, before any server is dialed. (2) **Who is hurt:** a host that declared an axis the type never allowed. It ran before, with the declaration folded as written; it is refused now. (3) **Compensation:** the refusal sentence names the server, the tool and the member, and lists the legal members or words; a host fixes the one declaration it names and resubmits, or asks `readMcpToolAxes` first and never submits the bad one. The compensating alternative is the same reader at the host's own door, so a refusal there and a refusal here are one answer.
+
+- **Before (7.51.1).** `McpServerSpec.toolAxes` was a TypeScript type with no reader behind it. The connect folded `spec.toolAxes?.[remoteName]` as it arrived (`src/core/mcp.ts:4098` into `applyCallerAxisOverride`, `:2573-2593`): an off-vocabulary word, a wrong-case word, a string `egress` or an unknown member went into the fold unjudged. A host that assembled the field from JSON wrote its own reader (server `src/mcp-tool-axes.ts`; web-admin `src/lib/config/mcp-tool-axes.ts` as a transitional copy), so one fact had three readers.
+- **Now.** `readMcpToolAxes(declared: unknown): McpToolAxesRead` (`src/core/mcp-server-spec.ts`, beside the type) answers `{ ok: true, toolAxes? }` or `{ ok: false, problem }`.
+  - **Accepted.** Absent. Otherwise a plain record of per-tool objects whose members are exactly `effect` / `egress` / `irreversibility`: `effect` one of the published vocabulary's tool effects, `egress` a boolean, `irreversibility` one of the vocabulary's words less `maybe` (the word the engine derives from a tool's own declaration; a caller can vouch only for the two poles). The words and the member set are derived from `SAFETY_AXIS_VOCABULARY` and the `toolAxes` type, so a word or member the engine gains moves the reader with it (a member the type gains is a compile error in the reader; the irreversibility words are held to the vocabulary by a compile-time lockstep).
+  - **Refused, whole.** A declaration that is not a plain data record (null, an array, a scalar, a map, a date, a class instance, or an object whose members are inherited from a prototype or are not enumerable: the connect used to read `toolAxes[name]` through the whole chain, so reading only own enumerable keys would have dropped a tightening mark without a word), an empty tool name, a tool whose declaration is not an object, an unknown member, a word outside the vocabulary, a non-boolean `egress`. A null-prototype record and a record built in another realm are plain. One bad tool refuses the whole declaration: the good tools are not kept and no word is defaulted, because a caller axis is two-way (it can vouch a tool down as well as mark it up) and a lost half is a trust root that is not in force. Present `null` is a refusal, not absence.
+  - **The sentence** names the tool and the member and never a value; names are quoted and cut at 80 characters. The reader is total: a getter, a proxy trap or a tag that throws while the declaration is read comes back as a refusal (without the thrown text), never as a throw.
+  - **The copy.** `ok: true` carries a plain copy of what was judged. Empty per-tool objects are dropped and `toolAxes` is absent when nothing is declared; the engine read those as absent already (`applyCallerAxisOverride` folds `{}` to the server's hint unchanged). A tool named `__proto__` is an ordinary key.
+- **The door.** `snapshotAndValidateMcpEntries` (`src/core/locked-config.ts`) asks the reader once per entry, after the content-class question. The entry then carries the reader's copy, frozen with the entry, so what the door approved is what connect and every refresh read: a caller writing its own `toolAxes` object after prepare no longer changes a later refresh, a tool that shallow-copies a server from `mountedMcp()` cannot rewrite the parent's axes (a write throws), and a getter is read once. It runs on every prepare leg (fresh, resume, child), before any side effect.
+- **The entrance.** `materializeMcpTools` (`src/core/mcp.ts`, right after the snapshot) asks the same question per server through the same function (`judgeEntryToolAxes`, `src/core/locked-config.ts`), because the library entrance and the no-run probe reach it without the door. A declaration the reader cannot read fails THAT server's dial: never spawned, a `failed` status of class `invalid_config`, a warning naming the tool and member (`config.invalid_argument`); its siblings dial normally, and a re-dial of it is refused the same way. A passing entry carries the judged frozen copy, so a caller writing its own object after the call does not reach a refresh. `probeMcpServers` dials through this entrance, so a refused declaration is a failed row of class `invalid_config` there.
+- **Not covered, stated.** `A2aServerSpec.toolAxes` has the same shape and no reader yet (A2A peers take neither the door nor the entrance). On a resume leg the door runs after the checkpoint claim, as the content-class question does: the resume's pre-claim screen (`refuseResumeDoors`) does not carry the MCP door, so a resume whose re-supplied `mcp` entry is refused here consumes the row the way those doors already do.
+- **Differs from the server's reader.** It refuses the layouts above (the server's reader returned an empty declaration for a map, a date, and a record whose tools are inherited or not enumerable, and took the inherited members of one tool), and its sentences differ in wording and add the legal members and words. Cell for cell on the server suite's own samples the verdicts are the same (the pin's B group).
+- **Consumers named.** *server* S-1581: retire `readMcpToolAxes` in `src/mcp-tool-axes.ts` and call this one (`web_admin_mcp_tool_axes_invalid.problem` takes the new wording). *web-admin*: delete the transitional copy and the copy in `scripts/check-mcp-header-owner.mjs`.
+- **Pins.** `test/backlog1763-mcp-tool-axes-judge.test.ts`: A (the reader: accepts, each refusal arm, whole refusal, no value in the sentence, bounded names, `__proto__`, one read per property, every vocabulary word), B (the server suite's own cells), C (the door: code and sentence, whole-prepare refusal, the plain-copy hand-off and its freeze, absent and empty mint no key), D (the public task lane: a refused declaration spawns no server, a legal one mounts, and the axes the door approved are the axes the fold carries), E (a resume leg: the MCP door sits after the claim, characterised against a screened door as the control), F (the library entrance, no door: a refused declaration fails that server's dial and is never spawned, siblings dial, a re-dial is refused, the probe's row is `invalid_config`, a passing entry carries the judged copy).
+
 ## 7.51.1 — 2026-10-14
 
 ### `inheritEnv: "all"` is defined once, in core: the whole environment less the deployment's own credentials (#1753; security; behavior narrowing where a deployment declares its list, open to veto; closed sets: +1 set `EngineCapability`, +1 member `SecretEnvFindingKind` `own-credential`; exports: +6, none removed; members: +1 optional notice detail key)

package/dist/agents/subagent.d.ts

@@ -144,6 +144,11 @@ export declare const FORK_SUBAGENT_TYPE = "fork";
  * override the built-in entry).
  */
 export declare const GENERAL_PURPOSE_SUBAGENT_TYPE = "general-purpose";
+/** The `subagent_type` words a default deployment accepts with no agent of its own: the two built-in definitions' names
+ *  and the two built-in routes (a same-named deployment definition shadows the built-in); hosts render pickers from it. */
+export declare const BUILTIN_SUBAGENT_TYPES: readonly ["Explore", "Plan", "fork", "general-purpose"];
+/** One word of {@link BUILTIN_SUBAGENT_TYPES}. */
+export type BuiltinSubagentType = (typeof BUILTIN_SUBAGENT_TYPES)[number];
 /**
  * design/136 §6 盲点① (1.256) + §2.1.a (BREAKING batch) — the fork-GOVERNANCE predicate for the
  * `Agent(subagent_type:"fork")` route (the ONLY fork face since the standalone `Fork` tool was retired,

package/dist/agents/subagent.js

@@ -256,6 +256,7 @@ function createToolStatsCounter(delegationToolName) {
 }
 export const FORK_SUBAGENT_TYPE = "fork";
 export const GENERAL_PURPOSE_SUBAGENT_TYPE = "general-purpose";
+export const BUILTIN_SUBAGENT_TYPES = Object.freeze(["Explore", "Plan", "fork", "general-purpose"]);
 export function forkGovernanceDenial(enableFork, allowFork) {
     if (enableFork === false)
         return "task";

package/dist/core/allow-entry.d.ts

@@ -7,8 +7,10 @@ import { type ToolNameListReading } from "./tool-name-list.js";
 import { type EngineNotice } from "./engine-notice.js";
 /** Why an entry grants (or refuses) nothing — the closed set the start-of-run notice names, for every list. `tool_name`: the
  *  entry's tool name is one the name judgment reads as stale against the run's roster (`verdict` says which); `near_miss`: the
- *  run mounts no tool of that exact name but mounts one that differs only by case (`currentName` is its spelling). */
-export declare const ALLOW_ENTRY_INERT_REASONS: readonly ["wildcard_all", "namespace_wildcard", "content_unsupported", "grammar", "tool_name", "near_miss"];
+ *  run mounts no tool of that exact name but mounts one that differs only by case (`currentName` is its spelling);
+ *  `earlier_grammar`: a session's stored rules are written in an earlier rule grammar, in which the entry named no tool (the
+ *  session store's list reading, `compileSessionRuleBucket` — this reader never answers it). */
+export declare const ALLOW_ENTRY_INERT_REASONS: readonly ["wildcard_all", "namespace_wildcard", "content_unsupported", "grammar", "tool_name", "near_miss", "earlier_grammar"];
 export type AllowEntryInertReason = (typeof ALLOW_ENTRY_INERT_REASONS)[number];
 /** The facts beside a reason: for `tool_name` / `near_miss` the judgment's word, the judgment's own one-line sentence when it has
  *  one (`guidance`, byte for byte — `retired` and `unmintable_segment` carry one, `unprefixed_namespace` none) and the spelling to

package/dist/core/allow-entry.js

@@ -11,7 +11,7 @@ import { mandateDisclosureOf } from "./ask-origin.js";
 import { inlineUntrusted } from "./untrusted-text.js";
 import { valueTypeLabel } from "./tool-name-list.js";
 import { deliverEngineNotice } from "./engine-notice.js";
-export const ALLOW_ENTRY_INERT_REASONS = Object.freeze(["wildcard_all", "namespace_wildcard", "content_unsupported", "grammar", "tool_name", "near_miss"]);
+export const ALLOW_ENTRY_INERT_REASONS = Object.freeze(["wildcard_all", "namespace_wildcard", "content_unsupported", "grammar", "tool_name", "near_miss", "earlier_grammar"]);
 export function nonStringMemberLabel(value) {
     return `<not a string: ${valueTypeLabel(value)}>`;
 }

package/dist/core/locked-config.d.ts

@@ -39,8 +39,8 @@ export interface LockedPreflight {
     /** The validated lock set (empty when the deployment declares none). */
     lockedKeys: ReadonlySet<LockedKey>;
     /** Effective MCP server list for this task: a validated, frozen SNAPSHOT of `spec.mcp` when the
-     *  key is unlocked (see {@link snapshotAndValidateMcpEntries} — the content-class declaration is read once
-     *  and judged here, so no mint site downstream can be handed a different value than the door
+     *  key is unlocked (see {@link snapshotAndValidateMcpEntries} — the content-class and `toolAxes` declarations
+     *  are read once and judged here, so no mint site downstream can be handed a different value than the door
      *  approved); with `mcp` locked a spec-supplied value has already been refused, so this is always
      *  `undefined` (core has no deployment-level MCP seat — a locked deployment mounts no
      *  task-supplied servers). */
@@ -84,15 +84,36 @@ export declare function resolveLockedKeys(config: LockedConfig | undefined): Rea
  * Boundary, stated: the copy is one level deep — nested option objects (transport, headers, env,
  * toolAxes) stay shared with the caller's entry exactly as before, because the axis this owns is the
  * content class; readers of the nested shapes normalize their own values (the transport DISCRIMINATOR
- * is derived, never echoed raw). Own ENUMERABLE properties only: an entry whose fields live on a
- * prototype was never the plain configuration record this type describes, and its absent class reads
- * fail-closed like any other absence.
+ * is derived, never echoed raw). `toolAxes` is the one nested shape both entrances replace with its
+ * reader's plain copy ({@link judgeEntryToolAxes}), and the one member this snapshot reads BY NAME rather
+ * than by spread, once: a declaration an entry carries as a non-enumerable or inherited property would
+ * otherwise vanish before any reader sees it, and an absent caller axis is a tightening lost, not a
+ * fail-closed absence. Every other member is taken as own ENUMERABLE properties only: an entry whose
+ * fields live on a prototype was never the plain configuration record this type describes, and its
+ * absent class reads fail-closed like any other absence.
  *
  * Exported because the SECOND boundary needs the identical guarantee: `materializeMcpTools` is public
  * and a library caller reaches it without passing any door, so it snapshots its own input through
  * this same function (idempotent over an already-frozen entry). One spelling, both entrances.
  */
 export declare function snapshotMcpEntries(entries: readonly McpServerSpec[]): McpServerSpec[];
+/**
+ * The `toolAxes` question for ONE snapshot entry — asked by the preparation door (a refusal ends the prepare) and by the materialization
+ * entrance (a refusal fails that server's dial), so there is one reading, one copy and one sentence whichever time it is asked.
+ * `ok: true` carries the entry with the reader's PLAIN COPY of the axes in place of the caller's object: what was judged is the very value
+ * the connect and every refresh read, not a live object that could answer differently later. The copy is frozen with the entry — a tool
+ * that shallow-copies a server (`mountedMcp()`) to customise its axes must not rewrite what the parent reads. `ok: false` carries the
+ * coded refusal (`config.invalid_argument`) naming the server, the tool and the member, never a value.
+ */
+export declare function judgeEntryToolAxes(copy: McpServerSpec): {
+    ok: true;
+    entry: McpServerSpec;
+} | {
+    ok: false;
+    error: Error & {
+        code: string;
+    };
+};
 /**
  * The single preflight resolver: validate the lock declaration, refuse a spec that tries to occupy
  * a locked slot (`config.locked_key`, two-state — the whole prepare is rejected, nothing is

package/dist/core/locked-config.js

@@ -1,3 +1,4 @@
+import { readMcpToolAxes } from "./mcp-server-spec.js";
 import { isToolContentOrigin, TOOL_CONTENT_ORIGINS } from "./memory-engine/content-origin.js";
 import { inlineUntrusted } from "./untrusted-text.js";
 import { assertNoRetiredToolPolicyKeys } from "./retired-keys.js";
@@ -27,7 +28,10 @@ export function resolveLockedKeys(config) {
     return keys;
 }
 export function snapshotMcpEntries(entries) {
-    return entries.map((entry) => Object.freeze({ ...entry }));
+    return entries.map((entry) => {
+        const { toolAxes, ...rest } = entry;
+        return Object.freeze((toolAxes === undefined ? rest : { ...rest, toolAxes }));
+    });
 }
 function describeDeclared(value) {
     try {
@@ -42,20 +46,41 @@ function describeDeclared(value) {
         }
     }
 }
+const serverNameOf = (copy) => inlineUntrusted(typeof copy.name === "string" ? JSON.stringify(copy.name) : describeDeclared(copy.name), 80);
+export function judgeEntryToolAxes(copy) {
+    const { toolAxes: declaredAxes, ...rest } = copy;
+    const axes = readMcpToolAxes(declaredAxes);
+    if (!axes.ok) {
+        return {
+            ok: false,
+            error: codedError("config.invalid_argument", `MCP server ${serverNameOf(copy)} declares toolAxes the engine cannot read: ${inlineUntrusted(axes.problem, 240)}. A per-tool safety-axis declaration is the ` +
+                `caller's trust root for the approval gate, so it is refused rather than partly applied — dropping one key or defaulting one word ` +
+                `would leave a declaration that reads as in force while it is not.`),
+        };
+    }
+    if (axes.toolAxes !== undefined) {
+        for (const perTool of Object.values(axes.toolAxes))
+            Object.freeze(perTool);
+        Object.freeze(axes.toolAxes);
+    }
+    return { ok: true, entry: Object.freeze(axes.toolAxes === undefined ? rest : { ...rest, toolAxes: axes.toolAxes }) };
+}
 function snapshotAndValidateMcpEntries(entries) {
-    const copies = snapshotMcpEntries(entries);
-    for (const copy of copies) {
+    return snapshotMcpEntries(entries).map((copy) => {
         const declared = copy.contentOrigin;
         if (declared !== undefined && !isToolContentOrigin(declared)) {
-            throw codedError("config.mcp_content_class", `MCP server ${inlineUntrusted(typeof copy.name === "string" ? JSON.stringify(copy.name) : describeDeclared(copy.name), 80)} declares contentOrigin ` +
+            throw codedError("config.mcp_content_class", `MCP server ${serverNameOf(copy)} declares contentOrigin ` +
                 `${inlineUntrusted(describeDeclared(declared), 80)}, which is not one of ` +
                 `${TOOL_CONTENT_ORIGINS.map((v) => `"${v}"`).join(" | ")}. The declaration decides whether this server's tools ` +
                 `mark the session's memory externally exposed — a value this engine cannot read is refused at the door rather ` +
                 `than folded to a class, because folding it would let a deployment believe a declaration is in force while every ` +
                 `call keeps writing a one-way durable mark.`);
         }
-    }
-    return copies;
+        const judged = judgeEntryToolAxes(copy);
+        if (!judged.ok)
+            throw judged.error;
+        return judged.entry;
+    });
 }
 export function preflightLockedConfig(spec, deps) {
     const lockedKeys = resolveLockedKeys(deps.lockedConfig);

package/dist/core/mcp-server-spec.d.ts

@@ -1,10 +1,3 @@
-/**
- * How a deployment DECLARES an external tool server and what an elicitation round-trip looks like:
- * `McpServerSpec` (stdio / HTTP / in-process MCP), `A2aServerSpec` (the agent-to-agent peer) and the
- * elicit pair (`McpElicitRequest` / `McpElicitResponse` / `OnElicit`). Named `mcp-server-spec.ts`, not
- * `mcp.ts`: `src/core/mcp.ts` is the CLIENT, and two files a letter apart would be a worse hazard than
- * a longer name. Layer 0 vocabulary; `types.ts` re-exports every name below.
- */
 import type { ToolContentOrigin, ToolEffect } from "./tool-spec.js";
 import type { ToolFamily, ToolPathTarget, ToolRenderHints, ToolRuleFace } from "./tool-face.js";
 /** Definition of an MCP server to connect to for the duration of one task, then discard. */
@@ -67,6 +60,15 @@ export interface McpServerSpec {
      * BRINGS BACK (memory-write governance, no gate/policy/roster effect). Neither implies the other —
      * a read-only tool can return third-party text, and a deployment's own writer brings back nothing
      * external — so vouching on one axis never quietly vouches on the other.
+     *
+     * THE SHAPE IS JUDGED, NOT TRUSTED: {@link readMcpToolAxes} is the one reader of this declaration. The
+     * preparation door runs it on every entry, and a declaration it cannot read refuses the whole prepare
+     * (`config.invalid_argument`) — one bad tool refuses the entry, a bad key is never dropped and a bad word
+     * never defaults, because a caller's safety axis that silently reads as absent is a trust root that is not
+     * in force. The materialization entrance (`materializeMcpTools`, which the no-run probe dials through) asks
+     * it again per server: a declaration it cannot read fails THAT server's dial. A host that assembles this
+     * field from JSON (a console, a deployment intake) asks the same reader at its own door, so both sides
+     * answer one question one way.
      */
     toolAxes?: Record<string, {
         effect?: ToolEffect;
@@ -147,6 +149,33 @@ export interface McpServerSpec {
      */
     fingerprint?: string;
 }
+type ToolAxes = NonNullable<McpServerSpec["toolAxes"]>;
+/**
+ * {@link readMcpToolAxes}'s answer. `ok: true` carries the declaration as a PLAIN COPY the reader built from
+ * what it judged (never the caller's own object); `toolAxes` is absent when the entry declares nothing — no
+ * key at all, or only empty per-tool objects (which the engine reads the same as no declaration). `ok: false`
+ * carries one sentence naming the tool and the member that did not fit, never a value.
+ */
+export type McpToolAxesRead = {
+    ok: true;
+    toolAxes?: ToolAxes;
+} | {
+    ok: false;
+    problem: string;
+};
+/**
+ * The one reader of a raw {@link McpServerSpec.toolAxes} declaration — the engine's preparation door and
+ * every host that assembles the field from JSON ask this same function. Absent ⇒ `{ ok: true }` (nothing
+ * declared). Anything else must be an object of per-tool objects whose members are exactly `effect` /
+ * `egress` / `irreversibility` with legal values; a declaration of any other shape, an empty tool name, an
+ * unknown member, a word outside the vocabulary or a non-boolean `egress` on ANY one tool refuses the whole
+ * declaration (`ok: false`) — the good tools are not kept and nothing is defaulted, since a caller axis is
+ * two-way (it can vouch a tool down as well as mark it up) and a silently lost half is a trust root that is
+ * not in force. The reader judges SHAPE only; whether the axes contradict each other (`egress` over a
+ * non-write effect) is the ingestion's own arithmetic. The reader is total: a getter, a proxy trap or a tag
+ * that throws while the declaration is read is a refusal that says so (never the thrown text), not a throw.
+ */
+export declare function readMcpToolAxes(declared: unknown): McpToolAxesRead;
 /** The identity of one mount of a declared server, as the host minted it ({@link McpServerSpec.fingerprint}). */
 export interface McpMountIdentity {
     readonly fingerprint: string;
@@ -254,3 +283,4 @@ export interface McpElicitResponse {
  * over-eager or untrusted server here (the request's `AbortSignal` is forwarded so a deadline can cancel it).
  */
 export type OnElicit = (req: McpElicitRequest, signal?: AbortSignal) => Promise<McpElicitResponse>;
+export {};

package/dist/core/mcp-server-spec.js

@@ -1 +1,84 @@
-export {};
+import { SAFETY_AXIS_VOCABULARY } from "./safety-axis-vocab.js";
+const TOOL_AXIS_MEMBERS = { effect: true, egress: true, irreversibility: true };
+const TOOL_AXIS_MEMBER_NAMES = Object.keys(TOOL_AXIS_MEMBERS);
+const TOOL_EFFECT_WORDS = SAFETY_AXIS_VOCABULARY.toolEffect;
+const ENGINE_DERIVED_IRREVERSIBILITY = "maybe";
+const IRREVERSIBILITY_POLE_WORDS = SAFETY_AXIS_VOCABULARY.irreversibility.filter((word) => word !== ENGINE_DERIVED_IRREVERSIBILITY);
+const irreversibilityPolesLockstep = true;
+void irreversibilityPolesLockstep;
+function quotedName(name) {
+    return JSON.stringify(name.length > 80 ? `${name.slice(0, 80)}…` : name);
+}
+function describeKind(value) {
+    return value === null ? "null" : Array.isArray(value) ? "an array" : typeof value === "object" ? "an object that is not a plain data record (a map, a class instance, or members that are inherited or not enumerable)" : `a ${typeof value}`;
+}
+const ROOT_PROTOTYPE_NAMES = Object.getOwnPropertyNames(Object.prototype).sort().join("\n");
+function isRootPrototype(proto) {
+    if (proto === Object.prototype)
+        return true;
+    return Object.getPrototypeOf(proto) === null && Object.getOwnPropertyNames(proto).sort().join("\n") === ROOT_PROTOTYPE_NAMES;
+}
+function isPlainRecord(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== null && !isRootPrototype(proto))
+        return false;
+    return Object.getOwnPropertyNames(value).length === Object.keys(value).length;
+}
+function isToolEffectWord(value) {
+    return typeof value === "string" && TOOL_EFFECT_WORDS.includes(value);
+}
+function isIrreversibilityPoleWord(value) {
+    return typeof value === "string" && IRREVERSIBILITY_POLE_WORDS.includes(value);
+}
+function readToolAxisEntry(raw) {
+    if (!isPlainRecord(raw))
+        return `the declaration is ${describeKind(raw)}, not an object of axes`;
+    for (const member of Object.keys(raw)) {
+        if (!TOOL_AXIS_MEMBER_NAMES.includes(member))
+            return `unknown member ${quotedName(member)} (the members are ${TOOL_AXIS_MEMBER_NAMES.join(", ")})`;
+    }
+    const { effect, egress, irreversibility } = raw;
+    if (effect !== undefined && !isToolEffectWord(effect))
+        return `member "effect" is not one of ${TOOL_EFFECT_WORDS.join(" | ")}`;
+    if (egress !== undefined && typeof egress !== "boolean")
+        return `member "egress" is not a boolean`;
+    if (irreversibility !== undefined && !isIrreversibilityPoleWord(irreversibility))
+        return `member "irreversibility" is not one of ${IRREVERSIBILITY_POLE_WORDS.join(" | ")}`;
+    return {
+        ...(effect !== undefined ? { effect } : {}),
+        ...(egress !== undefined ? { egress } : {}),
+        ...(irreversibility !== undefined ? { irreversibility } : {}),
+    };
+}
+export function readMcpToolAxes(declared) {
+    if (declared === undefined)
+        return { ok: true };
+    let perTool;
+    try {
+        if (!isPlainRecord(declared))
+            return { ok: false, problem: `toolAxes is ${describeKind(declared)}, not an object of per-tool axis declarations` };
+        perTool = Object.entries(declared);
+    }
+    catch {
+        return { ok: false, problem: "toolAxes could not be read: a property threw while it was read" };
+    }
+    const entries = [];
+    for (const [tool, raw] of perTool) {
+        if (tool.length === 0)
+            return { ok: false, problem: "toolAxes has an empty tool name" };
+        let entry;
+        try {
+            entry = readToolAxisEntry(raw);
+        }
+        catch {
+            entry = "a member threw while it was read";
+        }
+        if (typeof entry === "string")
+            return { ok: false, problem: `the axes declared for tool ${quotedName(tool)} do not fit: ${entry}` };
+        if (Object.keys(entry).length > 0)
+            entries.push([tool, entry]);
+    }
+    return entries.length > 0 ? { ok: true, toolAxes: Object.fromEntries(entries) } : { ok: true };
+}

package/dist/core/mcp.js

@@ -25,7 +25,7 @@ import { MARKED_BLOCK_AFTER_DATA } from "./reminder-mint.js";
 import { resolveMcpDeclaredResultSize, resolveMcpRequiresUserInteraction } from "./mcp-tool-meta.js";
 export { resolveMcpDeclaredResultSize } from "./mcp-tool-meta.js";
 import { withContentOrigin } from "./memory-engine/content-origin.js";
-import { snapshotMcpEntries } from "./locked-config.js";
+import { judgeEntryToolAxes, snapshotMcpEntries } from "./locked-config.js";
 import { validateJsonSchemaShape } from "./runner/strict-output-schema.js";
 import { schemaKeyBoundProblem } from "./tool-roster.js";
 import { readMember, thrownIs, thrownName, thrownText } from "./thrown-value.js";
@@ -657,7 +657,15 @@ export function mcpToolSchemaProblem(schema) {
     return undefined;
 }
 export async function materializeMcpTools(specs, principal, onElicit, imageResizer, reminderDisclosure, mcpRevocations, poolOpts, promptSections) {
-    const entries = snapshotMcpEntries(specs);
+    const snapshot = snapshotMcpEntries(specs);
+    const axesRefused = new WeakMap();
+    const entries = snapshot.map((spec) => {
+        const judged = judgeEntryToolAxes(spec);
+        if (judged.ok)
+            return judged.entry;
+        axesRefused.set(spec, judged.error);
+        return spec;
+    });
     {
         const collision = findNamespacePrefixCollision(MCP_NAMESPACE, entries.map((s) => s.name));
         if (collision) {
@@ -773,6 +781,10 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
         }
     };
     const dialKinds = entries.map(readDialKind);
+    const dialServer = (spec, dialKind, dialOpts) => {
+        const refusal = axesRefused.get(spec);
+        return refusal !== undefined ? Promise.reject(refusal) : connectServer(spec, principal, onElicit, imageResizer, mcpDisclosure, isServerRevoked, dialKind, poolOpts?.pool, dialOpts);
+    };
     const prefixOf = (name) => mintNamespacePrefix(MCP_NAMESPACE, name);
     const reconcileInstructions = (name, before, after, connected) => {
         let owedRemoval = false;
@@ -798,7 +810,7 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
         if (before !== undefined || owedRemoval || hadPendingAdd)
             instructionsDelta.pendingRemovals.push(name);
     };
-    const settled = await Promise.allSettled(entries.map((spec, i) => connectServer(spec, principal, onElicit, imageResizer, mcpDisclosure, isServerRevoked, dialKinds[i], poolOpts?.pool, { sections: promptSections })));
+    const settled = await Promise.allSettled(entries.map((spec, i) => dialServer(spec, dialKinds[i], { sections: promptSections })));
     try {
         for (let i = 0; i < entries.length; i++) {
             const r = settled[i];
@@ -855,7 +867,7 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
             const dialKind = readDialKind(spec);
             let connected;
             try {
-                connected = await connectServer(spec, principal, onElicit, imageResizer, mcpDisclosure, isServerRevoked, dialKind, poolOpts?.pool, { fresh: true, sections: promptSections });
+                connected = await dialServer(spec, dialKind, { fresh: true, sections: promptSections });
             }
             catch (err) {
                 const { kind, delivered, httpStatus } = classifyMcpFailure(err, { phase: "connect", transport: dialKind });

package/dist/core/runner/prepare-policy-chain.d.ts

@@ -25,7 +25,7 @@ import { type AskClass } from "../ask-class.js";
 import type { AutoModeDecider } from "../auto-mode.js";
 import { type Hooks } from "../hooks.js";
 import type { LockedPreflight } from "../locked-config.js";
-import type { SessionPermissionRules } from "../session-policy-store.js";
+import { type SessionPermissionRules } from "../session-policy-store.js";
 import { type OnAsk, type ToolPolicy } from "../tool-policy.js";
 import type { PathRuleBases } from "../permission-rule-model.js";
 import type { HeadLeads } from "../path-rule-binding.js";

package/dist/core/runner/prepare-policy-chain.js

@@ -7,6 +7,7 @@ import { cloneObserverInput, resolveHookTimeoutMs } from "../hooks.js";
 import { assertHookSeatsCallable } from "../hook-seats.js";
 import { isNamespacedCoveringRuleName, namespacedRuleNameCovers } from "../permission-rules.js";
 import { isIsolated } from "../remote-env.js";
+import { earlierGrammarAdvisory } from "../session-policy-store.js";
 import { askApproverIdentity, attest, attestationOf, checkToolPolicyProjection, combinePolicies, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, durableParkOptInDeclared, isLiveApproverSeat, mergeAttestation, refuseOutOfContractDecision, resolveAsk, toolPolicyNameSets, withAttestation, wrapToolPolicy } from "../tool-policy.js";
 import { judgeRuleToolName, mountedToolNames } from "../tool-name-aliases.js";
 import { approvalCardMemberOf } from "../tool-roster.js";
@@ -110,6 +111,7 @@ export async function preparePolicyChain(input) {
         catch {
         }
     };
+    const announceEarlierGrammar = (rulesSessionId) => (entries) => deps.onError?.(Object.assign(new Error(earlierGrammarAdvisory(rulesSessionId, entries)), { code: "config.session_rules_earlier_grammar" }), { phase: "config", sessionId });
     let sessionRulePolicy;
     if (deps.sessionPolicyStore && spec.sessionId) {
         const store = deps.sessionPolicyStore;
@@ -125,7 +127,7 @@ export async function preparePolicyChain(input) {
                 rules: row,
             };
         };
-        sessionRulePolicy = createSessionRulePolicy({ seed, read: createLiveSessionRules(store, { ...sessionRuleKey, seed }, { onUnreadable: announceSessionRulesUnreadable, onEnforced: publishOwnRules }) }, { env: executionEnv, rootPath: taskRootFinal, toolEffects, anchors: pathRuleAnchors.leg });
+        sessionRulePolicy = createSessionRulePolicy({ seed, read: createLiveSessionRules(store, { ...sessionRuleKey, seed }, { onUnreadable: announceSessionRulesUnreadable, onEnforced: publishOwnRules }) }, { env: executionEnv, rootPath: taskRootFinal, toolEffects, anchors: pathRuleAnchors.leg, onEarlierGrammar: announceEarlierGrammar(sessionRuleKey.sessionId) });
         if (rules)
             publishOwnRules(rules);
     }
@@ -146,7 +148,7 @@ export async function preparePolicyChain(input) {
             ...(deps.sessionPolicyStore
                 ? { read: createLiveSessionRules(deps.sessionPolicyStore, { sessionId: snap.sessionId, ...(snap.principal !== undefined ? { principal: snap.principal } : {}), seed }, { onUnreadable: announceSessionRulesUnreadable, onEnforced: publishAncestorRules }) }
                 : {}),
-        }, { env: executionEnv, rootPath: taskRootFinal, toolEffects, anchors: pathRuleAnchors.leg }));
+        }, { env: executionEnv, rootPath: taskRootFinal, toolEffects, anchors: pathRuleAnchors.leg, onEarlierGrammar: announceEarlierGrammar(snap.sessionId) }));
     }
     const frozenConstraintLayers = (seedInheritedGate?.constraintChain ?? [])
         .filter((e) => !("opaque" in e))

package/dist/core/runner/session-rule-policy.d.ts

@@ -111,7 +111,8 @@ export declare function createLiveSessionRules(store: SessionPolicyStore, floor:
  *    (a line it cannot read against the rule is refused too), a path rule over every view of the call's target.
  *  - `toolAllow` (if set) → deny any call no entry admits (the matcher's allow reading in the `narrowing` posture: every
  *    segment of a command line named by an entry; never the allow layer's auto-mode strip), naming the uncovered segment.
- *  - an entry that reads as nothing → in no row (it guards and grants nothing; the prepare-time audit names it).
+ *  - an entry that reads as nothing → in no row (it guards and grants nothing; the prepare-time audit names it, or
+ *    `onEarlierGrammar`, once per distinct set, when its snapshot's own earlier grammar reads it so).
  *  - a snapshot the shape reading refuses → deny every call, saying what it holds (never its text).
  *  - `allowDirs` (if set) → a WRITE tool must land inside one of the dirs (resolved via `canonicalizeTarget`,
  *    so a symlink can't carry across a write out); a write-capable tool that cannot be path-confined (e.g. `bash`)
@@ -131,4 +132,5 @@ export declare function createSessionRulePolicy(rules: SessionPermissionRules |
     rootPath?: string;
     toolEffects?: ReadonlyMap<string, ToolEffect>;
     anchors?: PathRuleBases;
+    onEarlierGrammar?: (entries: readonly string[]) => void;
 }): NamedToolPolicy;

package/dist/core/runner/session-rule-policy.js

@@ -1,6 +1,6 @@
 import { canonicalizeTarget, isWinFormPath, pathFamilyOf, writeTargetPath } from "../../tools/fs/safety.js";
-import { continuesLineage, readSessionRulesShape } from "../session-policy-store.js";
-import { compileAllowList, compiledEntryName, judgeAllowEntries, uncoveredCommandSegment } from "../allow-entry.js";
+import { compileSessionRuleBucket, continuesLineage, earlierGrammarAnnouncer, readSessionRulesShape } from "../session-policy-store.js";
+import { compiledEntryName, judgeAllowEntries, uncoveredCommandSegment } from "../allow-entry.js";
 import { inlineUntrusted } from "../untrusted-text.js";
 import { callTargetReadingOf, pathTargetBaseOf, readCallTarget } from "../effective-path-target.js";
 import { egressThrownText } from "../untrusted-egress.js";
@@ -104,26 +104,27 @@ export function createLiveSessionRules(store, floor, hooks) {
         return p;
     };
 }
-function compileSessionRules(rules) {
+function compileSessionRules(rules, announceEarlier) {
     const shaped = readSessionRulesShape(rules);
     if ("fault" in shaped) {
         const { field, got } = shaped.fault;
         const what = got === "not a rule bucket" ? "a key that is no rule bucket" : field === "" ? `a value that is ${got}, not an object of rule buckets` : `${field} holding ${got}`;
         return { deny: [], allow: undefined, allowDirs: undefined, pathRows: false, names: { deny: [], allow: [] }, unreadable: `the session rules cannot be read as rules (they hold ${what}) — every call is refused until they are rewritten` };
     }
-    const { toolDeny, toolAllow, allowDirs } = shaped.rules;
-    const denyList = compileAllowList(toolDeny ?? [], "deny");
-    const allowList = toolAllow === undefined ? undefined : compileAllowList(toolAllow, "allow");
+    const { toolAllow, allowDirs } = shaped.rules;
+    const denyList = compileSessionRuleBucket(shaped.rules, "toolDeny");
+    const allowList = toolAllow === undefined ? undefined : compileSessionRuleBucket(shaped.rules, "toolAllow");
     const rowsOf = (behavior, list) => list.rows.map((r) => ({ behavior, entry: r.entry, compiled: r.compiled }));
     const deny = rowsOf("deny", denyList);
     const allow = allowList === undefined ? undefined : rowsOf("allow", allowList);
-    const namesOf = (rows, list) => [...rows.map((r) => compiledEntryName(r.compiled)), ...(list?.inert ?? []).map((i) => i.entry)];
+    const named = (list, earlier) => (list?.inert ?? []).filter((i) => (i.reason === "earlier_grammar") === earlier).map((i) => i.entry);
+    announceEarlier(named(allowList, true));
     return {
         deny,
         allow,
         allowDirs: allowDirs !== undefined && allowDirs.length > 0 ? allowDirs : undefined,
         pathRows: [...deny, ...(allow ?? [])].some((r) => r.compiled.kind === "path"),
-        names: { deny: namesOf(deny, denyList), allow: namesOf(allow ?? [], allowList) },
+        names: { deny: [...deny.map((r) => compiledEntryName(r.compiled)), ...named(denyList, false)], allow: [...(allow ?? []).map((r) => compiledEntryName(r.compiled)), ...named(allowList, false)] },
     };
 }
 export function createSessionRulePolicy(rules, opts) {
@@ -132,11 +133,12 @@ export function createSessionRulePolicy(rules, opts) {
     const source = "seed" in rules ? rules : { seed: rules };
     const seed = source.seed;
     const readRules = source.read ?? (() => Promise.resolve(seed));
+    const announceEarlier = earlierGrammarAnnouncer(opts.onEarlierGrammar);
     let compiledFor;
     let compiled;
     const compile = (r) => {
         if (compiled === undefined || compiledFor !== r) {
-            compiled = compileSessionRules(r);
+            compiled = compileSessionRules(r, announceEarlier);
             compiledFor = r;
         }
         return compiled;

package/dist/core/secret-env.d.ts

@@ -63,6 +63,11 @@ export type InheritEnvPolicy = "all" | "scrub" | string[];
  * from the next spawn on — a spawn whose environment is already read (one announcing its findings) keeps it. The
  * list is copied. A malformed list — not an array, an entry that is no variable name, or a name the host hands every
  * child anyway ({@link runtimeSuppliedEnv}) — throws and leaves the declaration as it was.
+ *
+ * Two Windows readings, measured on a real machine: a withheld name that the child's own shell or runtime re-creates
+ * with a DEFAULT of its own (`ComSpec`, `PATHEXT`, `HOME`, `CommonProgramFiles`, …) shows up in the child's table with
+ * that default, never with this process's value — withheld, not leaked; and the disclosure (`detail.ownCredentials`)
+ * spells each withheld name as this process's environment spells it, not as the declaration spelled it.
  */
 export declare function declareWithheldEnv(names: readonly string[]): void;
 /** Test seam: never called by production code (a host re-declares `[]`). */