@sema-agent/server 7.78.0 → 7.78.2

package/dist/task-a2a.js

@@ -1,6 +1,8 @@
 import { resolveComplianceDenies } from "@sema-agent/core";
 import { isUsableWireName } from "./wire-name-bound.js";
 import { HttpError } from "./security.js";
+import { isToolAxisIrreversibility, isToolEffect } from "./tool-axis-words.js";
+import { GOVERNANCE_HTTP_STATUS } from "./governance-http-status.js";
 export const MAX_REQUEST_A2A_PEERS = 32;
 export function a2aInjectionHonored(config) {
     if (config.lockedConfigKeys?.includes("a2a") === true)
@@ -49,16 +51,16 @@ function normalizeA2aPeer(e) {
             if (!ax || typeof ax !== "object" || Array.isArray(ax))
                 return null;
             const a = ax;
-            if (a.effect !== undefined && a.effect !== "read" && a.effect !== "write" && a.effect !== "idempotent")
+            if (a.effect !== undefined && !isToolEffect(a.effect))
                 return null;
             if (a.egress !== undefined && typeof a.egress !== "boolean")
                 return null;
-            if (a.irreversibility !== undefined && a.irreversibility !== "always" && a.irreversibility !== "never")
+            if (a.irreversibility !== undefined && !isToolAxisIrreversibility(a.irreversibility))
                 return null;
             const entry = {
-                ...(a.effect !== undefined ? { effect: a.effect } : {}),
-                ...(a.egress !== undefined ? { egress: a.egress } : {}),
-                ...(a.irreversibility !== undefined ? { irreversibility: a.irreversibility } : {}),
+                ...(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[skill] = entry;
@@ -91,7 +93,7 @@ export function assertRequestA2aUnlocked(bodyA2a, lockedKeys) {
         return;
     if (bodyA2a === undefined || bodyA2a === null)
         return;
-    throw new HttpError(400, "`a2aPeers` is administratively locked by this deployment (locked key \"a2a\") — task-supplied A2A peers are refused; locks are config-time and there is no request-time unlock", {
+    throw new HttpError(GOVERNANCE_HTTP_STATUS["config.locked_key"], "`a2aPeers` is administratively locked by this deployment (locked key \"a2a\") — task-supplied A2A peers are refused; locks are config-time and there is no request-time unlock", {
         code: "config.locked_key",
     });
 }

package/dist/task-mcp.js

@@ -1,9 +1,11 @@
 import { mcpInjectionDroppedNotice, resolveComplianceDenies } from "@sema-agent/core";
 import { isUsableWireName } from "./wire-name-bound.js";
 import { HttpError } 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 { 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 function mcpInjectionHonored(config) {
@@ -72,9 +74,9 @@ function normalizeServer(e, noteBadOrigin) {
                 continue;
             const a = ax;
             const entry = {
-                ...(a.effect === "read" || a.effect === "write" || a.effect === "idempotent" ? { effect: a.effect } : {}),
+                ...(isToolEffect(a.effect) ? { effect: a.effect } : {}),
                 ...(typeof a.egress === "boolean" ? { egress: a.egress } : {}),
-                ...(a.irreversibility === "always" || a.irreversibility === "never" ? { irreversibility: a.irreversibility } : {}),
+                ...(isToolAxisIrreversibility(a.irreversibility) ? { irreversibility: a.irreversibility } : {}),
             };
             if (Object.keys(entry).length > 0)
                 axes[tool] = entry;
@@ -123,7 +125,7 @@ export function assertRequestMcpUnlocked(bodyMcp, lockedKeys) {
         return;
     if (bodyMcp === undefined || bodyMcp === null)
         return;
-    throw new HttpError(400, "`mcpServers` is administratively locked by this deployment (locked key \"mcp\") — task-supplied MCP servers are refused; locks are config-time and there is no request-time unlock", {
+    throw new HttpError(GOVERNANCE_HTTP_STATUS["config.locked_key"], "`mcpServers` is administratively locked by this deployment (locked key \"mcp\") — task-supplied MCP servers are refused; locks are config-time and there is no request-time unlock", {
         code: "config.locked_key",
     });
 }

package/dist/task-settings.d.ts

@@ -37,6 +37,7 @@
  */
 import { type ExecutionEnv, type TaskSpec, type ThinkingLevel, type ToolPolicy, type PromptProvider } from "@sema-agent/core";
 import type { HooksConfig } from "@sema-agent/settings-schema/hooks";
+import { type KeyClosureIssue } from "./request-key-closure.js";
 /** The permission MODE a client may request (SDK `SettingsPermissions.defaultMode`), the [ref]/[ref] five-word
  *  table. ⚠️ This is a DELIBERATE deployment set, NOT a copy of any CC set ([ref] P2-1 corpus check): CC's own
  *  full enum is SIX words (= ours + `dontAsk`), CC's managed/remote form accepts FOUR (= ours − `bypassPermissions`,
@@ -118,10 +119,40 @@ export declare function effectivePermissionMode(body: {
  * 把它折进来会逼出一个 `undefined` 返回值,而那正是「写 off」与「不写」被混同的入口(core 的
  * 缺席默认是 off,但**写**一个 off 会成为 governance 的 base,与缺席不是同一件事)。
  *
- * 🔴 **闭集 exhaustive switch,无 default 臂**:五个模式词是封闭词表,新增一个模式而不更新本表
+ * 🔴 **闭集穷举表,无 default 臂**:五个模式词是封闭词表,新增一个模式而不更新本表
  * 是**编译错误**([ref] 的安全轴纪律:词表的未知项不许有静默兜底臂)。
  */
 export declare function shellGateForMode(effMode: SettingsPermissionMode): "off" | "classify";
+/**
+ * [ref] —— 生效模式 → `TaskSpec.writeFace`(**写**面的 roots 容纳判断)。`"open"` = 工作区根之外也能写;
+ * `undefined` = **不写这个键**(core 缺省 `"roots"`,与 7.77.0 及以前逐字节相同)。表逐字在
+ * {@link MODE_ENGINE_FACES},裁定与硬边界写在 `resolve-spec.ts` 的写点上。
+ *
+ * 🔴 与 {@link shellGateForMode} 同律:入参非可选 —— 「表态缺席」不是这张表的一行(那是调用点判的
+ * 「整个键都不写」),把它折进来就会逼出第二个 `undefined` 语义。
+ */
+export declare function writeFaceForMode(effMode: SettingsPermissionMode): "open" | undefined;
+/**
+ * [ref] ① —— 生效模式 → `TaskSpec.autoModeRequested`(auto **意图**座,CC 250「用户开」半场)。
+ * `true` 只有 auto 一行;`undefined` = 不写键。表逐字在 {@link MODE_ENGINE_FACES}。
+ */
+export declare function autoModeRequestedForMode(effMode: SettingsPermissionMode): true | undefined;
+/**
+ * S-346 —— [ref] 技能清单预算两旋钮的**值域谓词**(一对具名单铸点)。
+ *
+ * 两层同问这一只:FRESH 提交面的 400 门(`http/server.ts`)问「合不合法」,RESUME 宽容层
+ * ({@link parseTaskSettings})问「收不收下」—— 这两句话在这两个键上是**同一个问题的正反面**
+ * (400 的条件恰是受理条件的否定)。修前它们各写一遍字面比较,而承重的两件事
+ * (`Number.isFinite` 挡 `NaN`/`Infinity`、`Number.isSafeInteger` 与引擎受理域**同字**)
+ * 靠两份注释各自记着 —— 任一处漏一个判据,同一个坏值就会在一条腿上 400、在另一条腿上被收下。
+ *
+ * 值域**抄 CC settings schema**,不自创;server 侧零加工(不夹紧、不换算、不复刻 core 的默认值),
+ * 判据全文见两个调用点的顶注。
+ */
+export declare function skillListingBudgetFractionOk(v: unknown): v is number;
+/** {@link skillListingBudgetFractionOk} 的孪生(`int().positive()`;`isSafeInteger` 而不是 `isInteger` 的
+ *  理由见那里)。 */
+export declare function skillListingMaxDescOk(v: unknown): v is number;
 /** The validated, service-trusted subset of `SemaSettings` we project onto the spec. `env` is parsed only to REPORT
  *  it as received-but-deferred when off the host lane (never silently dropped); a MALFORMED `hooks` likewise reports
  *  deferred (submit 路径另有 400 fail-loud),valid `hooks` 进 applied shape(hook-runner 阶段一)。 */
@@ -160,6 +191,13 @@ export interface ParsedTaskSettings {
      *  这里只 PARSE;应用点(main.ts resolveSpec)按单用户闸(`requirePrincipal !== true`)决定翻不翻成
      *  core `TaskSpec.hooks` 回调——多租户 lane 收到只警告忽略(hook 命令跑在 worker host = class ② 能力授予)。 */
     hooks?: HooksConfig;
+    /** [ref](7.77.0)—— CC settings 同名键:上下文窗口里**留给技能清单**的比例((0,1];CC 默认 0.01 = 1%)。
+     *  超预算时引擎把描述裁短、再不够退成 name-only(`cli259.js` 的清单渲染算法),**从不**拒掉一条技能 ——
+     *  这正是本版把技能条数/描述两条帽整条退役后的补偿面:per-turn 成本的旋钮在**渲染侧**,不在受理侧。
+     *  server 零加工透传到 `TaskSpec`,默认值属主是引擎(缺席 ⇒ 整键不写)。 */
+    skillListingBudgetFraction?: number;
+    /** 同族第二键:每条技能描述在清单里的字符帽(正整数;CC 默认 1536)。超出由引擎**截断**,不是拒。 */
+    skillListingMaxDescChars?: number;
 }
 /** The result of parsing an untrusted `body.settings`: the applied subset + the names of present-but-deferred
  *  fields (so the caller can log/advertise them — no silent drop). `null` settings ⇒ `{ settings: undefined }`. */
@@ -180,10 +218,15 @@ export declare const MAX_SETTINGS_ENV_VARS = 256;
 export declare const MAX_SETTINGS_ENV_VALUE_CHARS = 32768;
 export declare const MAX_SETTINGS_ENV_KEY_CHARS = 256;
 /** 本 service 真正**消费**的 `settings` 顶层键 —— 闭集。每一个都有消费点:
- *  `env`/`hooks`/`model`/`outputStyle`/`permissions`/`ultracode` 在 {@link parseTaskSettings};
- *  `webSearch` 在 `capabilities/scenarios.ts`(`webSearchConfigFromSettings`,单用户闸)。
- *  加键必须同时加消费点,否则就是往闭集里塞一个新的静默丢。 */
-export declare const TASK_SETTINGS_KEYS: readonly ["env", "hooks", "model", "outputStyle", "permissions", "ultracode", "webSearch"];
+ *  `env`/`hooks`/`model`/`outputStyle`/`permissions`/`ultracode` 与两个 `skillListing*` 在
+ *  {@link parseTaskSettings};`webSearch` 在 `capabilities/scenarios.ts`(`webSearchConfigFromSettings`,单用户闸)。
+ *  加键必须同时加消费点,否则就是往闭集里塞一个新的静默丢。
+ *
+ *  🔴 两个 `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 ["env", "hooks", "model", "outputStyle", "permissions", "skillListingBudgetFraction", "skillListingMaxDescChars", "ultracode", "webSearch"];
 /** 本 service 消费的 `settings.permissions` 子键 —— 闭集(值形校验另有既有门,本门只判键名)。 */
 export declare const TASK_SETTINGS_PERMISSION_KEYS: readonly ["allow", "ask", "defaultMode", "deny", "disableAutoMode"];
 /** CC/SDK 合约里合法、本 service **不接线**的顶层键。词表外的 CC 键落 `unknown` —— 两列都是 400,标签只影响
@@ -202,17 +245,6 @@ export declare const TASK_SETTINGS_UNSUPPORTED_KEYS: readonly ["apiKeyHelper", "
 /** 同上,`settings.permissions` 子层(出处 = SDK `SettingsPermissions` 的三个声明键)。
  *  `additionalDirectories` 有**同请求替代面**:顶层 `body.additionalDirectories`([ref],resolve-spec 真消费)。 */
 export declare const TASK_SETTINGS_UNSUPPORTED_PERMISSION_KEYS: readonly ["additionalDirectories", "disableBypassPermissionsMode"];
-/** 拒体里逐字回显的键名条数上限。键名原样回显(不猜语义),但**条数有界** —— 一个塞满键的体不许把 400 响应
- *  放大成流量面。超出部分只报数。 */
-export declare const MAX_SETTINGS_KEY_ECHO = 20;
-/** {@link taskSettingsKeyIssue} 的拒体:一句 wire 文案 + 两张分类键名表(消费端可机读,不必解析文案)。 */
-export interface TaskSettingsKeyIssue {
-    message: string;
-    /** 词表外的键(拼错/未来键),`settings.x` / `settings.permissions.x` 全路径形,已清洗+截断+排序+封顶。 */
-    unknownKeys: string[];
-    /** CC/SDK 合约合法但本 service 不接线的键,同形。 */
-    unsupportedKeys: string[];
-}
 /**
  * FRESH 提交面的 `settings` 键闭集裁决:顶层或 `permissions` 子层出现受理集之外的键 ⇒ 返回拒体(调用方 400
  * `request.body_shape`);全部受理 ⇒ `null`。
@@ -224,7 +256,7 @@ export interface TaskSettingsKeyIssue {
  *    「settings must be an object」/「settings.permissions must be an object」两道门,免得同一个体被两句话抢答。
  *  · `permissions: null` 是既有钉住的「容器缺席」形,照旧不咬。
  */
-export declare function taskSettingsKeyIssue(raw: unknown): TaskSettingsKeyIssue | null;
+export declare function taskSettingsKeyIssue(raw: unknown): KeyClosureIssue | null;
 /**
  * Validate an untrusted `body.settings` (raw `unknown` off the wire) into the service-trusted {@link
  * ParsedTaskSettings}. NEVER trusts the wire type — every field is shape-checked. `defaultMode` accepts the FIVE

package/dist/task-settings.js

@@ -1,6 +1,7 @@
 import { combinePolicies, createAllowDenyPolicy, createFsWriteGatePolicy, createPermissionRulePolicy, parseRuleText, tightenTaskSpec, resolveReasoningProfile, rankOf, isThinkingLevel, CYBER_RISK, URL_SAFETY, HARNESS_SECTION_ANCHOR, RUN_WORKFLOW_TOOL_NAME, ruleToolGrammarOf, } from "@sema-agent/core";
 import { findUnmatchableToolNames, formatUnmatchableToolNames } from "./config.js";
 import { CONTROL_AND_BIDI_STRIP_RE } from "./text-bidi.js";
+import { MAX_KEY_ECHO, keyClosureClause, scanKeyClosure } from "./request-key-closure.js";
 import { parseHooksConfig } from "./hooks/hook-runner.js";
 export function coercePermissionMode(raw) {
     const strict = coercePermissionModeStrict(raw);
@@ -34,15 +35,26 @@ export function effectivePermissionMode(body, settings) {
     return requested;
 }
 export function shellGateForMode(effMode) {
-    switch (effMode) {
-        case "bypassPermissions":
-            return "off";
-        case "auto":
-        case "default":
-        case "acceptEdits":
-        case "plan":
-            return "classify";
-    }
+    return MODE_ENGINE_FACES[effMode].shellGate;
+}
+const MODE_ENGINE_FACES = {
+    bypassPermissions: { shellGate: "off", writeFace: "open", autoModeRequested: undefined },
+    auto: { shellGate: "classify", writeFace: undefined, autoModeRequested: true },
+    default: { shellGate: "classify", writeFace: undefined, autoModeRequested: undefined },
+    acceptEdits: { shellGate: "classify", writeFace: undefined, autoModeRequested: undefined },
+    plan: { shellGate: "classify", writeFace: undefined, autoModeRequested: undefined },
+};
+export function writeFaceForMode(effMode) {
+    return MODE_ENGINE_FACES[effMode].writeFace;
+}
+export function autoModeRequestedForMode(effMode) {
+    return MODE_ENGINE_FACES[effMode].autoModeRequested;
+}
+export function skillListingBudgetFractionOk(v) {
+    return typeof v === "number" && Number.isFinite(v) && v > 0 && v <= 1;
+}
+export function skillListingMaxDescOk(v) {
+    return typeof v === "number" && Number.isSafeInteger(v) && v > 0;
 }
 export const MAX_SETTINGS_OUTPUT_STYLE_CHARS = 16_384;
 export const MAX_SETTINGS_PERMISSION_RULES = 1_000;
@@ -72,49 +84,31 @@ function cleanStringArray(v) {
     const out = v.filter((x) => typeof x === "string" && x.length > 0).slice(0, MAX_SETTINGS_PERMISSION_RULES);
     return out.length > 0 ? out : undefined;
 }
-export const TASK_SETTINGS_KEYS = ["env", "hooks", "model", "outputStyle", "permissions", "ultracode", "webSearch"];
+export const TASK_SETTINGS_KEYS = ["env", "hooks", "model", "outputStyle", "permissions", "skillListingBudgetFraction", "skillListingMaxDescChars", "ultracode", "webSearch"];
 export const TASK_SETTINGS_PERMISSION_KEYS = ["allow", "ask", "defaultMode", "deny", "disableAutoMode"];
 export const TASK_SETTINGS_UNSUPPORTED_KEYS = ["apiKeyHelper", "crossSessionInbound", "dialogExpiry", "sandbox", "statusLine"];
 export const TASK_SETTINGS_UNSUPPORTED_PERMISSION_KEYS = ["additionalDirectories", "disableBypassPermissionsMode"];
-export const MAX_SETTINGS_KEY_ECHO = 20;
-const MAX_SETTINGS_KEY_ECHO_CHARS = 64;
 const ACCEPTED_TOP = new Set(TASK_SETTINGS_KEYS);
 const ACCEPTED_PERM = new Set(TASK_SETTINGS_PERMISSION_KEYS);
 const UNSUPPORTED_TOP = new Set(TASK_SETTINGS_UNSUPPORTED_KEYS);
 const UNSUPPORTED_PERM = new Set(TASK_SETTINGS_UNSUPPORTED_PERMISSION_KEYS);
-function echoSettingsKey(prefix, key) {
-    const clean = key.replace(CONTROL_AND_BIDI_STRIP_RE, "");
-    return `${prefix}${clean.length > MAX_SETTINGS_KEY_ECHO_CHARS ? `${clean.slice(0, MAX_SETTINGS_KEY_ECHO_CHARS)}…` : clean}`;
-}
 export function taskSettingsKeyIssue(raw) {
     if (raw === null || raw === undefined || typeof raw !== "object" || Array.isArray(raw))
         return null;
-    const unknown = [];
-    const unsupported = [];
-    const scan = (bag, prefix, accepted, tolerated) => {
-        for (const k of Object.keys(bag)) {
-            if (accepted.has(k))
-                continue;
-            (tolerated.has(k) ? unsupported : unknown).push(echoSettingsKey(prefix, k));
-        }
-    };
-    scan(raw, "settings.", ACCEPTED_TOP, UNSUPPORTED_TOP);
+    const buckets = { unknown: [], unsupported: [] };
+    scanKeyClosure(raw, "settings.", ACCEPTED_TOP, UNSUPPORTED_TOP, buckets);
     const perms = raw.permissions;
     if (perms !== null && typeof perms === "object" && !Array.isArray(perms)) {
-        scan(perms, "settings.permissions.", ACCEPTED_PERM, UNSUPPORTED_PERM);
+        scanKeyClosure(perms, "settings.permissions.", ACCEPTED_PERM, UNSUPPORTED_PERM, buckets);
     }
+    const { unknown, unsupported } = buckets;
     if (unknown.length === 0 && unsupported.length === 0)
         return null;
     unknown.sort();
     unsupported.sort();
-    const clause = (names, label) => {
-        const shown = names.slice(0, MAX_SETTINGS_KEY_ECHO);
-        const more = names.length - shown.length;
-        return `${label}: ${shown.join(", ")}${more > 0 ? ` (+${more} more)` : ""}`;
-    };
     const parts = [
-        ...(unknown.length > 0 ? [clause(unknown, "unknown (not a settings key here — check the spelling)")] : []),
-        ...(unsupported.length > 0 ? [clause(unsupported, "unsupported (a CC settings key this service does not wire)")] : []),
+        ...(unknown.length > 0 ? [keyClosureClause(unknown, "unknown (not a settings key here — check the spelling)")] : []),
+        ...(unsupported.length > 0 ? [keyClosureClause(unsupported, "unsupported (a CC settings key this service does not wire)")] : []),
     ];
     const dirHint = unsupported.some((n) => n.endsWith(".additionalDirectories"))
         ? " Extra directories ride the top-level body.additionalDirectories instead."
@@ -123,8 +117,8 @@ export function taskSettingsKeyIssue(raw) {
         message: `settings: unrecognized key(s) — refused rather than dropped, because a dropped key reads as "in effect" to the caller. ` +
             `${parts.join("; ")}.${dirHint} ` +
             `Accepted: settings.{${[...TASK_SETTINGS_KEYS].join(",")}} and settings.permissions.{${[...TASK_SETTINGS_PERMISSION_KEYS].join(",")}}`,
-        unknownKeys: unknown.slice(0, MAX_SETTINGS_KEY_ECHO),
-        unsupportedKeys: unsupported.slice(0, MAX_SETTINGS_KEY_ECHO),
+        unknownKeys: unknown.slice(0, MAX_KEY_ECHO),
+        unsupportedKeys: unsupported.slice(0, MAX_KEY_ECHO),
     };
 }
 export function parseTaskSettings(raw) {
@@ -178,8 +172,13 @@ export function parseTaskSettings(raw) {
         out.ultracode = true;
     if (hooksConfig)
         out.hooks = hooksConfig;
-    const hasApplied = out.permissions !== undefined || out.model !== undefined || out.outputStyle !== undefined || out.shellEnv !== undefined || out.ultracode !== undefined || out.hooks !== undefined;
-    return { settings: hasApplied ? out : undefined, deferred };
+    const fraction = s.skillListingBudgetFraction;
+    if (skillListingBudgetFractionOk(fraction))
+        out.skillListingBudgetFraction = fraction;
+    const maxDesc = s.skillListingMaxDescChars;
+    if (skillListingMaxDescOk(maxDesc))
+        out.skillListingMaxDescChars = maxDesc;
+    return { settings: Object.keys(out).length > 0 ? out : undefined, deferred };
 }
 export function hasConstitutionAnchors(text) {
     return typeof text === "string" && text.includes(CYBER_RISK) && text.includes(URL_SAFETY) && text.includes(HARNESS_SECTION_ANCHOR);

package/dist/tool-approval.d.ts

@@ -1,5 +1,5 @@
 import type { IncomingMessage } from "node:http";
-import { type AskRequest, type AskOutcome, type RuleOffer } from "@sema-agent/core";
+import { type AskRequest, type AskOutcome, type ReadRootGrantCandidate, type RuleOffer } from "@sema-agent/core";
 import { type CardRulePersisted, type RuleConsentLane } from "./rules-consent.js";
 import { type DenialLimitFallback, type RuleOffersAbsence, type ApprovalRequestFrame, type ApprovalRevokeFrame, type RuleEvidenceProjection } from "./approval-card.js";
 import { type ApprovalAskStore } from "./plugins/approval-ask-store-sql.js";
@@ -169,6 +169,27 @@ export interface ToolApprovalFrame {
      * `GateDisposition.denied.cause`(`tool_end.gate` / `permissionDenied.gate`),ask 面自此没有这一位。
      */
     ruleStoreUnreadable?: string;
+    /**
+     * **[ref]**(core 7.19.0;**ADDITIVE**,`"tool_approval"` only)—— 这只**根外读** ask 的**清障目录**:
+     * 把 `dir` 加进本会话的读目录(壳侧既有的 `/add-dir` 口),同一条调用就不会再问。
+     *
+     * 🔴 **在场才读,永远不读缺席**。缺席不是「无计可施」:它同时覆盖敏感路径 deny 行(按模式判,加任何
+     * 根都不动它)、读边界压根读不懂的命令(heredoc / 换行 / 命令替换 / 参数当程序)、没展开的 glob、
+     * 递归遍历、以及每一只**不是**读边界提的 ask —— 7.18.0 及以前的**每**一只 ask 都是这一形。
+     *
+     * 🔴 **原样回传**(core 契约 `shell.read_boundary.grant_candidate_is_the_grant`):`dir` 是绝对、已做词法
+     * 折叠、用读边界自己的拼法写的串;**显示的串就是要加的串**。壳可以为了好看渲一个缩短形,回传必须是
+     * 本键里的原串。⇒ 本仓的姿势是「整只逐字带,或整只丢」,**绝不截**(见 `MAX_READ_ROOT_CANDIDATE_DIR`)。
+     *
+     * 🔴 **echo-only,零判读**:server 不从命令文本重推目录,也不复核它真不真能清掉这只 ask —— core 已经
+     * 把提议的根放回读边界又走了一遍才递出来,下游再判一遍就是同一事实的第二个判官(与 `origin` /
+     * `ruleStoreUnreadable` / `denialLimitFallback` 三条顶注的同一条禁令)。
+     *
+     * 🔴 **只此一面**:core 的负控逐字写着「the durable park row has no twin of this seat in this version」——
+     * 一只 PARKED 的根外读 ask 渲的仍是单独那张确认卡。所以 `card_json` / 耐久面**没有**这一座,本仓也不
+     * 自铸一个(自铸 = 同一事实的第二个源,而且那个源会在 park 兑现时说谎)。
+     */
+    readRootCandidate?: ReadRootGrantCandidate;
     /**
      * **E-14**([ref]② Trojan Source 族;**ADDITIVE**,`"tool_approval"` only)—— 这只 ask 的**工具输入**
      * (`AskRequest.args`)里含 bidi 控制符(LRM/RLM、嵌入/覆写、隔离符;字符类属主 `text-bidi.ts`)。
@@ -858,9 +879,20 @@ export declare class ToolApprovalCoordinator {
      * 残余 = 那类行的归因会记成 `routing_failure`(其实是政策 deny),归因精化登记为候件。
      */
     private unattendedOutcome;
+    /** 政策**读**口(不是终局铸口)—— 回答「这台部署把无人可答翻成 park 吗」。
+     *
+     *  🔴 与 {@link unattendedOutcome} 分家是 S-187 的一半:此前两件事共用一只方法,于是墓碑腿那次
+     *  纯粹的**政策查询**(`unattendedOutcome() !== false`)会和同一只 ask 的真终局各记一条遥测 ——
+     *  「一只 ask 一条线」当场不成立。读口不落日志,铸口落;谁也不兼职。 */
+    private get unattendedRoutesToPark();
     /** {@link unattendedOutcome} 的**公开**口:`windowZero` 的 immediate-unavailable 闭包长在装配层
-     *  (`http/routes/tasks.ts` 的 sync 腿),它必须与协调器内五臂读**同一个**旋钮值,而不是各算一遍。 */
-    unattendedAskOutcome(): "unavailable" | false;
+     *  (`http/routes/tasks.ts` 的 sync 腿),它必须与协调器内五臂读**同一个**旋钮值,而不是各算一遍。
+     *  出处随调用方给(那条腿知道自己是哪一只 ask)。 */
+    unattendedAskOutcome(site: {
+        taskId?: string;
+        owner?: string | null;
+        toolName?: string;
+    }): "unavailable" | false;
     /**
      * [ref] 车3 刀 3b —— [ref] §3.3 / 设计稿 §0 X-2 的**写侧准入门**。
      *

package/dist/tool-approval.js

@@ -8,7 +8,7 @@ import { approvalPayloadFingerprint } from "./plugins/approval-payload-fingerpri
 import { createLogger } from "./observability/logger.js";
 import { recordFailOpen } from "./observability/fail-open.js";
 import { deriveAskId, deriveBatchId, MAX_DECISION_NOTE_CHARS } from "./approval-ask-machine.js";
-import { ApprovalCardEnvelopeSchema, MAX_RULE_OFFERS, buildApprovalCard, buildApprovalCardEnvelope, buildApprovalRequestFrame, buildRevokeFrame, readDenialLimitFallback, readProbeCause, readRuleEvidence, readRuleOffersAbsence, RuleOfferRawSchema, backfillLegacyBatchMemberKind, screenUncoveredDetailSeat, } from "./approval-card.js";
+import { ApprovalCardEnvelopeSchema, MAX_RULE_OFFERS, buildApprovalCard, buildApprovalCardEnvelope, buildApprovalRequestFrame, buildRevokeFrame, readDenialLimitFallback, readProbeCause, readReadRootCandidate, readRuleEvidence, readRuleOffersAbsence, RuleOfferRawSchema, backfillLegacyBatchMemberKind, screenUncoveredDetailSeat, } from "./approval-card.js";
 import { projectAskTerminalClaimTruth } from "./plugins/approval-ask-store-sql.js";
 import { governanceAskMarksFor, runWithGovernanceAskScope } from "./governance-ask-marks.js";
 const defaultLogger = createLogger();
@@ -300,11 +300,29 @@ export class ToolApprovalCoordinator {
         this.parkTombstonePerPrincipalMax = opts?.parkTombstonePerPrincipalMax ?? DEFAULT_PARK_TOMBSTONE_PER_PRINCIPAL_MAX;
         this.askAudit = opts?.askAudit;
     }
-    unattendedOutcome() {
-        return this.unattendedPolicy === "deny" ? false : "unavailable";
+    unattendedOutcome(site) {
+        const outcome = this.unattendedPolicy === "deny" ? false : "unavailable";
+        defaultLogger.warn("approver_unavailable", {
+            arm: site.arm,
+            policy: this.unattendedPolicy,
+            outcome: outcome === false ? "deny" : "unavailable",
+            owner: site.owner ?? null,
+            taskId: site.taskId ?? null,
+            toolName: site.toolName ?? null,
+            reachability: site.reachability ?? null,
+        });
+        return outcome;
+    }
+    get unattendedRoutesToPark() {
+        return this.unattendedPolicy !== "deny";
     }
-    unattendedAskOutcome() {
-        return this.unattendedOutcome();
+    unattendedAskOutcome(site) {
+        return this.unattendedOutcome({
+            arm: "window_zero",
+            ...(site.taskId !== undefined ? { taskId: site.taskId } : {}),
+            ...(site.owner !== undefined && site.owner !== null ? { owner: site.owner } : {}),
+            ...(site.toolName !== undefined ? { toolName: site.toolName } : {}),
+        });
     }
     admit(taskId, owner) {
         if (!this.askStore)
@@ -758,7 +776,7 @@ export class ToolApprovalCoordinator {
     ask = async (req, signal) => {
         const ctx = this.als.getStore();
         if (!ctx)
-            return this.unattendedOutcome();
+            return this.unattendedOutcome({ arm: "no_run_context", toolName: req.toolName });
         return this.askBroadcast({
             taskId: ctx.taskId,
             owner: ctx.owner,
@@ -786,11 +804,9 @@ export class ToolApprovalCoordinator {
         const aliveCtxs = ctxs.filter((c) => !c.abortSignal?.aborted);
         const reachability = aliveCtxs.length === 0 ? "unreached" : "reachable";
         if (reachability === "unreached") {
-            const unattended = this.unattendedOutcome();
-            if (unattended === false)
-                return unattended;
-            if (!this.askStore)
-                return unattended;
+            if (!this.unattendedRoutesToPark || !this.askStore) {
+                return this.unattendedOutcome({ arm: "no_live_target", taskId: origin.taskId, ...(origin.owner !== null ? { owner: origin.owner } : {}), toolName: req.toolName, reachability });
+            }
         }
         const primary = aliveCtxs[0];
         const governanceForced = (this.governanceAskMarks ?? governanceAskMarksFor(this.streamKey(origin.owner, origin.sessionId, origin.taskId))).isMarked(req.toolCallId);
@@ -809,7 +825,7 @@ export class ToolApprovalCoordinator {
                 admitMaxPerTask: this.admitMaxPerTask,
                 admitMaxPerOwner: this.admitMaxPerOwner,
             });
-            return this.unattendedOutcome();
+            return this.unattendedOutcome({ arm: "admission_exhausted", taskId: origin.taskId, ...(origin.owner !== null ? { owner: origin.owner } : {}), toolName: req.toolName, reachability });
         }
         const id = uuidv7();
         const child = isChildAsk(req);
@@ -848,6 +864,7 @@ export class ToolApprovalCoordinator {
             ...((a) => (a !== undefined ? { ruleOffersAbsence: a } : {}))(readRuleOffersAbsence(req)),
             ...((f) => (f !== undefined ? { denialLimitFallback: f } : {}))(readDenialLimitFallback(req)),
             ...(typeof req.ruleStoreUnreadable === "string" && req.ruleStoreUnreadable.length > 0 ? { ruleStoreUnreadable: req.ruleStoreUnreadable } : {}),
+            ...((g) => (g !== undefined ? { readRootCandidate: g } : {}))(readReadRootCandidate(req)),
             ...((c) => (c !== undefined ? { probeCause: c } : {}))(readProbeCause(req)),
             ...((c) => (c !== undefined ? { ruleEvidence: c } : {}))(readRuleEvidence(req)),
             ...(bounded.omitted ? { argsOmitted: true } : { args: bounded.args }),
@@ -904,7 +921,9 @@ export class ToolApprovalCoordinator {
                 if (existingOrCreated.row.state !== "STREAM_PENDING") {
                     releaseAdmission();
                     const replayed = replayTerminalAskRow(existingOrCreated.row);
-                    return replayed === "unavailable" ? this.unattendedOutcome() : replayed;
+                    return replayed === "unavailable"
+                        ? this.unattendedOutcome({ arm: "replayed_parked", taskId: origin.taskId, ...(origin.owner !== null ? { owner: origin.owner } : {}), toolName: req.toolName, reachability })
+                        : replayed;
                 }
                 const persistedEnvelope = ApprovalCardEnvelopeSchema.safeParse(existingOrCreated.row.cardJson);
                 const maxMintableWindowMs = Math.max(effectiveWindowMs, this.unreachedTtlMs);
@@ -985,7 +1004,7 @@ export class ToolApprovalCoordinator {
                         voidAbandonedRow(lateEnsuredAskId);
                     if (reachability === "unreached") {
                         releaseAdmission();
-                        return this.unattendedOutcome();
+                        return this.unattendedOutcome({ arm: "unreached_no_row", taskId: origin.taskId, ...(origin.owner !== null ? { owner: origin.owner } : {}), toolName: req.toolName, reachability });
                     }
                 }
             }
@@ -1014,8 +1033,11 @@ export class ToolApprovalCoordinator {
             return false;
         };
         const shapeOutcome = (settled) => {
-            if (windowRouteUnavailable)
-                return this.unattendedOutcome() === false ? shapeDeny() : "unavailable";
+            if (windowRouteUnavailable) {
+                return this.unattendedOutcome({ arm: "window_expired", taskId: origin.taskId, ...(origin.owner !== null ? { owner: origin.owner } : {}), toolName: req.toolName, reachability }) === false
+                    ? shapeDeny()
+                    : "unavailable";
+            }
             if (settled.allowed) {
                 return settled.updatedInput !== undefined ? { allow: true, updatedInput: settled.updatedInput } : true;
             }
@@ -1032,7 +1054,7 @@ export class ToolApprovalCoordinator {
             for (const [sig, fn] of abortListeners)
                 sig.removeEventListener("abort", fn);
             this.pending.delete(id);
-            if (windowRouteUnavailable && askId !== undefined && batchId !== undefined && this.unattendedOutcome() !== false) {
+            if (windowRouteUnavailable && askId !== undefined && batchId !== undefined && this.unattendedRoutesToPark) {
                 this.recordParkTombstone(wireApprovalId, { kind: "park", askId, batchId, owner: origin.owner, parkedAtMs: Date.now() });
                 parkRouted = true;
             }
@@ -1456,11 +1478,11 @@ export class ToolApprovalCoordinator {
                 .catch(() => undefined);
         }
         if (emitFailed)
-            return this.unattendedOutcome();
+            return this.unattendedOutcome({ arm: "emit_failed", taskId: origin.taskId, ...(origin.owner !== null ? { owner: origin.owner } : {}), toolName: req.toolName, reachability });
         if (windowRouteUnavailable)
             return shapeOutcome(settled);
         if (!emitSettled && lastOutcome === "expired")
-            return this.unattendedOutcome();
+            return this.unattendedOutcome({ arm: "emit_unsettled", taskId: origin.taskId, ...(origin.owner !== null ? { owner: origin.owner } : {}), toolName: req.toolName, reachability });
         return shapeOutcome(settled);
     }
     respond(id, principal, body, httpReq) {

package/dist/tool-axis-words.d.ts

@@ -0,0 +1,30 @@
+/**
+ * S-249(DT-13)—— per-tool **风险轴覆写**的值域词表与谓词,**两面共用一份**。
+ *
+ * ## 病(修前)
+ * `task-mcp.ts` 与 `task-a2a.ts` 各自在请求腿上逐键校验同一个三成员结构
+ * (`effect` / `egress` / `irreversibility`),而两个**闭集词表**是**手抄的字面串**:四份字面量
+ * (两文件 × 两个词轴),没有一份钉在 core 的型上。后果不是「今天判错了」,而是**判据比声明窄**这件事
+ * 没有任何门看得见 —— core 哪天给 `ToolEffect` 加一个词(或把 `irreversibility` 的两词改成三词,它在
+ * `AskOrigin` 那一面**已经**是 `never|maybe|always` 三词了),两条请求腿会把那个**合法**的新词
+ * **静默剔除**(MCP 腿)或**整条 server 判假**(A2A 腿),而 tsc 一声不吭。
+ *
+ * ## 修法
+ * 词表留在本仓(运行期要它),但**两向钉死在 core 的型上**:core 加词 ⇒ 正向门红;本表留了一个 core
+ * 已经没有的词 ⇒ 反向门红。两个面共用**同一只**谓词,于是「什么算一个合法的轴值」在本仓只有一个答案。
+ *
+ * 🔴 **只管值域,不管处置**:两条腿对坏值的处置**刻意不同**(MCP = 丢这一键、留 server;A2A = 整条拒),
+ * 判据与理由各写在各自的调用点。合并处置会抹掉那条真实的分歧(MCP 的 `toolAxes` 有 server-hint 腿可折,
+ * A2A 收下的就是最终值),而分歧本身是裁定过的。
+ */
+import type { McpServerSpec, ToolEffect } from "@sema-agent/core";
+/** 一条 per-tool 轴覆写的形。取 MCP 那一面作代表 —— 下面的同型钉证明两面逐字同声明。 */
+export type ToolAxisEntry = NonNullable<McpServerSpec["toolAxes"]>[string];
+/** 轴覆写上那个**两词**的不可逆档(⚠️ 与 `AskOrigin` 面的**三词** `never|maybe|always` 不是同一个词表:
+ *  覆写面只收两极,`maybe` 是引擎按工具自己的声明定的,调用方说不出口)。 */
+export type ToolAxisIrreversibility = NonNullable<ToolAxisEntry["irreversibility"]>;
+/** 值是不是一个合法的 `effect` 词(两条请求腿共用)。 */
+export declare function isToolEffect(v: unknown): v is ToolEffect;
+/** 值是不是一个合法的**覆写面** `irreversibility` 词(两条请求腿共用)。 */
+export declare function isToolAxisIrreversibility(v: unknown): v is ToolAxisIrreversibility;
+//# sourceMappingURL=tool-axis-words.d.ts.map

package/dist/tool-axis-words.js

@@ -0,0 +1,9 @@
+const TOOL_EFFECT_WORDS = ["read", "write", "idempotent"];
+const TOOL_AXIS_IRREVERSIBILITY_WORDS = ["always", "never"];
+export function isToolEffect(v) {
+    return typeof v === "string" && TOOL_EFFECT_WORDS.includes(v);
+}
+export function isToolAxisIrreversibility(v) {
+    return typeof v === "string" && TOOL_AXIS_IRREVERSIBILITY_WORDS.includes(v);
+}
+//# sourceMappingURL=tool-axis-words.js.map

package/dist/trace/core-keyset-guard.d.ts

@@ -43,7 +43,7 @@ type _GuardBgNotifReverse = AssertAllKeysHandled<Exclude<BgNotifProjected | BgNo
 type RosterProjected = "name" | "agentId" | "sessionId" | "toolUseId" | "owner" | "scope" | "sessionScoped" | "rootSessionId" | "model" | "modelFallback" | "createdAt";
 type _GuardRoster = AssertAllKeysHandled<Exclude<keyof RosterEntry, RosterProjected>>;
 type _GuardRosterReverse = AssertAllKeysHandled<Exclude<RosterProjected, keyof RosterEntry>>;
-type AskProjected = "toolName" | "toolCallId" | "args" | "message" | "sourceTaskId" | "fromSubagent" | "sourceAgentName" | "delegation" | "ruleOffers" | "ruleOffersAbsence" | "persistedRuleShadowed" | "probeCause" | "ruleEvidence" | "requiresRealApproval" | "denialLimitFallback" | "origin" | "ruleStoreUnreadable";
+type AskProjected = "toolName" | "toolCallId" | "args" | "message" | "sourceTaskId" | "fromSubagent" | "sourceAgentName" | "delegation" | "ruleOffers" | "ruleOffersAbsence" | "persistedRuleShadowed" | "probeCause" | "ruleEvidence" | "requiresRealApproval" | "denialLimitFallback" | "origin" | "ruleStoreUnreadable" | "readRootCandidate";
 type AskExcluded = "preview" | "principal" | "riskAxes" | "boundInputHash" | "isDelegatedChild" | "probeReason" | "hasBidiControls" | "previewWithheld" | "execCwd";
 type _GuardAsk = AssertAllKeysHandled<Exclude<keyof AskRequest, AskProjected | AskExcluded>>;
 type _GuardAskReverse = AssertAllKeysHandled<Exclude<AskProjected | AskExcluded, keyof AskRequest>>;
@@ -121,8 +121,8 @@ type SummaryProjected = "sessionId" | "scope" | "createdAt" | "gateKind" | "seve
 type SummaryExcluded = "token" | "toolInput" | "toolName" | "toolCallId" | "preview" | "principal" | "sourceTaskId" | "contentKind" | "restoreMode" | "checkpointId" | "previewWithheld";
 type _GuardInboxSummary = AssertAllKeysHandled<Exclude<keyof CheckpointSummary, SummaryProjected | SummaryExcluded>>;
 type _GuardInboxSummaryReverse = AssertAllKeysHandled<Exclude<SummaryProjected | SummaryExcluded, keyof CheckpointSummary>>;
-type TaskSpecWired = "objective" | "principal" | "images" | "sessionId" | "requireExistingSession" | "oneShot" | "clientContext" | "resumeAt" | "resumeAtMode" | "model" | "compactionModel" | "thinking" | "systemPrompt" | "appendSystemPrompt" | "promptProvider" | "memory" | "suggestNextPrompts" | "restoreFiles" | "acceptPartialRestore" | "rewindFilesTo" | "tools" | "excludeTools" | "deferTools" | "toolMaterializeStrategy" | "promptProfile" | "toolPolicy" | "onAsk" | "onQuestion" | "hooks" | "durableApproval" | "resourceSuspend" | "resilience" | "finalVerification" | "checkpointStore" | "handsReadOnly" | "memoryPersistenceCapable" | "additionalDirectories" | "additionalReadDirectories" | "enablePlanMode" | "interactiveTools" | "enableFork" | "shellGate" | "mcp" | "a2a" | "skills" | "backgroundScope" | "envFacts" | "limits" | "configOverrides" | "forwardSubagentEvents" | "retainSubagentSessions" | "retainBackgroundProcesses" | "outputSchema" | "outputRetries" | "compaction" | "attachments" | "selfOrchestration" | "getApiKeyAndHeaders" | "interactionPosture" | "agents" | "taskId" | "signal" | "preemptSignal" | "modelRole" | "enableBlockedReport" | "maxSuspends" | "autoModeRequested";
-type TaskSpecUnwired = "excludeAllTools" | "writeFace" | "actor" | "roles" | "lspManager" | "tracer" | "readFace" | "readDenyPatterns" | "interactiveQuestionFallback" | "alwaysLoadTools" | "restoreGatedTools" | "deferSelfResolve" | "basePolicyForResumeEdit" | "lspDiagnostics" | "streamingToolExecution" | "toolResultThresholdChars";
+type TaskSpecWired = "objective" | "principal" | "images" | "sessionId" | "requireExistingSession" | "oneShot" | "clientContext" | "resumeAt" | "resumeAtMode" | "model" | "compactionModel" | "thinking" | "systemPrompt" | "appendSystemPrompt" | "promptProvider" | "memory" | "suggestNextPrompts" | "restoreFiles" | "acceptPartialRestore" | "rewindFilesTo" | "tools" | "excludeTools" | "deferTools" | "toolMaterializeStrategy" | "promptProfile" | "toolPolicy" | "onAsk" | "onQuestion" | "hooks" | "durableApproval" | "resourceSuspend" | "resilience" | "finalVerification" | "checkpointStore" | "handsReadOnly" | "memoryPersistenceCapable" | "additionalDirectories" | "additionalReadDirectories" | "enablePlanMode" | "interactiveTools" | "enableFork" | "shellGate" | "writeFace" | "mcp" | "a2a" | "skills" | "backgroundScope" | "envFacts" | "limits" | "configOverrides" | "forwardSubagentEvents" | "retainSubagentSessions" | "retainBackgroundProcesses" | "outputSchema" | "outputRetries" | "compaction" | "attachments" | "selfOrchestration" | "getApiKeyAndHeaders" | "interactionPosture" | "agents" | "taskId" | "signal" | "preemptSignal" | "modelRole" | "enableBlockedReport" | "maxSuspends" | "autoModeRequested" | "skillListingBudgetFraction" | "skillListingMaxDescChars";
+type TaskSpecUnwired = "excludeAllTools" | "actor" | "roles" | "lspManager" | "tracer" | "readFace" | "readDenyPatterns" | "interactiveQuestionFallback" | "alwaysLoadTools" | "restoreGatedTools" | "deferSelfResolve" | "basePolicyForResumeEdit" | "lspDiagnostics" | "streamingToolExecution" | "toolResultThresholdChars";
 type _GuardTaskSpec = AssertAllKeysHandled<Exclude<keyof TaskSpec, TaskSpecWired | TaskSpecUnwired>>;
 type _GuardTaskSpecReverse = AssertAllKeysHandled<Exclude<TaskSpecWired | TaskSpecUnwired, keyof TaskSpec>>;
 type TaskResultForwarded = "taskId" | "runId" | "sessionId" | "terminal" | "model" | "effectiveReasoning" | "result" | "salvagedOutput" | "remoteEnvFailures" | "apiFailure" | "retryAfterMs" | "degraded" | "structuredOutput" | "rewindNotes" | "haltedOnUserRejection" | "haltedByUser" | "strandedHumanAnswers" | "pendingApproval" | "approvalWaitedMs" | "effectiveReadFace" | "effectiveReadDenyPatterns" | "effectiveWriteFace" | "effectiveMemoryScopes" | "stats" | "editedFiles";