@sema-agent/settings-schema 17.2.0 → 19.0.0

package/dist/hooks-config.js

@@ -99,14 +99,26 @@ export const HOOK_EVENTS = [...CC_198_HOOK_EVENTS, ...POST_198_HOOK_EVENTS];
 const HOOK_GUARD_EVENTS = ["PreToolUse", "PermissionRequest"];
 // ── entry vocabulary and the one field table ───────────────────────────────────────────────────────────────
 /**
- * The hook entry `type` closed set — CC 2.1.296's five (`cli296.js:237454`): `command` (shell command on the host that runs the hook),
+ * The hook entry `type` closed set — CC 2.1.296's five (`cli296.js:237454`): `command` (a command on the host that runs the hook: a shell command line, or — with `args` — an executable spawned directly, no shell),
  * `prompt` (one-shot LLM evaluation of the hook input), `agent` (agentic verifier loop), `http` (POST the hook input to a URL),
  * `mcp_tool` (call a tool on an already-configured MCP server). An entry of another type is a bad piece — and in a guard event that rejects
  * the whole document, which is why `test/upstream-drift.test.ts` ①b holds this set against the CC anchor snapshot.
  */
 export const HOOK_ENTRY_TYPES = ["command", "prompt", "agent", "http", "mcp_tool"];
+/**
+ * The `onFailure` closed set (CC `cli309.js:252382`, `onFailure:At()`): what a FAILURE of the hook does — it could not start (a missing script), timed out, exited with a code other
+ * than 0 or 2, or printed JSON that is invalid or fails validation. `continue` (CC's default when the key is absent; this package does not fill it in — an absent key stays absent): the
+ * failure is reported and the action goes ahead. `block`: the failure counts as exit code 2, so the action the event guards is blocked. Carried by `command` and `http` entries only.
+ * CARRIED, not executed here: a consumer that reads `block` executes it or refuses it — ignoring it makes a guard that cannot start let the action through.
+ * The classifier reads this set through a closure-private projection that the compiler ties to it in both directions.
+ */
+export const HOOK_ON_FAILURE_WORDS = ["continue", "block"];
 /** `shell` values: 'bash' = the user's $SHELL family; 'powershell' = pwsh. Default bash. */
 const HOOK_SHELLS = ["bash", "powershell"];
+/** The classifier's reading of {@link HOOK_ON_FAILURE_WORDS}. The classifier is copied as source by consumers' generators, so its closure cannot read an exported name (its one free name
+ *  is {@link HOOK_EVENTS}): this record is the closure-private projection of the exported set, and the compiler ties the two in both directions — a word added to the set without a row
+ *  here, or a row here that the set does not hold, is a compile error. */
+const HOOK_ON_FAILURE_ACCEPTED = { continue: true, block: true };
 /** Fields every entry type takes: `if` = permission-rule syntax (e.g. "Bash(git *)") evaluated against tool_name/tool_input before the hook
  *  runs (tool events only; shell superset field, CC-compatible); `timeout` = seconds for this entry (default `DEFAULT_HOOK_TIMEOUT_SECONDS`);
  *  `statusMessage` = spinner status message; `once` = run once, then remove. */
