@sema-agent/server 7.148.0 → 7.149.0

package/dist/config.js

@@ -4,9 +4,9 @@ import { DEFAULT_AT_MENTION, DEFAULT_MODEL_REF, mintCapabilityKeys } from "./mod
 import { homedir } from "node:os";
 import { isAbsolute, join, posix as posixPath } from "node:path";
 import { fileURLToPath } from "node:url";
-import { hostOfUrl, HOST_UNREADABLE_SENTENCE, compileAllowList, inheritEnvPolicyProblem, BUILTIN_COMPLIANCE_DENIES, COMPLIANCE_CAPABILITIES, CROSS_SESSION_INBOUND_SETTINGS, CROSS_SESSION_DIALOG_EXPIRY_VALUES, compileReadDeny, resolveReadDenyBuiltins, isModelPriced, PROTOCOL_TABLE, RECOMMENDED_SENSITIVE_PATTERNS, judgeRuleToolName, resolveFileHistoryRetention, resolveLockedKeys, validatePermissionRules, WRITE_PROTECTED_DEFAULT_TABLE, resolveWriteProtectedTable, principalInboxConsumerOf, carriesCredential, isReplicableScope, resolveBashTimeoutCaps } from "@sema-agent/core";
+import { hostOfUrl, HOST_UNREADABLE_SENTENCE, compileAllowList, BUILTIN_COMPLIANCE_DENIES, COMPLIANCE_CAPABILITIES, CROSS_SESSION_INBOUND_SETTINGS, CROSS_SESSION_DIALOG_EXPIRY_VALUES, compileReadDeny, resolveReadDenyBuiltins, isModelPriced, PROTOCOL_TABLE, RECOMMENDED_SENSITIVE_PATTERNS, judgeRuleToolName, resolveFileHistoryRetention, resolveLockedKeys, validatePermissionRules, WRITE_PROTECTED_DEFAULT_TABLE, resolveWriteProtectedTable, principalInboxConsumerOf, carriesCredential, isReplicableScope, resolveBashTimeoutCaps } from "@sema-agent/core";
 import { ROSTER_PRIMARY_ROLES, ROSTER_CHEAP_ROLES, WEB_ADMIN_ENV, retiredEnvRefusal, stripControlAndBidi } from "@sema-agent/settings-schema";
-import { parseApprovalHmacKeys, parsePrincipalJwks } from "./auth-keys.js";
+import { parseApprovalHmacKeys, parsePrincipalJwks, parseServiceAuthTokens } from "./auth-keys.js";
 import { DEFAULT_ELICITATION_THROTTLE } from "./elicitation.js";
 import { buildRuleListJudgeOptions } from "./permission-rule-list.js";
 import { isV2ScopeKey, memoryReplicationCoverage, replicatesProjectLayersOf } from "./memory-scope.js";
@@ -27,7 +27,7 @@ import { resolveLocalDataRoot } from "./local-data-root.js";
 import { buildWriteProtectionPosture } from "./write-protection.js";
 import { RUN_STALE_SEC_DEFAULT } from "./run-stale-default.js";
 import { normalizeSshFingerprint } from "./ssh-host-key.js";
-import { ASSUMED_CONTEXT_WINDOW } from "./model-context-window.js";
+import { resolveContextWindow } from "./model-context-window.js";
 import { MODEL_THINKING_LEVELS, THINKING_LEVELS, THINKING_FORMATS, buildModelCompat, isModelThinkingLevel, isThinkingFormat, isThinkingTier } from "./model-compat.js";
 import {} from "./posture-source.js";
 import { COST_QUOTA_WINDOW_SEC_RANGE, costQuotaWindowSecInRange } from "./observability/cost-quota.js";
@@ -41,6 +41,7 @@ import { laneLivenessOf } from "./exec-bounds.js";
 import { SANDBOX_IPV6_DEFAULT, SANDBOX_IPV6_WORDS } from "./sandbox-egress-policy.js";
 import { WORKSPACE_CACHE_DEFAULT, WORKSPACE_CACHE_MOUNT_DEFAULT, WORKSPACE_CACHE_MOUNT_RESERVED, WORKSPACE_CACHE_SIZE_DEFAULT, WORKSPACE_CACHE_WORDS, isK8sQuantity, mountsOverlap, reservedMountCollision } from "./workspace-cache.js";
 import { DEPLOYMENT_SHAPE_PREDICATES } from "./deployment-shape.js";
+import { parseLocalStoreDurabilityWord } from "./local-store-declaration.js";
 import { sandboxForwardedEnvOf } from "./execution-config-root.js";
 import { SANDBOX_READ_FLOOR_DEFAULT, SANDBOX_READ_FLOOR_WORDS, laneMissingEnv, readDeclaredLaneTable } from "./execution-lane-caps.js";
 import { MEMORY_ENGINE_BACKENDS, SESSION_BACKENDS, STORE_BACKENDS } from "@sema-agent/settings-schema/execution-lanes";
@@ -61,7 +62,7 @@ import { echoCallerText } from "./caller-text-echo.js";
 import { PRINCIPAL_MAX_BYTES, principalShapeProblem } from "./principal-shape.js";
 import { buildDisplaySafeUrl, redactSecrets } from "./trace/redact.js";
 import { parseConfigLocalOwnerUid } from "./config-dir-trust.js";
-import { allowlistedEnv, ownCredentialDeclarationRefusal } from "./server-secret-env.js";
+import { allowlistedEnv, ownCredentialDeclarationRefusal, ownCredentialVariable } from "./server-secret-env.js";
 import { ENV_NAME_ALLOWLIST_KNOBS, ENV_NAME_ALLOWLIST_KNOB_NAMES, describeAllowlistPostures } from "./env-name-allowlist-knobs.js";
 import { APPROVAL_ASK_RETENTION_DEFAULT_MS, APPROVAL_ASK_RETENTION_FLOOR_MS } from "./approval-ask-retention.js";
 import { parseModsDeclaration } from "./mods-declaration.js";
@@ -565,14 +566,18 @@ const OWN_CREDENTIAL_HANDOFF = {
     "host-put-back": { where: "a put-back list hands the named variable back, as written, to the child the engine withheld it from", whom: "that child" },
     "sandbox-grant": { where: "a sandbox list puts the named variable, as written, into a sandbox the model can read", whom: "the sandbox" },
 };
