@sema-agent/server 7.129.1 → 7.131.0

package/dist/task-mcp.d.ts

@@ -24,6 +24,7 @@
  */
 import { type CompliancePosture, type EngineNotice, type LockedKey, type McpInjectionDropReason, type McpServerSpec } from "@sema-agent/core";
 import { type McpIdentityHeadersIssue, type RequestMcpServerSpec } from "./mcp-assertion-header.js";
+import type { StoredToolAxesRereadM19 } from "./stored-request-tool-axes-m19.js";
 /** Bound on caller-supplied servers (anti-DoS; a real local `.mcp.json` has a handful). */
 export declare const MAX_REQUEST_MCP_SERVERS = 32;
 /**
@@ -63,6 +64,10 @@ export declare const MAX_REQUEST_MCP_DROP_NAMES = 32;
  *  · 探测口**响亮拒**(400,点名 `mcpServers[i].<键>`)—— 它问的是「这台到底能不能用」,把一个拼错的键
  *    悄悄忽略再回一份好看的名单,正是那条面要根除的假答案。
  * 两个门,一个词表。表在这里,门在各自的腿上。
+ *
+ * ## 受理键的判官表也钉在这张表上
+ * fresh 提交腿对**受理键的值**同样响亮拒({@link assertRequestMcpEntries}):逐键判官表 {@link ENTRY_KEY_JUDGES} 是 `{ [K in 本表的键]: 判官 }` 的映射型 ——
+ * 本表多一个键而没写判官 ⇒ 编译红,不会出现「这个键写坏了却被悄悄受理」的新键。词表外的键仍由读器宽容、由探测口闭集拒(上面两条不变)。
  */
 export declare const MCP_SERVER_ENTRY_KEYS: readonly ["allowTools", "contentOrigin", "elicitation", "name", "source", "toolAxes", "toolFaces", "transport"];
 /** `transport.kind:"stdio"` 的键闭集(两向钉在 core 那一支上)。 */