@@ -114,18 +126,23 @@ const HOOK_ENTRY_COMMON_FIELDS = { if: "string?", timeout: "seconds?", statusMes
 /**
  * THE field table of a hook entry, per type — read by {@link classifyHooksConfig} (which field is bad, what is carried) and by the entry
  * types below (derived from it). Field order = the order a loaded entry's keys come out in.
- *  · command: `shell` (see above), `async` = run in background without blocking, `asyncRewake` = background + wake the model on exit 2;
+ *  · command: `args` = exec form (CC `cli309.js:252382`: when present — `[]` included — `command` is an executable spawned directly with these arguments, no shell; the mere
+ *    presence of `args` is the switch), `shell` (see above), `async` = run in background without blocking, `asyncRewake` = background + wake the model on exit 2,
+ *    `onFailure` (see {@link HOOK_ON_FAILURE_WORDS});
  *  · prompt / agent: `prompt` ($ARGUMENTS = the hook input JSON), `model`;
  *  · http: `url`, `headers` (values may reference $NAMEs listed in `allowedEnvVars` — env-NAME interpolation only, the config never carries a
- *    secret value; `interpolateHookEnvVars` is the one reading), `allowedEnvVars`;
+ *    secret value; `interpolateHookEnvVars` is the one reading), `allowedEnvVars`, `onFailure` (the other schema CC gives it to);
  *  · mcp_tool: `server` (an already-configured MCP server's name), `tool`, `input` (the tool's arguments; string values may interpolate
  *    `${path}` from the hook input JSON — CC 2.1.296 semantics, the runner's business).
+ * NOT in the table, on purpose: CC's `@internal` command / http keys `rewakeMessage` / `rewakeSummary` / `cloud` (not public settings keys; `cloud` even reads a bad value
+ * as 'skip' and loads the file) and the prompt entry's `continueOnBlock`. A key outside a type's row is not carried and not a bad piece (`docs/CC-DIVERGENCE.md` H7) —
+ * which is also why `args` on a non-command entry and `onFailure` on a prompt / agent / mcp_tool entry are such keys.
  */
 const HOOK_ENTRY_FIELDS = {
-    command: { command: "text", shell: "shell?", async: "boolean?", asyncRewake: "boolean?", ...HOOK_ENTRY_COMMON_FIELDS },
+    command: { command: "text", args: "argv?", shell: "shell?", async: "boolean?", asyncRewake: "boolean?", onFailure: "onFailure?", ...HOOK_ENTRY_COMMON_FIELDS },
     prompt: { prompt: "text", model: "string?", ...HOOK_ENTRY_COMMON_FIELDS },
     agent: { prompt: "text", model: "string?", ...HOOK_ENTRY_COMMON_FIELDS },
-    http: { url: "text", headers: "stringRecord?", allowedEnvVars: "stringList?", ...HOOK_ENTRY_COMMON_FIELDS },
+    http: { url: "text", headers: "stringRecord?", allowedEnvVars: "stringList?", onFailure: "onFailure?", ...HOOK_ENTRY_COMMON_FIELDS },
     mcp_tool: { server: "string", tool: "string", input: "record?", ...HOOK_ENTRY_COMMON_FIELDS },
 };
 // ── classification vocabulary ──────────────────────────────────────────────────────────────────────────────
@@ -338,6 +355,17 @@ function hookFieldFits(base, value) {
                 if (typeof value[i] !== "string")
                     return false;
             return true;
+        case "argv":
+            if (!hookIsArray(value))
+                return false;
+            for (let i = 0; i < value.length; i++) {
+                const arg = value[i];
+                if (typeof arg !== "string" || arg.includes("\0"))
+                    return false;
+            }
+            return true;
+        case "onFailure":
+            return typeof value === "string" && Object.hasOwn(HOOK_ON_FAILURE_ACCEPTED, value);
         case "record":
             return hookIsRecord(value);
         default: {

package/dist/hooks.d.ts

@@ -1442,8 +1442,8 @@ export declare const HookInput: z.ZodDiscriminatedUnion<[z.ZodObject<{
 export type HookInput = z.infer<typeof HookInput>;
 /** Legacy top-level decision (CC): "approve" ≈ allow, "block" feeds `reason` back to the model. */
 export declare const HookDecision: z.ZodEnum<{
-    approve: "approve";
     block: "block";
+    approve: "approve";
 }>;
 export type HookDecision = z.infer<typeof HookDecision>;
 /** PermissionRequest hook decision — mirrors CC PermissionResult (allow may rewrite input/permissions). */
@@ -1728,19 +1728,21 @@ export type HookSpecificOutput = z.infer<typeof HookSpecificOutput>;
  * Synchronous hook JSON output (stdout of a command hook, CC-verbatim). Exit-code semantics ride
  * alongside: exit 0 = success (stdout parsed as this shape when JSON); exit 2 = BLOCKING error (stderr is fed
  * back to the model as the block reason / additionalContext, per event); any other exit, a timeout, a spawn
- * failure or malformed JSON = NON-BLOCKING failure: the run continues, and the consumer's hook-runner forwards
+ * failure or malformed JSON = NON-BLOCKING failure by default (the entry's `onFailure` is absent or `continue`): the run continues, and the consumer's hook-runner forwards
  * it as a `hook_non_blocking_failure` notice (a `hook_notice` frame on the task/fleet stream carrying hook name,
  * event, reason, exit code and the stderr text redacted-then-bounded to 512 chars), so the failure is visible
  * from the task's point of view instead of only in server logs. There is no separate "shown to the user"
  * surface: what a user sees is whatever their client renders from that notice frame.
+ * An entry that carries `onFailure: "block"` (a contract field of `command` and `http` entries, see `./hooks-config`) counts exactly those failures as exit 2 instead;
+ * executing that is the consumer's business, and a consumer that ignores it lets through a guarded action whose guard could not run.
  */
 export declare const SyncHookOutput: z.ZodObject<{
     continue: z.ZodOptional<z.ZodBoolean>;
     suppressOutput: z.ZodOptional<z.ZodBoolean>;
     stopReason: z.ZodOptional<z.ZodString>;
     decision: z.ZodOptional<z.ZodEnum<{
-        approve: "approve";
         block: "block";
+        approve: "approve";
     }>>;
     reason: z.ZodOptional<z.ZodString>;
     systemMessage: z.ZodOptional<z.ZodString>;
@@ -1935,8 +1937,8 @@ export declare const HookOutput: z.ZodUnion<readonly [z.ZodObject<{
     suppressOutput: z.ZodOptional<z.ZodBoolean>;
     stopReason: z.ZodOptional<z.ZodString>;
     decision: z.ZodOptional<z.ZodEnum<{
-        approve: "approve";
         block: "block";
+        approve: "approve";
     }>>;
     reason: z.ZodOptional<z.ZodString>;
     systemMessage: z.ZodOptional<z.ZodString>;

package/dist/hooks.js

@@ -546,11 +546,13 @@ export const HookSpecificOutput = z.union([
  * Synchronous hook JSON output (stdout of a command hook, CC-verbatim). Exit-code semantics ride
  * alongside: exit 0 = success (stdout parsed as this shape when JSON); exit 2 = BLOCKING error (stderr is fed
  * back to the model as the block reason / additionalContext, per event); any other exit, a timeout, a spawn
- * failure or malformed JSON = NON-BLOCKING failure: the run continues, and the consumer's hook-runner forwards
+ * failure or malformed JSON = NON-BLOCKING failure by default (the entry's `onFailure` is absent or `continue`): the run continues, and the consumer's hook-runner forwards
  * it as a `hook_non_blocking_failure` notice (a `hook_notice` frame on the task/fleet stream carrying hook name,
  * event, reason, exit code and the stderr text redacted-then-bounded to 512 chars), so the failure is visible
  * from the task's point of view instead of only in server logs. There is no separate "shown to the user"
  * surface: what a user sees is whatever their client renders from that notice frame.
+ * An entry that carries `onFailure: "block"` (a contract field of `command` and `http` entries, see `./hooks-config`) counts exactly those failures as exit 2 instead;
+ * executing that is the consumer's business, and a consumer that ignores it lets through a guarded action whose guard could not run.
  */
 export const SyncHookOutput = z.object({
     /** Whether the run should continue after the hook (default true). */

package/dist/mcp-request-entry.d.ts

@@ -1,4 +1,5 @@
 import { type McpContentOrigin } from "./types.js";
+import { type ReservedMemberName } from "./reserved-member-name.js";
 /** 值的**种类**(不回显值本身)。总(不抛):形状只问座位,读不出的对象说全包唯一的「检视不了」那一句。 */
 export declare function describeValueShape(v: unknown): string;
 /** 「不是字符串数组」的种类:数组里混了非串元素说那一句,否则回落到 {@link describeValueShape}。总(不抛):`isJsonArray` 是座位的总版。 */
@@ -12,19 +13,13 @@ export declare function describeNotStringRecord(v: unknown): string;
  */
 export declare function isStringArray(v: unknown): v is string[];
 /**
- * 纯数据的「名 → 串」记录(空对象合法;数组、`Map`、类实例、自有 `__proto__` 成员、有非串成员的对象都不是)—— 类型守卫,所以是**严归类**:成员经内核的
+ * 纯数据的「名 → 串」记录(空对象合法;数组、`Map`、类实例、有保留名成员({@link isReservedMemberName})、有非串成员的对象都不是)—— 类型守卫,所以是**严归类**:成员经内核的
  * `ownEntriesOf` 读(整容器读的严归类:每个自有串键一份描述符;访问器成员或不可枚举的成员 ⇒ 不是,getter 一次都不调 —— 守卫为真,调用方随后的普通读读到的就是判过的那一份)。
- * 传输读器读 `env` / `headers`({@link readPlainStringRecord})交出去的是**副本**,按宽归类读(不可枚举的成员照读、访问器调一次);值与成员名的判据(是串、不叫 `__proto__`)两边同一条。
+ * 传输读器读 `env` / `headers`({@link readPlainStringRecord})交出去的是**副本**,按宽归类读(不可枚举的成员照读、访问器调一次);值与成员名的判据(是串、不是保留名)两边同一条。
  */
 export declare function isStringRecord(v: unknown): v is Record<string, string>;
-/** 引擎 `TOOL_WIRE_NAME_MAX_CHARS` 的镜像:一台 MCP server(或 A2A 对端)的申报名会成为线上工具名的命名空间段,引擎对超界名是**拒**(不截断)。 */
-export declare const TOOL_WIRE_NAME_MAX_CHARS = 128;
-/**
- * 这个申报名能用吗。严判:非串、空串、超 {@link TOOL_WIRE_NAME_MAX_CHARS}、**首尾带空白**一律不可用。不截断、不 trim、不规范化 —— 截短或剥掉一个名字就是**换一个身份**,
- * 而被换掉身份的那台 server 上挂的 allowTools / toolFaces 收窄声明会一起对不上号。首尾空白 = 坏名(它不是另一个名字:名字是 `mcp__<server>__<tool>` 的身份片,
- * 带着空白的一端无从与不带的那个对上号);内部空白(`a b`)照旧是合法名,本判官不扩判。
- */
-export declare function isUsableWireName(v: unknown): v is string;
+export { TOOL_WIRE_NAME_MAX_CHARS, isUsableWireName } from "./wire-name.js";
+export { RESERVED_MEMBER_NAMES, isReservedMemberName, type ReservedMemberName } from "./reserved-member-name.js";
 /**
  * 坏名的**可打印**摘要(进拒句 / 告警元数据):种类、`empty`,或引号形的回显加原因 —— 绝不把任意长度的申报串原样回显。回显口径见 {@link quotedCallerText}
  * (剥控制与双向字符、截 64 字)。串的原因是:超界 ⇒ `N chars > 128`(N 是送来的原长度,不是剥完的);首尾带空白 ⇒ `leading or trailing whitespace`
@@ -82,7 +77,7 @@ export type RequestMcpTransport = {
  * `env` / `headers` 这两张「名 → 串」记录上的坏形另带两格机读位,调用方分流不必解析句子:`fault` = 闭集词({@link PLAIN_STRING_RECORD_FAULTS},与公开的记录读器 {@link readPlainStringRecord} 同一张表)——
  *  · `not_plain_record`:这个键的值不是纯数据记录(不是对象 / 数组 / `null`,或不是朴素 JSON 对象 —— 原型链比座位的判据长:`Map`、`Set`、类实例;读形状就抛的对象同);整张记录不交;
  *  · `member_not_string`:有一个成员的值不是串,或它读不出(它的访问器抛了,或读它的描述符时代理陷阱抛了);整张记录不交,`member` 点名它,两种情形句子分说;
- *  · `member_name_reserved`:有一个成员叫 `__proto__`(引擎的声明收据拒这个名)。成员的值是串 ⇒ 只剔这个成员、其余照交,`path` 是成员级(`transport.env.__proto__`);
+ *  · `member_name_reserved`:有成员叫保留名({@link RESERVED_MEMBER_NAMES}:`__proto__` / `constructor` / `prototype`)。值是串 ⇒ 只剔它、其余照交,每个一条、`path` 是成员级(`transport.env.__proto__`);
  *    成员的值也不是串(或读不出)⇒ 整张记录不交,`path` 是键级,句子一次说全两件事 —— 名坏优先、值坏并列,所以词仍是 `member_name_reserved`。
  * `member` 是成员名的**回显形**(剥控制与双向字符、截 64 字加 `…`),可直接进日志与句子,不是回查原对象的键。其余的坏形(`args` / `url` / `principalHeader` / ……)两格都不带。
  */
@@ -107,16 +102,11 @@ export type RequestMcpTransportRead = {
  *  · 软坏形(`args` 不是串数组 / `env` `headers` 不是纯数据的串记录 / `principalHeader` 非串)⇒ 读器**丢这个键**(重放存量提交体时的升级前读法),并把它记进 `lost`
  *    (受理新提交的门据它响亮拒)。`assertionHeader` 不在 `lost` 里:两个身份头的键组合与 `assertionHeader` 的值形由调用方在读之前对原始传输判。
  *  · `env` / `headers` 只收**纯数据**的记录({@link readPlainStringRecord}):必须是朴素 JSON 对象(`./plain-json-object` 的判据;`Map`、`Set`、类实例整张不收),每个自有成员的值都是串;
- *    交出的是**副本**(不是调用方的对象,改原对象不影响读后的形)。名叫 `__proto__` 的成员(JSON 文本铸得出这个自有键,对象字面量写不出)不进副本、单独记进 `lost`。
+ *    交出的是**副本**(不是调用方的对象,改原对象不影响读后的形)。名叫保留名({@link RESERVED_MEMBER_NAMES})的成员不进副本、每个单独记进 `lost`。
  *    坏形的 `lost` 条目带机读位(见 {@link McpEntryKeyIssue})。
  * url 的拒句不回显值:它常规地带凭据(userinfo)。
  */
 export declare function readRequestMcpTransport(t: unknown): RequestMcpTransportRead;
-/**
- * 引擎的声明收据不收的成员名(core `mcp-server-spec`:按赋值拷贝它会变成原型):JSON 文本铸得出这个**自有**键,对象字面量写不出。
- * 公开,因为读器交出 `reservedMember: true` 时消费方要点名它 —— 名字只在这里定一次。
- */
-export declare const PLAIN_STRING_RECORD_RESERVED_MEMBER = "__proto__";
 /**
  * 「名 → 串」记录读不交(或交时点名保留名)的**原因词**,闭集,三个词、一张表:
  * 整张一词(`not_plain_record`)· 成员级一词(`member_not_string`:值读成了别的种类,或读成员时抛了 —— 句子分说)· 名字级一词(`member_name_reserved`)。
@@ -127,12 +117,12 @@ export declare const PLAIN_STRING_RECORD_FAULTS: readonly ["not_plain_record", "
 export type PlainStringRecordFault = (typeof PLAIN_STRING_RECORD_FAULTS)[number];
 /**
  * {@link readPlainStringRecord} 的读数:`ok:false` = 记录不交(`fault` = 原因词;`detail` 是接在 `must be a plain object of string values — ` 后面的句子;坏在某个成员时 `member` 点名它的回显形);
- * `ok:true` = 交出去的纯数据副本,`reservedMember` = 记录里有一个名叫 {@link PLAIN_STRING_RECORD_RESERVED_MEMBER} 的成员(它没进副本)。
+ * `ok:true` = 交出去的纯数据副本,`reservedMembers` = 记录里名叫保留名({@link RESERVED_MEMBER_NAMES})的成员,按自有键序(它们没进副本)。
  */
 export type PlainStringRecordRead = {
     readonly ok: true;
     readonly record: Record<string, string>;
-    readonly reservedMember: boolean;
+    readonly reservedMembers: readonly ReservedMemberName[];
 } | {
     readonly ok: false;
     readonly detail: string;
@@ -143,7 +133,7 @@ export type PlainStringRecordRead = {
  * 读一份「名 → 串」记录 —— **公开读口**:传输读器读 `env` / `headers` 用的就是它,消费方读自己的「名 → 串」记录(中心名册的引用表)调同一只,不抄镜像。从不抛。记录交不交:是朴素 JSON 对象(座位的判据,见 `./plain-json-object`:原型是 `null`,或原型自己的原型是 `null`;纯数据 —— `Map`、`Set`、类实例、建在原型上的记录都不是),
  * 且每个成员的值都是串。成员 = `Object.getOwnPropertyNames` 的每一个名字(不可枚举的也算 —— 引擎的收据按全部自有属性名读),值经内核 `readKey` 读(一份描述符:数据属性取值,访问器调一次,不问 `get` 陷阱;访问器或描述符 trap 抛了同判为坏 —— 词与「值不是串」同是 `member_not_string`,句子说读不出)。
  * 读原型与成员名时代理 trap 抛了 ⇒ 整张不交(读器对调用方递来的任何对象都不抛;`JSON` 存体里不会有代理,这条只落在直接调读器的嵌入方身上)。
- * 交出去的是副本(原型 `Object.prototype`、成员全可枚举),调用方的对象不被交出去、也不被改;名叫 `__proto__` 的成员不进副本,`reservedMember` 记下它。
- * 名叫 `__proto__` 而值也坏的成员,句子一次说全两件事(名坏在前、值坏并列):调用方照值改完再撞第二条是两步才改对。
+ * 交出去的是副本(原型 `Object.prototype`、成员全可枚举),调用方的对象不被交出去、也不被改;名叫保留名({@link isReservedMemberName})的成员不进副本,`reservedMembers` 记下它们。
+ * 名叫保留名而值也坏的成员,句子一次说全两件事(名坏在前、值坏并列):调用方照值改完再撞第二条是两步才改对。
  */
 export declare function readPlainStringRecord(v: unknown): PlainStringRecordRead;

package/dist/mcp-request-entry.js

@@ -10,7 +10,7 @@
  * 判据与原因句逐字等于消费方请求腿的那一份(钉:`test/mcp-request-entry-14.0.0.test.ts` 逐例搬了消费方既有钉的夹具与期望)。
  * 本模块只答「这一格的形」;拒绝的整句(条目下标、条目名的回显清洗、收尾句)与「拒还是降级」的后果仍是消费方按自己的腿定的 —— 判据一份,后果按腿分。
  * 与最初搬来时相比有三处收严,都是收到与消费方请求腿同严、不是新语义,消费方改 import 这一份之后不再各留一份旧判据:申报名判官另判**首尾空白**;
- * `env` / `headers` 只收**纯数据**的「名 → 串」记录(Map / 类实例 / 自有 `__proto__` 成员不收,交出的是副本);两只回显描述器用消费方的回显口径(剥控制与双向字符、截 64 字、引号形)。
+ * `env` / `headers` 只收**纯数据**的「名 → 串」记录(Map / 类实例不收;保留成员名 {@link RESERVED_MEMBER_NAMES} 不进副本,交出的是副本);两只回显描述器用消费方的回显口径(剥控制与双向字符、截 64 字、引号形)。
  *
  * ## 依赖的引擎事实(镜像 + 漂移门)
  *  · 申报名的线长界 {@link TOOL_WIRE_NAME_MAX_CHARS} = 引擎同名常量(值级对拍:上游漂移门 ⑧);
@@ -31,6 +31,8 @@ import { isJsonArray, isPlainJsonObject, jsonShapeOf } from "./plain-json-object
 import { MCP_CONTENT_ORIGINS } from "./types.js";
 import { RESERVED_MCP_SERVER_NAME_REASON, isReservedMcpServerName } from "./mcp-server-name.js";
 import { startsWithHttpScheme } from "./url-shape.js";
+import { TOOL_WIRE_NAME_MAX_CHARS, hasEdgeWhitespace, isUsableWireName } from "./wire-name.js";
+import { isReservedMemberName } from "./reserved-member-name.js";
 // ── 值的种类描述(拒句只说「你写的是什么形」,不回显值:值可能带凭据、可能任意长)──────────────────────────────────────
 /** 值的**种类词**(不回显值本身):`null` / `array` / `typeof` 词(`object` / `function` / `string` …);读不出的对象 ⇒ 全包唯一的那一句。形状只问座位(总,不抛):两只坏值描述器共用这一只。 */
 function describeKindWord(v) {
@@ -92,15 +94,15 @@ export function isStringArray(v) {
     return captureStringArray(v, "strict") !== undefined;
 }
 /**
- * 纯数据的「名 → 串」记录(空对象合法;数组、`Map`、类实例、自有 `__proto__` 成员、有非串成员的对象都不是)—— 类型守卫,所以是**严归类**:成员经内核的
+ * 纯数据的「名 → 串」记录(空对象合法;数组、`Map`、类实例、有保留名成员({@link isReservedMemberName})、有非串成员的对象都不是)—— 类型守卫,所以是**严归类**:成员经内核的
  * `ownEntriesOf` 读(整容器读的严归类:每个自有串键一份描述符;访问器成员或不可枚举的成员 ⇒ 不是,getter 一次都不调 —— 守卫为真,调用方随后的普通读读到的就是判过的那一份)。
- * 传输读器读 `env` / `headers`({@link readPlainStringRecord})交出去的是**副本**,按宽归类读(不可枚举的成员照读、访问器调一次);值与成员名的判据(是串、不叫 `__proto__`)两边同一条。
+ * 传输读器读 `env` / `headers`({@link readPlainStringRecord})交出去的是**副本**,按宽归类读(不可枚举的成员照读、访问器调一次);值与成员名的判据(是串、不是保留名)两边同一条。
  */
 export function isStringRecord(v) {
     if (!isPlainJsonObject(v))
         return false;
     const entries = ownEntriesOf(v);
-    return entries.ok && entries.value.every(([name, value]) => name !== PLAIN_STRING_RECORD_RESERVED_MEMBER && typeof value === "string");
+    return entries.ok && entries.value.every(([name, value]) => !isReservedMemberName(name) && typeof value === "string");
 }
 // ── 调用方写的串的回显口径 ──────────────────────────────────────────────────────────────────────────
 /** 句子里点名一个值的写法:{@link echoCallerText} 外加一对双引号;内部的引号与反斜杠逐字(不转义)。 */
@@ -108,21 +110,9 @@ function quotedCallerText(text) {
     return `"${echoCallerText(text)}"`;
 }
 // ── 申报名的线长界 ──────────────────────────────────────────────────────────────────────────────────
-/** 引擎 `TOOL_WIRE_NAME_MAX_CHARS` 的镜像:一台 MCP server(或 A2A 对端)的申报名会成为线上工具名的命名空间段,引擎对超界名是**拒**(不截断)。 */
-export const TOOL_WIRE_NAME_MAX_CHARS = 128;
-/**
- * 首尾带空白吗 —— 「空白」就是 `String.prototype.trim` 剥的那一组(ECMAScript 的 WhiteSpace + LineTerminator:空格 / 制表 / 换行 / NBSP / BOM / 全角空格 / 行段分隔符等)。
- * {@link isUsableWireName} 与 {@link describeBadWireName} 共读这一个定义,判与说不会各按各的口径。
- */
-const hasEdgeWhitespace = (v) => v.trim() !== v;
-/**
- * 这个申报名能用吗。严判:非串、空串、超 {@link TOOL_WIRE_NAME_MAX_CHARS}、**首尾带空白**一律不可用。不截断、不 trim、不规范化 —— 截短或剥掉一个名字就是**换一个身份**,
- * 而被换掉身份的那台 server 上挂的 allowTools / toolFaces 收窄声明会一起对不上号。首尾空白 = 坏名(它不是另一个名字:名字是 `mcp__<server>__<tool>` 的身份片,
- * 带着空白的一端无从与不带的那个对上号);内部空白(`a b`)照旧是合法名,本判官不扩判。
- */
-export function isUsableWireName(v) {
-    return typeof v === "string" && v.length > 0 && v.length <= TOOL_WIRE_NAME_MAX_CHARS && !hasEdgeWhitespace(v);
-}
+// 判据住在零依赖叶子 `./wire-name`(18.0.0 搬过去:`./types` 的 `a2a` 对端名也问它,而本模块引 `./types` —— 留在这里会成环);公开名照旧经本模块转出,同一个函数对象。
+export { TOOL_WIRE_NAME_MAX_CHARS, isUsableWireName } from "./wire-name.js";
+export { RESERVED_MEMBER_NAMES, isReservedMemberName } from "./reserved-member-name.js"; // 18.0.0: the one reserved-member-name table (schema guard · this reader · the center-refs resolver)
 /**
  * 坏名的**可打印**摘要(进拒句 / 告警元数据):种类、`empty`,或引号形的回显加原因 —— 绝不把任意长度的申报串原样回显。回显口径见 {@link quotedCallerText}
  * (剥控制与双向字符、截 64 字)。串的原因是:超界 ⇒ `N chars > 128`(N 是送来的原长度,不是剥完的);首尾带空白 ⇒ `leading or trailing whitespace`
@@ -222,7 +212,7 @@ const inheritedIdentityIssue = (key) => ({
  *  · 软坏形(`args` 不是串数组 / `env` `headers` 不是纯数据的串记录 / `principalHeader` 非串)⇒ 读器**丢这个键**(重放存量提交体时的升级前读法),并把它记进 `lost`
  *    (受理新提交的门据它响亮拒)。`assertionHeader` 不在 `lost` 里:两个身份头的键组合与 `assertionHeader` 的值形由调用方在读之前对原始传输判。
  *  · `env` / `headers` 只收**纯数据**的记录({@link readPlainStringRecord}):必须是朴素 JSON 对象(`./plain-json-object` 的判据;`Map`、`Set`、类实例整张不收),每个自有成员的值都是串;
- *    交出的是**副本**(不是调用方的对象,改原对象不影响读后的形)。名叫 `__proto__` 的成员(JSON 文本铸得出这个自有键,对象字面量写不出)不进副本、单独记进 `lost`。
+ *    交出的是**副本**(不是调用方的对象,改原对象不影响读后的形)。名叫保留名({@link RESERVED_MEMBER_NAMES})的成员不进副本、每个单独记进 `lost`。
  *    坏形的 `lost` 条目带机读位(见 {@link McpEntryKeyIssue})。
  * url 的拒句不回显值:它常规地带凭据(userinfo)。
  */
@@ -323,12 +313,8 @@ function snapshotTransport(tr) {
     return { ok: true, value: { kind: "other", value: kind.value } };
 }
 // ── 「名 → 串」记录的读法(`env` / `headers`)────────────────────────────────────────────────────────
-/**
- * 引擎的声明收据不收的成员名(core `mcp-server-spec`:按赋值拷贝它会变成原型):JSON 文本铸得出这个**自有**键,对象字面量写不出。
- * 公开,因为读器交出 `reservedMember: true` 时消费方要点名它 —— 名字只在这里定一次。
- */
-export const PLAIN_STRING_RECORD_RESERVED_MEMBER = "__proto__";
-const RESERVED_MEMBER_FAULT = `no member of a declaration may be named "${PLAIN_STRING_RECORD_RESERVED_MEMBER}"`;
+/** 保留成员名的原因句(一个名一句;名字取自那一张表 {@link RESERVED_MEMBER_NAMES})。 */
+const reservedMemberFault = (name) => `no member of a declaration may be named "${name}"`;
 /**
  * 「名 → 串」记录读不交(或交时点名保留名)的**原因词**,闭集,三个词、一张表:
  * 整张一词(`not_plain_record`)· 成员级一词(`member_not_string`:值读成了别的种类,或读成员时抛了 —— 句子分说)· 名字级一词(`member_name_reserved`)。
@@ -361,8 +347,8 @@ function notPlainDetail(shape, v) {
  * 读一份「名 → 串」记录 —— **公开读口**:传输读器读 `env` / `headers` 用的就是它,消费方读自己的「名 → 串」记录(中心名册的引用表)调同一只,不抄镜像。从不抛。记录交不交:是朴素 JSON 对象(座位的判据,见 `./plain-json-object`:原型是 `null`,或原型自己的原型是 `null`;纯数据 —— `Map`、`Set`、类实例、建在原型上的记录都不是),
  * 且每个成员的值都是串。成员 = `Object.getOwnPropertyNames` 的每一个名字(不可枚举的也算 —— 引擎的收据按全部自有属性名读),值经内核 `readKey` 读(一份描述符:数据属性取值,访问器调一次,不问 `get` 陷阱;访问器或描述符 trap 抛了同判为坏 —— 词与「值不是串」同是 `member_not_string`,句子说读不出)。
  * 读原型与成员名时代理 trap 抛了 ⇒ 整张不交(读器对调用方递来的任何对象都不抛;`JSON` 存体里不会有代理,这条只落在直接调读器的嵌入方身上)。
- * 交出去的是副本(原型 `Object.prototype`、成员全可枚举),调用方的对象不被交出去、也不被改;名叫 `__proto__` 的成员不进副本,`reservedMember` 记下它。
- * 名叫 `__proto__` 而值也坏的成员,句子一次说全两件事(名坏在前、值坏并列):调用方照值改完再撞第二条是两步才改对。
+ * 交出去的是副本(原型 `Object.prototype`、成员全可枚举),调用方的对象不被交出去、也不被改;名叫保留名({@link isReservedMemberName})的成员不进副本,`reservedMembers` 记下它们。
+ * 名叫保留名而值也坏的成员,句子一次说全两件事(名坏在前、值坏并列):调用方照值改完再撞第二条是两步才改对。
  */
 export function readPlainStringRecord(v) {
     // 形状归座位旁的分类(不在这里再推一遍;座位总 —— 读形状就抛的对象答 `uninspectable`)。成员名的读取(`ownKeys` 陷阱抛)读不出的对象也不是纯数据。
@@ -377,7 +363,7 @@ export function readPlainStringRecord(v) {
     // 累加器是零原型的袋、成员用 `Object.defineProperty` + 零原型描述符写(定义语义,不走 [[Set]]),最后用对象展开(同为定义语义)铸成普通对象:原型上被污染成只读的同名键不让读器抛,
     // 原型上的数字键 setter 吞不掉成员(此前 `entries.push` + `Object.fromEntries` 被继承的数字键 getter / setter 弄抛)
     const members = Object.create(null);
-    let reservedMember = false;
+    const reservedMembers = names.filter(isReservedMemberName); // `filter` 走 CreateDataProperty,不走 [[Set]](继承的数字键 setter 吞不掉)
     for (const name of names) {
         // 成员经内核读(契约见函数头注):一份描述符里取值 —— 数据属性取值、访问器调一次、从不问 Proxy 的 `get` 陷阱;成员在两次读之间被删掉 ⇒ 不是串(不读继承来的值)
         const read = readKey(v, name);
@@ -385,28 +371,25 @@ export function readPlainStringRecord(v) {
         const value = read.presence === "own" ? read.value : undefined;
         if (unreadable || typeof value !== "string") {
             const valueFault = unreadable ? "could not be read (its getter threw)" : `must be a string — got ${describeValueShape(value)}`;
-            const reserved = name === PLAIN_STRING_RECORD_RESERVED_MEMBER;
             // 词:名坏优先(句子里值坏并列说全);名没问题时,读不出与值不是串同词,句子分说
-            const fault = reserved ? "member_name_reserved" : "member_not_string";
+            const fault = isReservedMemberName(name) ? "member_name_reserved" : "member_not_string";
             return {
                 ok: false,
                 fault,
                 member: echoCallerText(name),
-                detail: `its member "${echoCallerText(name)}" ${reserved ? `is not allowed (${RESERVED_MEMBER_FAULT}) and its value ${valueFault}` : valueFault}`,
+                detail: `its member "${echoCallerText(name)}" ${isReservedMemberName(name) ? `is not allowed (${reservedMemberFault(name)}) and its value ${valueFault}` : valueFault}`,
             };
         }
-        if (name === PLAIN_STRING_RECORD_RESERVED_MEMBER)
-            reservedMember = true;
-        else
+        if (!isReservedMemberName(name))
             Object.defineProperty(members, name, dataDescriptor(value));
     }
-    return { ok: true, record: { ...members }, reservedMember };
+    return { ok: true, record: { ...members }, reservedMembers };
 }
 /** 把诊断条目铸成数组:`undefined`(这一处没有诊断)略去。`filter` 的结果走 `CreateDataProperty`,不走 `[[Set]]` —— `lost` 是「门拒什么」的读数,不能被继承的数字键 setter 吞掉。 */
 const issuesOf = (...candidates) => candidates.filter((c) => c !== undefined);
 /**
  * `transport.env` / `transport.headers` 的读法(两键同一只):缺席 ⇒ 缺席;记录不交 ⇒ 一处诊断点名**这个键**(不交的是整张记录;坏在某个成员时句子与 `member` 点名它);
- * 交 ⇒ 纯数据副本,名叫 `__proto__` 的成员单记一处诊断、路径 `<键>.__proto__`。
+ * 交 ⇒ 纯数据副本,名叫保留名的成员每个单记一处诊断、路径 `<键>.<保留名>`。
  */
 function readTransportRecord(path, raw) {
     if (raw === undefined)
@@ -420,6 +403,6 @@ function readTransportRecord(path, raw) {
     }
     return {
         record: read.record,
-        issues: read.reservedMember ? [{ path: `${path}.${PLAIN_STRING_RECORD_RESERVED_MEMBER}`, reason: RESERVED_MEMBER_FAULT, member: PLAIN_STRING_RECORD_RESERVED_MEMBER, fault: "member_name_reserved" }] : [],
+        issues: read.reservedMembers.map((name) => ({ path: `${path}.${name}`, reason: reservedMemberFault(name), member: name, fault: "member_name_reserved" })),
     };
 }

package/dist/one-time-migrations.js

@@ -138,7 +138,7 @@ export const ONE_TIME_MIGRATIONS = [
         releasedOn: "2026-10-10",
         removableAfter: "2026-11-09",
         rewrites: "every NON_SECRET_URL seat in a domain document (derived from the domain schemas, not listed by hand — today models.models[].baseUrl, " +
-            "mcp.servers[].transport.url, execution.sessionMirror.engineUrl, workers.workers[].coords.gitApiBaseUrl): `#` and everything after it are removed " +
+            "mcp.servers[].transport.url, a2a.peers[].url, a2a.peers[].cardUrl, execution.sessionMirror.engineUrl, workers.workers[].coords.gitApiBaseUrl): `#` and everything after it are removed " +
             "(a fragment never goes on the wire); the same walk covers config.d/remote-exec.json, derived from its schema the same way " +
             "(today the k8s apiUrl and s3Snapshot.endpoint) — the command-line migrate reads and rewrites it as one more document",
         removal: "the next major after the window: delete the SS-M7 step and its schema walk; the NON_SECRET_URL fragment rule loses its SS-M7 clause",

package/dist/portable-domains.d.ts

@@ -12,7 +12,7 @@
  *  同形**。当年 `limits` 域就是这样在单机腿静默丢了一整片限额发布(远端腿同批可用,所以更难看出来)。
  *  今日的兜底:漏登记的文件会被 `FileConfigStore`(`./node`)的 `"unread-config-file"` 警告点名(fail-loud,
  *  见 getEffective),但那只在消费方接了 `onWarning` 时才响 —— **登记仍是第一现场的义务**。 */
-export declare const PORTABLE_DOMAINS: readonly ["models", "rosters", "skills", "mcp", "plugins", "scenarios", "collab", "governance", "execution", "prompts", "limits"];
+export declare const PORTABLE_DOMAINS: readonly ["models", "rosters", "skills", "mcp", "plugins", "scenarios", "collab", "governance", "execution", "prompts", "limits", "a2a"];
 export type PortableDomain = (typeof PORTABLE_DOMAINS)[number];
 /**
  * 非便携域的**排除理由表**(#282 件5 附带裁定:禁裸排除)。

package/dist/portable-domains.js

@@ -12,7 +12,7 @@
  *  同形**。当年 `limits` 域就是这样在单机腿静默丢了一整片限额发布(远端腿同批可用,所以更难看出来)。
  *  今日的兜底:漏登记的文件会被 `FileConfigStore`(`./node`)的 `"unread-config-file"` 警告点名(fail-loud,
  *  见 getEffective),但那只在消费方接了 `onWarning` 时才响 —— **登记仍是第一现场的义务**。 */
-export const PORTABLE_DOMAINS = ["models", "rosters", "skills", "mcp", "plugins", "scenarios", "collab", "governance", "execution", "prompts", "limits"];
+export const PORTABLE_DOMAINS = ["models", "rosters", "skills", "mcp", "plugins", "scenarios", "collab", "governance", "execution", "prompts", "limits", "a2a"];
 /**
  * 非便携域的**排除理由表**(#282 件5 附带裁定:禁裸排除)。
  *

package/dist/remote-exec.d.ts

@@ -12,6 +12,9 @@
  *   - `host`          run tools DIRECTLY on this machine, no container (the TOC default, like a local coding
  *                     agent). No isolation.
  *   - `local-docker`  containers on THIS machine's docker (isolation for parallel/untrusted fan-out).
+ *   Either:
+ *   - `none`          (18.0.0) no execution environment for the agent's tools — the file form of `REMOTE_EXEC=none`. No fields:
+ *                     there is nothing to configure.
  *
  * 7.0.0: every `provider` word here is an execution lane word (`EXECUTION_LANE_WORDS`, `execution-lanes.ts` — the ONE
  * vocabulary; `test/execution-lanes-7.0.0.test.ts` pins `provider ⊆ EXECUTION_LANE_WORDS`, at runtime and at compile time).
@@ -90,5 +93,7 @@ export declare const RemoteExecSpec: z.ZodDiscriminatedUnion<[z.ZodObject<{
     serial: z.ZodString;
     adbPath: z.ZodOptional<z.ZodString>;
     mountPath: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    provider: z.ZodLiteral<"none">;
 }, z.core.$strip>], "provider">;
 export type RemoteExecSpec = z.infer<typeof RemoteExecSpec>;

package/dist/remote-exec.js

@@ -12,6 +12,9 @@
  *   - `host`          run tools DIRECTLY on this machine, no container (the TOC default, like a local coding
  *                     agent). No isolation.
  *   - `local-docker`  containers on THIS machine's docker (isolation for parallel/untrusted fan-out).
+ *   Either:
+ *   - `none`          (18.0.0) no execution environment for the agent's tools — the file form of `REMOTE_EXEC=none`. No fields:
+ *                     there is nothing to configure.
  *
  * 7.0.0: every `provider` word here is an execution lane word (`EXECUTION_LANE_WORDS`, `execution-lanes.ts` — the ONE
  * vocabulary; `test/execution-lanes-7.0.0.test.ts` pins `provider ⊆ EXECUTION_LANE_WORDS`, at runtime and at compile time).
@@ -147,6 +150,8 @@ export const RemoteExecSpec = z.discriminatedUnion("provider", [
         adbPath: execStr.optional(),
         mountPath: execStr.optional(),
     }),
+    // ── none (18.0.0): no execution environment for the agent's tools (REMOTE_EXEC=none). Zero fields — nothing to configure, no secrets.
+    z.object({ provider: z.literal("none") }),
 ], {
     // A retired lane word as `provider` (no matching discriminator) gets the tombstone's way out; any other miss keeps zod's sentence.
     // `provider` is read from the input's OWN keys (the input is the caller's object: an inherited / polluted `provider` is not the word they wrote; a proxy that cannot be read has no word to refuse)

package/dist/reserved-member-name.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 包内私有叶子模块(运行期零依赖,浏览器安全;不进 `package.json` 的 exports,主桶经 `./mcp-request-entry` 转出这里的公开名):
+ * **一个名字能不能作「名 → 串」记录的成员名**的唯一判据 —— 原型链上的三个名字永远不能:`__proto__`(按赋值拷贝会变成原型;zod 的 record 读键前先跳过它、不判它的值)、
+ * `constructor` / `prototype`(读方对普通对象做 `obj[名]` 时撞上原型成员)。
+ * 三个读口问它,同一张表、同一个答案:域 schema 的凭据引用集合(`./types` 的 `credentialRefs`:在场 ⇒ 集合坏)· 公开的记录读器(`./mcp-request-entry` 的 `readPlainStringRecord` /
+ * `isStringRecord`,请求面传输的 `env` / `headers` 同读:剔出副本并点名)· 中心引用解析口(`./center-refs`,经记录读器:在场 ⇒ `refs_unreadable`)。
+ * 住在叶子里,是因为 `./types` 与 `./mcp-request-entry` 都要它,而后者反过来引 `./types`。
+ */
+/** 保留成员名,闭集。 */
+export declare const RESERVED_MEMBER_NAMES: readonly ["__proto__", "constructor", "prototype"];
+export type ReservedMemberName = (typeof RESERVED_MEMBER_NAMES)[number];
+/** 这个名字是保留成员名吗(大小写敏感:`Constructor` / `X-Prototype` 不是)。 */
+export declare function isReservedMemberName(name: string): name is ReservedMemberName;

package/dist/reserved-member-name.js

@@ -0,0 +1,14 @@
+/**
+ * 包内私有叶子模块(运行期零依赖,浏览器安全;不进 `package.json` 的 exports,主桶经 `./mcp-request-entry` 转出这里的公开名):
+ * **一个名字能不能作「名 → 串」记录的成员名**的唯一判据 —— 原型链上的三个名字永远不能:`__proto__`(按赋值拷贝会变成原型;zod 的 record 读键前先跳过它、不判它的值)、
+ * `constructor` / `prototype`(读方对普通对象做 `obj[名]` 时撞上原型成员)。
+ * 三个读口问它,同一张表、同一个答案:域 schema 的凭据引用集合(`./types` 的 `credentialRefs`:在场 ⇒ 集合坏)· 公开的记录读器(`./mcp-request-entry` 的 `readPlainStringRecord` /
+ * `isStringRecord`,请求面传输的 `env` / `headers` 同读:剔出副本并点名)· 中心引用解析口(`./center-refs`,经记录读器:在场 ⇒ `refs_unreadable`)。
+ * 住在叶子里,是因为 `./types` 与 `./mcp-request-entry` 都要它,而后者反过来引 `./types`。
+ */
+/** 保留成员名,闭集。 */
+export const RESERVED_MEMBER_NAMES = ["__proto__", "constructor", "prototype"];
+/** 这个名字是保留成员名吗(大小写敏感:`Constructor` / `X-Prototype` 不是)。 */
+export function isReservedMemberName(name) {
+    return RESERVED_MEMBER_NAMES.includes(name);
+}

package/dist/retired-envs.js

@@ -75,6 +75,8 @@ export const RETIRED_ENVS = [
     ["HOST_EXEC_SPOOL_DISABLED", "HOST_EXEC_SPOOL_ENABLED", "replaced", negativeAliasWhy("HOST_EXEC_SPOOL_DISABLED", "HOST_EXEC_SPOOL_ENABLED")],
     // 无人值守腿的模式旋钮退役:这些腿的答集是常量,不是旋钮。
     ["UNATTENDED_PERMISSION_MODE", "since server 7.109.0 the unattended legs (leader workers and their repair legs, run-local, and their durable resumes) always run permissionMode \"default\" with an approver that answers by ask class: a machine answers only \"ordinary\" asks, and every other class goes to the leg's approver seat (run-local's terminal prompt) or parks / is refused — there is no mode to choose", "removed"],
+    // 执行车道总开关:每个部署都点名自己的车道之后它恒真(「点名了没有」只剩一个答者 REMOTE_EXEC),留着 = 两个键答一个问题;「没有执行环境」也是一个声明(REMOTE_EXEC=none)。
+    ["REQUIRE_EXECUTION_LANE", "REMOTE_EXEC", "replaced", "every deployment names its execution lane; REMOTE_EXEC=none declares one with no execution environment"],
 ];
 // 冻结:拿到导出的人改不了拒启判据(读拒句的与投影 wire 的是同一个数组对象)。
 for (const row of RETIRED_ENVS)

package/dist/secret-refs.d.ts

@@ -18,7 +18,7 @@ export interface EnvRef {
     envName: string;
     refs: EnvRefUse[];
 }
-/** Every env-NAME referenced across models / workers / mcp, grouped + sorted by name.
+/** Every env-NAME referenced across models / workers / mcp / a2a, grouped + sorted by name.
  *  (integrations domain DELETED in 0.6.0 — OA/Gitea coordinates ride worker.env/secretEnv, EXPERT-REDESIGN §9.) */
 export declare function collectEnvRefs(eff: EffectiveConfig): EnvRef[];
 /**

package/dist/secret-refs.js

@@ -1,4 +1,4 @@
-/** Every env-NAME referenced across models / workers / mcp, grouped + sorted by name.
+/** Every env-NAME referenced across models / workers / mcp / a2a, grouped + sorted by name.
  *  (integrations domain DELETED in 0.6.0 — OA/Gitea coordinates ride worker.env/secretEnv, EXPERT-REDESIGN §9.) */
 export function collectEnvRefs(eff) {
     const map = new Map();
@@ -33,6 +33,10 @@ export function collectEnvRefs(eff) {
         for (const [key, envName] of Object.entries(refs ?? {}))
             add(envName, "mcp", `server "${s.name}" ${kind}.${key}`);
     }
+    // 18.0.0: an A2A peer's header references are env-NAMEs the reading side must provide, like an http MCP server's.
+    for (const p of eff.a2a.peers)
+        for (const [key, envName] of Object.entries(p.headerRefs ?? {}))
+            add(envName, "a2a", `peer "${p.name}" headerRefs.${key}`);
     return [...map.entries()].map(([envName, refs]) => ({ envName, refs })).sort((a, b) => a.envName.localeCompare(b.envName));
 }
 /**