@sema-agent/settings-schema 17.2.0 → 19.0.0

package/dist/config-fns.d.ts

@@ -570,6 +570,7 @@ export declare const DOMAIN_READ_FALLBACK: {
     readonly projects: "throw";
     readonly prompts: "default";
     readonly limits: "throw";
+    readonly a2a: "default";
 };
 /** Per-domain ENTRY-SALVAGE policy (12.3.0, S-1494) — may the view-face domain reader ({@link parseDomainSalvaged}) drop single bad
  *  entries (an array element, a Record value, and — recursively — a bad entry inside a surviving entry) and read the rest?
@@ -605,7 +606,10 @@ export declare const DOMAIN_READ_FALLBACK: {
  *    - governance: NONE — a dropped commandPolicy / approvalRequire row is a guardrail silently gone (放权,不许).
  *    - entitlement: NONE — a dropped tier / subject / binding / budget group changes who may do what (放权,不许).
  *    - execution: NONE — a dropped lane / public key changes the execution mandate (放权,不许).
- *    - limits: NONE — a dropped allowlist row changes a published ceiling (the domain is the one publishing seat of those ceilings). */
+ *    - limits: NONE — a dropped allowlist row changes a published ceiling (the domain is the one publishing seat of those ceilings).
+ *    - a2a: SALVAGE (18.0.0) — the peer roster is a capability catalog like mcp: a dropped peer is one remote agent fewer. A peer's
+ *      credential references (`headerRefs`) are in {@link ATOMIC_SALVAGE}: a bad reference drops the whole peer, never the reference
+ *      alone (a peer kept with half of its credentials is the wrong failure direction). */
 export declare const DOMAIN_ENTRY_SALVAGE: {
     readonly models: "salvage";
     readonly rosters: "none";
@@ -623,6 +627,7 @@ export declare const DOMAIN_ENTRY_SALVAGE: {
     readonly projects: "salvage";
     readonly prompts: "none";
     readonly limits: "none";
+    readonly a2a: "salvage";
 };
 /** 一个读者向店要文档的口:配置域,以及墓碑表里的retired 域({@link RETIRED_DOMAINS})—— 后者只为让墓碑看见没迁的旧文档。 */
 export type StoredDocumentReader = (d: DomainName | RetiredDomainName) => unknown;

package/dist/config-fns.js

@@ -23,7 +23,7 @@ import { isJsonArray, isPlainJsonObject, jsonShapeOf } from "./plain-json-object
 import { carriesUserinfo, secretScanForms } from "./secret-scan.js"; // package-private normalization (both scanners read it) + the userinfo judgement (not in the barrel)
 import { sha256Hex } from "./sha256.js";
 import { unwrapSchema } from "./zod-unwrap.js"; // package-private: the ONE reading of zod's wrapper layers (salvage + the one-time migrations share it)
-import { DOMAIN_SCHEMAS, InfraCostRates, LimitsConfig, PRIVATE_KEY_PEM_HEADER, RETIRED_DOMAINS, SkillsManifestSchema, containsSecretToken, isDomainName, isRetiredDomainName, renderQuotedSentence, retiredDomainSentence } from "./types.js";
+import { ATOMIC_SALVAGE, DOMAIN_SCHEMAS, InfraCostRates, LimitsConfig, PRIVATE_KEY_PEM_HEADER, RETIRED_DOMAINS, SkillsManifestSchema, containsSecretToken, isDomainName, isRetiredDomainName, renderQuotedSentence, retiredDomainSentence } from "./types.js";
 /** Redact secret-shaped tokens from a validation MESSAGE — a zod error echoes the offending value (e.g.
  *  `received 'sk-live-…'`), so a secret pasted into the WRONG field would leak via the error string. Redacts
  *  space-spanning auth credentials (`Bearer <token>`) FIRST (the token pass can't see across the space), then
@@ -197,6 +197,10 @@ export const DOMAIN_WRITE_ROLE = {
     // limits (0.19.0): editor —— 与它的前身 runtime 域(11.0.0 retired)同档,刻意不抬 publisher:本域是纯数值
     // 旋钮,无 prompt 注入面、无凭据、无可执行内容;真正的执法点在消费方的限额闸,发布闸(PUBLISH_MODE /
     // 审批流)才是"要不要多一道人"的属主。default 即 editor,故不列条目;此注释即该裁定的落点。
+    // a2a (18.0.0): a peer is a remote agent whose skills are mounted into the agent's tool surface, plus the env-NAMEs that
+    // carry its credentials — the same executable-surface + credential-reference profile as mcp, so the same raised gate.
+    // Written out (not left to the default) because the default would be the WRONG answer here.
+    a2a: "publisher",
 };
 /** The minimum role required to write `domain` (the raised gate for skills/mcp, else editor). */
 export function domainWriteRole(domain) {
@@ -495,6 +499,9 @@ function salvageLayerUnsafe(schema, raw) {
     const patch = {};
     for (const [field, fieldSchema] of Object.entries(shape)) {
         const collection = unwrapSchema(fieldSchema);
+        // 凭据引用集合(按 schema 身份,见 ATOMIC_SALVAGE)不下钻:它是一个值,坏一项 ⇒ 它所属的条目在上一层整条判不过、整条丢。
+        if (ATOMIC_SALVAGE.has(collection))
+            continue;
         const isArray = collection instanceof z.ZodArray;
         if (!isArray && !(collection instanceof z.ZodRecord))
             continue; // 不是条目集合:连读都不读(少触发一次访问器)
@@ -1006,6 +1013,8 @@ export const DOMAIN_READ_FALLBACK = {
     // 降级成空域 = 中央发布的成本/限流天花板整片蒸发,消费方回自己的 env 底(可能宽得多)= 预算轴放权。
     // 消费方 fail-static 在上一份好配置严格更好。
     limits: "throw",
+    // a2a(18.0.0):能力目录(同 mcp)—— 整域读不进 ⇒ 空名册 = 不拨任何对端(能力消失,fail-closed;没有闸因此丢掉)。
+    a2a: "default",
 };
 /** Per-domain ENTRY-SALVAGE policy (12.3.0, S-1494) — may the view-face domain reader ({@link parseDomainSalvaged}) drop single bad
  *  entries (an array element, a Record value, and — recursively — a bad entry inside a surviving entry) and read the rest?
@@ -1041,7 +1050,10 @@ export const DOMAIN_READ_FALLBACK = {
  *    - governance: NONE — a dropped commandPolicy / approvalRequire row is a guardrail silently gone (放权,不许).
  *    - entitlement: NONE — a dropped tier / subject / binding / budget group changes who may do what (放权,不许).
  *    - execution: NONE — a dropped lane / public key changes the execution mandate (放权,不许).
- *    - limits: NONE — a dropped allowlist row changes a published ceiling (the domain is the one publishing seat of those ceilings). */
+ *    - limits: NONE — a dropped allowlist row changes a published ceiling (the domain is the one publishing seat of those ceilings).
+ *    - a2a: SALVAGE (18.0.0) — the peer roster is a capability catalog like mcp: a dropped peer is one remote agent fewer. A peer's
+ *      credential references (`headerRefs`) are in {@link ATOMIC_SALVAGE}: a bad reference drops the whole peer, never the reference
+ *      alone (a peer kept with half of its credentials is the wrong failure direction). */
 export const DOMAIN_ENTRY_SALVAGE = {
     models: "salvage",
     rosters: "none",
@@ -1059,6 +1071,7 @@ export const DOMAIN_ENTRY_SALVAGE = {
     projects: "salvage",
     prompts: "none",
     limits: "none",
+    a2a: "salvage",
 };
 /**
  * Merge every domain into the effective config a consumer pulls. Shared by all store impls.
@@ -1111,6 +1124,7 @@ export function buildEffective(version, getRaw, updatedAt, onWarning) {
         // `{}` 不下发中心层,default 不扩权)。
         prompts: parseOr("prompts", getRaw("prompts")),
         limits: parseOr("limits", getRaw("limits")),
+        a2a: parseOr("a2a", getRaw("a2a")),
     };
 }
 /** READ-side tolerant judgment for a GET /effective **wire payload**(the {@link EffectiveWire} contract)at

package/dist/execution-lanes.d.ts

@@ -1,6 +1,6 @@
 /**
- * 执行车道 + 存储后端的**词表正本**(7.0.0,M-R2 WorkerSpec 结构块)。纯数据常量,外加两只纯判官函数(退役车道词的拒句 `retiredLaneWordRefusal`、
- * 车道坐标的空白判官 `isBlankCoordinate`),零依赖(叶模块:本文件不 import 任何东西,`types.ts` 反过来引它)。
+ * 执行车道 + 存储后端的**词表正本**(7.0.0,M-R2 WorkerSpec 结构块)。纯数据常量,外加三只纯判官函数(退役车道词的拒句 `retiredLaneWordRefusal`、
+ * 车道坐标的空白判官 `isBlankCoordinate`、车道表合法性的唯一判官 `laneSetFlaws`〔18.0.0〕),零依赖(叶模块:本文件不 import 任何东西,`types.ts` 反过来引它)。
  *
  * ## 为什么在这里
  * 车道词、每条车道读哪些 env、哪条车道分租户、存储后端词 —— 这几张表以前在四处各抄一份(引擎的能力表、
@@ -12,8 +12,8 @@
  * 写闸与起服读同一张表 ⇒ 不会分叉。
  *
  * ## 行内容的出处(逐行抄自引擎真码,坐标 = server 7.112.0 树)
- *  · 车道词与次序:`src/execution-lane-caps.ts` `EXECUTION_LANE_WORDS`(:335)去掉 `in-process` =
- *    `REMOTE_EXEC_PROVIDER_WORDS`(:366)。次序照抄,于是引擎改派生之后,拒启句里的 `valid:` 列表与出路列表逐字不变。
+ *  · 车道词与次序:前七词抄自 `src/execution-lane-caps.ts` `REMOTE_EXEC_PROVIDER_WORDS`(:366)。次序照抄,于是引擎改派生之后,拒启句里的 `valid:` 列表与出路列表逐字不变。
+ *    `none`(18.0.0)尾插:它的出处就是本表(见下「`none`」一节),引擎提货本版后从本表派生词表与拒句。
  *  · `tenantSeparation`:同文件 `executionLaneCaps` 每臂的 `tenantSeparation` 位(:209 host / :230 e2b / :249 k8s /
  *    :269 ssh / :288 adb / :308 local-docker / :327 device)。`tenantSeparationBasis`(11.0.0):分租户的那几臂凭什么分 ——
  *    e2b / k8s / local-docker 每任务一只隔离目标(`isolation`),device 是发起者自己的设备(`principal-binding`)。
@@ -30,15 +30,22 @@
  *    收进车道栏会把它们保留成「k8s 专属」,别的车道就再也设不了快照对象存储。也**不收**臂外的适配器调参键
  *    (`HOST_BG_*` / `E2B_BG_*` / `K8S_BG_*` / `HOST_SHELL_PATH` …):它们不是车道坐标,照旧走 `env` 逃生口。
  *
+ * ## `none`:不给智能体的工具提供执行环境(18.0.0)
+ * 每个部署都点名自己的执行车道;没有执行环境的部署点名 `none` —— 这是一个声明,不是「没写车道」的副作用。用户面可观察的事实:
+ *  · 每个 run:工具的手不挂(两个执行环境座都缺席;引擎的装配清单报 hands 未挂、原因是没有执行环境);
+ *  · 部署级:执行车道读数是 `none`、工具不在本机执行、没有隔离读数;引擎能力表的 `none` 行除分租户外整排不支持;
+ *  · 分租户(依据 `no-execution-target`):没有执行目标,也就没有跨租户共享的目标;不挂在副本上(`singleReplica: false`);四栏 env 全空(没有要配的坐标与密钥);
+ *  · 只能独成一集:含依据为 `no-execution-target` 的车道的车道表恰好一项 —— 判官 {@link laneSetFlaws} 按依据列判(拒因 `not_alone`),不点名车道词。
+ * 不在它的射程内(各有自己的属主轴,不随车道):请求体里的 hook 命令条目与 stdio MCP 服务器条目在 worker 宿主上起进程,它们的闸是多租户姿态 / 锁键 / 合规档。
+ * 它取代引擎内部「没有声明车道」那个状态的名字 `in-process`(那从来不是可声明的词,本表也从未收过);引擎侧的改名随它提货本版的那一版。
+ *
  * ## 不在表里的词
- *  · `in-process`:引擎内部「没有 remoteExec」这个状态的名字,不是可声明的车道 —— 显式「无手」的 worker 在模型要用工具时
- *    仍回 completed + 零工具,就是那个病换了个合法名字。要无手 worker 先另立设计、定用户面行为再给词。
  *  · `remote-docker`:引擎有一只没接线的适配器工厂,但没有任何读点能把这个词变成一条在跑的车道
  *    (`REMOTE_EXEC=remote-docker` 起服即拒;远端 docker 守护进程今天的真形 = `local-docker` + `DOCKER_HOST`)。
  *    它在退役词墓碑 {@link RETIRED_LANE_WORDS} 里:读到即拒,拒句带出路。
  */
-/** 可声明的执行车道闭集(= 引擎 `REMOTE_EXEC` 收的词,逐字同序)。 */
-export declare const EXECUTION_LANE_WORDS: readonly ["host", "e2b", "k8s", "ssh", "adb", "local-docker", "device"];
+/** 可声明的执行车道闭集(= 引擎 `REMOTE_EXEC` 收的词,逐字同序;18.0.0 尾插 `none`)。 */
+export declare const EXECUTION_LANE_WORDS: readonly ["host", "e2b", "k8s", "ssh", "adb", "local-docker", "device", "none"];
 export type ExecutionLane = (typeof EXECUTION_LANE_WORDS)[number];
 /**
  * 已退役的车道**值** —— 墓碑(与退役 env 名的墓碑表 `RETIRED_ENVS` 同一条线:永久、只增不减、一跳 —— 去向恒是现行车道词)。
@@ -53,9 +60,10 @@ export declare function retiredLaneWordRefusal(word: unknown): string | undefine
  *  `supported` = 每个租户的命令落在各自的目标上;`single-user-only` = 所有任务落同一个共享目标 ⇒ 只许单用户 worker。 */
 export declare const TENANT_SEPARATION_WORDS: readonly ["supported", "single-user-only"];
 export type TenantSeparation = (typeof TENANT_SEPARATION_WORDS)[number];
-/** 分租户车道**凭什么**分租户(两档):`isolation` = 每个任务一只隔离的目标(microVM / pod / 容器);`principal-binding` = 目标绑在
- *  发起者身上(设备 ↔ principal 绑定),目标本身不隔离。只有 `tenantSeparation: "supported"` 的车道有依据。 */
-export declare const TENANT_SEPARATION_BASES: readonly ["isolation", "principal-binding"];
+/** 分租户车道**凭什么**分租户(三档):`isolation` = 每个任务一只隔离的目标(microVM / pod / 容器);`principal-binding` = 目标绑在
+ *  发起者身上(设备 ↔ principal 绑定),目标本身不隔离;`no-execution-target`(18.0.0)= 根本没有执行目标(工具没有执行环境),也就没有跨租户共享的目标 ——
+ *  这一档还带一条集合规则:含这档车道的车道表只能有它这一项(判官 {@link laneSetFlaws} 读这一列)。只有 `tenantSeparation: "supported"` 的车道有依据。 */
+export declare const TENANT_SEPARATION_BASES: readonly ["isolation", "principal-binding", "no-execution-target"];
 export type TenantSeparationBasis = (typeof TENANT_SEPARATION_BASES)[number];
 /** 车道的租户分离位与它的依据 —— 判别联合:分租户 ⇔ 依据在场(类型保证,不靠一句注释)。消费方的规则读依据列,不点名车道。 */
 export type LaneTenancy = {
@@ -78,6 +86,102 @@ export type ExecutionLaneRow = {
     readonly optionalEnv: readonly string[];
     readonly optionalSecretEnv: readonly string[];
 } & LaneTenancy;
+/** 逐车道一行。`satisfies Record<ExecutionLane, …>` = 词表加词而这里不加行 ⇒ 编译红。 */
+declare const LANE_ROWS: {
+    /** server `config.ts` :4014 臂(无必需键);`execution-lane-caps.ts` :209 `single-user-only`(所有任务落 worker 宿主)。 */
+    readonly host: {
+        readonly tenantSeparation: "single-user-only";
+        readonly singleReplica: true;
+        readonly requiredEnv: readonly [];
+        readonly requiredSecretEnv: readonly [];
+        readonly optionalEnv: readonly ["HOST_WORKSPACE_BASE", "HOST_COMMAND_TIMEOUT_MS"];
+        readonly optionalSecretEnv: readonly [];
+    };
+    /** server `config.ts` :3925 臂;`E2B_API_KEY` 目录 :351 类型 `secret`、`E2B_SANDBOX_ENV` :359 类型 `secret`;
+     *  `execution-lane-caps.ts` :230 `supported`(每任务一只 microVM)。 */
+    readonly e2b: {
+        readonly tenantSeparation: "supported";
+        readonly tenantSeparationBasis: "isolation";
+        readonly singleReplica: false;
+        readonly requiredEnv: readonly [];
+        readonly requiredSecretEnv: readonly ["E2B_API_KEY"];
+        readonly optionalEnv: readonly ["E2B_TEMPLATE", "E2B_TIMEOUT_MS", "E2B_LIVENESS_MS", "E2B_ALLOW_NET", "E2B_MOUNT_PATH", "E2B_ORPHAN_RECLAIM"];
+        readonly optionalSecretEnv: readonly ["E2B_SANDBOX_ENV"];
+    };
+    /** server `config.ts` :3957 臂;`K8S_TOKEN` 目录 :412 类型 `secret`、`K8S_CA_CERT_B64` :403 类型 `opaque`;
+     *  `execution-lane-caps.ts` :249 `supported`(每任务一只 pod)。`MINIO_*` 刻意不收(见文件头)。
+     *  `K8S_NAMESPACE`(沙箱 pod 所在的命名空间)是**必需**坐标:pod 住哪是部署自己的声明,表不替它留缺省;服务端的必需 env 门按本行 `requiredEnv` 拒启,
+     *  所以这里没有「可选」一说。 */
+    readonly k8s: {
+        readonly tenantSeparation: "supported";
+        readonly tenantSeparationBasis: "isolation";
+        readonly singleReplica: false;
+        readonly requiredEnv: readonly ["K8S_SANDBOX_IMAGE", "K8S_NAMESPACE"];
+        readonly requiredSecretEnv: readonly [];
+        readonly optionalEnv: readonly ["K8S_API_URL", "K8S_INSECURE_TLS", "K8S_RUNTIME_CLASS", "K8S_MOUNT_PATH", "K8S_TIMEOUT_MS", "K8S_MEMORY", "K8S_CPU", "WORKSPACE_SNAPSHOT_BUCKET", "WORKSPACE_SNAPSHOT_PREFIX", "WORKSPACE_SNAPSHOT_TTL_SEC"];
+        readonly optionalSecretEnv: readonly ["K8S_TOKEN", "K8S_CA_CERT_B64"];
+    };
+    /** server `config.ts` :3991 臂 + `parseSshHostKeyEnv` :1521;`SSH_PRIVATE_KEY` 目录 :687 类型 `secret`;
+     *  `execution-lane-caps.ts` :269 `single-user-only`(一台跨任务共享的常驻真机)。 */
+    readonly ssh: {
+        readonly tenantSeparation: "single-user-only";
+        readonly singleReplica: false;
+        readonly requiredEnv: readonly ["SSH_HOST", "SSH_USER"];
+        readonly requiredSecretEnv: readonly ["SSH_PRIVATE_KEY"];
+        readonly optionalEnv: readonly ["SSH_PORT", "SSH_MOUNT_PATH", "SSH_HOST_FINGERPRINT", "SSH_KNOWN_HOSTS"];
+        readonly optionalSecretEnv: readonly [];
+    };
+    /** server `config.ts` :4006 臂;`execution-lane-caps.ts` :288 `single-user-only`(一台跨任务共享的设备)。 */
+    readonly adb: {
+        readonly tenantSeparation: "single-user-only";
+        readonly singleReplica: false;
+        readonly requiredEnv: readonly ["ADB_SERIAL"];
+        readonly requiredSecretEnv: readonly [];
+        readonly optionalEnv: readonly ["ADB_PATH", "ADB_MOUNT_PATH"];
+        readonly optionalSecretEnv: readonly [];
+    };
+    /** server `config.ts` :4026 臂;`DOCKER_SANDBOX_ENV` 目录 :345 类型 `secret`;`execution-lane-caps.ts` :308 `supported`
+     *  (每任务一只容器)。`DOCKER_HOST` 在本行:远端 docker 守护进程 = 本车道 + `coords.DOCKER_HOST`。 */
+    readonly "local-docker": {
+        readonly tenantSeparation: "supported";
+        readonly tenantSeparationBasis: "isolation";
+        readonly singleReplica: false;
+        readonly requiredEnv: readonly ["DOCKER_IMAGE"];
+        readonly requiredSecretEnv: readonly [];
+        readonly optionalEnv: readonly ["DOCKER_MOUNT_PATH", "DOCKER_PATH", "DOCKER_HOST", "DOCKER_MEMORY", "DOCKER_CPUS", "DOCKER_PIDS_LIMIT", "DOCKER_DROP_CAPS", "DOCKER_NETWORK", "DOCKER_COMMAND_TIMEOUT_MS"];
+        readonly optionalSecretEnv: readonly ["DOCKER_SANDBOX_ENV"];
+    };
+    /** server `config.ts` :4055 臂 + `parseDevicePreAuthPerRemoteEnv` :871 / `parseDeviceEnrollTokenTtlEnv` :857;`execution-lane-caps.ts` :327
+     *  `supported`(发起者自己的设备)。16.0.0:`DEVICE_RELAY_URL`(设备拨哪里)是**必需**坐标 —— 引擎的 device 臂缺它即拒启
+     *  (`parseDeviceRelayUrlEnv`;此前它是 device 臂读而本表漏登记的键),值只有两种:ws(s) 绝对 URL 或字面 `none`(值的文法见 `./device-relay`)。
+     *  17.1.0:`DEVICE_TRUSTED_PROXY_CIDRS`(可选)= 设备 WS 未鉴权握手 per-remote 帽键的可信代理名单(CIDR 闭集,缺省空 = 不读任何代理头);值文法由引擎起服判。 */
+    readonly device: {
+        readonly tenantSeparation: "supported";
+        readonly tenantSeparationBasis: "principal-binding";
+        readonly singleReplica: true;
+        readonly requiredEnv: readonly ["DEVICE_RELAY_URL"];
+        readonly requiredSecretEnv: readonly [];
+        readonly optionalEnv: readonly ["DEVICE_DELIVERY_TIMEOUT_MS", "DEVICE_RECONNECT_GRACE_MS", "DEVICE_EXEC_TIMEOUT_MS", "DEVICE_MAX_INFLIGHT_PER_DEVICE", "DEVICE_MAX_PREAUTH_PER_REMOTE", "DEVICE_ENROLL_TOKEN_TTL_SEC", "DEVICE_TRUSTED_PROXY_CIDRS", "DEVICE_SUPERSEDE"];
+        readonly optionalSecretEnv: readonly [];
+    };
+    /** 18.0.0:没有执行环境(见文件头「`none`」一节)。分租户,依据 `no-execution-target`(没有执行目标,就没有跨租户共享的目标);不挂在副本上;
+     *  四栏全空(没有要配的坐标与密钥)。本行先于引擎:引擎提货本版后它的能力表 / 必需键门 / 拒句从本行派生。 */
+    readonly none: {
+        readonly tenantSeparation: "supported";
+        readonly tenantSeparationBasis: "no-execution-target";
+        readonly singleReplica: false;
+        readonly requiredEnv: readonly [];
+        readonly requiredSecretEnv: readonly [];
+        readonly optionalEnv: readonly [];
+        readonly optionalSecretEnv: readonly [];
+    };
+};
+/** 依据为 `no-execution-target` 的车道(型从表行的依据列派生,不点名车道词;今天 = `none`):声明了它的车道表只能有它这一项。 */
+export type StandaloneLane = {
+    [L in ExecutionLane]: (typeof LANE_ROWS)[L] extends {
+        readonly tenantSeparationBasis: "no-execution-target";
+    } ? L : never;
+}[ExecutionLane];
 /** 车道表(次序 = {@link EXECUTION_LANE_WORDS})。整张表深冻结 —— 它是唯一正本,消费方拿到的不许被改。 */
 export declare const EXECUTION_LANES: readonly ExecutionLaneRow[];
 /**
@@ -90,6 +194,48 @@ export declare const EXECUTION_LANES: readonly ExecutionLaneRow[];
  * 车道表的派生索引与写闸也从这里 import,全包只有这一处函数体。
  */
 export declare function isBlankCoordinate(value: string): boolean;
+/**
+ * 一张车道表**不合法**的拒因 —— 闭集,判别字段 `kind`(消费方穷举 `switch`:加一种拒因 ⇒ 消费方编译红,不会静默落进「别的」)。`at` = 那一项在表里的下标(从 0 起)。
+ *  · `empty_set`:表是空的(一项都没有);
+ *  · `blank_entry`:那一项是空串或只含空白(判官 {@link isBlankCoordinate});
+ *  · `unknown`:那一项不是车道词({@link EXECUTION_LANE_WORDS};逐字比:不 trim、不折大小写),也不是车道值墓碑里的旧词 —— 包括根本不是字符串的项(数、`null`、对象 …:
+ *    读 JSON 的写闸会见到;`word` 是那一项的原值,判官只比较、不读它的任何属性,渲染给人看时由调用方自己描述它的形);
+ *  · `retired`:那一项是车道值墓碑 {@link RETIRED_LANE_WORDS} 里的旧词(出路取 {@link retiredLaneWordRefusal},一句);
+ *  · `duplicate`:那一项是车道词,但表里更早已经有它了(报在第二次及以后出现的那一格;不是车道词的重复不报这一条 —— 它们各自已是拒因);
+ *  · `not_alone`(18.0.0):表里有独占车道({@link StandaloneLane},依据列为 `no-execution-target`),却还有不是它的项 —— 独占车道只能独成一集。
+ *    这是整张表的拒因(没有 `at`);独占车道自己的重复只报 `duplicate`。
+ */
+export type LaneSetFlaw = {
+    readonly kind: "empty_set";
+} | {
+    readonly kind: "blank_entry";
+    readonly at: number;
+} | {
+    readonly kind: "unknown";
+    readonly at: number;
+    readonly word: unknown;
+} | {
+    readonly kind: "retired";
+    readonly at: number;
+    readonly word: string;
+} | {
+    readonly kind: "duplicate";
+    readonly at: number;
+    readonly lane: ExecutionLane;
+} | {
+    readonly kind: "not_alone";
+    readonly lane: StandaloneLane;
+};
+/** 车道表的规则句(不含值,与 `DEVICE_RELAY_RULE` 同形):写闸的拒句、引擎的拒启句、表单的提示读这一句,句子只在这里写。 */
+export declare const LANE_SET_RULE: string;
+/**
+ * 车道表合不合法的**唯一判官**:合法 ⇒ `[]`;否则按表的次序交回每一条拒因({@link LaneSetFlaw})。纯函数,不抛。
+ * 谁问它:写闸(`WorkerSpec` 的 `runtime.execution.lanes`)逐条映射成 issue;引擎把 `REMOTE_EXEC` 按逗号切段后交给它(引擎只留切段);web-admin 表单同问。
+ * 入参是任意值的表(读 JSON 的写闸原样交进来;引擎切段后交的是字符串):不是字符串的项不是车道词 ⇒ `unknown`,与写错的词同一条拒因 —— 「每一项都是车道词」只有这一处判。
+ * 按下标读(`0 … length-1`):稀疏表的空洞读成 `undefined`,是一项不是字符串的项 —— 与写闸的下标快照同答(`forEach` / `some` 会跳过空洞)。
+ * 只判「这张表合不合法」;每条车道缺不缺必需坐标、本引擎版本服务不服务这条车道,是调用方各自的门。
+ */
+export declare function laneSetFlaws(lanes: readonly unknown[]): readonly LaneSetFlaw[];
 /** 存储后端(→ `DB_BACKEND`)。= server `src/config-types.ts` `DB_BACKEND_WORDS`(:67)逐字同序。 */
 export declare const STORE_BACKENDS: readonly ["mysql", "pg", "local", "memory"];
 export type StoreBackend = (typeof STORE_BACKENDS)[number];
@@ -101,3 +247,4 @@ export type SessionBackend = (typeof SESSION_BACKENDS)[number];
  *  收成一个字,与 {@link STORE_BACKENDS} 同字;硬破坏,`tidb` 读写两面拒、指路一次性迁移 SS-M12)。次序 file → pg → mysql。 */
 export declare const MEMORY_ENGINE_BACKENDS: readonly ["file", "pg", "mysql"];
 export type MemoryEngineBackend = (typeof MEMORY_ENGINE_BACKENDS)[number];
+export {};

package/dist/execution-lanes.js

@@ -1,6 +1,6 @@
 /**
- * 执行车道 + 存储后端的**词表正本**(7.0.0,M-R2 WorkerSpec 结构块)。纯数据常量,外加两只纯判官函数(退役车道词的拒句 `retiredLaneWordRefusal`、
- * 车道坐标的空白判官 `isBlankCoordinate`),零依赖(叶模块:本文件不 import 任何东西,`types.ts` 反过来引它)。
+ * 执行车道 + 存储后端的**词表正本**(7.0.0,M-R2 WorkerSpec 结构块)。纯数据常量,外加三只纯判官函数(退役车道词的拒句 `retiredLaneWordRefusal`、
+ * 车道坐标的空白判官 `isBlankCoordinate`、车道表合法性的唯一判官 `laneSetFlaws`〔18.0.0〕),零依赖(叶模块:本文件不 import 任何东西,`types.ts` 反过来引它)。
  *
  * ## 为什么在这里
  * 车道词、每条车道读哪些 env、哪条车道分租户、存储后端词 —— 这几张表以前在四处各抄一份(引擎的能力表、
@@ -12,8 +12,8 @@
  * 写闸与起服读同一张表 ⇒ 不会分叉。
  *
  * ## 行内容的出处(逐行抄自引擎真码,坐标 = server 7.112.0 树)
- *  · 车道词与次序:`src/execution-lane-caps.ts` `EXECUTION_LANE_WORDS`(:335)去掉 `in-process` =
- *    `REMOTE_EXEC_PROVIDER_WORDS`(:366)。次序照抄,于是引擎改派生之后,拒启句里的 `valid:` 列表与出路列表逐字不变。
+ *  · 车道词与次序:前七词抄自 `src/execution-lane-caps.ts` `REMOTE_EXEC_PROVIDER_WORDS`(:366)。次序照抄,于是引擎改派生之后,拒启句里的 `valid:` 列表与出路列表逐字不变。
+ *    `none`(18.0.0)尾插:它的出处就是本表(见下「`none`」一节),引擎提货本版后从本表派生词表与拒句。
  *  · `tenantSeparation`:同文件 `executionLaneCaps` 每臂的 `tenantSeparation` 位(:209 host / :230 e2b / :249 k8s /
  *    :269 ssh / :288 adb / :308 local-docker / :327 device)。`tenantSeparationBasis`(11.0.0):分租户的那几臂凭什么分 ——
  *    e2b / k8s / local-docker 每任务一只隔离目标(`isolation`),device 是发起者自己的设备(`principal-binding`)。
@@ -30,15 +30,22 @@
  *    收进车道栏会把它们保留成「k8s 专属」,别的车道就再也设不了快照对象存储。也**不收**臂外的适配器调参键
  *    (`HOST_BG_*` / `E2B_BG_*` / `K8S_BG_*` / `HOST_SHELL_PATH` …):它们不是车道坐标,照旧走 `env` 逃生口。
  *
+ * ## `none`:不给智能体的工具提供执行环境(18.0.0)
+ * 每个部署都点名自己的执行车道;没有执行环境的部署点名 `none` —— 这是一个声明,不是「没写车道」的副作用。用户面可观察的事实:
+ *  · 每个 run:工具的手不挂(两个执行环境座都缺席;引擎的装配清单报 hands 未挂、原因是没有执行环境);
+ *  · 部署级:执行车道读数是 `none`、工具不在本机执行、没有隔离读数;引擎能力表的 `none` 行除分租户外整排不支持;
+ *  · 分租户(依据 `no-execution-target`):没有执行目标,也就没有跨租户共享的目标;不挂在副本上(`singleReplica: false`);四栏 env 全空(没有要配的坐标与密钥);
+ *  · 只能独成一集:含依据为 `no-execution-target` 的车道的车道表恰好一项 —— 判官 {@link laneSetFlaws} 按依据列判(拒因 `not_alone`),不点名车道词。
+ * 不在它的射程内(各有自己的属主轴,不随车道):请求体里的 hook 命令条目与 stdio MCP 服务器条目在 worker 宿主上起进程,它们的闸是多租户姿态 / 锁键 / 合规档。
+ * 它取代引擎内部「没有声明车道」那个状态的名字 `in-process`(那从来不是可声明的词,本表也从未收过);引擎侧的改名随它提货本版的那一版。
+ *
  * ## 不在表里的词
- *  · `in-process`:引擎内部「没有 remoteExec」这个状态的名字,不是可声明的车道 —— 显式「无手」的 worker 在模型要用工具时
- *    仍回 completed + 零工具,就是那个病换了个合法名字。要无手 worker 先另立设计、定用户面行为再给词。
  *  · `remote-docker`:引擎有一只没接线的适配器工厂,但没有任何读点能把这个词变成一条在跑的车道
  *    (`REMOTE_EXEC=remote-docker` 起服即拒;远端 docker 守护进程今天的真形 = `local-docker` + `DOCKER_HOST`)。
  *    它在退役词墓碑 {@link RETIRED_LANE_WORDS} 里:读到即拒,拒句带出路。
  */
-/** 可声明的执行车道闭集(= 引擎 `REMOTE_EXEC` 收的词,逐字同序)。 */
-export const EXECUTION_LANE_WORDS = ["host", "e2b", "k8s", "ssh", "adb", "local-docker", "device"];
+/** 可声明的执行车道闭集(= 引擎 `REMOTE_EXEC` 收的词,逐字同序;18.0.0 尾插 `none`)。 */
+export const EXECUTION_LANE_WORDS = ["host", "e2b", "k8s", "ssh", "adb", "local-docker", "device", "none"];
 export const RETIRED_LANE_WORDS = Object.freeze([
     Object.freeze(["remote-docker", "local-docker", "point it at the remote docker daemon with DOCKER_HOST (in a worker spec: runtime.execution.coords.DOCKER_HOST)"]),
 ]);
@@ -50,9 +57,10 @@ export function retiredLaneWordRefusal(word) {
 /** 车道分不分租户(引擎能力表的 `tenantSeparation` 位,两档,没有「不表态」)。
  *  `supported` = 每个租户的命令落在各自的目标上;`single-user-only` = 所有任务落同一个共享目标 ⇒ 只许单用户 worker。 */
 export const TENANT_SEPARATION_WORDS = ["supported", "single-user-only"];
-/** 分租户车道**凭什么**分租户(两档):`isolation` = 每个任务一只隔离的目标(microVM / pod / 容器);`principal-binding` = 目标绑在
- *  发起者身上(设备 ↔ principal 绑定),目标本身不隔离。只有 `tenantSeparation: "supported"` 的车道有依据。 */
-export const TENANT_SEPARATION_BASES = ["isolation", "principal-binding"];
+/** 分租户车道**凭什么**分租户(三档):`isolation` = 每个任务一只隔离的目标(microVM / pod / 容器);`principal-binding` = 目标绑在
+ *  发起者身上(设备 ↔ principal 绑定),目标本身不隔离;`no-execution-target`(18.0.0)= 根本没有执行目标(工具没有执行环境),也就没有跨租户共享的目标 ——
+ *  这一档还带一条集合规则:含这档车道的车道表只能有它这一项(判官 {@link laneSetFlaws} 读这一列)。只有 `tenantSeparation: "supported"` 的车道有依据。 */
+export const TENANT_SEPARATION_BASES = ["isolation", "principal-binding", "no-execution-target"];
 /** 逐车道一行。`satisfies Record<ExecutionLane, …>` = 词表加词而这里不加行 ⇒ 编译红。 */
 const LANE_ROWS = {
     /** server `config.ts` :4014 臂(无必需键);`execution-lane-caps.ts` :209 `single-user-only`(所有任务落 worker 宿主)。 */
@@ -161,7 +169,25 @@ const LANE_ROWS = {
         ],
         optionalSecretEnv: [],
     },
+    /** 18.0.0:没有执行环境(见文件头「`none`」一节)。分租户,依据 `no-execution-target`(没有执行目标,就没有跨租户共享的目标);不挂在副本上;
+     *  四栏全空(没有要配的坐标与密钥)。本行先于引擎:引擎提货本版后它的能力表 / 必需键门 / 拒句从本行派生。 */
+    none: {
+        tenantSeparation: "supported",
+        tenantSeparationBasis: "no-execution-target",
+        singleReplica: false,
+        requiredEnv: [],
+        requiredSecretEnv: [],
+        optionalEnv: [],
+        optionalSecretEnv: [],
+    },
 };
+/** 一条车道是不是独占车道 —— 读表行的依据列(运行期判据与 {@link StandaloneLane} 的型读同一列)。 */
+function isStandaloneLane(lane) {
+    const row = LANE_ROWS[lane];
+    return row.tenantSeparation === "supported" && row.tenantSeparationBasis === "no-execution-target";
+}
+/** 独占车道,按词表次序(从依据列现算)。 */
+const STANDALONE_LANES = EXECUTION_LANE_WORDS.filter(isStandaloneLane);
 /** 车道表(次序 = {@link EXECUTION_LANE_WORDS})。整张表深冻结 —— 它是唯一正本,消费方拿到的不许被改。 */
 export const EXECUTION_LANES = Object.freeze(EXECUTION_LANE_WORDS.map((lane) => {
     const row = LANE_ROWS[lane];
@@ -188,6 +214,45 @@ export const EXECUTION_LANES = Object.freeze(EXECUTION_LANE_WORDS.map((lane) =>
 export function isBlankCoordinate(value) {
     return value.trim() === "";
 }
+/** 车道表的规则句(不含值,与 `DEVICE_RELAY_RULE` 同形):写闸的拒句、引擎的拒启句、表单的提示读这一句,句子只在这里写。 */
+export const LANE_SET_RULE = `must be a non-empty list — the ordered execution lane set (the first one is the default) of ${EXECUTION_LANE_WORDS.join(" | ")}, each at most once; a lane set with no execution environment for the agent's tools is ${STANDALONE_LANES.map((lane) => `[${JSON.stringify(lane)}]`).join(" or ")}, alone`;
+/**
+ * 车道表合不合法的**唯一判官**:合法 ⇒ `[]`;否则按表的次序交回每一条拒因({@link LaneSetFlaw})。纯函数,不抛。
+ * 谁问它:写闸(`WorkerSpec` 的 `runtime.execution.lanes`)逐条映射成 issue;引擎把 `REMOTE_EXEC` 按逗号切段后交给它(引擎只留切段);web-admin 表单同问。
+ * 入参是任意值的表(读 JSON 的写闸原样交进来;引擎切段后交的是字符串):不是字符串的项不是车道词 ⇒ `unknown`,与写错的词同一条拒因 —— 「每一项都是车道词」只有这一处判。
+ * 按下标读(`0 … length-1`):稀疏表的空洞读成 `undefined`,是一项不是字符串的项 —— 与写闸的下标快照同答(`forEach` / `some` 会跳过空洞)。
+ * 只判「这张表合不合法」;每条车道缺不缺必需坐标、本引擎版本服务不服务这条车道,是调用方各自的门。
+ */
+export function laneSetFlaws(lanes) {
+    if (lanes.length === 0)
+        return [{ kind: "empty_set" }];
+    const flaws = [];
+    const seen = [];
+    const entries = Array.from({ length: lanes.length }, (_, at) => lanes[at]); // 按下标:空洞 ⇒ undefined(见上)
+    for (const [at, entry] of entries.entries()) {
+        if (typeof entry !== "string") {
+            flaws.push({ kind: "unknown", at, word: entry }); // 不是字符串:不是车道词(不读它的属性)
+            continue;
+        }
+        if (isBlankCoordinate(entry)) {
+            flaws.push({ kind: "blank_entry", at });
+            continue;
+        }
+        const lane = EXECUTION_LANE_WORDS.find((w) => w === entry); // 裸比较让编译器收窄(不把开放串断言成闭集词)
+        if (lane !== undefined) {
+            if (seen.includes(lane))
+                flaws.push({ kind: "duplicate", at, lane });
+            else
+                seen.push(lane);
+            continue;
+        }
+        flaws.push(retiredLaneWordRefusal(entry) === undefined ? { kind: "unknown", at, word: entry } : { kind: "retired", at, word: entry });
+    }
+    for (const lane of STANDALONE_LANES)
+        if (seen.includes(lane) && entries.some((entry) => entry !== lane))
+            flaws.push({ kind: "not_alone", lane });
+    return flaws;
+}
 /** 存储后端(→ `DB_BACKEND`)。= server `src/config-types.ts` `DB_BACKEND_WORDS`(:67)逐字同序。 */
 export const STORE_BACKENDS = ["mysql", "pg", "local", "memory"];
 /** session 店(→ `SESSION_BACKEND`)。= server `src/config.ts` :1760 `enumEnv("SESSION_BACKEND", …)` 的词表逐字同序

package/dist/file-edit.d.ts

@@ -30,7 +30,7 @@ export interface RequiredEnvName {
     /** true if this env-NAME resolves in the supplied environment (.env merged over process.env). */
     present: boolean;
 }
-/** LIST every env-NAME the current local config requires (across models/workers/mcp + the
+/** LIST every env-NAME the current local config requires (across models/workers/mcp/a2a + the
  *  remote-exec backend), marking which are MISSING from the resolved env — the TOC "you still need to set
  *  these secrets" panel. Reuses collectEnvRefs for the domain side, then appends the remoteExec secret refs. */
 export declare function listRequiredEnvNames(eff: EffectiveConfig, remoteExec: RemoteExecSpec | undefined, resolvedEnv: Record<string, string | undefined>): RequiredEnvName[];

package/dist/file-edit.js

@@ -69,7 +69,7 @@ export async function writeDomainFile(root, domain, value) {
     writeFileAtomic(path.join(dir, `${domain}.json`), configDDocumentText(parsed), "config-document");
     return parsed;
 }
-/** LIST every env-NAME the current local config requires (across models/workers/mcp + the
+/** LIST every env-NAME the current local config requires (across models/workers/mcp/a2a + the
  *  remote-exec backend), marking which are MISSING from the resolved env — the TOC "you still need to set
  *  these secrets" panel. Reuses collectEnvRefs for the domain side, then appends the remoteExec secret refs. */
 export function listRequiredEnvNames(eff, remoteExec, resolvedEnv) {
@@ -108,6 +108,7 @@ export function listRequiredEnvNames(eff, remoteExec, resolvedEnv) {
             case "adb":
             case "host":
             case "local-docker":
+            case "none":
                 break; // these carry no secret env-NAME refs
             default: {
                 const unhandled = re;

package/dist/hooks-config.d.ts

@@ -52,24 +52,39 @@ export declare const HOOK_EVENTS: readonly ["PreToolUse", "PostToolUse", "PostTo
 /** One hook event name (the same union as `./hooks`' `HookEventName`, which is the zod enum over {@link HOOK_EVENTS}). */
 type HookEventWord = (typeof HOOK_EVENTS)[number];
 /**
- * The hook entry `type` closed set — CC 2.1.296's five (`cli296.js:237454`): `command` (shell command on the host that runs the hook),
+ * The hook entry `type` closed set — CC 2.1.296's five (`cli296.js:237454`): `command` (a command on the host that runs the hook: a shell command line, or — with `args` — an executable spawned directly, no shell),
  * `prompt` (one-shot LLM evaluation of the hook input), `agent` (agentic verifier loop), `http` (POST the hook input to a URL),
  * `mcp_tool` (call a tool on an already-configured MCP server). An entry of another type is a bad piece — and in a guard event that rejects
  * the whole document, which is why `test/upstream-drift.test.ts` ①b holds this set against the CC anchor snapshot.
  */
 export declare const HOOK_ENTRY_TYPES: readonly ["command", "prompt", "agent", "http", "mcp_tool"];
 export type HookEntryType = (typeof HOOK_ENTRY_TYPES)[number];
+/**
+ * The `onFailure` closed set (CC `cli309.js:252382`, `onFailure:At()`): what a FAILURE of the hook does — it could not start (a missing script), timed out, exited with a code other
+ * than 0 or 2, or printed JSON that is invalid or fails validation. `continue` (CC's default when the key is absent; this package does not fill it in — an absent key stays absent): the
+ * failure is reported and the action goes ahead. `block`: the failure counts as exit code 2, so the action the event guards is blocked. Carried by `command` and `http` entries only.
+ * CARRIED, not executed here: a consumer that reads `block` executes it or refuses it — ignoring it makes a guard that cannot start let the action through.
+ * The classifier reads this set through a closure-private projection that the compiler ties to it in both directions.
+ */
+export declare const HOOK_ON_FAILURE_WORDS: readonly ["continue", "block"];
+/** One word of {@link HOOK_ON_FAILURE_WORDS}. */
+export type HookOnFailure = (typeof HOOK_ON_FAILURE_WORDS)[number];
 /** `shell` values: 'bash' = the user's $SHELL family; 'powershell' = pwsh. Default bash. */
 declare const HOOK_SHELLS: readonly ["bash", "powershell"];
 /**
  * THE field table of a hook entry, per type — read by {@link classifyHooksConfig} (which field is bad, what is carried) and by the entry
  * types below (derived from it). Field order = the order a loaded entry's keys come out in.
- *  · command: `shell` (see above), `async` = run in background without blocking, `asyncRewake` = background + wake the model on exit 2;
+ *  · command: `args` = exec form (CC `cli309.js:252382`: when present — `[]` included — `command` is an executable spawned directly with these arguments, no shell; the mere
+ *    presence of `args` is the switch), `shell` (see above), `async` = run in background without blocking, `asyncRewake` = background + wake the model on exit 2,
+ *    `onFailure` (see {@link HOOK_ON_FAILURE_WORDS});
  *  · prompt / agent: `prompt` ($ARGUMENTS = the hook input JSON), `model`;
  *  · http: `url`, `headers` (values may reference $NAMEs listed in `allowedEnvVars` — env-NAME interpolation only, the config never carries a
- *    secret value; `interpolateHookEnvVars` is the one reading), `allowedEnvVars`;
+ *    secret value; `interpolateHookEnvVars` is the one reading), `allowedEnvVars`, `onFailure` (the other schema CC gives it to);
  *  · mcp_tool: `server` (an already-configured MCP server's name), `tool`, `input` (the tool's arguments; string values may interpolate
  *    `${path}` from the hook input JSON — CC 2.1.296 semantics, the runner's business).
+ * NOT in the table, on purpose: CC's `@internal` command / http keys `rewakeMessage` / `rewakeSummary` / `cloud` (not public settings keys; `cloud` even reads a bad value
+ * as 'skip' and loads the file) and the prompt entry's `continueOnBlock`. A key outside a type's row is not carried and not a bad piece (`docs/CC-DIVERGENCE.md` H7) —
+ * which is also why `args` on a non-command entry and `onFailure` on a prompt / agent / mcp_tool entry are such keys.
  */
 declare const HOOK_ENTRY_FIELDS: {
     readonly command: {
@@ -78,9 +93,11 @@ declare const HOOK_ENTRY_FIELDS: {
         readonly statusMessage: "string?";
         readonly once: "boolean?";
         readonly command: "text";
+        readonly args: "argv?";
         readonly shell: "shell?";
         readonly async: "boolean?";
         readonly asyncRewake: "boolean?";
+        readonly onFailure: "onFailure?";
     };
     readonly prompt: {
         readonly if: "string?";
@@ -106,6 +123,7 @@ declare const HOOK_ENTRY_FIELDS: {
         readonly url: "text";
         readonly headers: "stringRecord?";
         readonly allowedEnvVars: "stringList?";
+        readonly onFailure: "onFailure?";
     };
     readonly mcp_tool: {
         readonly if: "string?";
@@ -117,7 +135,7 @@ declare const HOOK_ENTRY_FIELDS: {
         readonly input: "record?";
     };
 };
-type HookFieldBaseValue<B> = B extends "text" | "string" ? string : B extends "shell" ? (typeof HOOK_SHELLS)[number] : B extends "boolean" ? boolean : B extends "seconds" ? number : B extends "stringRecord" ? Record<string, string> : B extends "stringList" ? string[] : B extends "record" ? Record<string, unknown> : never;
+type HookFieldBaseValue<B> = B extends "text" | "string" ? string : B extends "shell" ? (typeof HOOK_SHELLS)[number] : B extends "onFailure" ? HookOnFailure : B extends "boolean" ? boolean : B extends "seconds" ? number : B extends "stringRecord" ? Record<string, string> : B extends "stringList" | "argv" ? string[] : B extends "record" ? Record<string, unknown> : never;
 type HookFieldValue<K> = K extends `${infer B}?` ? HookFieldBaseValue<B> : HookFieldBaseValue<K>;
 type Flat<O> = {
     [K in keyof O]: O[K];
@@ -130,7 +148,7 @@ type HookEntryOf<T extends HookEntryType, F = (typeof HOOK_ENTRY_FIELDS)[T]> = F
 } & {
     -readonly [K in keyof F as F[K] extends `${string}?` ? K : never]?: HookFieldValue<F[K]>;
 }>;
-/** `command` — shell command on the host that runs the hook (DESIGN POINT ② in `./hooks`). */
+/** `command` — a command on the host that runs the hook: a shell command line, or — when the entry carries `args` — an executable spawned directly with those arguments, no shell (DESIGN POINT ② in `./hooks`). */
 export type CommandHookEntry = HookEntryOf<"command">;
 /** `prompt` — one-shot LLM evaluation of the hook input ($ARGUMENTS = input JSON). */
 export type PromptHookEntry = HookEntryOf<"prompt">;