-function ownCredentialNameProblem(name, channel) {
-    if (inheritEnvPolicyProblem([name]) === undefined)
+function ownCredentialProblem(name, channel) {
+    const held = ownCredentialVariable(name);
+    if (held === undefined)
         return undefined;
     const { where, whom } = OWN_CREDENTIAL_HANDOFF[channel];
-    return `this deployment's own credential — ${where}; give ${whom} a credential of its own (another name and another value) and list that name instead (the engine refuses it on any allow list)`;
+    const copy = held === "value" ? "a copy under another name (its value is one of this service's credentials); " : "";
+    const engine = held === "name" ? "the engine refuses it on any allow list" : "the engine withholds it from every child";
+    return `this deployment's own credential — ${copy}${where}; give ${whom} a credential of its own (another name and another value) and list that name instead (${engine})`;
 }
 const NAMES_IN_FORCE = {
     LSP_ENV_ALLOW: (c) => c.lspEnvAllow,
+    HOOK_ENV_ALLOW: (c) => c.hookEnvAllow,
     E2B_SANDBOX_ENV: (c) => (c.remoteExec.provider === "e2b" ? Object.keys(sandboxForwardedEnvOf(c)) : []),
     K8S_SANDBOX_ENV: (c) => (c.remoteExec.provider === "k8s" ? Object.keys(sandboxForwardedEnvOf(c)) : []),
     DOCKER_SANDBOX_ENV: (c) => (c.remoteExec.provider === "local-docker" ? Object.keys(sandboxForwardedEnvOf(c)) : []),
@@ -583,7 +588,7 @@ export function sandboxEnvNamesInForce(seats) {
 }
 export function ownCredentialHitsInForce(seats) {
     return SERVER_ENV_NAME_ALLOWLIST_KNOBS.flatMap((knob) => NAMES_IN_FORCE[knob](seats).flatMap((name) => {
-        const problem = ownCredentialNameProblem(name, ENV_NAME_ALLOWLIST_KNOBS[knob].channel);
+        const problem = ownCredentialProblem(name, ENV_NAME_ALLOWLIST_KNOBS[knob].channel);
         return problem === undefined ? [] : [{ knob, name, problem }];
     }));
 }
@@ -600,7 +605,7 @@ export function parseEnvNameAllowlist(knob, singleUserTurnkey) {
                 ? 'not an environment-variable name (letters, digits and "_", not starting with a digit)'
                 : ENV_NAME_ALLOWLIST_KNOB_NAMES.has(seg.toUpperCase())
                     ? `the name of a name-list knob (${[...ENV_NAME_ALLOWLIST_KNOB_NAMES].join(" / ")}: their raw text is withheld from every child process and sandbox; naming one would put that text back)`
-                    : ownCredentialNameProblem(seg, spec.channel);
+                    : ownCredentialProblem(seg, spec.channel);
         if (problem === undefined)
             return;
         throw new Error(`env ${knob}: entry #${i + 1} of ${segments.length} is ${problem}` +
@@ -762,6 +767,7 @@ function optionalEnumKey(key, envName, raw, allowed) {
     }
     return { [key]: raw };
 }
+const PRINCIPAL_INBOX_ECHO_CHARS = 96;
 function principalInboxAssistantKey(raw) {
     if (raw === undefined || raw === "")
         return {};
@@ -769,7 +775,9 @@ function principalInboxAssistantKey(raw) {
         principalInboxConsumerOf({ principalInboxConsumer: { assistant: raw } });
     }
     catch (err) {
-        throw new Error(`env PRINCIPAL_INBOX_ASSISTANT must name the agent handle that consumes the principal inbox (or stay UNSET for no cross-principal delivery): ${err instanceof Error ? err.message : String(err)}`);
+        const shown = JSON.stringify(raw.length > PRINCIPAL_INBOX_ECHO_CHARS ? `${raw.slice(0, PRINCIPAL_INBOX_ECHO_CHARS)}…` : raw);
+        throw new Error(`env PRINCIPAL_INBOX_ASSISTANT must name the agent handle that consumes the principal inbox, or be unset or the empty string for no cross-principal delivery (a blank value is neither — whitespace is not "empty"): ` +
+            `the value ${shown} is refused — ${err instanceof Error ? err.message : String(err)}`);
     }
     return { principalInboxAssistant: raw };
 }
@@ -975,6 +983,7 @@ function parseStoreDomain(ctx) {
             return raw;
         })()),
         runStoreStrictHydrate: parseRunStoreStrictHydrate(process.env.RUN_STORE_STRICT_HYDRATE),
+        localStoreDurability: parseLocalStoreDurabilityWord(process.env.LOCAL_STORE_DURABILITY),
         tidb: needsDb && dbBackend === "mysql"
             ? {
                 host: env("MYSQL_HOST"),
@@ -1085,7 +1094,7 @@ function parseModelDomain() {
     });
     const envCompat = envApi === "openai-completions" ? envCompatDeclared : undefined;
     const modelCapability = { reasoning: parseBoolWord("MODEL_REASONING", process.env.MODEL_REASONING), vision: parseBoolWord("MODEL_VISION", process.env.MODEL_VISION) };
-    const contextWindow = numEnv("MODEL_CONTEXT_WINDOW", String(ASSUMED_CONTEXT_WINDOW));
+    const mainWindow = resolveContextWindow(optNumEnvStrict("MODEL_CONTEXT_WINDOW"));
     const model = {
         id: modelId,
         name: modelId,
@@ -1099,10 +1108,10 @@ function parseModelDomain() {
             cacheRead: costEnv("MODEL_COST_CACHE_READ", "unset"),
             cacheWrite: costEnv("MODEL_COST_CACHE_WRITE", "unset"),
         }, undefined)),
-        contextWindow,
+        contextWindow: mainWindow.window,
         maxTokens: process.env.MODEL_MAX_TOKENS !== undefined && process.env.MODEL_MAX_TOKENS !== ""
             ? parseNumOrFail("MODEL_MAX_TOKENS", process.env.MODEL_MAX_TOKENS)
-            : Math.min(32000, contextWindow),
+            : Math.min(32000, mainWindow.window),
         ...(optFinitePositiveEnv("MODEL_CHARS_PER_TOKEN") !== undefined ? { charsPerToken: optFinitePositiveEnv("MODEL_CHARS_PER_TOKEN") } : {}),
         params: { promptCacheFamily: envLaneWire.promptCacheFamily },
         ...(thinkingDefault ? { defaultThinking: thinkingDefault } : {}),
@@ -1138,6 +1147,8 @@ function parseModelDomain() {
             break;
     }
     const cheapMintedId = mintedCheapId(cheapSlot);
+    const cheapDeclaredWindow = cheapMintedId === undefined ? undefined : optNumEnvStrict("MODEL_CHEAP_CONTEXT_WINDOW");
+    const cheapWindow = resolveContextWindow(cheapDeclaredWindow, mainWindow);
     const cheapModel = cheapMintedId !== undefined
         ? {
             ...model,
@@ -1150,7 +1161,7 @@ function parseModelDomain() {
                 cacheRead: costEnv("MODEL_CHEAP_COST_CACHE_READ", "declares-zero"),
                 cacheWrite: costEnv("MODEL_CHEAP_COST_CACHE_WRITE", "declares-zero"),
             }, model.cost)),
-            contextWindow: numEnvOr("MODEL_CHEAP_CONTEXT_WINDOW", model.contextWindow),
+            contextWindow: cheapWindow.window,
             maxTokens: numEnvOr("MODEL_CHEAP_MAX_TOKENS", model.maxTokens),
             ...(optFinitePositiveEnv("MODEL_CHEAP_CHARS_PER_TOKEN") !== undefined ? { charsPerToken: optFinitePositiveEnv("MODEL_CHEAP_CHARS_PER_TOKEN") } : {}),
         }
