@sema-agent/server 7.134.0 → 7.136.0

package/dist/task-mcp.js

@@ -1,11 +1,14 @@
 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 { MCP_CONTENT_ORIGINS, describeBadContentOrigin, describeNotStringArray, describeValueShape, findUrlCredential, isContentOriginWord, isStringArray, isUsableWireName, readRequestMcpTransport, stripControlAndBidi, } from "@sema-agent/settings-schema";
+import { HttpError } 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 { readRequestToolAxes } from "./request-tool-axes.js";
+import { urlCredentialHeaderExit, urlCredentialRefusalReason } from "./url-credential-refusal.js";
+import { MALFORMED_NAME, declarationFieldRefusal, declarationNameIssue, declaredName, judgeDeclarationKeys, requestDeclarationRefusal, throwDeclarationRefusal, } from "./request-declaration-refusal.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 +19,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);
@@ -25,12 +28,6 @@ function isElicitationFlag(v) {
     return typeof v === "boolean";
 }
 const bad = (field) => ({ ok: false, field });
-const MALFORMED_NAME = "<malformed>";
-function declaredName(e) {
-    return e && typeof e === "object" && typeof e.name === "string" && e.name !== ""
-        ? String(e.name)
-        : MALFORMED_NAME;
-}
 function normalizeServer(e, noteBadOrigin, storedToolAxes) {
     if (!e || typeof e !== "object")
         return bad("entry");
@@ -131,32 +128,21 @@ function requestEntryIdentityRefusal(entry, at) {
         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) });
+    return declarationFieldRefusal(MCP_SEAT, entry, at, { path: "transport.assertionHeader", reason: describeMcpAssertionHeaderNotAString(value) });
 }
 export function requestMcpDeclarationRefusal(list) {
-    if (list === undefined || list === null)
-        return undefined;
-    if (!Array.isArray(list))
-        return listRefusal(`mcpServers is ${describeValueShape(list)}, not an array of MCP server declarations`);
-    if (list.length > MAX_REQUEST_MCP_SERVERS)
-        return listRefusal(`mcpServers carries ${list.length} declarations, above this deployment's ceiling of ${MAX_REQUEST_MCP_SERVERS}`);
-    for (let i = 0; i < list.length; i++) {
-        const refusal = requestEntryRefusal(list[i], `mcpServers[${i}]`);
-        if (refusal !== undefined)
-            return refusal;
-    }
-    return undefined;
+    return requestDeclarationRefusal(MCP_SEAT, list, requestEntryRefusal);
 }
 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] });
-}
-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).";
-function listRefusal(head) {
-    return { errorCode: "request.field_invalid", message: `${head}. ${LIST_REFUSAL_TAIL}` };
+    throwDeclarationRefusal(requestMcpDeclarationRefusal(bodyMcp));
 }
+const MCP_SEAT = {
+    list: "mcpServers",
+    cap: MAX_REQUEST_MCP_SERVERS,
+    subject: "server",
+    declaration: "an MCP server declaration",
+    declarations: "MCP server declarations",
+};
 const ENTRY_KEY_SET = new Set(MCP_SERVER_ENTRY_KEYS);
 const STDIO_TRANSPORT_KEY_SET = new Set(STDIO_MCP_TRANSPORT_KEYS);
 const HTTP_TRANSPORT_KEY_SET = new Set(HTTP_MCP_TRANSPORT_KEYS);
@@ -172,6 +158,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
@@ -184,7 +176,7 @@ const ENTRY_KEY_JUDGES = {
                 ` (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 ${describeValueShape(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)}` }),
