@sema-agent/server 7.133.0 → 7.135.0

package/dist/task-a2a.js

@@ -1,9 +1,13 @@
-import { readToolAxes, resolveComplianceDenies } from "@sema-agent/core";
+import { resolveComplianceDenies } from "@sema-agent/core";
 import { isUsableWireName } from "@sema-agent/settings-schema";
-import { HttpError } from "./security.js";
+import { HttpError, createCodedHttpError } from "./security.js";
 import { readPlainStringRecord } from "./plain-string-record.js";
+import { readRequestToolAxes } from "./request-tool-axes.js";
 import { echoKeyName } from "./request-key-closure.js";
+import { limitRefusal } from "./limit-refusal.js";
+import { buildRequestUrlCredentialRefusal, findUrlCredential, urlCredentialHeaderExit } from "./url-credential.js";
 import { GOVERNANCE_HTTP_STATUS } from "./governance-http-status.js";
+import { DEPLOYMENT_SHAPE_PREDICATES } from "./deployment-shape.js";
 export const MAX_REQUEST_A2A_PEERS = 32;
 export function a2aInjectionHonored(config) {
     if (config.lockedConfigKeys?.includes("a2a") === true)
@@ -13,7 +17,7 @@ export function a2aInjectionHonored(config) {
         if (denies.has("a2a_peers"))
             return false;
     }
-    return config.requirePrincipal !== true;
+    return !DEPLOYMENT_SHAPE_PREDICATES.multiTenant.holds(config);
 }
 const HTTP_URL_RE = /^https?:\/\//i;
 function normalizeA2aPeer(e, leg, storedToolAxes) {
@@ -45,12 +49,12 @@ function normalizeA2aPeer(e, leg, storedToolAxes) {
     if (Array.isArray(o.allowSkills))
         spec.allowSkills = o.allowSkills;
     if (o.toolAxes !== undefined) {
-        const axes = readToolAxes(o.toolAxes, "a2a");
+        const axes = readRequestToolAxes(o.toolAxes, "a2a");
         if (!axes.ok && storedToolAxes !== undefined) {
             const before = storedToolAxes.a2a(o.toolAxes);
             if (before === null)
                 return dropped;
-            const again = readToolAxes(before, "a2a");
+            const again = readRequestToolAxes(before, "a2a");
             if (!again.ok)
                 return dropped;
             if (again.toolAxes !== undefined)
@@ -93,6 +97,35 @@ function validateRequestA2aEntries(raw, leg, storedToolAxes) {
         dropped.push(`(+${raw.length - MAX_REQUEST_A2A_PEERS} over cap of ${MAX_REQUEST_A2A_PEERS})`);
     return { ok, dropped, toolAxesReread, headersLost };
 }
+const A2A_PEER_URL_KEYS = ["url", "cardUrl"];
+function requestA2aPeerUrlRefusal(list) {
+    if (!Array.isArray(list))
+        return undefined;
+    if (list.length > MAX_REQUEST_A2A_PEERS) {
+        return limitRefusal("a2aPeers", "entries", list.length, MAX_REQUEST_A2A_PEERS, {
+            tail: "The request is refused rather than mounting the first peers and dropping the rest: the whole list is stored with the task, and each peer's url / cardUrl is checked for credentials",
+        });
+    }
+    for (const [i, peer] of list.entries()) {
+        if (peer === null || typeof peer !== "object")
+            continue;
+        const entry = peer;
+        for (const key of A2A_PEER_URL_KEYS) {
+            const value = entry[key];
+            const found = typeof value === "string" ? findUrlCredential(value) : undefined;
+            if (found === undefined)
+                continue;
+            const at = `a2aPeers[${i}]`;
+            return buildRequestUrlCredentialRefusal(`${at}.${key}`, found, urlCredentialHeaderExit(`${at}.headers`), typeof entry.name === "string" && entry.name !== "" ? `peer "${echoKeyName("", entry.name)}"` : undefined);
+        }
+    }
+    return undefined;
+}
+export function assertRequestA2aPeerUrls(bodyA2a) {
+    const refusal = requestA2aPeerUrlRefusal(bodyA2a);
+    if (refusal !== undefined)
+        throw createCodedHttpError(400, "request.field_invalid", refusal.message, refusal.facts);
+}
 export function assertRequestA2aUnlocked(bodyA2a, lockedKeys) {
     if (!lockedKeys.has("a2a"))
         return;

package/dist/task-cwd.d.ts

@@ -1,10 +1,11 @@
+import { type DeploymentShapeInput } from "./deployment-shape.js";
 /**
  * 词法归一:纯字符串运算,折 `.` / `..` / 重复分隔符,**不碰 fs**。
  * `posix.normalize` 把 `..` 在根部截断(`/../x` → `/x`),与「根之上没有东西」的语义一致;尾部分隔符
  * 统一剥掉(根 `/` 除外),让同一目标只有一个 key —— 前缀判域(见 {@link dirCoversPath})靠的就是
  * key 的唯一性。
  *
- * 🔴 **单点**(S-351 起):此前它的一份私有副本住在 `boot/deferred-sandbox-path-env.ts`(沙箱代理的
+ * 🔴 **单点**([ref] 起):此前它的一份私有副本住在 `boot/deferred-sandbox-path-env.ts`(沙箱代理的
  * `absolutePath` 词法臂),而写门豁免域与任务根的判域现在读的是同一条律 —— 两份各自归一就是两个 key
  * 空间,而「豁免域盖没盖住任务根」这种判断在两个 key 空间里可以同时答是和否。
  * (core 内部有同形的 `normalizeAbsPathLexically`,但未从包根导出;此处是 Node 标准库的等价运算,
@@ -22,97 +23,20 @@ export declare function normalizeAbsolutePathLexically(p: string): string;
  * 段感知由「归一后 + 分隔符前缀」保证:`/a/bc` **不在** `/a/b` 域内。
  */
 export declare function dirCoversPath(dir: string, target: string): boolean;
-/**
- * The deployment-level gate: does THIS deployment honor a caller-supplied `cwd`? TRUE only for the single-user
- * `host` lane (see module header). All cloud/container lanes + any multi-tenant deployment → FALSE (cwd ignored).
- */
-export declare function cwdHonored(config: {
-    remoteExec?: {
-        provider?: string;
-    };
-    requirePrincipal?: boolean;
-}): boolean;
-/**
- * S-377 —— 「**工具跑的那台机器**就是本进程这台吗」。回答的是一个**文件系统同一性**问题,不是权限问题:
- * server 盘上的一条绝对路径(出厂 `SKILLS_DIR` 下、或中心 plugin 缓存里某个技能自己的目录)对模型的工具**有没有意义**。
- *
- * 判据 = 能力表两位的合取 {@link handsOnWorkerFilePlane}(`coreRemoteExecutionEnv ∧ hostFilePlane`,都读表,
- * 本函数不手写任何车道词):
- * · `host`(run-on-this-machine,无容器)⇒ 真;
- * · `in-process`(`REMOTE_EXEC` 未设)⇒ **假**(S-602,clay 裁 [ref] A 翻面;改前判真)—— 该 lane 根本
- *   没挂手(core 落 `StubExecutionEnv`),「工具的盘」这句话在这里没有指称对象。改前的理由「文件系统同一性
- *   这条轴上确实是同一台机器,判真让规则只剩一条」把**缺席折成了邻居**:wire 上的 `toolsOnThisHost` 因此
- *   对无手部署说真,消费端的 doctor 据此说「工具在本机」。代价如实记:出厂目录形技能在 in-process 上不再带
- *   `baseDir` —— core 律:缺席 ⇒ 结果逐字节同 baseDir 到货之前,而那条 lane 上本来也没有能读它的工具;
- * · 其余每一条(`k8s` / `e2b` / `ssh` / `adb` / `device` / `local-docker`)⇒ 假:工具的盘在别处,
- *   server 自己的路径在那边**不存在**,声明它等于给模型一条指向不存在文件的线索,还顺带把本机目录
- *   布局说了出去;
- * · 认不出的词 ⇒ 假(fail-closed:没认出来的车道不许被当成「本机」)。
- *
- * 🔴 **为什么不复用 {@link cwdHonored}**:那一只是**权限**判据(单用户 ∧ host),它的 `requirePrincipal`
- * 那一半防的是「一个租户的输入把 agent 指向另一个租户的文件」。本谓词判的路径不是调用方给的,是**运维
- * 自己烤进镜像**的出厂内容 —— 每个租户拿到的是同一份,没有跨租户面。把租户判据搭进来会让多租户 host
- * 部署平白失去这条线索,那是**用错轴**(与 `deviceCwdHonored` 拒绝并进 `cwdHonored` 同一条理由)。
- */
-export declare function toolsRunOnThisHost(config: {
-    remoteExec?: {
-        provider?: string;
-    };
-}): boolean;
-/**
- * device lane 的**平行**判别式(device-executor-lane-v2 §4.3.3,车A-4)——「员工在自己设备的项目目录
- * 里干活」是这条车道的存在理由,所以 caller cwd 必须被尊重。
- *
- * 🔴 **为什么不合并进 {@link cwdHonored}**:两闸语义不同,合并会把 host 的单用户约束**放松**。
- *  · `cwdHonored` 的 `requirePrincipal !== true` 防的是「一个租户的输入把 agent 指向 **worker 宿主**上
- *    另一个租户/运维的目录」—— 那是一台共享机器上的跨租户穿越;
- *  · device lane 上那个穿越面**结构性不存在**:路径落在**发起者自己的设备**上,而设备归属已由
- *    `device_session` 绑定行(提交期用验证过的 principal 写下)+ 准入链的 owner 谓词验过。所以本闸
- *    **不要求**单用户 —— 多租户部署里每个员工各连各的设备,正是这条车道的正常形态。
- * 合并两者 = 让 host 车道在多租户下也开始尊重 cwd,那是一条真实的超范围面。
- *
- * 消费者:写侧 = `boot/resolve-spec.ts`(**单写者**,与 cwdHonored 同一处);读侧 =
- * `plugins/remote-env-device.ts` 的工厂(`effectiveDeviceCwd`)。两侧必须同批落 —— 只开写侧会留下一个
- * 没有消费者的登记项(这正是 A-1 把它登记进 `PLANNED_LANE_DIVERGENCES` 而不是当场开的理由)。
- *
- * ⚠️ 刻意**不**连带放开 `additionalDirectories`:那一位在 device v1 上诚实缺席(v2 §4.1 capability
- * projectContext 行:「拆精确字段,device v1 对 unsupported 项显式 false,不打包沿用」)。
- */
-export declare function deviceCwdHonored(config: {
-    remoteExec?: {
-        provider?: string;
-    };
-    requirePrincipal?: boolean;
-}): boolean;
-/**
- * [ref]P3a — the OTHER host-semantics lane: provider UNSET = the in-process single-user lane. It has NO shell
- * hands (core prepare-task: no factory/executionEnv ⇒ StubExecutionEnv), so the perSession cwd/env registries
- * have no consumer there — but PROCESS-level consumers (hooks commands, the C4 projectContext local read) still
- * see the engine's own `process.cwd()`/`process.env`. When the shell spawned the engine in the caller's own
- * dir/env, a caller override is often ALREADY satisfied by that process state, and a per-task "ignored" warn
- * contradicts it (飞轮双平台观测). Signal-truth split: satisfied ⇒ debug, real mismatch ⇒ warn. True per-session
- * honoring remains `REMOTE_EXEC=host`. Multi-tenant excluded for the same reason as {@link cwdHonored}.
- */
-export declare function inProcessSingleUserLane(config: {
-    remoteExec?: {
-        provider?: string;
-    };
-    requirePrincipal?: boolean;
-}): boolean;
 /**
  * [ref](F-1,[ref] 修向 (b')):卡批「不再询问」落盘规则的 **project root** —— 「这次授权是在哪个
  * 工作目录里点的」。取值与既有 cwd 语义同源,不新造坐标系:
  *   1. session 显式注册的 cwd(cwd seam,host lane;与 {@link effectiveHostWorkspace} 第 1 优先级同源)
  *      —— **今天唯一真的会命中的那一臂**;⚠️ 它**不含 lane 判据**,lane 语义完全依赖「`perSessionCwd`
- *      只在 `cwdHonored` 为真时被写」这条跨文件外部不变量(写侧唯一入口 boot/resolve-spec.ts)。这是
+ *      只在部署形表行 `callerCwd` 为真时被写」这条跨文件外部不变量(写侧唯一入口 boot/resolve-spec.ts)。这是
  *      刻意的单写者惯用法,不是疏漏:在消费端补第二道闸 = 把一条不变量拆给两个属主(同族消费者
  *      {@link effectiveHostWorkspace} 形状完全相同)。机器背书 = test/task-cwd.test.ts 的 [ref] 两格。
  *   2. 🔴 **前瞻/防御臂,本仓当前装配下零命中**([ref],2026-08-19 合并重扫 partial,存活断言):
- *      in-process 单用户 lane({@link inProcessSingleUserLane})取引擎自身 `process.cwd()`。它读起来像在
+ *      in-process 单用户 lane(部署形表行 `inProcessSingleUser`)取引擎自身 `process.cwd()`。它读起来像在
  *      服务一个真部署形,其实到不了 —— 该 lane 的 `remoteExec` 未设 ⇒ boot/execution-env.ts 六条工厂臂全
  *      不命中 ⇒ core 落 `StubExecutionEnv` ⇒ `handsEnabled=false` ⇒ 不挂 Bash ⇒ 未知工具在 agent-loop 走
  *      `tool.not_found`(**不进审批座**)⇒ 无 `ruleOffers` ⇒ 本函数在规则车道上根本不被调用;同 lane
- *      第 1 臂也因写侧闸只在 `cwdHonored` 下开而恒空。危害口径按 refuter **降级**:死枝 ≡ 落第 3 臂
+ *      第 1 臂也因写侧闸只在 `callerCwd` 下开而恒空。危害口径按 refuter **降级**:死枝 ≡ 落第 3 臂
  *      `undefined` ≡ core global 缺省 ≡ [ref] 修前行为,**今天零用户可见伤害**,不是「恒不命中」类缺陷。
  *      🚧 **给将来接手的人的红线**:这条 lane 若哪天真接上 hands,root 必须取 `executionEnv.cwd`(core 的
  *      `taskRootFinal` 就是它),**不是** `process.cwd()` —— 两者在静态 env 装配形下可以完全不同,照现注
@@ -134,12 +58,7 @@ export declare function inProcessSingleUserLane(config: {
  * `path.resolve` 不抛 ⇒ 初版的 realpath 失败 F 类兜底臂(`rule-scope-root-unresolvable`)随之退役
  * (census 行同批销,fail-open.ts)。
  */
-export declare function cardRuleScopeRoot(registeredCwd: string | undefined, config: {
-    remoteExec?: {
-        provider?: string;
-    };
-    requirePrincipal?: boolean;
-}, cwd?: () => string): string | undefined;
+export declare function cardRuleScopeRoot(registeredCwd: string | undefined, config: DeploymentShapeInput<"lane" | "principal">, cwd?: () => string): string | undefined;
 /** Is a requested cwd ALREADY the engine process's working dir? realpath BOTH sides (macOS `/tmp` →
  *  `/private/tmp`-class symlinks); either side failing to resolve ⇒ treated as a mismatch (warn — never a
  *  false downgrade). `realpath`/`cwd` are parameters for testability; production passes `fs.realpathSync`. */
@@ -153,7 +72,7 @@ export declare const MAX_ADDITIONAL_DIRS = 64;
 /**
  * [ref] (CC `--add-dir` parity): validate an untrusted `body.additionalDirectories` — extra host dirs the
  * FILE tools may access beyond the containment root (core canonicalizes each into its allowlist + lists them in the
- * `# Environment` block). Gated identically to {@link cwdHonored}: these are the caller's OWN-machine paths, so they
+ * `# Environment` block). Gated by the deployment-shape row `callerOwnsWorkerDisk` (hands on this worker's disk ∧ one owner): these are the caller's OWN-machine paths, so they
  * only make sense — and are only safe — on the single-user host lane (on a cloud/container lane a file-tool root is
  * the sandbox fs, and a multi-tenant lane must never let one caller widen containment onto operator/other-tenant
  * host paths). Each element gets the SAME structural check as `cwd` (absolute, no `..` traversal, no NUL, capped);

package/dist/task-cwd.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { isAbsoluteHostPath } from "@sema-agent/settings-schema";
-import { executionLaneOf, handsOnWorkerFilePlane } from "./execution-lane-caps.js";
+import { DEPLOYMENT_SHAPE_PREDICATES } from "./deployment-shape.js";
 export function normalizeAbsolutePathLexically(p) {
     const collapsed = path.posix.normalize(p.replace(/^\/+/, "/"));
     return collapsed.length > 1 ? collapsed.replace(/\/+$/, "") : collapsed;
@@ -10,21 +10,8 @@ export function dirCoversPath(dir, target) {
     const p = normalizeAbsolutePathLexically(target);
     return p === root || p.startsWith(root.endsWith("/") ? root : `${root}/`);
 }
-export function cwdHonored(config) {
-    return config.remoteExec?.provider === "host" && config.requirePrincipal !== true;
-}
-export function toolsRunOnThisHost(config) {
-    const lane = executionLaneOf(config.remoteExec?.provider);
-    return lane !== undefined && handsOnWorkerFilePlane(lane);
-}
-export function deviceCwdHonored(config) {
-    return config.remoteExec?.provider === "device";
-}
-export function inProcessSingleUserLane(config) {
-    return config.remoteExec === undefined && config.requirePrincipal !== true;
-}
 export function cardRuleScopeRoot(registeredCwd, config, cwd = process.cwd) {
-    const raw = registeredCwd ?? (inProcessSingleUserLane(config) ? cwd() : undefined);
+    const raw = registeredCwd ?? (DEPLOYMENT_SHAPE_PREDICATES.inProcessSingleUser.holds(config) ? cwd() : undefined);
     return raw === undefined ? undefined : path.resolve(raw);
 }
 export function satisfiedByProcessCwd(requested, realpath, cwd = process.cwd) {

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 UrlCredentialFacts } from "./url-credential.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;
@@ -43,10 +44,10 @@ export declare const MAX_REQUEST_MCP_SERVERS = 32;
  */
 export declare const MAX_REQUEST_MCP_DROP_NAMES = 32;
 /**
- * S-481 —— 一条 `mcpServers[]` 条目在 wire 上的**键闭集**,与它两种传输各自的键闭集。
+ * [ref] —— 一条 `mcpServers[]` 条目在 wire 上的**键闭集**,与它两种传输各自的键闭集。
  *
  * ## 属主为什么在这里
- * 这个文件就是「请求腿的 MCP 条目形」的家({@link normalizeServer} 逐键读的正是这些)。S-481 的探测口
+ * 这个文件就是「请求腿的 MCP 条目形」的家({@link normalizeServer} 逐键读的正是这些)。[ref] 的探测口
  * ({@link import("./capabilities/mcp-probe.js").readMcpProbeBody})要的是**同一个**词表 —— 它在自己那边
  * 再写一份就是一份手抄投影([ref]:任何仓第一排查点),而两份哪天分岔,窄的那一份会把**合法**的键当成
  * 拼写错误 400 掉。
@@ -73,7 +74,7 @@ export declare const STDIO_MCP_TRANSPORT_KEYS: readonly ["args", "command", "env
 export declare const HTTP_MCP_TRANSPORT_KEYS: readonly ["assertionHeader", "headers", "kind", "principalHeader", "url"];
 /**
  * Does THIS deployment honor caller-supplied per-request MCP servers? TRUE for a SINGLE-USER deployment
- * (`requirePrincipal !== true`) — the requester is the super-admin of their own worker, so their `.mcp.json` is
+ * (deployment-shape row `multiTenant` does not hold) — the requester is the super-admin of their own worker, so their `.mcp.json` is
  * authoritative (CC-parity), on ANY execution lane (the stdio command runs on the worker, not the exec env, so the
  * lane is irrelevant — see module header). FALSE on a multi-tenant deployment (a tenant can't make the shared worker
  * run an arbitrary command / connect to an arbitrary URL).
@@ -84,7 +85,7 @@ export declare function mcpInjectionHonored(config: {
     compliancePosture?: CompliancePosture;
 }): boolean;
 /**
- * L-167(core 7.9.1)—— 一条**没有被挂上**的请求腿 MCP 条目的**事实**。宿主报事实,core 铸词:
+ * [ref](core 7.9.1)—— 一条**没有被挂上**的请求腿 MCP 条目的**事实**。宿主报事实,core 铸词:
  * `reason` 的词表属主是 core(`McpInjectionDropReason` = malformed_entry / name_reserved_by_deployment /
  * gate_closed / over_cap),本仓一个词都不枚举,通告的码/受众/句子一个字都不拼。
  *
@@ -97,7 +98,7 @@ export interface McpInjectionDrop {
     /** `malformed_entry` 专用:**哪个键**判不出形。结构性给出(读器在拒的那一行就知道),不从文案里 parse。 */
     readonly field?: string;
 }
-/** L-167:本条腿的用户面通告席。`sessionId` = 路由半场(`auth.sessionId`,与 `spec.sessionId` 同源);
+/** [ref]:本条腿的用户面通告席。`sessionId` = 路由半场(`auth.sessionId`,与 `spec.sessionId` 同源);
  *  `emit` = 收下 core 铸好的 `EngineNotice`。**本模块不知道**它最后落在 SSE、账本还是日志上 —— 那是
  *  投递腿的事,本模块只负责「事实 → core 工厂 → 一条通告」。 */
 export interface McpInjectionDropSeat {
@@ -141,12 +142,14 @@ export declare function assertRequestMcpUnlocked(bodyMcp: unknown, lockedKeys: R
 /** 一条**原始**请求条目上两个身份头的问题类(没有问题 / 不是对象 / 不是 http 传输 ⇒ `undefined`)—— 提交腿的门、探测口、重放腿的披露三处共读,
  *  判据本体在 `mcp-assertion-header.ts`;这里只负责把「条目 → 传输对象」那一步读出来。 */
 export declare function requestEntryIdentityIssue(entry: unknown): McpIdentityHeadersIssue | undefined;
-/** 请求面 `mcpServers` 的一次拒:码 + 句 + 词表外的键名表(只在闭集那一形上在场)。两扇门(fresh 提交腿 / 探测口)同一份,状态恒 400。 */
+/** 请求面 `mcpServers` 的一次拒:码 + 句 + 词表外的键名表(只在闭集那一形上在场)+ 机读位(只在「url 带凭据」那一形上在场)。两扇门(fresh 提交腿 / 探测口)同一份,状态恒 400。 */
 export interface RequestMcpRefusal {
     readonly errorCode: "request.body_shape" | "request.field_invalid";
     readonly message: string;
     /** 词表外的键,全路径形(`mcpServers[0].transport.header`;已清洗 + 截长 + 排序 + 封顶)。 */
     readonly unknownKeys?: readonly string[];
+    /** [ref]:`transport.url` 带凭据 ⇒ 拒体顶层的 `field`(`mcpServers[i].transport.url`)+ `reason`(判官的拒因词,闭集)—— 与 `request.field_invalid` 上既有的 `field` / `reason` 同名同读。 */
+    readonly facts?: UrlCredentialFacts;
 }
 /**
  * 请求面 `mcpServers`「这份声明能不能原样用」的**唯一回答者** —— fresh 提交腿({@link assertRequestMcpEntries})与探测口
@@ -158,10 +161,11 @@ export interface RequestMcpRefusal {
  *  ② **键名**:条目层、或 `transport` 按 `kind` 那一形的键闭集之外的键 ⇒ `400 request.body_shape`,拒体带 `unknownKeys`(拼错的键被悄悄不读,同样读起来像生效了)。
  *  ③ **身份头的键组合**(`principalHeader` 与 `assertionHeader` 同设 / `assertionHeader` 非串)⇒ {@link requestEntryIdentityRefusal}(同设那一句对契约包解析期原句逐字)。
  *  ④ **受理键的值** ⇒ 逐键问判官表 {@link ENTRY_KEY_JUDGES},`400 request.field_invalid`,拒句点名 `mcpServers[i].<键路径>`、server 名与**该键判官的原因句**({@link entryFieldRefusal})。
- *     判官**就是读器用的那一只**,不是第二份:`toolAxes` = 引擎根导出的 `readMcpToolAxes`;`toolFaces` = `readMcpToolFaces`;`contentOrigin` = `isContentOriginWord`;`source` = `isMcpSourceLabel`;
+ *     判官**就是读器用的那一只**,不是第二份:`toolAxes` = {@link readRequestToolAxes}(引擎根导出的 `readToolAxes` + 请求腿不收 `boundaryFlow`);`toolFaces` = 引擎根导出的 `readToolFaces`;
+ *     `startupTimeoutMs` = 引擎根导出的 `mcpStartupTimeoutMs`(坏值抛 `config.mcp_startup_timeout_invalid`,本门把那一句作原因句);`contentOrigin` = `isContentOriginWord`;`source` = `isMcpSourceLabel`;
  *     `name` = `isUsableWireName`;`allowTools` / `transport.args` = {@link isStringArray};`transport.env` / `headers` = 契约包读器 {@link readRequestMcpTransport} 的纯数据记录读法;`elicitation` = {@link isElicitationFlag};
- *     `transport` 的硬字段(`kind` / `command` / `url`)与软字段(`args` / `env` / `headers` / `principalHeader`)= {@link readRequestMcpTransport}(读器投影 transport 的那一只函数,门读它报的 `lost`;读器在契约包,本仓只据 `lost[0]` 拒、据 `lost` 在重放腿逐处点名)。
- *     判官只在引擎里、包根没给读口的键(今天只有 `startupTimeoutMs`)不在这里判,原样过境、由引擎在拨号时按 server 拒(不写第二份判据;到货读口即换)。
+ *     `transport` 的硬字段(`kind` / `command` / `url`)与软字段(`args` / `env` / `headers` / `principalHeader`)= {@link readRequestMcpTransport}(读器投影 transport 的那一只函数,门读它报的 `lost`;读器在契约包,本仓只据 `lost[0]` 拒、据 `lost` 在重放腿逐处点名);
+ *     读器交回的 http `url` 再问「带不带凭据」= `url-credential.ts` 的 `findUrlCredential`([ref];拒体另带机读 `field` + `reason`,见 {@link transportUrlCredentialIssue})。
  * 于是判官受理的条目,读器({@link normalizeServer})交回的就是申报本身(只差判官自己的合法归一:空容器 / `skillScopeEligible:false` 折成缺席、`toolAxes` 取引擎的拷贝)——
  * 探测口拨的那一份因此就是提交腿会挂的那一份,不另比一遍(另比就是第二只回答者)。唯一按门分的后果是「声明了 `assertionHeader`」这一个事实(引擎尚无座,
  * 承载、不发送):新提交照挂 + 运维 info,探测口整条拒 —— 判据是同一只谓词 `specWithholdsMcpAssertionHeader`(开关 `MCP_ASSERTION_HEADER_SENT` 假时「声明了」即「被扣下」),不是第二份判法(见 `readMcpProbeBody`)。
@@ -224,7 +228,7 @@ export declare function resolveRequestMcp(baseline: McpServerSpec[] | undefined,
     info?(m: string, meta?: unknown): void;
     warn(m: string, meta?: unknown): void;
 }, 
-/** L-167:本条腿的**用户面**投递口。`sessionId` = 通告的路由半场(缺席 ⇒ 一条都不铸,见
+/** [ref]:本条腿的**用户面**投递口。`sessionId` = 通告的路由半场(缺席 ⇒ 一条都不铸,见
  *  {@link mintInjectionDropNotices});`emit` 收下 core 铸好的通告,由调用腿决定投到哪(见 `boot/resolve-spec.ts`)。
  *  整段缺席(桩、单测、非 HTTP 腿)⇒ 只走日志终点,行为逐字与本件之前相同。 */
 notice?: McpInjectionDropSeat, 

package/dist/task-mcp.js

@@ -1,11 +1,13 @@
-import { mcpInjectionDroppedNotice, readMcpToolAxes, resolveComplianceDenies } from "@sema-agent/core";
+import { mcpInjectionDroppedNotice, mcpStartupTimeoutMs, readToolFaces, resolveComplianceDenies } from "@sema-agent/core";
 import { MCP_CONTENT_ORIGINS, describeBadContentOrigin, describeBadWireName, describeNotStringArray, describeValueShape, isContentOriginWord, isStringArray, isUsableWireName, readRequestMcpTransport, stripControlAndBidi, } from "@sema-agent/settings-schema";
 import { HttpError, createCodedHttpError } from "./security.js";
 import { GOVERNANCE_HTTP_STATUS } from "./governance-http-status.js";
+import { DEPLOYMENT_SHAPE_PREDICATES } from "./deployment-shape.js";
 import { MCP_SOURCE_LABEL_MAX, isMcpSourceLabel, readMcpSourceLabel } from "./mcp-source-label.js";
 import { describeMcpAssertionHeaderNotAString, describeMcpIdentityHeadersConflict, mcpIdentityHeadersIssue, noteMcpAssertionHeaderIgnored, noteMcpAssertionHeaderNotSent, specWithholdsMcpAssertionHeader, toCoreMcpServerSpec } from "./mcp-assertion-header.js";
 import { MAX_KEY_ECHO, echoKeyName, keyClosureClause, scanKeyClosure } from "./request-key-closure.js";
-import { readMcpToolFaces } from "./mcp-tool-faces.js";
+import { readRequestToolAxes } from "./request-tool-axes.js";
+import { findUrlCredential, urlCredentialFacts, urlCredentialHeaderExit, urlCredentialRefusalReason } from "./url-credential.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", "startupTimeoutMs", "toolAxes", "toolFaces", "transport"];
@@ -16,7 +18,7 @@ export function mcpInjectionHonored(config) {
         return false;
     if (config.compliancePosture !== undefined && resolveComplianceDenies(config.compliancePosture).has("mcp_servers"))
         return false;
-    return config.requirePrincipal !== true;
+    return !DEPLOYMENT_SHAPE_PREDICATES.multiTenant.holds(config);
 }
 function isRecord(v) {
     return v !== null && typeof v === "object" && !Array.isArray(v);
@@ -48,11 +50,11 @@ function normalizeServer(e, noteBadOrigin, storedToolAxes) {
     }
     if (isElicitationFlag(o.elicitation))
         spec.elicitation = o.elicitation;
-    const axes = readMcpToolAxes(o.toolAxes);
+    const axes = readRequestToolAxes(o.toolAxes, "mcp");
     let judged = axes;
     let toolAxesReread;
     if (!axes.ok && storedToolAxes !== undefined) {
-        const again = readMcpToolAxes(storedToolAxes.mcp(o.toolAxes));
+        const again = readRequestToolAxes(storedToolAxes.mcp(o.toolAxes), "mcp");
         if (again.ok) {
             judged = again;
             toolAxesReread = stripControlAndBidi(axes.problem);
@@ -71,7 +73,7 @@ function normalizeServer(e, noteBadOrigin, storedToolAxes) {
     Object.assign(spec, readMcpSourceLabel(spec.name, o.source));
     if (o.startupTimeoutMs !== undefined)
         spec.startupTimeoutMs = o.startupTimeoutMs;
-    const faces = readMcpToolFaces(o.toolFaces);
+    const faces = readToolFaces(o.toolFaces);
     if (!faces.ok)
         return bad("toolFaces");
     if (faces.faces !== undefined)
@@ -149,8 +151,10 @@ export function requestMcpDeclarationRefusal(list) {
 }
 export function assertRequestMcpEntries(bodyMcp) {
     const refusal = requestMcpDeclarationRefusal(bodyMcp);
-    if (refusal !== undefined)
-        throw createCodedHttpError(400, refusal.errorCode, refusal.message, refusal.unknownKeys === undefined ? undefined : { unknownKeys: [...refusal.unknownKeys] });
+    if (refusal === undefined)
+        return;
+    const extra = { ...(refusal.unknownKeys === undefined ? {} : { unknownKeys: [...refusal.unknownKeys] }), ...(refusal.facts ?? {}) };
+    throw createCodedHttpError(400, refusal.errorCode, refusal.message, Object.keys(extra).length === 0 ? undefined : extra);
 }
 const LIST_REFUSAL_TAIL = "The request is refused rather than acting on part of the list: declarations that silently did not apply would read as in effect to whoever sent them. " +
     "Fix the list (an empty list declares none).";
@@ -172,6 +176,12 @@ function entryUnknownKeys(entry, at) {
     }
     return buckets.unknown.sort();
 }
+function transportUrlCredentialIssue(url) {
+    const found = findUrlCredential(url);
+    if (found === undefined)
+        return undefined;
+    return { path: "transport.url", reason: urlCredentialRefusalReason(found, urlCredentialHeaderExit("transport.headers")), credential: found };
+}
 const ENTRY_KEY_JUDGES = {
     allowTools: (o) => o.allowTools === undefined || isStringArray(o.allowTools)
         ? undefined
@@ -188,18 +198,34 @@ const ENTRY_KEY_JUDGES = {
     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 ${describeValueShape(o.source)}` },
-    startupTimeoutMs: () => undefined,
+    startupTimeoutMs: (o) => {
+        if (o.startupTimeoutMs === undefined)
+            return undefined;
+        try {
+            mcpStartupTimeoutMs({ name: typeof o.name === "string" ? o.name : "", startupTimeoutMs: o.startupTimeoutMs });
+            return undefined;
+        }
+        catch (e) {
+            if (e.code !== "config.mcp_startup_timeout_invalid")
+                throw e;
+            return { path: "startupTimeoutMs", reason: e instanceof Error ? e.message : String(e) };
+        }
+    },
     toolAxes: (o) => {
-        const read = readMcpToolAxes(o.toolAxes);
+        const read = readRequestToolAxes(o.toolAxes, "mcp");
         return read.ok ? undefined : { path: "toolAxes", reason: read.problem };
     },
     toolFaces: (o) => {
-        const read = readMcpToolFaces(o.toolFaces);
+        const read = readToolFaces(o.toolFaces);
         return read.ok ? undefined : { path: "toolFaces", reason: read.problem };
     },
     transport: (o) => {
         const read = readRequestMcpTransport(o.transport);
-        return read.ok ? read.lost[0] : read.issue;
+        if (!read.ok)
+            return read.issue;
+        if (read.lost[0] !== undefined)
+            return read.lost[0];
+        return read.transport.kind === "http" ? transportUrlCredentialIssue(read.transport.url) : undefined;
     },
 };
 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. " +
@@ -209,6 +235,7 @@ function entryFieldRefusal(entry, at, issue) {
     return {
         errorCode: "request.field_invalid",
         message: `${at}.${issue.path} (server "${server}") is not a usable declaration — ${stripControlAndBidi(issue.reason)}. ${ENTRY_REFUSAL_TAIL}`,
+        ...(issue.credential === undefined ? {} : { facts: urlCredentialFacts(`${at}.${issue.path}`, issue.credential) }),
     };
 }
 function requestEntryRefusal(entry, at) {

package/dist/task-settings.d.ts

@@ -59,7 +59,7 @@ import { type TightenOnlySeatValues } from "./tighten-only-seats.js";
  * `?permissionMode=` 查询串三处同读)。本仓不持有第二份词表,也不持有「收 / 不收」的表态:判据 = core 的 `isPermissionMode`,型 = core 的
  * `PermissionMode`,wire 句子里的词表只从这里取词({@link PERMISSION_MODE_WORDS})。core 加一个词 ⇒ 请求面自动收它、原样过境,本仓没有
  * 按词分的臂要补;core 删 / 改名一个词 ⇒ 本仓按名写出它的地方(`PLAN_APPROVE_PERMISSION_MODES_AFTER` 等)编译红。
- * 生效模式原样过境 `TaskSpec.permissionMode`(S-877):引擎自己解释模式 —— 含 `dontAsk`(CC 的「自动拒」档:凡是要问的一律由模式拒,零卡,
+ * 生效模式原样过境 `TaskSpec.permissionMode`([ref]):引擎自己解释模式 —— 含 `dontAsk`(CC 的「自动拒」档:凡是要问的一律由模式拒,零卡,
  * 门记录 `deniedBy:"mode"`)与 acceptEdits 的免问写域(引擎的写根:任务根 + `additionalDirectories` + 宣告的可写目录),本仓不另写判。
  */
 /** 请求面闭集的 wire 文案形(`"a" | "b" | …`,core 序)—— 三处 400(顶层 / bundle / 查询串)的句子从这里取词,不再各抄一份。 */
@@ -82,7 +82,7 @@ export declare function coercePermissionMode(raw: unknown): PermissionMode | und
  *  上面的宽读只是本函数外再包一层折叠;词表只有 core 的 `PERMISSION_MODES`(判据 `isPermissionMode`)。 */
 export declare function coercePermissionModeStrict(raw: unknown): PermissionMode | undefined;
 /**
- * S-433 —— 一份**被批准的计划**之后,这条会话继续用的 permission mode(`plan_review` 决裁体的
+ * [ref] —— 一份**被批准的计划**之后,这条会话继续用的 permission mode(`plan_review` 决裁体的
  * `permissionModeAfter`)。core 的契约句是 `present-plan-tool.js`:「If the plan is approved, the run
  * continues (and any read-only restriction is lifted)」—— 而 core 顶层 resume 把宿主的续跑配置**整体**
  * 展开成新一段 spec、读的是那段 spec 上的模式词(`TaskSpec.permissionMode`),所以「松开」这件事的属主在
@@ -99,7 +99,7 @@ export declare function coercePermissionModeStrict(raw: unknown): PermissionMode
 export declare const PLAN_APPROVE_PERMISSION_MODES_AFTER: readonly ["default", "acceptEdits"];
 /** {@link PLAN_APPROVE_PERMISSION_MODES_AFTER} 的类型形(值表单点,类型从值派生 —— 两处各写一份就会漂)。 */
 export type PlanApprovePermissionModeAfter = (typeof PLAN_APPROVE_PERMISSION_MODES_AFTER)[number];
-/** S-433 值闭集判据(wire 门用)。**宽臂一个都没有**:词表外的值 400 响亮拒 —— 这一位选的是批准之后
+/** [ref] 值闭集判据(wire 门用)。**宽臂一个都没有**:词表外的值 400 响亮拒 —— 这一位选的是批准之后
  *  模型有没有手,把一个拼错的词折成任何一档都是安全轴上的静默降级([ref]「无静默 fail-open」)。 */
 export declare function isPlanApprovePermissionModeAfter(raw: unknown): raw is PlanApprovePermissionModeAfter;
 /**
@@ -130,7 +130,7 @@ export declare function stampEntryPermissionMode<B extends {
     readonly entry: EntryPermissionMode;
 };
 /**
- * S-433 —— **一条已持久化的提交体的生效 permission mode**,单点。
+ * [ref] —— **一条已持久化的提交体的生效 permission mode**,单点。
  *
  * 它只是把 {@link effectivePermissionMode} 与「拿哪一份 settings 去问」这**一对**绑在一起:后者是
  * `parseTaskSettings(body.settings)`(resume 重放共用的宽容解析层)。两处各写一遍这一对,就会在
@@ -161,7 +161,7 @@ export declare function effectivePermissionMode(body: {
     permissionMode?: unknown;
 }, settings: ParsedTaskSettings | undefined): PermissionMode | undefined;
 /**
- * S-346 —— [ref] 技能清单预算两旋钮的**值域谓词**(一对具名单铸点)。
+ * [ref] —— [ref] 技能清单预算两旋钮的**值域谓词**(一对具名单铸点)。
  *
  * 两层同问这一只:FRESH 提交面的 400 门(`http/server.ts`)问「合不合法」,RESUME 宽容层
  * ({@link parseTaskSettings})问「收不收下」—— 这两句话在这两个键上是**同一个问题的正反面**
@@ -204,7 +204,7 @@ export interface ParsedTaskSettings {
     /** `settings.env` → per-task shell env. core deliberately keeps NO
      *  `TaskSpec.env` (an untrusted caller must not swap the sandbox — [ref] §7 Q4); per-session shell env rides
      *  the TRUSTED `executionEnvFactory` seam (`shellEnv`) instead. [ref] "env = capability axis": HONORED only on
-     *  the single-user host lane (`cwdHonored`), IGNORED on any cloud/multi-tenant lane. Parsed here; gated at apply. */
+     *  the lanes of deployment-shape row `callerCwd` (single-user host, or device), IGNORED on any cloud/multi-tenant lane. Parsed here; gated at apply. */
     shellEnv?: Record<string, string>;
     /** L2 ultracode preset ([ref]): a CC-parity `settings.ultracode` boolean that EXPANDS to the two existing
      *  orthogonal axes — `thinking:"max"` (the reasoning axis) + `selfOrchestration:true` (the orchestration axis,
@@ -221,7 +221,7 @@ export interface ParsedTaskSettings {
     skillListingBudgetFraction?: number;
     /** 同族第二键:每条技能描述在清单里的字符帽(正整数;CC 默认 1536)。超出由引擎**截断**,不是拒。 */
     skillListingMaxDescChars?: number;
-    /** S-1351 —— 「只收紧」座位族(`tighten-only-seats.ts` 的四座:读拒模式 / 写保护名的加法 / 合规额外禁项 / 永不自动放行名单)的归一值,**一个键**而不是四个散字段:
+    /** [ref] —— 「只收紧」座位族(`tighten-only-seats.ts` 的四座:读拒模式 / 写保护名的加法 / 合规额外禁项 / 永不自动放行名单)的归一值,**一个键**而不是四个散字段:
      *  wire 位置由座位表说(三座在 `settings` 顶层,`neverAuto` 在 `settings.permissions`),解析后与位置无关。空数组 ≡ 缺席(不铸键)。
      *  去处:三座经 {@link applyTaskSettings} 落 core 任务层席;`neverAuto` 经 {@link deriveSettingsPolicy} 落请求叶策略。 */
     tightenOnly?: TightenOnlySeatValues;
@@ -282,24 +282,28 @@ export interface SettingsPermissionBucketIssue {
 export declare function settingsPermissionBucketIssue(perms: unknown): SettingsPermissionBucketIssue | null;
 /** 本 service 真正**消费**的 `settings` 顶层键 —— 闭集。每一个都有消费点:
  *  `env`/`hooks`/`model`/`outputStyle`/`permissions`/`ultracode` 与两个 `skillListing*` 在
- *  {@link parseTaskSettings};`webSearch` 在 `capabilities/scenarios.ts`(判决 `judgeRequestWebSearch`,单用户闸;形错在受理面 400,S-199)。
+ *  {@link parseTaskSettings};`webSearch` 在 `capabilities/scenarios.ts`(判决 `judgeRequestWebSearch`,单用户闸;形错在受理面 400,[ref])。
  *  加键必须同时加消费点,否则就是往闭集里塞一个新的静默丢。
  *
- *  🔴 `readDenyPatterns` / `writeProtectedExtra` / `complianceAdditionalDenies` 与 `permissions.neverAuto`(S-1351)= **「只收紧」座位族**:消费点 = `tighten-only-seats.ts`
+ *  🔴 `readDenyPatterns` / `writeProtectedExtra` / `complianceAdditionalDenies` 与 `permissions.neverAuto`([ref])= **「只收紧」座位族**:消费点 = `tighten-only-seats.ts`
  *  的座位表(位置、条目律、去处都由那张表说),读入在 {@link parseTaskSettings},投影在 {@link applyTaskSettings} / {@link deriveSettingsPolicy}。这四个键不是 CC settings 键
  *  (sdk 的 `SemaSettings` 尚未声明 —— 对账门 `test/task-settings-sdk-key-parity.test.ts` 的「server 先于 sdk」登记表记着它们)。
  *
+ *  🔴 `approvalFrameFamilies`([ref])= 这条 run 的客户端**声明**渲染得了哪些审批开卡帧族 —— 不进引擎,不是 CC settings 键。消费点 = 三条执行腿的审批装配
+ *  (`tool-approval.ts` 的唯一读者 `declaredApprovalFrameFamilies` → `resolveApprovalLeg`),判官 `approvalFrameFamiliesIssue`(fresh 受理 400 与宽容读者同一只)。
+ *  `parseTaskSettings` 刻意不读它(它管的是落到 `TaskSpec` 的设置)。sdk 型面待声明(对账门的「server 先于 sdk」登记表记着)。
+ *
  *  🔴 两个 `skillListing*`([ref],7.77.0)= **CC settings 同名键**,值域抄 CC 的 schema 声明
  *  (`skillListingBudgetFraction` 是 `gt(0).lte(1)`、`skillListingMaxDescChars` 是 `int().positive()`);
  *  消费点 = 本文件的 parse + `boot/resolve-spec.ts` 的 `TaskSpec` 透传。语义(预算怎么花、描述怎么裁、
  *  溢出怎么退成 name-only)整个归引擎,本仓一个字节都不渲染,也**不复刻默认值**——缺席即整键不写。 */
-export declare const TASK_SETTINGS_KEYS: readonly ["complianceAdditionalDenies", "env", "hooks", "model", "outputStyle", "permissions", "readDenyPatterns", "skillListingBudgetFraction", "skillListingMaxDescChars", "ultracode", "webSearch", "writeProtectedExtra"];
+export declare const TASK_SETTINGS_KEYS: readonly ["approvalFrameFamilies", "complianceAdditionalDenies", "env", "hooks", "model", "outputStyle", "permissions", "readDenyPatterns", "skillListingBudgetFraction", "skillListingMaxDescChars", "ultracode", "webSearch", "writeProtectedExtra"];
 /** 本 service 消费的 `settings.permissions` 子键 —— 闭集(值形校验另有既有门,本门只判键名)。 */
 export declare const TASK_SETTINGS_PERMISSION_KEYS: readonly ["allow", "ask", "defaultMode", "deny", "disableAutoMode", "neverAuto"];
 /** CC/SDK 合约里合法、本 service **不接线**的顶层键。词表外的 CC 键落 `unknown` —— 两列都是 400,标签只影响
  *  文案,不影响判决。前三个的出处 = `@sema-agent/sdk` `SemaSettings` 尾注逐字点名的 deferred CC 键。
  *
- *  🔴 `crossSessionInbound` / `dialogExpiry`(S-111)为什么在**这一列**而不是受理列:它们是**每会话**的
+ *  🔴 `crossSessionInbound` / `dialogExpiry`([ref])为什么在**这一列**而不是受理列:它们是**每会话**的
  *  保护型设置(`refuse` = 本会话退出入站跨会话车道),而引擎只给了**部署级**座位(一个 Runner 单例,
  *  getter 无会话上下文)。受理它们只能做到「解析 + 记一行运维日志」——调用方拿到 202、以为自己的
  *  opt-out 生效了,而实际没有任何 per-session 生效点。**在保护型配置上,「受理但不执行」比「响亮拒」
@@ -325,8 +329,20 @@ export declare const TASK_SETTINGS_UNSUPPORTED_PERMISSION_KEYS: readonly ["addit
  */
 export declare function taskSettingsKeyIssue(raw: unknown): KeyClosureIssue | null;
 /**
- * 🔒 **`settings.hooks` 会不会被采纳** —— 全仓**唯一**的车道谓词(S-995,主会话裁):hook 命令跑在 WORKER HOST([ref] class ② 能力授予),所以只有单用户车道
- * (`requirePrincipal !== true`,与 scheduler / backgroundShell / lspHost / MCP 注入同一姿势)采纳;多租户车道收到 hooks **整只忽略**(`task_hooks_ignored`),绝不执行。
+ * FRESH 提交面 `settings.hooks` 子树的键闭集裁决 —— 键闭集门的**第三个实例**(类与另两个实例见 `request-key-closure.ts` 头注;判决、机器面、文案骨架同一只):
+ * 一只匹配组 / 一个条目上**读者不携带**的键 ⇒ 返回拒体(调用方 400 `request.body_shape`);全部携带 ⇒ `null`。
+ *
+ * 词表 = **读者自己的答案**:`config` 是同一份 `raw` 经 {@link parseHooksConfig} 受理的产物,一只组 / 一个条目受理的键 = 可跑形在同一坐标上那只对象的键
+ * (契约分类器携带的字段 + 本仓 wire 键:组的 `source`、command 条目的 `plugin` / `args`)。本函数不另立键表 —— 契约给某一型加字段、分类器开始携带它,这里随之受理;
+ * 受理 ⇒ 分类器答 `loaded` ⇒ 组与条目的下标与原值逐位对齐。值为 `undefined` 的键与缺席同读(读者同一口径)。坐标经 {@link hooksCoordinate}(契约包出门形 + 回显口径;凭据形键段不原样回显)。
+ *
+ * 判据边界(与另两个实例同):只判**键名**(值形归读者);拒只在 FRESH 提交面 —— 续跑重放走 {@link parseTaskSettings},读者照旧剥掉它不携带的键,存量体按受理时的读法重放(4xx 打在重放腿上会砖死停驻任务)。
+ * 为什么必须拒:一只被剥掉的键对调用方读作「生效了」—— 守卫条目上的 `onFailure: "block"` 被剥掉,守卫起不来时照放行;`plugin` / `args` 写在 http 条目上被剥掉,写的人以为插件上下文在。
+ */
+export declare function hooksKeyIssue(raw: unknown, config: RunnableHooksConfig): KeyClosureIssue | null;
+/**
+ * 🔒 **`settings.hooks` 会不会被采纳** —— 全仓**唯一**的属主([ref],主会话裁):hook 命令跑在 WORKER HOST([ref] class ② 能力授予),所以只有单主部署
+ * (部署形表行 `multiTenant` 不成立,与 scheduler / backgroundShell / lspHost / MCP 注入同一姿势)采纳;多租户车道收到 hooks **整只忽略**(`task_hooks_ignored`),绝不执行。
  * 三处读它,谁也不许内联 `requirePrincipal`(各写各的 = 迟早漂):
  *  · `boot/resolve-spec.ts` —— 装配:不采纳 ⇒ 不铸 `TaskSpec.mods` 的 `settings.hooks` 注册 + 一条 `task_hooks_ignored`;
  *  · `http/routes/capabilities.ts` —— 能力位 `taskSettings.hooks`(「says yes ⟺ route works」);
@@ -377,29 +393,29 @@ export interface WorkflowGateWiring {
  */
 export interface FsWriteGateWiring {
     /**
-     * 🔴 S-177 / codex r1 [high](验真后修)—— **权限规则**的路径基(core `PathRuleBases.root`),**只在真任务根已知时**在场。
+     * 🔴 [ref] / codex r1 [high](验真后修)—— **权限规则**的路径基(core `PathRuleBases.root`),**只在真任务根已知时**在场。
      *
      * host 腿上「这条 session 还没登记工作目录」时,`resolve-spec` 的路径裁决 env 落在一个**永不创建的哨兵目录**上
      * (`fs-write-gate-unrooted`,治理层守卫集的 cwd)。那对守卫是 fail-SAFE 的(相对目标在哨兵下解析不出真身);但规则编译器按**词法**匹配、
      * 不问目录存不存在 ⇒ 把哨兵当根递进来,`deny Edit(src/**)` 会编译成功、指向一个谁也不会写的目录,对真实工作区的
      * `<工作区>/src/secret.ts` 判 allow —— 一条亲手写下的收紧规则**静默失效**。所以哨兵从不被声明成基。
      *
-     * 缺席 ⇒ 不声明根 ⇒ 需要该基的拼法(`Edit(src/**)` / `Edit(/etc/**)`)锚在**装入这只策略的那条腿**的真根(core 7.46.0 #1383 车 B:
+     * 缺席 ⇒ 不声明根 ⇒ 需要该基的拼法(`Edit(src/**)` / `Edit(/etc/**)`)锚在**装入这只策略的那条腿**的真根(core 7.46.0 [ref] 车 B:
      * 锚装一次、在被装入处;`unsupported.path_base` 只剩「声明了一个用不了的基」)。修前(core ≤7.45)缺席 ⇒ 整表拒(→ 422):沙箱车道上
      * 相对 / `/x` 形规则恒 422。绝对形(`//abs`)不需要基;`~/` 形见下一字段。
      */
     taskRoot?: string;
     /**
-     * 🔴 S-177 / codex r2 [high](验真后修)—— **执行环境的 home**(core `PathRuleBases.home`,`~/…` 形的基)。
+     * 🔴 [ref] / codex r2 [high](验真后修)—— **执行环境的 home**(core `PathRuleBases.home`,`~/…` 形的基)。
      *
-     * 🔴 **S-213④ 起本字段在远端车道上也可以有值**:四只远端 adapter 此前一个都不声明 `ExecutionEnv.homeDir`,
+     * 🔴 **[ref]④ 起本字段在远端车道上也可以有值**:四只远端 adapter 此前一个都不声明 `ExecutionEnv.homeDir`,
      * 而本字段那时只在 `remoteExec` 整个缺席时才铸 —— 于是**每一条远端部署的 `~/` 规则都恒 422**(接入审计
      * M13)。修法不是放松下面那道门,而是让部署**真的知道** home:`execution-lane-caps.ts` 的
      * `executionLaneHomeDir` 是唯一属主,`boot/execution-env.ts` 把它递给 adapter 的 `homeDir` 座、
      * `boot/resolve-spec.ts` / `boot/parked-revive-gate.ts` 把**同一个值**递成本字段。两处同源是承重的:
      * 各算一份就会出现「422 门放行而引擎判 unreadable」或反过来。
      *
-     * 🔴 **S-213⑦ 改真话**(亲读 core 7.12.0 `dist/core/permission-rule-model.js` /
+     * 🔴 **[ref]⑦ 改真话**(亲读 core 7.12.0 `dist/core/permission-rule-model.js` /
      * 的 `resolvePathPattern`,推翻本注此前的两句):
      *  · core 对缺席的 `home` **不**回落 `os.homedir()` —— `resolvePathPattern` 走
      *    `lexicalNormalAbsolutePathOf(baseValueOf("home", bases) ?? "")`,base 缺席 ⇒ `undefined` ⇒ 直接回