@@ -1172,7 +1183,7 @@ function parseModelDomain() {
     if (cheapModel) {
         const cheapAct = optFinitePositiveEnv("MODEL_CHEAP_AUTO_COMPACT_TOKENS");
         if (applyAutoCompactWindow(cheapModel, cheapAct) === "removed-1m") {
-            const inherited = process.env.MODEL_CHEAP_CONTEXT_WINDOW === undefined || process.env.MODEL_CHEAP_CONTEXT_WINDOW === "";
+            const inherited = cheapDeclaredWindow === undefined;
             CONFIG_NOTICES.push({
                 level: "warn",
                 event: "auto_compact_window_not_derived_1m",
@@ -1186,6 +1197,7 @@ function parseModelDomain() {
         noticeAutoCompactAboveWindow("cheap", "MODEL_CHEAP_AUTO_COMPACT_TOKENS", cheapModel);
     }
     const models = envLaneTable(modelId, model, cheapModel);
+    const contextWindowSources = Object.fromEntries(Object.entries(envLaneTable(modelId, { id: model.id, source: mainWindow.source }, cheapModel !== undefined ? { id: cheapModel.id, source: cheapWindow.source } : undefined)).map(([name, slot]) => [name, slot.source]));
     const gatewayApiKey = route.gatewayApiKey;
     if (gatewayBaseUrl === undefined && declaredCredential(gatewayApiKey) !== undefined) {
         CONFIG_NOTICES.push({
@@ -1241,7 +1253,9 @@ function parseModelDomain() {
         },
         model,
         envModel: model,
+        envModelContextWindowSource: mainWindow.source,
         models,
+        contextWindowSources,
         modelApiKeyEnv: {},
         modelApiKeys: {},
         modelRefusals: {},
@@ -1980,12 +1994,7 @@ function parseAuthDomain(ctx) {
     const principalJwtIss = process.env.PRINCIPAL_JWT_ISS || undefined;
     const principalJwtAud = process.env.PRINCIPAL_JWT_AUD || undefined;
     const principalJwtMaxTtlSec = parseNumOrFailNonNegative("PRINCIPAL_JWT_MAX_TTL_SEC", env("PRINCIPAL_JWT_MAX_TTL_SEC", "120"));
-    const authTokens = Object.fromEntries((process.env.SERVICE_AUTH_TOKENS ?? "")
-        .split(",")
-        .map((s) => s.trim())
-        .filter((s) => s.includes("="))
-        .map((s) => [s.slice(0, s.indexOf("=")).trim(), s.slice(s.indexOf("=") + 1).trim()])
-        .filter(([tok, sys]) => tok.length > 0 && sys.length > 0));
+    const authTokens = parseServiceAuthTokens(process.env.SERVICE_AUTH_TOKENS);
     return {
         bindHost: process.env.BIND_HOST || undefined,
         bindHostSource: process.env.BIND_HOST ? "BIND_HOST" : undefined,
@@ -2028,6 +2037,7 @@ function parseOrchestrationDomain(ctx) {
     const lspHostEnabled = boolEnv("LSP_HOST_ENABLED", true);
     const autoBackgroundOnTimeout = boolEnv("AUTO_BACKGROUND_ON_TIMEOUT", true);
     const lspEnvAllow = parseEnvNameAllowlist("LSP_ENV_ALLOW", singleUserTurnkey) ?? [];
+    const hookEnvAllow = parseEnvNameAllowlist("HOOK_ENV_ALLOW", singleUserTurnkey) ?? [];
     const declaredLane = declaredExecutionLane(process.env.REMOTE_EXEC);
     const readFaceFacts = process.env.READ_FACE !== undefined
         ? { readFace: enumEnv("READ_FACE", "roots", ["open", "roots"]), readFaceSource: "env" }
@@ -2203,6 +2213,7 @@ function parseOrchestrationDomain(ctx) {
         lspHostEnabled,
         autoBackgroundOnTimeout,
         lspEnvAllow,
+        hookEnvAllow,
         workflowAgentsReadOnly: boolEnv("WORKFLOW_AGENTS_READONLY", false),
         imageBakes: {
             enabled: boolEnv("IMAGE_BAKES_ENABLED", false),
@@ -2619,11 +2630,11 @@ function parseA2aServeAudience(v, at) {
 }
 const STORE_GROUP_KEYS = [
     "sessionBackend", "sessionCacheTtlSec", "storeProbeIntervalMs", "storeLockWaitMs", "dbBackend", "dbBackendExplicit", "localDataRoot", "sealedKeyDir",
-    "runStoreStrictHydrate",
+    "runStoreStrictHydrate", "localStoreDurability",
     "tidb", "pg", "dbQueryTimeoutMs", "snapshotBlobStore", "snapshotBlobSqlMaxBytes", "snapshotBlobAllowSql", "fileHistory", "fileHistoryCapture", "sendUserFile",
 ];
 const MODEL_PLANE_GROUP_KEYS = [
-    "gatewayBaseUrl", "gatewayApiKey", "gatewayFallbackUrls", "gatewayMaxRetries", "anthropic", "resilience", "model", "envModel", "models",
+    "gatewayBaseUrl", "gatewayApiKey", "gatewayFallbackUrls", "gatewayMaxRetries", "anthropic", "resilience", "model", "envModel", "envModelContextWindowSource", "models", "contextWindowSources",
     "modelApiKeyEnv", "modelApiKeys", "modelRefusals", "droppedCatalogEntries", "modelQuotaWeights", "tiers", "projects", "roles", "atMention", "cascadeLadder", "degrade",
 ];
 const APPROVAL_GROUP_KEYS = [
@@ -2650,7 +2661,7 @@ const ORCHESTRATION_GROUP_KEYS = [
     "workflowOrphanGraceMs", "workflowJournalRetentionMs", "workflowRunRetentionMs", "usageWindows", "workflowAgentsReadOnly",
     "workflowSizeGuideline", "backgroundAgentRetentionMs", "backgroundAgentStaleRunningMs", "backgroundAgentStallMs",
     "backgroundAgentParkClaimStaleMs", "delegationEntryCaps", "rosterRetentionMs", "leaderRunStaleMs", "scratchpadSweepTtlMs", "sandboxPkgSource", "sandboxPkgSourceCustom",
-    "sessionAutoTitle", "sessionAutoTitleSource", "selectEnvironmentTool", "envFactsEnabled", "toolDeferLongtail", "lspHostEnabled", "lspEnvAllow", "autoBackgroundOnTimeout",
+    "sessionAutoTitle", "sessionAutoTitleSource", "selectEnvironmentTool", "envFactsEnabled", "toolDeferLongtail", "lspHostEnabled", "lspEnvAllow", "hookEnvAllow", "autoBackgroundOnTimeout",
     "imageBakes", "readFace", "readFaceSource", "taskWriteFaceEscalation", "readDenyPatterns", "readDenyBuiltinTiers", "readDenyBuiltinExclude", "readDenyFloorRequired", "sandboxReadFloor",
     "agentConfigDir", "configLkgPath", "configLkgEnabled",
 ];

package/dist/context-window-notice.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 「这只模型的窗是假定的」运维通告的**唯一发声器**(行的形与事件名属 `model-context-window.ts` 的 `buildContextWindowAssumedNotice`)。
+ *
+ * ## 说什么
+ * **进程此刻服务的那张模型表**里,窗来源(`config.contextWindowSources`,与 `GET /v1/models` 行的 `contextWindowSource` 同一张表)是 `assumed` 的每只模型一行;
+ * 一个名每进程只说一次(同一份活配置一本账 —— 起服说过的名,目录落地 / 「无中心配置」档回到 env 表时不再说)。
+ *
+ * ## 在哪说(位置即判据,与「配了 $ 天花板但目录未定价」那一句同一条纪律)
+ *  · 起服:模型表**定形之后**(装配第 2 段目录应用之后的不变量区末尾、run-local 配置源应用之后的同一位置)—— 不在 `loadConfig` 里说:那一拍只见 env 表,
+ *    目录随后在 boot 被采纳时 env 表整张不服务,在那里说就是对一只不会服务的模型报警(行里还会说 `GET /v1/models` 有它的行,而那一行并不存在)。
+ *  · 运行中:每次模型面 commit 之后(目录换代、迟到的 boot 目录、「无中心配置」档回到 env 表 —— `applyEffective` 一处)。
+ * 严格名册布防时 env 表是占位、从不被派发(`isRosterGateArmed`;路由判官对它豁免的同一个事实)⇒ env 表在服时不说。
+ *
+ * ## 哪些名
+ * 别名(`default` 与某个本名指向同一只模型)不另说;目录里真有一条**叫** `default` 的条目(不是别名)照说。
+ */
+import type { Model } from "@sema-agent/core";
+import { type ContextWindowSource } from "./model-context-window.js";
+/** 发声器读的那几格活配置(结构子集;`ServiceConfig` 满足)。 */
+export interface AssumedWindowView {
+    readonly model: Model;
+    readonly envModel: Model;
+    readonly models: Readonly<Record<string, Model>>;
+    readonly contextWindowSources: Readonly<Record<string, ContextWindowSource>>;
+}
+export declare function warnAssumedContextWindows(config: AssumedWindowView, logger: {
+    warn(event: string, fields?: Record<string, unknown>): void;
+} | undefined, opts: {
+    readonly envTableIsPlaceholder: boolean;
+}): void;
+//# sourceMappingURL=context-window-notice.d.ts.map

package/dist/context-window-notice.js

@@ -0,0 +1,28 @@
+import { buildContextWindowAssumedNotice } from "./model-context-window.js";
+import { DEFAULT_MODEL_REF, servedModelTableLeg } from "./model-select.js";
+const assumedWindowNamesSaid = new WeakMap();
+export function warnAssumedContextWindows(config, logger, opts) {
+    if (logger === undefined)
+        return;
+    const leg = servedModelTableLeg(config);
+    if (leg === "env" && opts.envTableIsPlaceholder)
+        return;
+    const said = assumedWindowNamesSaid.get(config) ?? new Set();
+    assumedWindowNamesSaid.set(config, said);
+    const named = new Set(Object.entries(config.models).filter(([name]) => name !== DEFAULT_MODEL_REF).map(([, m]) => m));
+    for (const [name, m] of Object.entries(config.models)) {
+        if (name === DEFAULT_MODEL_REF && named.has(m))
+            continue;
+        if (said.has(name) || config.contextWindowSources[name] !== "assumed")
+            continue;
+        said.add(name);
+        const declareAt = leg === "catalog"
+            ? "the catalog entry's contextWindow (or MODEL_CONTEXT_WINDOW, which every entry without one inherits)"
+            : m === config.envModel
+                ? "MODEL_CONTEXT_WINDOW"
+                : "MODEL_CHEAP_CONTEXT_WINDOW (or MODEL_CONTEXT_WINDOW, which the cheap slot inherits)";
+        const notice = buildContextWindowAssumedNotice({ model: name, window: m.contextWindow, declareAt });
+        logger.warn(notice.event, notice.fields);
+    }
+}
+//# sourceMappingURL=context-window-notice.js.map

package/dist/deployment-shape.d.ts

@@ -105,36 +105,45 @@ export declare const DEPLOYMENT_SHAPE_PREDICATES: Readonly<{
     principalRequired: DeploymentShapePredicate<"principal">;
     /**
      * 「这台部署有没有身份边界」的问法 —— 有 = 请求里有东西替主体作保或拦在门外:声明了 `REQUIRE_PRINCIPAL`,或配置接了任一已验身份来源
-     * (service 凭据 / 鉴权桥 issuer,含中心回退 / 直连门),或声明了只读 trace 凭据。没有 = dev-open:主体头是谁都能自报的标签。
+     * (service 凭据 / 鉴权桥 issuer,含中心回退 / 直连门),或声明了只读 trace 凭据。没有 = dev-open:主体头是谁都能自报的(不是认证;报了它的请求仍为那位主体)。
      * 只读配置(验签器在起服第 9 段按同一个配置读数建 ⇒「验签器在场」≡「配置里有桥」),所以先于验签器的起服段(第 3 段的一次性迁移)与请求面读到同一个答案。
-     * 读者:请求面的 dev-open 判据(`http/principal-gate.ts` 的 `devOpenDeployment`:属主存取器的 fleet 一格与 `/metrics` 族的免凭据臂)、
+     * 读者:请求面的 dev-open 判据(`http/principal-gate.ts` 的 `devOpenDeployment`,`actsForDeployment` 的一臂:不报主体的调用方在属主存取器的 fleet 一格与 `/metrics` 族上代部署本人)、
      * 一次性迁移 M48 的输入(`plugins/store-backend.ts`:有边界 ⇒ 不改写哨兵属主)。
      */
-    identityBoundary: DeploymentShapePredicate<"identity" | "principal">;
+    identityBoundary: DeploymentShapePredicate<"principal" | "identity">;
     /**
      * 租户轴的问法。今天与 {@link DEPLOYMENT_SHAPE_PREDICATES.principalRequired} 读**同一个声明**([ref] ①:托管 / 多租 ⇔ `REQUIRE_PRINCIPAL=true`,
      * 签发方配置是身份验签轴、不算租户证据)—— 两个问题、一根轴、一个读口;「鉴权必需」与「多租形」拆成两个声明时只改这一行的判官。
      */
     multiTenant: DeploymentShapePredicate<"principal">;
     /** 读能力表 `callerCwd` 位(host = 单主才开;device = 路径落在发起者自己的设备上,归属由根会话行执行格上的设备绑定验过,不要求单主)。 */
-    callerCwd: DeploymentShapePredicate<"lane" | "principal">;
+    callerCwd: DeploymentShapePredicate<"principal" | "lane">;
     /** 调用方给的宿主绝对路径(附加目录 / 项目上下文 / 本机 SendUserFile / 指令文件探针)只在「手就在本 worker 的盘上 ∧ 单主」时指向调用方自己的东西;
-     *  本机语言服务器(`createLspManager`:本机子进程、在 worker 盘上找根)同问这一句,读这一行 × `LSP_HOST_ENABLED`。 */
-    callerOwnsWorkerDisk: DeploymentShapePredicate<"lane" | "principal">;
+     *  本机语言服务器(`createLspManager`:本机子进程、在 worker 盘上找根)同问这一句,读这一行 × `LSP_HOST_ENABLED`。
+     *  local 店的声明(`local-store-declaration.ts` 的 `localStoreDeclarationOf`)同问这一句:店的数据根就在这块盘上,盘是调用方自己的且易失 ⇒ 部署不替他声明它活过替换。 */
+    callerOwnsWorkerDisk: DeploymentShapePredicate<"principal" | "lane">;
     /** wire `executionLane.toolsOnThisHost` 与出厂 / 中心技能的 `baseDir`:只问文件系统同一性,与租户无关(出厂内容每个租户拿到同一份)。 */
     toolsOnThisHost: DeploymentShapePredicate<"lane">;
     /** 无手形(声明 `none`;判据读执行环境块 `io`,不点名车道词)且单主:进程级消费者(hooks 命令、项目上下文本机读、卡批规则 root)看到的就是引擎自己的进程 cwd / env。 */
-    noHandsSingleUser: DeploymentShapePredicate<"lane" | "principal">;
+    noHandsSingleUser: DeploymentShapePredicate<"principal" | "lane">;
     /** 任务层替部署声明宿主姿态(bypassPermissions 开写面 / host shell 继承整份环境)的射程:device 车道上跨租户宿主穿越结构性不存在(clay 裁定③)。 */
-    taskHostPostureDeclarations: DeploymentShapePredicate<"lane" | "principal">;
+    taskHostPostureDeclarations: DeploymentShapePredicate<"principal" | "lane">;
     /** 写门走代理裁决(执行环境块 `hostLocalPaths` 为假:路径不是本 worker 盘上的文件);认不出的词 ⇒ 走代理(代理 slot 空 ⇒ 写门 fail-closed)。 */
     sandboxPathAdjudication: DeploymentShapePredicate<"lane">;
     /** 读能力表 `sandboxSendUserFile` 位(e2b / k8s 每任务一只沙箱 ⇒ 任何租户;ssh 共享一台真机 ⇒ 只单主)。 */
-    sandboxSendUserFile: DeploymentShapePredicate<"lane" | "principal">;
+    sandboxSendUserFile: DeploymentShapePredicate<"principal" | "lane">;
     /** 读能力表 `remoteScratchpad` 位(`/tmp/scratchpad/<sessionId>` 远端约定)。 */
     remoteScratchpad: DeploymentShapePredicate<"lane">;
+    /**
+     * 读能力表 `backgroundShell` 位 —— 「这条车道的执行环境能不能开后台 shell(`run_in_background` / `BashOutput` / `KillShell`),含把运行中的前台命令领养成后台任务」的**唯一**答者:
+     * e2b / k8s 每任务一只沙箱 ⇒ 任何租户;host(命令落在 worker 宿主上的同一张进程表)⇒ 只单主;其余车道(含 none)没有后台 shell;认不出的车道 ⇒ 否。
+     * 读者(同读这一行,没有第二份判别式):三只声明后台 shell 的适配器的 `backgroundCapabilities`(`supported` 与 `supportsDetach` 是同一个答案)、
+     * host 适配器的装配点(`boot/execution-env.ts` / `run-local.ts` 把行的答案交给适配器的 `backgroundShell`)、能力事实 `autoBackgroundOnTimeout`(`/health.autoBackgroundOnTimeout`)。
+     * 全局关停开关 `HOST_BG_ENABLED` 不在行里 —— 它是旋钮不是部署形,host 适配器与事实在行之上各合取一次。
+     */
+    backgroundShell: DeploymentShapePredicate<"principal" | "lane">;
     /** 读能力表 `tenantSeparation` 位(值来自 settings-schema 车道词表正本);唯一读者 = 跨域不变量 `multi-tenant-shared-lane`。 */
-    laneSeparatesTenants: DeploymentShapePredicate<"lane" | "principal">;
+    laneSeparatesTenants: DeploymentShapePredicate<"principal" | "lane">;
     /**
      * [ref] —— **VM 级**隔离强度(独立内核:e2b 的 Firecracker microVM;k8s 只在 Kata / gVisor 运行时类上)。与执行环境块 `isolation` 键
      * (OS 级边界,容器即算;wire `executionLane.isolated` 的属主 `laneIsolated`)是两个问题,所以不叫「isolated」。读者:A 值路由。
@@ -157,7 +166,7 @@ export declare const DEPLOYMENT_SHAPE_PREDICATES: Readonly<{
      *  · `none`:没有执行环境(能力事实先判无手车道,这里照样表态)。
      * 读者:能力事实 `sessionRewindFiles`(能力位与该口的 501 同读这一行)。
      */
-    rewindableWorkspace: DeploymentShapePredicate<"lane" | "principal">;
+    rewindableWorkspace: DeploymentShapePredicate<"principal" | "lane">;
 }>;
 export {};
 //# sourceMappingURL=deployment-shape.d.ts.map

package/dist/deployment-shape.js

@@ -63,6 +63,7 @@ export const DEPLOYMENT_SHAPE_PREDICATES = Object.freeze({
     sandboxPathAdjudication: createPredicate(["lane"], "车道:写门的路径事实要经代理到执行环境里取(文件平面不在本 worker 盘上;认不出的车道也走代理)。", ({ lane }) => lane.block === undefined || !lane.block.hostLocalPaths),
     sandboxSendUserFile: createPredicate(["lane", "principal"], "车道 × 租户:SendUserFile 的沙箱直传腿可以挂(沙箱盘 = 租户自己的任务工作区,或共享真机上的单主部署)。", ({ lane, principal }) => lane.caps !== undefined && capabilityHolds(lane.caps.sandboxSendUserFile, principal)),
     remoteScratchpad: createPredicate(["lane"], "车道:执行环境里按会话分的远端 scratchpad 约定适用。", ({ lane }) => lane.caps !== undefined && lane.caps.remoteScratchpad === "supported"),
+    backgroundShell: createPredicate(["lane", "principal"], "车道 × 租户:本车道的执行环境可以开后台 shell(含领养运行中的前台命令)—— e2b / k8s 任何租户,host 只单主,其余车道没有。", ({ lane, principal }) => lane.caps !== undefined && capabilityHolds(lane.caps.backgroundShell, principal)),
     laneSeparatesTenants: createPredicate(["lane", "principal"], "车道 × 租户:这条车道在这台部署上不让两个租户的命令落在同一个共享目标上(单主部署恒成立;认不出的车道不成立)。", ({ lane, principal }) => lane.caps !== undefined && capabilityHolds(lane.caps.tenantSeparation, principal)),
     vmIsolatedHands: createPredicate(["lane"], "车道 / 隔离强度:手跑在 VM 级边界里(独立内核);runc / 共享内核 / 真机 / 认不出 ⇒ 否。", ({ lane }) => {
         if (lane.lane === "e2b")

package/dist/env-name-allowlist-knobs.d.ts

@@ -6,14 +6,15 @@
  *  · `example` 进拒句;
  *  · `multiTenant` = `REQUIRE_PRINCIPAL=true` 下名单作不作数 —— **只有服务进程读的旋钮有这一列**(姿态是服务进程的概念):
  *    - `LSP_ENV_ALLOW` ⇒ ignored:host 腿语言服务器在多租户姿态下本来就不起,名单无处作数,设了要说出来([ref])。
+ *    - `HOOK_ENV_ALLOW` ⇒ ignored:请求的 `settings.hooks` 在多租户姿态下整只不跑(`task-settings.ts` `taskHooksHonored`,同一只部署形谓词),名单无处作数。
  *    - 三只沙箱名单(e2b / local-docker / k8s 各一只) ⇒ honored:[ref] 照录修前语义(任何姿态下都转发),[ref] 主会话裁定维持 —— 沙箱 env 是部署方为隔离沙箱显式配的
  *      带外凭据(e2b / docker / k8s 车道本来就是多租户 fleet 的主形),与 LSP 那条「本机子进程」的形不同;多租户下起服说一句。
  *  · `BAKE_ENV_ALLOW`([ref] 残余,7.103.0)由 **bake-runner 进程**读(构建宿主守护进程:没有主体、没有租户 ⇒ 没有姿态列,
- *    不进 {@link describeAllowlistPostures} 的姿态句)。它与服务侧四只旋钮同一只解析器、同一只「点名放行」谓词、同一条「原文按凭据类」律。
- *  · `channel` = 这张名单**交给谁、在谁的减法之上**(闭集两词)。它只定拒句里「交到哪里」那半句与出路的主语,**不定拒不拒**:「不许点哪些名」对五只一律
+ *    不进 {@link describeAllowlistPostures} 的姿态句)。它与服务侧五只旋钮同一只解析器、同一只「点名放行」谓词、同一条「原文按凭据类」律。
+ *  · `channel` = 这张名单**交给谁、在谁的减法之上**(闭集两词)。它只定拒句里「交到哪里」那半句与出路的主语,**不定拒不拒**:「不许点哪些名」对六只一律
  *    = 名单型旋钮名 ∪ 本服务自有凭据名(引擎此刻的声明:起服解析时判一次,声明增长时由换代声明对活配置里每只服务侧名单此刻交出去的名重判一次;判官 = 引擎
  *    `inheritEnvPolicyProblem`,与引擎拒嵌入方白名单同句),规则全文在解析器头注 ②。
- *    - `host-put-back`(`LSP_ENV_ALLOW` / `BAKE_ENV_ALLOW`)—— 剥后放回形:宿主子进程的 env 先经唯一组合(引擎扣掉本服务自有凭据 + 形状剥),
+ *    - `host-put-back`(`LSP_ENV_ALLOW` / `HOOK_ENV_ALLOW` / `BAKE_ENV_ALLOW`)—— 剥后放回形:宿主子进程的 env 先经唯一组合(引擎扣掉本服务自有凭据 + 形状剥 / 严格名单),
  *      名单点到的键再从本进程环境**原样**取回叠上去;点到本服务自有凭据名 = 把引擎刚扣下的那枚交回那只子进程。
  *    - `sandbox-grant`(三只沙箱名单)—— 沙箱 env 的唯一来源(沙箱不从本进程继承任何东西),部署方显式交出的带外凭据([ref] 照转发);
  *      点到本服务自有凭据名 = 把它装进模型读得到的沙箱 env。沙箱要凭据 ⇒ 部署方给沙箱另铸一把(名与值都不同于本服务的任何凭据)。
@@ -25,7 +26,7 @@
  * 当场撒谎。为什么是纯叶:`config-catalog.ts` 被 `config.ts` 值引,表留在 `config.ts` 会成装载环。
  */
 /** 服务进程(`config.ts` `loadConfig`)读的名单型旋钮 —— 有多租户姿态。 */
-export type ServerEnvNameAllowlistKnob = "LSP_ENV_ALLOW" | "E2B_SANDBOX_ENV" | "DOCKER_SANDBOX_ENV" | "K8S_SANDBOX_ENV";
+export type ServerEnvNameAllowlistKnob = "LSP_ENV_ALLOW" | "HOOK_ENV_ALLOW" | "E2B_SANDBOX_ENV" | "DOCKER_SANDBOX_ENV" | "K8S_SANDBOX_ENV";
 /** bake-runner 进程(`bake-runner/main.ts` `loadEnv`)读的名单型旋钮 —— 构建宿主守护进程没有主体 / 租户,没有姿态。 */
 export type RunnerEnvNameAllowlistKnob = "BAKE_ENV_ALLOW";
 export type EnvNameAllowlistKnob = ServerEnvNameAllowlistKnob | RunnerEnvNameAllowlistKnob;
@@ -52,7 +53,7 @@ export type EnvNameAllowlistKnobTable = {
     readonly [K in EnvNameAllowlistKnob]: K extends ServerEnvNameAllowlistKnob ? ServerEnvNameAllowlistKnobRow : RunnerEnvNameAllowlistKnobRow;
 };
 export declare const ENV_NAME_ALLOWLIST_KNOBS: EnvNameAllowlistKnobTable;
-/** 名单型旋钮的全部名字(五只;表键派生)—— 两处用:解析器的「点名名单型旋钮 = 形错」、剥除的「名单原文按凭据类」臂。 */
+/** 名单型旋钮的全部名字(六只;表键派生)—— 两处用:解析器的「点名名单型旋钮 = 形错」、剥除的「名单原文按凭据类」臂。 */
 export declare const ENV_NAME_ALLOWLIST_KNOB_NAMES: ReadonlySet<string>;
 /**
  * 多租户姿态句 —— **由表派生**,不许在别处手写。形:`under REQUIRE_PRINCIPAL=true: <旋钮> is ignored; <旋钮> / <旋钮> are forwarded as configured`

package/dist/env-name-allowlist-knobs.js

@@ -4,6 +4,11 @@ export const ENV_NAME_ALLOWLIST_KNOBS = {
         channel: "host-put-back",
         multiTenant: { kind: "ignored", why: "the host-lane language server is not started in this posture, and the language-server env keeps the full secret strip" },
     },
+    HOOK_ENV_ALLOW: {
+        example: "HOOK_ENV_ALLOW=HOOK_TOKEN,WEBHOOK_SIGNING_KEY",
+        channel: "host-put-back",
+        multiTenant: { kind: "ignored", why: "request settings hooks are not run in this posture, so no hook environment reads the list" },
+    },
     E2B_SANDBOX_ENV: { example: "E2B_SANDBOX_ENV=GIT_TOKEN,NPM_TOKEN", channel: "sandbox-grant", multiTenant: { kind: "honored" } },
     DOCKER_SANDBOX_ENV: { example: "DOCKER_SANDBOX_ENV=GIT_TOKEN,NPM_TOKEN", channel: "sandbox-grant", multiTenant: { kind: "honored" } },
     K8S_SANDBOX_ENV: { example: "K8S_SANDBOX_ENV=GIT_TOKEN,NPM_TOKEN", channel: "sandbox-grant", multiTenant: { kind: "honored" } },

package/dist/execution-lane-caps.d.ts

@@ -16,9 +16,8 @@ export type ExecutionLane = DeclarableLane;
 export interface ExecutionLaneCaps {
     /** 调用方送来的 `cwd` 是否被尊重。读者:部署形表行 `callerCwd`(本位即判据;改前对账 `task-cwd.ts` 的 `cwdHonored || deviceCwdHonored`)。 */
     readonly callerCwd: LaneCapability;
-    /** core 的后台 shell 面(`run_in_background`/`BashOutput`/`KillShell`)。判别式:各 adapter 的
-     *  `backgroundCapabilities.supported`(`plugins/remote-env-{host,e2b,k8s}.ts`);host 腿的闸在
-     *  `boot/execution-env.ts` 的 `hostCfg.backgroundShell`。 */
+    /** core 的后台 shell 面(`run_in_background`/`BashOutput`/`KillShell`),含把运行中的前台命令领养成后台任务(`supportsDetach`)。读者:部署形表行 `backgroundShell`(本位即判据);
+     *  三只适配器的 `backgroundCapabilities`(`supported` 与 `supportsDetach` 同一个答案)、host 适配器的装配点与事实 `autoBackgroundOnTimeout` 同读这一行,没有第二份判别式。 */
     readonly backgroundShell: LaneCapability;
     /** 自唤醒 scheduler(`CronCreate`/…)。判别式:`boot/execution-env.ts` host 臂的 `hostScheduler`
      *  与 `http/routes/capabilities.ts` 的 `scheduler` 位(两处同判据)。 */
@@ -330,11 +329,27 @@ export declare function buildLaneHomeBootNote(deployment: LaneHomeDeployment): {
     readonly event: string;
     readonly note: string;
 } | undefined;
+/**
+ * 读拒表的字节地板不守时一条 run 的**两种结局**(闭集):`ran` = 部署没要求地板,run 照跑(引擎每 run 一条 `config.read_deny_floor_unkept` 通告);
+ * `refused` = 部署要求地板(`READ_DENY_FLOOR_REQUIRED=true`),run 在准备期拒(同码失败终局,同步提交 409)。判官只有引擎一只(`judgeReadFloorKept`),
+ * 结局由旋钮分开 —— 本仓只说话。
+ */
+export type ReadDenyFloorOutcome = "ran" | "refused";
+/**
+ * **读拒字节地板不守的那一句** —— 本仓说这件事的**唯一**组句器(纯字符串 ⇒ `build*`):点名执行环境(`REMOTE_EXEC=<车道>`,运维写的那一格)、
+ * 「不守读拒字节地板」与出路 `READ_DENY_FLOOR_REQUIRED`。读它的面(一个事实一句话,不另写第二句):
+ *  · `ran` —— run 事件流的 `engine_notice` 帧、运维 `engine_notice` 日志行与终局结果的 `readDenyFloor.message`(`read-deny-floor-notice.ts` 的呈现器);
+ *  · `refused` —— 失败终局的句子(同步提交 409 的 `error`、run 行 `error`、`done` 帧 `terminal.message`,`terminal.ts` 的两只出口属主)与起服那一行
+ *    `read_deny_floor_required_unkept` 的 `note`({@link buildReadDenyFloorUnkeptNote})。
+ * 句子不带行数(行数在通告的 `detail.rowCount`):同一条部署上同一种结局逐字同一句,运维能把起服行、409 与日志对上。
+ * 车道名以旋钮形 `REMOTE_EXEC=<词>` 出现 —— 那是调用方 / 运维写得出、查得到的名字,不是本仓对执行车道的自称。
+ */
+export declare function buildReadDenyFloorSentence(lane: string, outcome: ReadDenyFloorOutcome): string;
 /**
  * 「部署要求读拒表的字节地板(`READ_DENY_FLOOR_REQUIRED=true`),而本部署车道的执行环境块不守地板」时起服那一行的 `note`(纯字符串 ⇒ `build*`);否则 `undefined`。
  * 判据只读部署的要求与 {@link capabilitiesFor} 的 `keepsReadFloor`(认不出的车道答不出块 ⇒ 按不守说,不静默)。`none` 的桩块守地板 ⇒ 不出。
- * 句子点名车道与键:这条车道上每个读拒表有行的 run(出厂读拒档在岗时就有行)都在准备期拒,一个命令都不起 —— 起服先把后果与两条出路说出来,
- * 不让运维从第一条 409 才知道。
+ * 句子 = 这条车道上每条被拒的 run 的拒句({@link buildReadDenyFloorSentence} 的 `refused`,一字不差):起服先把后果与两条出路说出来,
+ * 运维不必从第一条 409 才知道,且起服行与 409 是同一句。
  */
 export declare function buildReadDenyFloorUnkeptNote(deployment: CapabilitiesDeployment & {
     readonly readDenyFloorRequired: boolean;

package/dist/execution-lane-caps.js

@@ -327,14 +327,28 @@ export function buildLaneHomeBootNote(deployment) {
         return { event: LANE_HOME_UNDECLARED_EVENT, note: buildHomeAbsentNote(homeLane, "REMOTE_EXEC_HOME_DIR is unset, and this lane cannot read its execution environment's home", DECLARE_HOME_REMEDY) };
     return { event: LANE_HOME_UNMEASURED_EVENT, note: buildHomeUnmeasuredNote(homeLane, home) };
 }
+export function buildReadDenyFloorSentence(lane, outcome) {
+    const env = `the execution environment (REMOTE_EXEC=${lane}) does not keep the read-deny byte floor`;
+    switch (outcome) {
+        case "ran":
+            return (`This run's read-deny rules are not byte-enforced: ${env} — a path a rule refuses is refused when a command names it, ` +
+                `but a program a command runs can still open it (a recursive read under a directory reads the files below it, denied ones included), ` +
+                `and their bytes can reach the conversation. READ_DENY_FLOOR_REQUIRED is not set, so the run went ahead; set READ_DENY_FLOOR_REQUIRED=true to refuse such runs instead.`);
+        case "refused":
+            return (`READ_DENY_FLOOR_REQUIRED=true, and ${env} (a program a command runs could open a path a read-deny rule refuses): ` +
+                `a run with read-deny rules is refused before any command starts (config.read_deny_floor_unkept; a synchronous submit answers 409). ` +
+                `Run on an execution environment that keeps the floor, or unset READ_DENY_FLOOR_REQUIRED to let such runs go ahead with a notice.`);
+        default: {
+            const unhandled = outcome;
+            throw new Error(`unhandled read-deny floor outcome: ${String(unhandled)}`);
+        }
+    }
+}
 export function buildReadDenyFloorUnkeptNote(deployment) {
     if (!deployment.readDenyFloorRequired)
         return undefined;
     if (capabilitiesFor(deployment)?.keepsReadFloor === true)
         return undefined;
-    return (`READ_DENY_FLOOR_REQUIRED=true, but the "${deployment.remoteExec.provider}" execution lane does not keep the read-deny byte floor (a program its commands run can open a path ` +
-        `the read-deny table refuses). Every run whose read-deny table has rows — the shipped default tiers put rows there unless READ_DENY_BUILTIN_TIERS=none — ` +
-        `is refused before any command starts (config.read_deny_floor_unkept; a synchronous submit answers 409). ` +
-        `Either run on a lane that keeps the floor, or unset READ_DENY_FLOOR_REQUIRED to run with one operator notice per run instead.`);
+    return buildReadDenyFloorSentence(deployment.remoteExec.provider, "refused");
 }
 //# sourceMappingURL=execution-lane-caps.js.map

package/dist/hooks/command-spawn.d.ts

@@ -46,9 +46,14 @@ export type CommandSpawnPlan = {
 export declare function composeHookEnvLayer(requestEnv: Readonly<Record<string, string>> | undefined, cwd: string, plugin: HookPluginContext | undefined): Record<string, string> & {
     CLAUDE_PROJECT_DIR: string;
 };
+/**
+ * 这条 hook 的子进程会拿到的环境:有效环境层叠在继承那一半之上(组合属主 = `hook-runner.ts` 的 `hookChildEnv`,本模块不写第二份组合,只问它的读数)。
+ * 组合拒(授予形坏 / 放回点到本服务自有凭据名)⇒ 抛,起法按「起不来」答(与 spawn 时组合抛同一个结局)。
+ */
+export type HookChildEnvOf = (layer: Readonly<Record<string, string>>) => Readonly<Record<string, string | undefined>>;
 /**
  * 一条 command 条目的起法(规则见文件头)。`cwd` = 本次 hook 的工作目录(`CLAUDE_PROJECT_DIR` 的缺省值);`requestEnv` = 请求 `settings.env`(hook 环境的一层;**必传**:没有就显式传 `undefined`,
- * 漏传是编译红,不会静默丢掉请求给的 env),合并与读法见 {@link composeHookEnvLayer} / {@link contextVarValue}。有副作用的只有两步,都只在条目带 `plugin` 时发生:读插件根是否是目录、建数据目录(CC 同:注入即建)。
+ * 漏传是编译红,不会静默丢掉请求给的 env),合并与读法见 {@link composeHookEnvLayer} / {@link contextVarValue};`childEnvOf` = 组合的读数入口({@link HookChildEnvOf})。有副作用的只有两步,都只在条目带 `plugin` 时发生:读插件根是否是目录、建数据目录(CC 同:注入即建)。
  */
-export declare function planCommandSpawn(entry: RunnableCommandHookEntry, cwd: string, requestEnv: Readonly<Record<string, string>> | undefined): Promise<CommandSpawnPlan>;
+export declare function planCommandSpawn(entry: RunnableCommandHookEntry, cwd: string, requestEnv: Readonly<Record<string, string>> | undefined, childEnvOf: HookChildEnvOf): Promise<CommandSpawnPlan>;
 //# sourceMappingURL=command-spawn.d.ts.map

package/dist/hooks/command-spawn.js

@@ -59,17 +59,24 @@ const refOf = (name) => "${" + name + "}";
 export function composeHookEnvLayer(requestEnv, cwd, plugin) {
     return { ...requestEnv, CLAUDE_PROJECT_DIR: requestEnv?.CLAUDE_PROJECT_DIR ?? cwd, ...hookPluginEnv(plugin) };
 }
-function contextVarValue(name, layer) {
-    const v = layer[name];
+function contextVarValue(name, env) {
+    const v = env[name];
     return v !== undefined && v.length > 0 ? v : undefined;
 }
-export async function planCommandSpawn(entry, cwd, requestEnv) {
+export async function planCommandSpawn(entry, cwd, requestEnv, childEnvOf) {
     const texts = [entry.command, ...(entry.args ?? [])];
     const p = entry.plugin;
     const env = composeHookEnvLayer(requestEnv, cwd, p);
+    let seen;
+    try {
+        seen = childEnvOf(env);
+    }
+    catch (e) {
+        return { kind: "refused", error: e instanceof Error ? e.message : String(e) };
+    }
     const values = new Map([["CLAUDE_PROJECT_DIR", env.CLAUDE_PROJECT_DIR]]);
     for (const [name, ref] of CONTEXT_VARS) {
-        const value = contextVarValue(name, env);
+        const value = contextVarValue(name, seen);
         if (value !== undefined) {
             values.set(name, value);
             continue;
@@ -79,8 +86,8 @@ export async function planCommandSpawn(entry, cwd, requestEnv) {
         return {
             kind: "refused",
             error: p !== undefined
-                ? `hook command references ${ref} but only ${ROOT_REF} is available for this hook (it carries no plugin data directory and the request settings.env does not set ${name})`
-                : `hook command references ${ref} but the hook is not associated with a plugin and the request settings.env does not set ${name} (the variable is only available to hooks that carry a plugin context, or to a request that sets it in settings.env)`,
+                ? `hook command references ${ref} but only ${ROOT_REF} is available for this hook (it carries no plugin data directory and the hook environment does not set ${name}; a request can set it in settings.env)`
+                : `hook command references ${ref} but the hook is not associated with a plugin and the hook environment does not set ${name} (the variable is set for hooks that carry a plugin context; a request can set it in settings.env)`,
         };
     }
     if (p !== undefined) {

package/dist/hooks/hook-runner.d.ts

@@ -533,6 +533,11 @@ export interface HookRunnerContext {
      * `[]` = 没有层写名单(不限,与引擎外的参照实现「名单未设 ⇒ 不限」同读)。今天唯一的层来源是请求的 `settings`(`task-settings.ts` 的 `httpHookAllowlist`,源 `flagSettings`)。
      */
     httpHookAllowlistLayers: readonly HttpHookAllowlistLayer[];
+    /**
+     * 部署方点名放回 hook 环境的服务进程变量名(`HOOK_ENV_ALLOW` 的生效名单,`config.hookEnvAllow`;读者 = {@link hookChildEnv} 的两个入口:命令腿 spawn 与 http 插值)。必填:每个装配点都要说 ——
+     * `[]` = 不放回(hook 环境 = 十二名基础名单 + 有效环境层)。这是服务进程变量进 hook 环境的**唯一**来源;请求层(条目 `allowedEnvVars`、`settings.httpHookAllowedEnvVars`)只收窄、不授予。
+     */
+    hookEnvAllow: readonly string[];
     /**
      * 部署座在**任务座之下**挂了链成员的站点式样(引擎的准入记录读出,`boot/deployment-mods.ts` 的 `belowTaskChainPatternsOf`)。必填:每个装配点都要说 ——
      * `[]` = 任务座之下没有部署座的链成员(部署注册只在任务座之上、只有观察者,或没有部署注册)。读者 = PreToolUse 翻译的只许收紧({@link chainsBelowTaskOn};请求钩子两条车道在这些站上只许收紧)。