@@ -114,6 +119,7 @@ export interface McpInjectionDropSeat {
  * Shape-check the raw `body.mcpServers`. `null` → a non-array (caller error; the route may 400). Otherwise the
  * valid subset + the names of dropped (malformed/over-cap) entries + [ref]'s `badContentOrigin`
  * (**降级**掉的内容出处声明,与 `dropped` 是两回事:那条 server **留着**,丢的只是它的声明)。
+ * 这一口没有 M19 的重读座(探测口与单测读到的 `toolAxes` 恒是判官的读数);重读只在续跑重放腿经 {@link resolveRequestMcp} 发生。
  */
 export declare function validateRequestMcp(raw: unknown): ValidatedRequestMcp | null;
 type ValidatedRequestMcp = {
@@ -143,71 +149,57 @@ type ValidatedRequestMcp = {
  * 任务。同样是失败,同步 400 至少是**立刻可诊断**的那一种,而且拒得出理由(锁在哪、怎么改)。
  */
 export declare function assertRequestMcpUnlocked(bodyMcp: unknown, lockedKeys: ReadonlySet<LockedKey>): void;
-/**
- * [ref](core 5.60.0 提货批件②)—— 请求体里 `mcpServers[].contentOrigin` 的**值域门**,腿首同步拒。
- *
- * ## 先把 core 的硬条款抄下来,因为本腿的全部争议都在它上面
- * `McpServerSpec.contentOrigin` 顶注逐字:「TRUST SOURCE — a DEPLOYMENT-plane key … any assembly layer
- * that accepts REQUEST-side MCP entries **must reject or strip this key** from them … A single-tenant
- * superuser surface (a host reading its own `--mcp-config` file) **IS the deployment plane and needs no
- * such gate**.」
- *
- * ## 本仓怎么兑现这条义务(**结构性**,不是靠纪律)
- * 请求腿的条目只有在 {@link mcpInjectionHonored} 为真时才被读进 `TaskSpec.mcp`,而那只谓词的语义正是
- * 「本部署是单用户 ⇒ 请求者就是这台 worker 的超管」—— core 点名豁免的那一格。多租户部署
- * (`requirePrincipal===true`)整只 `mcpServers` 被忽略,租户**结构上**够不着这个键(钉见
- * `test/task-mcp.test.ts` 的多租户格)。同一条腿今天已经透传 `toolAxes`(喂**审批门**,权限比本键**高**
- * 一档 —— core 明写 contentOrigin「no gate/policy/roster effect」)与 stdio 的**任意命令**(worker 宿主
- * 上的真无限制执行);在那两样之后,「我声明我自己这台 server 的内容不算外来」不构成任何新的暴露面。
- * 名字撞车时 baseline 恒赢(`mergeRequestMcp`)⇒ 调用方也改写不了一台**已配置** server 的声明。
- *
- * ## 为什么 fresh 腿是 400 而不是静默丢键
- * 静默丢键会把一次**信任边界声明**变成探针 —— 调用方以为声明生效了,其实没有。本仓 `opts.leg` 的成文
- * 契约(`ServiceDeps.resolveSpec` 顶注)逐字写着 fresh 腿「may fail-loud 400 on combos that would
- * silently discard caller payload」,这正是那种 combo。
- *
- * ## 🔴 但只在 fresh 腿(与 {@link assertRequestMcpUnlocked} **刻意分歧**)
- * 锁那条敢在 resume 腿同拒,是因为它有一个本门**没有**的前提:锁在场 ⇒ core 的 preflight 无论如何都会
- * 拒这条腿,放进去只换来一个跑起来又终态失败的任务。而坏 `contentOrigin` 在本仓两个平面都被**降级**掉了
- * (`normalizeServer` / `resolveMcpServers`),core 根本看不到它,也就永远不会拒。
- * 与此同时 `checkpoint_ctx` 存的是**原始** `TaskRequestBody`,耐久 resume 逐字重放它,从本门逃出去的
- * `HttpError` 会被 `src/http/server.ts` 折成 `409 resume_blocked_by_policy` ⇒ 一条**升级前** park、body 里
- * 带着当时被静默忽略的坏值的任务,升级后**永久**恢复不了(codex 交叉复审 R1-[high],验真后采纳)。
- * ⇒ 照本仓成文的三处 `opts.leg` 先例(`appendSystemPrompt` 案 / `@model` 名单 [ref] 终裁 (a) /
- * `compactionModel` 案,都逐字写着「砖死 resume 比降级糟」):fresh fail-loud,resume 降级 + 留声
- * (留声点 = {@link resolveRequestMcp} 的 `mcp_content_class_dropped`)。挂点判据在 `boot/resolve-spec.ts`。
- *
- * ## 位置与射程
- * 排在腿首、`assertRequestMcpUnlocked` 旁边 —— **任何副作用之前**(附件绑定 / per-session cwd·env 写入;
- * 理由逐字见 `boot/resolve-spec.ts` 那两行的注)。判据是**纯值域**、与**租户车道**无关:一个写坏的请求
- * 在哪条车道上都是写坏的,而多租户腿本来就要忽略整只数组,告诉调用方「你这个键写错了」只多不少。
- * 形不合(非数组 / 条目非对象)**不归本门**——那是 `validateRequestMcp` 的既有宽容形,本门不抢裁决。
- */
-export declare function assertRequestMcpContentOrigin(bodyMcp: unknown): void;
-/**
- * S-1515 —— `mcpServers[].transport`(http)上两个身份头的**值域门**(fresh 腿限定,同步 400):`principalHeader` 与 `assertionHeader`
- * **同设**(`request.body_shape`),或 `assertionHeader` 在场而**不是字符串**(`request.field_invalid`)。
- *
- * 前者:两个键回答同一个问题(「这台 http 服务器的请求上用哪个头送身份」),同设 = 两个答案。settings 面由契约包在解析期判拒;
- * 请求面在这里判拒 —— **同一条规则、两处执行者**,判据与拒句单点在 `mcp-assertion-header.ts`(对契约包原句逐字,差分钉守)。
- * 后者:契约包的 zod 类型拒它;请求面若把它读成"没写过",一条鉴权声明就无声消失、server 却照常挂上去连。
- *
- * ## 位置与 leg 分流(与 {@link assertRequestMcpContentOrigin} 同款理由,不发明第二套)
- * 排在腿首、任何副作用之前;**只在 fresh 腿**:`checkpoint_ctx` 存的是原始 `TaskRequestBody`,耐久 resume 逐字重放它,
- * 从这里逃出去的 `HttpError` 会被折成 `409 resume_blocked_by_policy`,把一条 park 任务永久砖死。resume 腿走读器
- * ({@link normalizeServer}):**降级到升级前的读法**(server 照挂、`principalHeader` 胜、`assertionHeader` 不生效)+ `classifyHonored` 一行 warn ——
- * 不拒、也不摘 server。判据是纯值域、与租户车道无关(多租户腿本来就忽略整只数组,告诉调用方「你这条写错了」只多不少)。
- */
-export declare function assertRequestMcpIdentityHeaders(bodyMcp: unknown): void;
 /** 一条**原始**请求条目上两个身份头的问题类(没有问题 / 不是对象 / 不是 http 传输 ⇒ `undefined`)—— 提交腿的门、探测口、重放腿的披露三处共读,
  *  判据本体在 `mcp-assertion-header.ts`;这里只负责把「条目 → 传输对象」那一步读出来。 */
 export declare function requestEntryIdentityIssue(entry: unknown): McpIdentityHeadersIssue | undefined;
-/** 问题类 → wire 拒面(码 + 句子):两扇拒绝门(提交腿 / 探测口)同一份。条目名进句子,过唯一的回显清洗(剥控制 / 双向字符 + 截长);
- *  读不出名字的条目用与丢弃点同一个占位。 */
-export declare function requestEntryIdentityRefusal(entry: unknown): {
+/** 问题类 → wire 拒面(码 + 句子):两扇拒绝门(提交腿 / 探测口)同一份。`both_set` 是键**组合**不合法(`request.body_shape`),句子对契约包解析期原句逐字,条目名过唯一的回显清洗
+ *  (剥控制 / 双向字符 + 截长;读不出名字的条目用与丢弃点同一个占位);`assertionHeader` 非串是该键的值不合法,与其余所有受理键同一个拒形({@link entryFieldRefusal},点名 `<at>.transport.assertionHeader`)。 */
+export declare function requestEntryIdentityRefusal(entry: unknown, at: string): {
     errorCode: "request.body_shape" | "request.field_invalid";
     message: string;
 } | undefined;
+/**
+ * S-1629 —— 请求体 `mcpServers[i]` **每个受理键**的值域门(fresh 腿限定,同步 400):**一条律**,取代此前按键各开一扇的三道门
+ * (`contentOrigin` / 身份头 / `toolAxes`)与其余键上「整条悄悄摘掉」「悄悄丢键」两种沉默。
+ *
+ * ## 律
+ * fresh 提交腿上,条目的**任一受理键**写坏 ⇒ `400 request.field_invalid`,拒句点名 `mcpServers[i].<键路径>`、server 名与**该键判官的原因句**。
+ * 不挂一半、不丢声明、不默认:调用方是请求体作者,同一扇门对同一类错误只有一种答案。修前同一条条目上有三种(`toolAxes` / `contentOrigin` 坏 ⇒ 400;
+ * `allowTools` / `toolFaces` / `name` / `transport` 坏 ⇒ 200 + 整条 server 不进 + 运维 warn;`elicitation` / `source` / `transport.{args,env,headers,principalHeader}`
+ * 坏 ⇒ 200 + 悄悄丢键),而「两个键方向相反所以处置不同」只是读器**对存量 body** 的取舍({@link normalizeServer}),不是给在场调用方的答复该有的差别:
+ * 对一个 fresh 调用方,「收窄声明没生效」与「放宽声明没生效」同样是一份没有生效的声明,响亮拒比两种沉默都好。
+ *
+ * ## 每个键一只判官({@link ENTRY_KEY_JUDGES},表的键集两向钉在 `MCP_SERVER_ENTRY_KEYS` 上:新增受理键而没写判官 ⇒ 编译红)
+ * 判官**就是读器用的那一只**,不是第二份:`toolAxes` = 引擎根导出的 `readMcpToolAxes`;`toolFaces` = `readMcpToolFaces`;`contentOrigin` = `isContentOriginWord`;
+ * `source` = `isMcpSourceLabel`;`name` = `isUsableWireName`;`allowTools` / `transport.args` = {@link isStringArray};`transport.env` / `headers` = {@link isStringRecord};
+ * `elicitation` = {@link isElicitationFlag};`transport` 的硬字段(`kind` / `command` / `url`)与软字段(`args` / `env` / `headers` / `principalHeader`)= {@link readRequestTransport}
+ * (读器投影 transport 的那一只函数,门读它报的 `lost`)。两个身份头的**键组合**(同设 / `assertionHeader` 非串)仍归 `mcp-assertion-header.ts` 的判官({@link requestEntryIdentityRefusal},
+ * 码 `request.body_shape` 的那一句对契约包原句逐字),在逐键之前先判。
+ *
+ * ## 位置与 leg 分流(沿用本仓成文的 `opts.leg` 姿势,不发明第二套)
+ * 排在腿首、`assertRequestMcpUnlocked` 旁边 —— **任何副作用之前**(①阶段会把附件行持久绑定到 session,②阶段会写 per-session 的 cwd/env 表;一个最终 400 的请求若已经改掉这两样,
+ * 它就改变了后续被接受的任务会物化什么、在哪执行)。**只在 fresh 腿**:`checkpoint_ctx` 存的是**原始** `TaskRequestBody`,耐久 resume 逐字重放它,从这里逃出去的 `HttpError`
+ * 会被 `src/http/server.ts` 折成 `409 resume_blocked_by_policy` ⇒ 一条**升级前** park、body 里带着当时被受理的坏值的任务,升级后永久恢复不了
+ * (本仓三处 `opts.leg` 先例 —— `appendSystemPrompt` 案 / `@model` 名单 [ref] 终裁 (a) / `compactionModel` 案 —— 逐字写着「砖死 resume 比降级糟」)。
+ * 重放腿走读器({@link normalizeServer}),处置**逐字不变**:坏硬键(`name` / `transport` 硬字段 / `allowTools` / `toolAxes` / `toolFaces`)⇒ 这一条 server 整条不进 + 运维 warn
+ * `mcp_injection_dropped` + 用户面通告 `mcp.injection_dropped` 点名 `field`(`toolAxes` 在一次性迁移 M19 的窗开着时先按升级前读法重读一次,过了就挂,见读器的注);坏软键(`contentOrigin` / `elicitation` / `source` / `transport` 软字段)⇒ 丢键、server 照挂(`contentOrigin` 另有 `mcp_content_class_dropped` 留声)。
+ *
+ * ## 射程
+ * 判据是**纯值域**、与租户车道无关:一个写坏的请求在哪条车道上都是写坏的,而多租户腿本来就忽略整只数组,告诉调用方「你这个键写错了」只多不少。
+ * 只判前 `MAX_REQUEST_MCP_SERVERS` 条(能被挂载的那一段,与读器同一个切片)。不在本门的:条目本身不是对象 / `mcpServers` 不是数组(`validateRequestMcp` 的既有宽容形)、词表外的键(读器对未知键宽容,探测口才闭集)、超上限的尾项(`over_cap` 点名;它们不挂载,为一个永远不会生效的声明拒掉整份请求是新开一条拒绝面)。
+ * 关于 `contentOrigin` 的信任语义(core 把它定性为**部署面**键):请求腿的条目只有在 {@link mcpInjectionHonored} 为真(单用户 = 请求者就是这台 worker 的超管)时才被读进 `TaskSpec.mcp`,
+ * 多租户部署整只数组被忽略 ⇒ 租户**结构上**够不着这个键;名字撞车时 baseline 恒赢({@link mergeRequestMcp})⇒ 调用方也改写不了一台**已配置** server 的声明。
+ */
+export declare function assertRequestMcpEntries(bodyMcp: unknown): void;
+/**
+ * 一条**原始**请求条目上 `toolAxes` 的拒面(码 + 句子);没有问题 / 条目不是对象 / 没写 `toolAxes` ⇒ `undefined`。探测口(`mcp-probe.ts` 的 `entryValueIssue`)在它自己的通用读器之前读这一只,
+ * 所以 `toolAxes` 在两扇拒绝门上是**同一句**:判官 = {@link ENTRY_KEY_JUDGES} 的 `toolAxes` 格(引擎的 `readMcpToolAxes`),句子 = {@link entryFieldRefusal}(与 fresh 提交腿的每个键同一个形)。
+ * `at` = 条目的键路径(`mcpServers[3]`)。
+ */
+export declare function requestEntryToolAxesRefusal(entry: unknown, at: string): {
+    errorCode: "request.field_invalid";
+    message: string;
+} | undefined;
 /**
  * The ONE predicate for "this MCP server name belongs to the deployment": the scenario baseline (what mounted for
  * this scenario) ∪ every name the deployment DECLARED (`CenterMcp.reservedNames` — mounted or not, any scenario).
@@ -247,6 +239,9 @@ export declare function resolveRequestMcp(baseline: McpServerSpec[] | undefined,
 /** L-167:本条腿的**用户面**投递口。`sessionId` = 通告的路由半场(缺席 ⇒ 一条都不铸,见
  *  {@link mintInjectionDropNotices});`emit` 收下 core 铸好的通告,由调用腿决定投到哪(见 `boot/resolve-spec.ts`)。
  *  整段缺席(桩、单测、非 HTTP 腿)⇒ 只走日志终点,行为逐字与本件之前相同。 */
-notice?: McpInjectionDropSeat): McpServerSpec[] | undefined;
+notice?: McpInjectionDropSeat, 
+/** 一次性迁移 M19 的重读座(窗口见 `plugins/one-time-migrations.ts` 登记表):只在续跑重放腿、只在窗开着时由 `boot/resolve-spec.ts` 递进来;
+ *  缺席(新提交腿 / 窗关 / 桩)⇒ 判官判不过的 `toolAxes` 照原臂整条不进。 */
+storedToolAxes?: StoredToolAxesRereadM19): McpServerSpec[] | undefined;
 export {};
 //# sourceMappingURL=task-mcp.d.ts.map

package/dist/task-mcp.js

@@ -1,13 +1,13 @@
-import { mcpInjectionDroppedNotice, resolveComplianceDenies } from "@sema-agent/core";
-import { isUsableWireName } from "./wire-name-bound.js";
+import { mcpInjectionDroppedNotice, readMcpToolAxes, resolveComplianceDenies } from "@sema-agent/core";
+import { describeBadWireName, isUsableWireName } from "./wire-name-bound.js";
 import { HttpError, createCodedHttpError } from "./security.js";
 import { GOVERNANCE_HTTP_STATUS } from "./governance-http-status.js";
 import { CONTENT_ORIGIN_WORDS, describeBadContentOrigin, isContentOriginWord } from "./mcp-content-origin.js";
-import { readMcpSourceLabel } from "./mcp-source-label.js";
+import { MCP_SOURCE_LABEL_MAX, isMcpSourceLabel, readMcpSourceLabel } from "./mcp-source-label.js";
 import { declaresMcpAssertionHeader, describeMcpAssertionHeaderNotAString, describeMcpIdentityHeadersConflict, mcpIdentityHeadersIssue, noteMcpAssertionHeaderIgnored, noteMcpAssertionHeaderNotSent, readMcpIdentityHeaders, toCoreMcpServerSpec } from "./mcp-assertion-header.js";
 import { echoKeyName } from "./request-key-closure.js";
+import { CONTROL_AND_BIDI_STRIP_RE } from "./text-bidi.js";
 import { readMcpToolFaces } from "./mcp-tool-faces.js";
-import { isToolAxisIrreversibility, isToolEffect } from "./tool-axis-words.js";
 export const MAX_REQUEST_MCP_SERVERS = 32;
 export const MAX_REQUEST_MCP_DROP_NAMES = MAX_REQUEST_MCP_SERVERS;
 export const MCP_SERVER_ENTRY_KEYS = ["allowTools", "contentOrigin", "elicitation", "name", "source", "toolAxes", "toolFaces", "transport"];
@@ -27,6 +27,80 @@ export function mcpInjectionHonored(config) {
 function isStringRecord(v) {
     return !!v && typeof v === "object" && !Array.isArray(v) && Object.values(v).every((x) => typeof x === "string");
 }
+function isRecord(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+function isStringArray(v) {
+    return Array.isArray(v) && v.every((a) => typeof a === "string");
+}
+function isElicitationFlag(v) {
+    return typeof v === "boolean";
+}
+function describeShape(v) {
+    if (v === undefined)
+        return "nothing (the key is absent)";
+    if (v === null)
+        return "null";
+    if (Array.isArray(v))
+        return "an array";
+    if (typeof v === "string")
+        return v.length === 0 ? "an empty string" : `a string of ${v.length} characters`;
+    if (typeof v === "object")
+        return "an object";
+    return `a ${typeof v}`;
+}
+function describeNotStringArray(v) {
+    return Array.isArray(v) ? "an array with a non-string element" : describeShape(v);
+}
+function describeNotStringRecord(v) {
+    return isRecord(v) ? "an object with a non-string value" : describeShape(v);
+}
+const transportBad = (path, reason) => ({ ok: false, issue: { path, reason } });
+function readRequestTransport(t) {
+    if (!t || typeof t !== "object")
+        return transportBad("transport", `must be an object with a "kind" of "stdio" or "http" — got ${describeShape(t)}`);
+    const tr = t;
+    const lost = [];
+    if (tr.kind === "stdio") {
+        if (typeof tr.command !== "string" || tr.command.length === 0)
+            return transportBad("transport.command", `must be a non-empty string (the command to run) — got ${describeShape(tr.command)}`);
+        if (tr.args !== undefined && !isStringArray(tr.args))
+            lost.push({ path: "transport.args", reason: `must be an array of strings — got ${describeNotStringArray(tr.args)}` });
+        if (tr.env !== undefined && !isStringRecord(tr.env))
+            lost.push({ path: "transport.env", reason: `must be an object of string values — got ${describeNotStringRecord(tr.env)}` });
+        return {
+            ok: true,
+            transport: {
+                kind: "stdio",
+                command: tr.command,
+                ...(isStringArray(tr.args) ? { args: tr.args } : {}),
+                ...(isStringRecord(tr.env) ? { env: tr.env } : {}),
+            },
+            lost,
+        };
+    }
+    if (tr.kind === "http") {
+        if (typeof tr.url !== "string" || !/^https?:\/\//i.test(tr.url))
+            return transportBad("transport.url", "must be an absolute http(s) URL (put credentials in transport.headers, never in the URL)");
+        const ids = readMcpIdentityHeaders(tr);
+        if (tr.headers !== undefined && !isStringRecord(tr.headers))
+            lost.push({ path: "transport.headers", reason: `must be an object of string values — got ${describeNotStringRecord(tr.headers)}` });
+        if (tr.principalHeader !== undefined && ids.principalHeader === undefined) {
+            lost.push({ path: "transport.principalHeader", reason: `must be a string (the HTTP header NAME the end-user principal is injected into) — got ${describeShape(tr.principalHeader)}` });
+        }
+        return {
+            ok: true,
+            transport: {
+                kind: "http",
+                url: tr.url,
+                ...(isStringRecord(tr.headers) ? { headers: tr.headers } : {}),
+                ...ids,
+            },
+            lost,
+        };
+    }
+    return transportBad("transport.kind", `must be "stdio" or "http" — got ${describeShape(tr.kind)}`);
+}
 const bad = (field) => ({ ok: false, field });
 const MALFORMED_NAME = "<malformed>";
 function declaredName(e) {
@@ -34,65 +108,37 @@ function declaredName(e) {
         ? String(e.name)
         : MALFORMED_NAME;
 }
-function normalizeServer(e, noteBadOrigin) {
+function normalizeServer(e, noteBadOrigin, storedToolAxes) {
     if (!e || typeof e !== "object")
         return bad("entry");
     const o = e;
     if (!isUsableWireName(o.name))
         return bad("name");
-    const t = o.transport;
-    if (!t || typeof t !== "object")
-        return bad("transport");
-    const tr = t;
-    let transport;
-    if (tr.kind === "stdio") {
-        if (typeof tr.command !== "string" || tr.command.length === 0)
-            return bad("transport.command");
-        transport = {
-            kind: "stdio",
-            command: tr.command,
-            ...(Array.isArray(tr.args) && tr.args.every((a) => typeof a === "string") ? { args: tr.args } : {}),
-            ...(isStringRecord(tr.env) ? { env: tr.env } : {}),
-        };
-    }
-    else if (tr.kind === "http") {
-        if (typeof tr.url !== "string" || !/^https?:\/\//i.test(tr.url))
-            return bad("transport.url");
-        transport = {
-            kind: "http",
-            url: tr.url,
-            ...(isStringRecord(tr.headers) ? { headers: tr.headers } : {}),
-            ...readMcpIdentityHeaders(tr),
-        };
-    }
-    else {
-        return bad("transport.kind");
-    }
-    const spec = { name: o.name, transport };
+    const read = readRequestTransport(o.transport);
+    if (!read.ok)
+        return bad(read.issue.path);
+    const spec = { name: o.name, transport: read.transport };
     if (o.allowTools !== undefined) {
-        if (!Array.isArray(o.allowTools) || !o.allowTools.every((a) => typeof a === "string"))
+        if (!isStringArray(o.allowTools))
             return bad("allowTools");
         spec.allowTools = o.allowTools;
     }
-    if (typeof o.elicitation === "boolean")
+    if (isElicitationFlag(o.elicitation))
         spec.elicitation = o.elicitation;
-    if (o.toolAxes && typeof o.toolAxes === "object" && !Array.isArray(o.toolAxes)) {
-        const axes = {};
-        for (const [tool, ax] of Object.entries(o.toolAxes)) {
-            if (!ax || typeof ax !== "object" || Array.isArray(ax))
-                continue;
-            const a = ax;
-            const entry = {
-                ...(isToolEffect(a.effect) ? { effect: a.effect } : {}),
-                ...(typeof a.egress === "boolean" ? { egress: a.egress } : {}),
-                ...(isToolAxisIrreversibility(a.irreversibility) ? { irreversibility: a.irreversibility } : {}),
-            };
-            if (Object.keys(entry).length > 0)
-                axes[tool] = entry;
+    const axes = readMcpToolAxes(o.toolAxes);
+    let judged = axes;
+    let toolAxesReread;
+    if (!axes.ok && storedToolAxes !== undefined) {
+        const again = readMcpToolAxes(storedToolAxes(o.toolAxes));
+        if (again.ok) {
+            judged = again;
+            toolAxesReread = axes.problem.replace(CONTROL_AND_BIDI_STRIP_RE, "");
         }
-        if (Object.keys(axes).length > 0)
-            spec.toolAxes = axes;
     }
+    if (!judged.ok)
+        return bad("toolAxes");
+    if (judged.toolAxes !== undefined)
+        spec.toolAxes = judged.toolAxes;
     if (o.contentOrigin !== undefined) {
         if (isContentOriginWord(o.contentOrigin))
             spec.contentOrigin = o.contentOrigin;
@@ -105,29 +151,32 @@ function normalizeServer(e, noteBadOrigin) {
         return bad("toolFaces");
     if (faces.faces !== undefined)
         spec.toolFaces = faces.faces;
-    return { ok: true, spec };
+    return { ok: true, spec, ...(toolAxesReread !== undefined ? { toolAxesReread } : {}) };
 }
 export function validateRequestMcp(raw) {
-    if (raw === undefined || raw === null)
-        return validateRequestMcpEntries([]);
-    if (!Array.isArray(raw))
+    if (raw !== undefined && raw !== null && !Array.isArray(raw))
         return null;
-    return validateRequestMcpEntries(raw);
+    const { ok, dropped, droppedTotal, badContentOrigin } = validateRequestMcpEntries(Array.isArray(raw) ? raw : []);
+    return { ok, dropped, droppedTotal, badContentOrigin };
 }
-function validateRequestMcpEntries(raw) {
+function validateRequestMcpEntries(raw, storedToolAxes) {
     const ok = [];
     const dropped = [];
     const badContentOrigin = [];
+    const toolAxesReread = [];
     for (const e of raw.slice(0, MAX_REQUEST_MCP_SERVERS)) {
-        const v = normalizeServer(e, (server, value) => badContentOrigin.push({ server, value: describeBadContentOrigin(value) }));
-        if (v.ok)
+        const v = normalizeServer(e, (server, value) => badContentOrigin.push({ server, value: describeBadContentOrigin(value) }), storedToolAxes);
+        if (v.ok) {
             ok.push(v.spec);
+            if (v.toolAxesReread !== undefined)
+                toolAxesReread.push({ server: v.spec.name, problem: v.toolAxesReread });
+        }
         else
             dropped.push({ server: declaredName(e), reason: "malformed_entry", field: v.field });
     }
     for (const e of raw.slice(MAX_REQUEST_MCP_SERVERS, MAX_REQUEST_MCP_SERVERS + MAX_REQUEST_MCP_DROP_NAMES))
         dropped.push({ server: declaredName(e), reason: "over_cap" });
-    return { ok, dropped, droppedTotal: Math.max(0, raw.length - ok.length), badContentOrigin };
+    return { ok, dropped, droppedTotal: Math.max(0, raw.length - ok.length), badContentOrigin, toolAxesReread };
 }
 export function assertRequestMcpUnlocked(bodyMcp, lockedKeys) {
     if (!lockedKeys.has("mcp"))
@@ -138,30 +187,6 @@ export function assertRequestMcpUnlocked(bodyMcp, lockedKeys) {
         code: "config.locked_key",
     });
 }
-export function assertRequestMcpContentOrigin(bodyMcp) {
-    if (!Array.isArray(bodyMcp))
-        return;
-    for (const e of bodyMcp) {
-        if (!e || typeof e !== "object" || Array.isArray(e))
-            continue;
-        const v = e.contentOrigin;
-        if (v === undefined)
-            continue;
-        if (isContentOriginWord(v))
-            continue;
-        throw new HttpError(400, `mcpServers[].contentOrigin must be one of ${CONTENT_ORIGIN_WORDS.map((w) => `"${w}"`).join(" | ")} — got ${describeBadContentOrigin(v)}` +
-            ` (omit the key entirely for the default: this server's tools classify as external content)`, { code: "request.field_invalid" });
-    }
-}
-export function assertRequestMcpIdentityHeaders(bodyMcp) {
-    if (!Array.isArray(bodyMcp))
-        return;
-    for (const e of bodyMcp) {
-        const refusal = requestEntryIdentityRefusal(e);
-        if (refusal !== undefined)
-            throw createCodedHttpError(400, refusal.errorCode, refusal.message);
-    }
-}
 export function requestEntryIdentityIssue(entry) {
     if (!entry || typeof entry !== "object" || Array.isArray(entry))
         return undefined;
@@ -170,15 +195,81 @@ export function requestEntryIdentityIssue(entry) {
         return undefined;
     return mcpIdentityHeadersIssue(t);
 }
-export function requestEntryIdentityRefusal(entry) {
+export function requestEntryIdentityRefusal(entry, at) {
     const issue = requestEntryIdentityIssue(entry);
-    if (issue === undefined)
+    if (issue === undefined || !isRecord(entry))
         return undefined;
-    const name = echoKeyName("", declaredName(entry));
     if (issue === "both_set")
-        return { errorCode: "request.body_shape", message: describeMcpIdentityHeadersConflict(name) };
-    const value = (entry.transport).assertionHeader;
-    return { errorCode: "request.field_invalid", message: describeMcpAssertionHeaderNotAString(name, value) };
+        return { errorCode: "request.body_shape", message: describeMcpIdentityHeadersConflict(echoKeyName("", declaredName(entry))) };
+    const transport = entry.transport;
+    const value = isRecord(transport) ? transport.assertionHeader : undefined;
+    return entryFieldRefusal(entry, at, { path: "transport.assertionHeader", reason: describeMcpAssertionHeaderNotAString(value) });
+}
+export function assertRequestMcpEntries(bodyMcp) {
+    if (!Array.isArray(bodyMcp))
+        return;
+    for (let i = 0; i < Math.min(bodyMcp.length, MAX_REQUEST_MCP_SERVERS); i++) {
+        const refusal = requestEntryRefusal(bodyMcp[i], `mcpServers[${i}]`);
+        if (refusal !== undefined)
+            throw createCodedHttpError(400, refusal.errorCode, refusal.message);
+    }
+}
+const ENTRY_KEY_JUDGES = {
+    allowTools: (o) => o.allowTools === undefined || isStringArray(o.allowTools)
+        ? undefined
+        : { path: "allowTools", reason: `must be an array of strings (omit the key to leave the server's tools unrestricted) — got ${describeNotStringArray(o.allowTools)}` },
+    contentOrigin: (o) => o.contentOrigin === undefined || isContentOriginWord(o.contentOrigin)
+        ? undefined
+        : {
+            path: "contentOrigin",
+            reason: `must be one of ${CONTENT_ORIGIN_WORDS.map((w) => `"${w}"`).join(" | ")} — got ${describeBadContentOrigin(o.contentOrigin)}` +
+                ` (omit the key for the default: this server's tools classify as external content)`,
+        },
+    elicitation: (o) => (o.elicitation === undefined || isElicitationFlag(o.elicitation) ? undefined : { path: "elicitation", reason: `must be a boolean — got ${describeShape(o.elicitation)}` }),
+    name: (o) => (isUsableWireName(o.name) ? undefined : { path: "name", reason: `must be a non-empty string within the wire-name length bound — got ${describeBadWireName(o.name)}` }),
+    source: (o) => o.source === undefined || isMcpSourceLabel(o.source)
+        ? undefined
+        : { path: "source", reason: `must be a non-empty string of at most ${MCP_SOURCE_LABEL_MAX} characters (a display label) — got ${describeShape(o.source)}` },
+    toolAxes: (o) => {
+        const read = readMcpToolAxes(o.toolAxes);
+        return read.ok ? undefined : { path: "toolAxes", reason: read.problem };
+    },
+    toolFaces: (o) => {
+        const read = readMcpToolFaces(o.toolFaces);
+        return read.ok ? undefined : { path: "toolFaces", reason: read.problem };
+    },
+    transport: (o) => {
+        const read = readRequestTransport(o.transport);
+        return read.ok ? read.lost[0] : read.issue;
+    },
+};
+const ENTRY_REFUSAL_TAIL = "The request is refused rather than mounting the server without it: a declaration that silently did not apply would leave the server running differently from what you declared. " +
+    "Fix the entry (an optional key may also be omitted).";
+function entryFieldRefusal(entry, at, issue) {
+    const server = echoKeyName("", declaredName(entry));
+    return {
+        errorCode: "request.field_invalid",
+        message: `${at}.${issue.path} (server "${server}") is not a usable declaration — ${issue.reason.replace(CONTROL_AND_BIDI_STRIP_RE, "")}. ${ENTRY_REFUSAL_TAIL}`,
+    };
+}
+function requestEntryRefusal(entry, at) {
+    if (!isRecord(entry))
+        return undefined;
+    const identity = requestEntryIdentityRefusal(entry, at);
+    if (identity !== undefined)
+        return identity;
+    for (const key of MCP_SERVER_ENTRY_KEYS) {
+        const issue = ENTRY_KEY_JUDGES[key](entry);
+        if (issue !== undefined)
+            return entryFieldRefusal(entry, at, issue);
+    }
+    return undefined;
+}
+export function requestEntryToolAxesRefusal(entry, at) {
+    if (!isRecord(entry))
+        return undefined;
+    const issue = ENTRY_KEY_JUDGES.toolAxes(entry);
+    return issue === undefined ? undefined : entryFieldRefusal(entry, at, issue);
 }
 export function deploymentClosedMcpNames(baseline, reservedNames) {
     return new Set([...(baseline ?? []).map((s) => s.name), ...reservedNames]);
@@ -190,20 +281,20 @@ export function mergeRequestMcp(baseline, gated, reservedNames) {
     const add = gated.filter((s) => !closed.has(s.name));
     return add.length === 0 ? baseline : [...(baseline ?? []), ...add];
 }
-export function resolveRequestMcp(baseline, bodyMcp, config, logger, notice) {
+export function resolveRequestMcp(baseline, bodyMcp, config, logger, notice, storedToolAxes) {
     if (bodyMcp === undefined || bodyMcp === null)
         return baseline;
-    const { mcp, drops } = classifyRequestMcp(baseline, bodyMcp, config, logger);
+    const { mcp, drops } = classifyRequestMcp(baseline, bodyMcp, config, logger, storedToolAxes);
     mintInjectionDropNotices(drops, notice);
     return mcp;
 }
-function classifyRequestMcp(baseline, bodyMcp, config, logger) {
+function classifyRequestMcp(baseline, bodyMcp, config, logger, storedToolAxes) {
     if (bodyMcp !== undefined && bodyMcp !== null && !Array.isArray(bodyMcp)) {
         logger?.warn("mcp_injection_ignored", { reason: "mcpServers not an array" });
         return { mcp: baseline, drops: [] };
     }
     const entries = Array.isArray(bodyMcp) ? bodyMcp : [];
-    const outcome = mcpInjectionHonored(config) ? classifyHonored(baseline, entries, config, logger) : classifyGateClosed(baseline, entries);
+    const outcome = mcpInjectionHonored(config) ? classifyHonored(baseline, entries, config, logger, storedToolAxes) : classifyGateClosed(baseline, entries);
     if (outcome.drops.length > 0)
         logger?.warn("mcp_injection_dropped", { dropped: outcome.drops, droppedTotal: outcome.droppedTotal });
     return { mcp: outcome.mcp, drops: outcome.drops };
@@ -215,8 +306,8 @@ function classifyGateClosed(baseline, entries) {
         droppedTotal: entries.length,
     };
 }
-function classifyHonored(baseline, entries, config, logger) {
-    const v = validateRequestMcpEntries(entries);
+function classifyHonored(baseline, entries, config, logger, storedToolAxes) {
+    const v = validateRequestMcpEntries(entries, storedToolAxes);
     if (v.badContentOrigin.length > 0) {
         logger?.warn("mcp_content_class_dropped", {
             entries: v.badContentOrigin,
@@ -236,6 +327,16 @@ function classifyHonored(baseline, entries, config, logger) {
         if (issue !== undefined && mounted.has(declaredName(e)))
             noteMcpAssertionHeaderIgnored(logger, declaredName(e), issue);
     }
+    for (const r of v.toolAxesReread) {
+        if (!mounted.has(r.server))
+            continue;
+        logger?.warn("mcp_tool_axes_read_as_before_upgrade", {
+            server: r.server,
+            migration: "M19",
+            problem: r.problem,
+            note: "this replayed request was stored before the upgrade and its toolAxes declaration does not pass the engine's reader; while one-time migration M19 is open it is read the way the pre-upgrade server read it (members that did not fit are dropped, a declaration that is not an object counts as none) and the server stays mounted — once the window closes the same request leaves this server unmounted",
+        });
+    }
     return {
         mcp: mergeRequestMcp(baseline, v.ok.map(toCoreMcpServerSpec), reservedNames),
         drops: [...v.dropped, ...blocked.map((server) => ({ server, reason: "name_reserved_by_deployment" }))],

package/dist/task-settings.d.ts

@@ -47,9 +47,10 @@
  *  - (`hooks` NO LONGER deferred either — 轴B #2 注释保鲜:applied 形已接线(本文件 hooks 分片 +
  *    main.ts 单用户闸),仅 malformed 才报 deferred;旧「需要 remote hook-runner」是接线前拍照。)
  */
-import { type ExecutionEnv, type TaskSpec, type ThinkingLevel, type ToolPolicy, type PromptProvider, type PermissionMode } from "@sema-agent/core";
-import type { HooksConfig } from "@sema-agent/settings-schema/hooks";
+import { type PathRuleBases, type ExecutionEnv, type TaskSpec, type ThinkingLevel, type ToolPolicy, type PromptProvider, type PermissionMode } from "@sema-agent/core";
 import { type KeyClosureIssue } from "./request-key-closure.js";
+import { type RunnableHooksConfig } from "./hooks/hook-runner.js";
+import type { StoredHooksRereadM20 } from "./stored-request-hooks-m20.js";
 import { type EntryPermissionMode } from "./runtime-governance.js";
 /**
  * 请求面 `permissionMode` 的闭集 = core `PERMISSION_MODES` **全集**(顶层 `permissionMode` / `settings.permissions.defaultMode` /
@@ -213,10 +214,10 @@ export interface ParsedTaskSettings {
      *  orthogonal axes — `thinking:"max"` (the reasoning axis) + `selfOrchestration:true` (the orchestration axis,
      *  through its existing fail-closed gate). NOT a new mechanism; just a preset that fans out to existing spec fields. */
     ultracode?: boolean;
-    /** hooks hook-runner(阶段一):registry-core 0.1.51 契约校验过的 hooks 配置。像 shellEnv 一样
+    /** hooks hook-runner(阶段一):经 `parseHooksConfig`(契约包分类器 + 服务侧上限 + 本仓会跑的条目类型)判过的 hooks 配置。像 shellEnv 一样
      *  这里只 PARSE;应用点(main.ts resolveSpec)按单用户闸(`requirePrincipal !== true`)决定翻不翻成
      *  core `TaskSpec.hooks` 回调——多租户 lane 收到只警告忽略(hook 命令跑在 worker host = class ② 能力授予)。 */
-    hooks?: HooksConfig;
+    hooks?: RunnableHooksConfig;
     /** [ref](7.77.0)—— CC settings 同名键:上下文窗口里**留给技能清单**的比例((0,1];CC 默认 0.01 = 1%)。
      *  超预算时引擎把描述裁短、再不够退成 name-only(`cli259.js` 的清单渲染算法),**从不**拒掉一条技能 ——
      *  这正是本版把技能条数/描述两条帽整条退役后的补偿面:per-turn 成本的旋钮在**渲染侧**,不在受理侧。
@@ -232,6 +233,15 @@ export interface ParseTaskSettingsResult {
     /** Sub-fields the caller SENT but this version does not wire(`env`;`hooks` 仅在 MALFORMED 时入列——valid hooks
      *  已是 applied 字段)。Empty when none. */
     deferred: string[];
+    /** 一次性迁移 M20(窗口见 `plugins/one-time-migrations.ts` 登记表):存下的 hooks 被唯一读者拒掉、经重读座剥掉点名的键后过了读者 ⇒ 本次读数里 `settings.hooks` 是重读的产物,
+     *  并带被剥的坐标(出门形)。缺席 = 没有发生重读。 */
+    hooksReread?: {
+        readonly stripped: readonly string[];
+    };
+}
+/** `parseTaskSettings` 的可选座:续跑重放腿才有的重读座(一次性迁移 M20;新提交腿与不问 hooks 的读者不递)。 */
+export interface ParseTaskSettingsSeats {
+    readonly storedHooksReread?: StoredHooksRereadM20;
 }
 /** Cap on `outputStyle` length — it lands in the system prompt, so it shares the `MAX_SYSTEM_PROMPT_CHARS` (16384)
  *  posture (an uncapped prompt body is a per-turn token-cost hole; cross review). Exported so the HTTP layer
@@ -333,7 +343,7 @@ export declare function taskHooksHonored(config: {
  * 重放也走的宽容层,一个 4xx 在这里会把存量 parked 任务永久砖死;FRESH 提交面由 {@link taskSettingsKeyIssue}
  * 在 `server.ts` prepareSpec 里 400 响亮拒 + 逐字列名。双层姿势与 outputStyle / permissionMode 两处逐字相同。
  */
-export declare function parseTaskSettings(raw: unknown): ParseTaskSettingsResult;
+export declare function parseTaskSettings(raw: unknown, seats?: ParseTaskSettingsSeats): ParseTaskSettingsResult;
 /** Defensive acceptance of the `appendSystemPrompt` rider ([ref] R2 + codex F2): the HTTP 400 gate (prepareSpec,
  *  MAX_SYSTEM_PROMPT_CHARS) only covers FRESH submits — every resume family re-enters resolveSpec on a STORED body,
  *  and a pre-1.243 store preserved unknown request keys verbatim (the field was INERT then), so an over-cap legacy
@@ -457,6 +467,32 @@ export interface FsWriteGateWiring {
      *  本 wiring 的组合点。) */
     isExempt?: (toolName: string, canonicalPath: string) => boolean | Promise<boolean>;
 }
+/**
+ * deny / ask 两桶(core 规则编译器读的收紧表)的**问序,单表**:{@link rulePolicyBucketsRefusal} 的两段循环(名字层 + 文法 · `~/` 要 home)都迭代它 ——
+ * 两桶都有坏条目时,拒点与存体预判点名同一个桶、说同一句。表里每个词同时是 core 规则的 `behavior`。
+ */
+export declare const RULE_POLICY_BUCKETS: readonly ["ask", "deny"];
+export type RulePolicyBucket = (typeof RULE_POLICY_BUCKETS)[number];
+/**
+ * deny / ask 两桶的**完整规则判**,唯一一只(拒点 {@link rejectUnmatchableSettingsNames} 与存体预判 `http/stored-body-replay.ts` 同调):
+ *  ② 按 {@link RULE_POLICY_BUCKETS} 的序逐桶问 `unmatchableToolNamesRefusal`(名字层 + core 规则文法);③ 都过了,再逐桶判 `~/` 形要 home 的那一拒。第一个坏处答 `{ bucket, message }`。
+ * 入参:桶、{@link RulePolicyBases}。**home 同源**:拒点的 home 是 `resolve-spec.ts` 的 `laneHomeBase()` 经 `executionLaneHomeDir(config)` 算出的,预判传同一个函数对同一份部署配置算出的。
+ * **声明给文法的基**只有拒点有(根 + home 的并集,执行车道才知道根):core 的规则文法对**没声明**的基不下判词(见 `config.ts` `uncompilableRuleGuidance`),所以预判什么也不声明、两腿逐字同句;
+ * 预判不能把 home 当「半个基」声明给文法 —— core 的路径族只从根推,缺根时一个合法的 Windows 形 home 会按默认族被判 `unsupported.path_base`(V6-k)。
+ * ③ 排在最后:一条同时文法不成立又带 `~/` 的规则,先说文法(补上 home 它仍被文法拒,先说 home 是误导)。
+ */
+export interface RulePolicyBases {
+    /** 声明给 core 规则文法的路径基(这条 task 的根 + home):拒点才有;存体预判不声明。 */
+    readonly declared?: PathRuleBases;
+    /** 执行环境的 home(`~/` 形规则的前提);这个部署解不出 ⇒ 缺席。 */
+    readonly home?: string;
+}
+export declare function rulePolicyBucketsRefusal(permissions: Readonly<Partial<Record<RulePolicyBucket, readonly string[]>>>, bases: RulePolicyBases): {
+    readonly bucket: RulePolicyBucket;
+    readonly message: string;
+} | undefined;
+/** 请求的 settings 编不成生效的规则 / 有永远不生效的条目 ⇒ 422 的句首(三只桶同一个出口;`resolveSpec` 的拒点与存体重放预判的 409 句子同用这一个,不各写一份)。 */
+export declare const REQUEST_SETTINGS_REFUSAL_PREFIX = "request settings cannot be applied as written: ";
 export declare function deriveSettingsPolicy(settings: ParsedTaskSettings, gate?: FsWriteGateWiring, workflowGate?: WorkflowGateWiring): {
     toolPolicy?: ToolPolicy;
 };