+    name: declarationNameIssue,
     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)}` },
@@ -211,21 +203,14 @@ const ENTRY_KEY_JUDGES = {
     },
     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. " +
-    "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 — ${stripControlAndBidi(issue.reason)}. ${ENTRY_REFUSAL_TAIL}`,
-    };
-}
 function requestEntryRefusal(entry, at) {
-    if (!isRecord(entry))
-        return listRefusal(`${at} is ${describeValueShape(entry)}, not an MCP server declaration (an object)`);
     const unknownKeys = entryUnknownKeys(entry, at);
     if (unknownKeys.length > 0) {
         return {
@@ -239,12 +224,7 @@ function requestEntryRefusal(entry, at) {
     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;
+    return judgeDeclarationKeys(MCP_SEAT, entry, at, MCP_SERVER_ENTRY_KEYS, ENTRY_KEY_JUDGES);
 }
 export function deploymentClosedMcpNames(baseline, reservedNames) {
     return new Set([...(baseline ?? []).map((s) => s.name), ...reservedNames]);

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,14 +282,14 @@ 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`(S-1914)= 这条 run 的客户端**声明**渲染得了哪些审批开卡帧族 —— 不进引擎,不是 CC settings 键。消费点 = 三条执行腿的审批装配
+ *  🔴 `approvalFrameFamilies`([ref])= 这条 run 的客户端**声明**渲染得了哪些审批开卡帧族 —— 不进引擎,不是 CC settings 键。消费点 = 三条执行腿的审批装配
  *  (`tool-approval.ts` 的唯一读者 `declaredApprovalFrameFamilies` → `resolveApprovalLeg`),判官 `approvalFrameFamiliesIssue`(fresh 受理 400 与宽容读者同一只)。
  *  `parseTaskSettings` 刻意不读它(它管的是落到 `TaskSpec` 的设置)。sdk 型面待声明(对账门的「server 先于 sdk」登记表记着)。
  *
@@ -303,7 +303,7 @@ export declare const TASK_SETTINGS_PERMISSION_KEYS: readonly ["allow", "ask", "d
 /** 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 生效点。**在保护型配置上,「受理但不执行」比「响亮拒」
@@ -329,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」);
@@ -381,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` ⇒ 直接回

package/dist/task-settings.js

@@ -1,17 +1,19 @@
 import { combinePolicies, parseRuleText, resolveReasoningProfile, rankOf, isThinkingLevel, RUN_WORKFLOW_TOOL_NAME, PERMISSION_MODES, isPermissionMode, ruleToolGrammarOf, } from "@sema-agent/core";
 import { judgeUnmatchableToolNames } from "./config.js";
+import { NAME_TABLE_BEHAVIOR } from "./namespaced-rule-name.js";
 import { entryProblem } from "./entry-problems.js";
 import { MAX_PERMISSION_RULES_PER_LIST, createRuleListPolicy } from "./permission-rule-list.js";
 import { allowLayerEntryCountIssue, describeAllowLayerOverCap, ruleEntryListShapeOk } from "./rule-entry-list.js";
 import { limitRefusal } from "./limit-refusal.js";
 import { tightenGoverned } from "./governance-overrides.js";
 import { MAX_KEY_ECHO, keyClosureClause, scanKeyClosure } from "./request-key-closure.js";
-import { parseHooksConfig } from "./hooks/hook-runner.js";
+import { hooksCoordinate, parseHooksConfig } from "./hooks/hook-runner.js";
 import { heldRuleName } from "./tool-rule-names.js";
 import { entryPermissionMode } from "./runtime-governance.js";
 import { policyAskStandingAnswerFacts, standingAnswerDurablyRecordable } from "./tool-approval.js";
 import { createRequestNeverAutoPolicy } from "./approval.js";
 import { readTightenOnlySeats, tightenOnlySeatField, tightenOnlySpecSeats } from "./tighten-only-seats.js";
+import { DEPLOYMENT_SHAPE_PREDICATES } from "./deployment-shape.js";
 export const PERMISSION_MODE_WORDS = PERMISSION_MODES.map((m) => `"${m}"`).join(" | ");
 export function coercePermissionMode(raw) {
     const strict = coercePermissionModeStrict(raw);
@@ -191,8 +193,36 @@ export function taskSettingsKeyIssue(raw) {
         unsupportedKeys: unsupported.slice(0, MAX_KEY_ECHO),
     };
 }
+export function hooksKeyIssue(raw, config) {
+    const unknown = [];
+    const member = (node, key) => node !== null && typeof node === "object" && Object.hasOwn(node, key) ? node[key] : undefined;
+    const scan = (rawNode, carried, at) => {
+        if (rawNode === null || typeof rawNode !== "object" || Array.isArray(rawNode))
+            return;
+        for (const [key, value] of Object.entries(rawNode))
+            if (value !== undefined && !Object.hasOwn(carried, key))
+                unknown.push(hooksCoordinate([...at, key]));
+    };
+    for (const [event, groups] of Object.entries(config)) {
+        for (const [groupIndex, group] of (groups ?? []).entries()) {
+            const rawGroup = member(member(raw, event), groupIndex);
+            scan(rawGroup, group, ["hooks", event, groupIndex]);
+            for (const [entryIndex, entry] of group.hooks.entries())
+                scan(member(member(rawGroup, "hooks"), entryIndex), entry, ["hooks", event, groupIndex, "hooks", entryIndex]);
+        }
+    }
+    if (unknown.length === 0)
+        return null;
+    unknown.sort();
+    const label = "unknown (not read on that matcher group or hook entry by this server — a misspelling, a key of another entry type (plugin / args are read on command entries only), or a hook key this server does not run)";
+    return {
+        message: `settings.hooks: unrecognized key(s) — refused rather than dropped, because a dropped key reads as "in effect" to the caller. ${keyClosureClause(unknown, label)}.`,
+        unknownKeys: unknown.slice(0, MAX_KEY_ECHO),
+        unsupportedKeys: [],
+    };
+}
 export function taskHooksHonored(config) {
-    return config.requirePrincipal !== true;
+    return !DEPLOYMENT_SHAPE_PREDICATES.multiTenant.holds(config);
 }
 function tightenOnlySeatDeferredName(name) {
     return tightenOnlySeatField(name).replace(/^settings\./, "");
@@ -384,7 +414,7 @@ export function deriveSettingsPolicy(settings, bases) {
 }
 export function neverAutoNamesRefusal(names) {
     const field = tightenOnlySeatField("neverAuto");
-    const judged = judgeUnmatchableToolNames(field.replace(/^settings\./, ""), names, { consumer: "tool-name-table", behavior: "deny" });
+    const judged = judgeUnmatchableToolNames(field.replace(/^settings\./, ""), names, { consumer: "tool-name-table", behavior: NAME_TABLE_BEHAVIOR });
     if (judged === undefined)
         return undefined;
     return { message: judged.message, problems: judged.bad.map((b) => entryProblem(SETTINGS_RULE_REFUSAL_CODE, field, b.name, b.reason)) };

package/dist/task-workflow.d.ts

@@ -1,27 +1,3 @@
-/**
- * Workflow super-set unlock — map the per-task `body.selfOrchestration` intent onto
- * `TaskSpec.selfOrchestration`, the gate that mounts core's LLM-authored `run_workflow` engine (the workflow.ts
- * agent/parallel/pipeline orchestrator). Same shape as the rank-1 roster gap: the engine (core run_workflow +
- * workflow.ts) is BUILT, but nothing mapped a body field to the per-task spec flag, so it was unreachable over HTTP
- * (capabilities advertised `workflows:true` but the LLM could never call run_workflow).
- *
- * Gating:
- *  - DEPLOYMENT: `selfOrchestrationEnabled` must be on (the workflowScriptRunner + stores are wired). Otherwise a set
- *    flag is a harmless no-op (core fail-closes run_workflow without the sandbox runner), so it's dropped for clarity.
- *  - MULTI-TENANT: honored ONLY when a per-principal entitlement RESOLVER is wired (`hasEntitlementResolver`). 🔴 core's
- *    `allowWorkflows` (RuntimeCaps) is TIGHTEN-ONLY — a resolver can only DENY; `undefined` = NO restriction, so the
- *    deployment capability governs. Therefore WITHOUT a resolver the engine would mount run_workflow UNGATED for every
- *    tenant. So we fail-closed here (defense-in-depth: a misconfigured multi-tenant deployment with no entitlement
- *    source must NOT leak the LLM-authored workflow engine). WITH a resolver, core enforces `allowWorkflows`
- *    per-principal (deny → fail-closed). Single-user (owns its own worker) honors directly. Three-gate: engine-can ∧
- *    center-may(allowWorkflows) ∧ shell-show.
- *
- * 🔴 [ref](2026-09-03):fail-closed 的**方向**从来是对的,错的是它**没人说**。多租户 + 无 entitlement 源
- * 的部署上,这条腿把 `body.selfOrchestration:true`(以及 `settings.ultracode` 展开出来的同一个意图)静默
- * 折成 `undefined`,而 `/v1/capabilities` 照报 `workflows:true` ⇒ 「壳显示支持、引擎按普通 run 跑」。修法
- * 是把部署级半场抽成下面的 {@link selfOrchestrationDenial}(能力位与准入**同一只**谓词),提交面在拒因
- * 在场时**响亮**拒(`routes` 的 501 `capability.self_orchestration_required`),不再静默折。
- */
 export declare function selfOrchestrationFromBody(body: {
     selfOrchestration?: unknown;
 }, config: SelfOrchestrationGateConfig, hasEntitlementResolver: boolean): true | undefined;

package/dist/task-workflow.js

@@ -1,3 +1,4 @@
+import { DEPLOYMENT_SHAPE_PREDICATES } from "./deployment-shape.js";
 export function selfOrchestrationFromBody(body, config, hasEntitlementResolver) {
     if (body.selfOrchestration !== true || config.selfOrchestrationEnabled !== true)
         return undefined;
@@ -15,7 +16,7 @@ export function enableForkFromBody(body, config, hasEntitlementResolver) {
         return false;
     if (body.enableFork === false)
         return false;
-    if (config.requirePrincipal !== true)
+    if (!DEPLOYMENT_SHAPE_PREDICATES.multiTenant.holds(config))
         return true;
     return hasEntitlementResolver;
 }

package/dist/terminal.d.ts

@@ -31,7 +31,7 @@ import { terminalProjection, type PausedCause, type TaskStatus, type TerminalCau
  */
 export declare function failureCodeOf(terminal: TerminalCause): string | undefined;
 /**
- * 本仓**对外机器码**的词法(S-548)。附录 A 那张表、core 的点名族(`limits.*` / `config.*` /
+ * 本仓**对外机器码**的词法([ref])。附录 A 那张表、core 的点名族(`limits.*` / `config.*` /
  * `resume_at.*` / `output.*` / brain 扁平码)、工具层自注册码 —— 全体成员都是这一形:**小写**的
  * `a-z0-9_`,用 `.` 分族。门 {@link OUTWARD_CODE_SHAPE} 在 `test/terminal-store-error-fold.test.ts`
  * 里对**目录里真有的每一个码**断言这条词法(判据由 catalog 机器派生,不是手抄的一张清单)。
@@ -40,7 +40,7 @@ export declare const OUTWARD_CODE_SHAPE: RegExp;
 /** 域外失败码的**唯一**落点(附录外的新码;原码进日志与 message,不丢)。 */
 export declare const STORE_ERROR_CODE = "internal.store_error";
 /**
- * 一个失败码要上 wire 之前的**归一**(S-548)。在词法内 ⇒ 原样;词法外 ⇒ {@link STORE_ERROR_CODE}。
+ * 一个失败码要上 wire 之前的**归一**([ref])。在词法内 ⇒ 原样;词法外 ⇒ {@link STORE_ERROR_CODE}。
  *
  * ── 病(test T-47,三库一致)────────────────────────────────────────────────────────────────────
  * 本仓的 SQL 店把**驱动原生错误**原样抛回引擎,而 core 的 `errorCodeOf` 沿 `err.code`/`cause` 链取
@@ -63,7 +63,7 @@ export declare function outwardFailureCode(code: string): string;
 /**
  * **一条结果离开引擎、进入本仓(可重放账本 / run 行 / wire)的唯一封口** —— 两件事,一个出口:
  *  ①摘掉**耐久恢复能力凭据**(`CheckpointToken`);②把**域外的失败码**折成本仓的 `internal.store_error`
- *  ({@link outwardFailureCode},S-548)。
+ *  ({@link outwardFailureCode},[ref])。
  *
  * 🔴 为什么两件事合在一只函数里而不是并列两只(7.92.2 改名 `stripResumeToken` → `sealResultForExit`):
  * 它们是**同一个出口上的同一件事** —— 「这条结果可以见人了吗」。并列两只 = 六个结算点各自要记得调两次,
@@ -92,12 +92,12 @@ export declare function sealResultForExit<T extends {
     terminal: TerminalCause;
 }>(result: T): T;
 /**
- * **投影出口的唯一属主**(S-548)—— core 的 `terminalProjection` + 对外码归一,一次。
+ * **投影出口的唯一属主**([ref])—— core 的 `terminalProjection` + 对外码归一,一次。
  *
  * `docs/ASSISTANT-WIRE-CONTRACT.md` §5.0 说清了终局有**两张脸**:①结果**本身**(`done.result` / 200 体 /
  * `GET /v1/runs/:id → result`,零投影)与②**五词投影**(run 行的 `status` / `error_code` 列、fleet 终态词、
  * 决策腿 200 体的三格平面词)。两张脸各有一个属主:①是 {@link sealResultForExit},②就是本函数。
- * **两个属主都折码**,否则同一次失败在两张脸上说两个不同的码 —— 而缺的那一张正是 S-548 修前仍在泄漏的
+ * **两个属主都折码**,否则同一次失败在两张脸上说两个不同的码 —— 而缺的那一张正是 [ref] 修前仍在泄漏的
  * 那条路(codex 对抗复审本轮 [medium],亲读证实:决策腿的 200 体从**未封口的** result 投影 `errorCode`,
  * 于是驱动原生码照旧上 wire,尽管同一段代码落库那份已经折过)。
  *

package/dist/tighten-only-seats.d.ts

@@ -16,7 +16,7 @@
  *  · **请求面没有放宽臂**:列表只能加行;送空、送别的行,部署的表一行不少。
  *  · **条目律借引擎的判官**(同一批 env 腿读的那几只:`compileReadDeny` / `resolveWriteProtectedTable` / `COMPLIANCE_CAPABILITIES`),宿主不自造第二份校验语义;读拒条目的元素文法 env / 中心 / 请求三腿同读
  *    `read-deny-entry.ts` 的那一只。受理面在 prepare 之前把坏形响亮拒掉(400),不让它变成 200 之后才失败的一跑。
- *  · 受理判据一处({@link tightenOnlySeatIssue}):不是数组 / 超帽 / 坏项 ⇒ 400 `request.field_invalid` + 机读位(`field` / `reason` / `count`+`cap` | `index`),与 S-904 三桶同形。
+ *  · 受理判据一处({@link tightenOnlySeatIssue}):不是数组 / 超帽 / 坏项 ⇒ 400 `request.field_invalid` + 机读位(`field` / `reason` / `count`+`cap` | `index`),与 [ref] 三桶同形。
  *    fresh 受理口、`resolveSpec`(两腿)、存体重放预判三处调这一只。
  *  · 座位表是闭集:加一座 = 加一行(`TIGHTEN_ONLY_SEAT_NAMES` 与表互为编译期穷举;`wire` 位置必须落在 `task-settings.ts` 的受理列里 —— 下面的编译期门)。
  *
@@ -93,13 +93,14 @@ interface SeatRow<E> {
     };
 }
 /**
- * 读拒模式的**成本单位 = 一颗 `*`**:引擎(core `compileSegmentPattern`)把每一颗 `*` 编成一个 `[^/]*`,相邻的星就是相邻的回溯点 ——
- * 一段里 k 颗 `*` 对长度 n 的路径段是 n 的 k 次方级回溯(实测 16 颗连续的星对 17 字的段 ≈ 4 s,跑在事件循环上、任何计时器打不断)。
- * 所以界按**调用方写下的每一颗**计,不按「连续的一串」计。整段 `**` / `id_rsa*` / `*.pem` / `*secret*` / `*_*_key` / `a**b` 都在内。
+ * 读拒模式的请求侧星号界:**一颗 `*` 算一颗**(调用方写下的每一颗都计,不按「连续的一串」计;整段 `**` / `id_rsa*` / `*.pem` / `*secret*` / `*_*_key` / `a**b` 都在内)。
+ *
+ * ⚠️ 这条界当初的理由(引擎把每一颗 `*` 编成一个 `[^/]*`,一段里 k 颗星对长度 n 的段是 n 的 k 次方级回溯)自引擎 7.55.0 起**不成立**:段匹配是 `*` glob,
+ * 没有从模式铸出来的表达式,代价至多是模式长度与段长的乘积、与星的个数和排布无关。所以界今天是**受理面的口径**(请求是不可信的写者),不再对应引擎里的某个成本 ——
+ * 拒句与契约都不再给「引擎回溯」这个理由。界本身退不退是放宽方向的另一件事,不在这里。
  */
 export declare const MAX_READ_DENY_STARS_PER_SEGMENT = 2;
-/** 整张 `readDenyPatterns` 列表的 `*` 总预算:引擎每次判路径对每条模式、每个路径段各跑一遍,一段 2 颗星是段长的平方 —— 总量只界住「乘几遍」(128 颗时 64 条的表对万字段 ≈ 3.9 s)。
- *  不是上界:16 颗的整表(8 条各 2 颗)对对手形的 4000 字段本机实测约 1 s、万字段约 5–6 s;段长的那一维只能在引擎里收(线性时间匹配或路径段长度上限,已向引擎请托)。 */
+/** 整张 `readDenyPatterns` 列表的 `*` 总预算(同一条受理口径,理由见 {@link MAX_READ_DENY_STARS_PER_SEGMENT}:星的个数不再对应引擎里的成本;条数与单条长度才是还在的两个成本维度)。 */
 export declare const MAX_READ_DENY_STARS_TOTAL = 16;
 /** 每座条数的缺省上限 —— 与 `settings.permissions` 三桶同一只帽(编译口的整表帽;超了响亮拒,不截)。读拒模式另有更紧的一只({@link MAX_READ_DENY_ENTRIES}),每座的帽写在座位表那一行。 */
 export declare const MAX_TIGHTEN_ONLY_SEAT_ENTRIES = 1000;

package/dist/tighten-only-seats.js

@@ -54,7 +54,7 @@ export const TIGHTEN_ONLY_SEATS = {
             }
             const stars = maxStarsPerSegment(read.entry.pattern);
             if (stars > MAX_READ_DENY_STARS_PER_SEGMENT) {
-                return { ok: false, after: ` has a path segment with ${stars} "*" wildcards — at most ${MAX_READ_DENY_STARS_PER_SEGMENT} per segment are accepted in a request, each "*" counted (the engine matches a segment by backtracking and the cost grows with each extra wildcard); merge them, or ask the operator to put the row in READ_DENY_PATTERNS` };
+                return { ok: false, after: ` has a path segment with ${stars} "*" wildcards — at most ${MAX_READ_DENY_STARS_PER_SEGMENT} per segment are accepted in a request, each "*" counted; merge them, or ask the operator to put the row in READ_DENY_PATTERNS` };
             }
             return { ok: true, value: read.entry };
         },