@sema-agent/server 7.145.0 → 7.147.0

package/dist/hooks/command-spawn.js

@@ -8,17 +8,6 @@ function isRecord(v) {
     const proto = Object.getPrototypeOf(v);
     return proto === Object.prototype || proto === null;
 }
-export function readHookArgs(raw) {
-    if (!Array.isArray(raw))
-        return undefined;
-    const out = [];
-    for (const a of raw) {
-        if (typeof a !== "string" || a.includes("\0"))
-            return undefined;
-        out.push(a);
-    }
-    return out;
-}
 export function readHookPlugin(raw) {
     if (!isRecord(raw))
         return undefined;

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

@@ -57,20 +57,27 @@ export declare const SETTINGS_HOOK_STATIONS: {
     readonly PreCompact: readonly ["classic.PreCompact"];
     readonly PostCompact: readonly ["classic.PostCompact"];
 };
-/** 这张注册的名字 —— wire 可见(`wiring_manifest.mods[].name`、`allowRuleShadowed[].entries`),也是 handler 失败时引擎拒句点名的扩展名。 */
-export declare const SETTINGS_HOOKS_REGISTRATION = "settings.hooks";
 /**
- * 律四 · `HOOKS_TIMEOUT_MS` 未设时本注册每个 handler 的预算(ms)。
+ * **一条车道一张注册**:每张的名字 —— wire 可见(`wiring_manifest.mods[].name`、`allowRuleShadowed[].entries`、问因项 `askReasons[].registration`),
+ * 也是 handler 失败时引擎拒句点名的扩展名。没有托管组的请求只铸非托管那一张(名字与托管车道之前逐字同)。
+ */
+export declare const SETTINGS_HOOKS_REGISTRATIONS: {
+    readonly managed: "settings.hooks.managed";
+    readonly unmanaged: "settings.hooks";
+};
+/**
+ * 律四 · `HOOKS_TIMEOUT_MS` 未设时**每张车道注册**每个 handler 的预算(ms;两张注册各一份同值,不另铸数)。
  *
  * **这只数是引擎的钟,不是本服务跑钩子子进程的墙钟。** 引擎对 `budgetMs` 的定义(core `ModRegistration.budgetMs` 的注释,逐字)是
  * "Each handler's own time" —— 每个 handler 自己的时间:一只在 handler 等 `next` / `$` 调用时暂停的钟(core 的 `SelfBudget`),
- * 到点 ⇒ 这个 handler 失败(PreToolUse / UserPromptSubmit 上 fail-closed 拒,其余站跳过)。命令钩子子进程自己的墙钟另有两只,都在本文件:
- * 单条命令的 `timeout`(上限 {@link MAX_HOOK_TIMEOUT_SECONDS})与一个事件里同步条目的总墙钟({@link MAX_HOOK_EVENT_TOTAL_SECONDS},到点不再起下一条)。
+ * 到点 ⇒ 这个 handler 失败(PreToolUse / UserPromptSubmit 上 fail-closed 拒,其余站跳过)。托管车道是外层、先等 `next`:它的表在非托管车道跑的那段停着 ——
+ * 非托管条目吃光的只是非托管那张的预算,托管车道照跑;托管车道自己的预算用尽 ⇒ 撞上的托管条目记未跑成(`budget_exhausted`)。命令钩子子进程自己的墙钟另有两只,都在本文件:
+ * 单条命令的 `timeout`(上限 {@link MAX_HOOK_TIMEOUT_SECONDS})与一个事件里一条车道同步条目的总墙钟({@link MAX_HOOK_EVENT_TOTAL_SECONDS},到点不再起下一条)。
  *
  * 缺省取单条命令超时的上限 {@link MAX_HOOK_TIMEOUT_SECONDS} × 1000(两只钟起点不同:引擎的钟在 handler 起跑时就开始走,命令的 `timeout` 钟要等 shell 解析和 spawn 之后,
  * 同一 handler 里串行的几条还共用这一只钟 —— 配到 600 s 的命令跑满时预算会先到)。不是抄引擎缺省(10 s):一条跑 11 s 的 PreToolUse 钩子会因此被 fail-closed 拒。
  *
- * 两只钟的交汇:预算到,与任务被取消一样,引擎对这个 handler 的信号({@link ClassicAnswer} 的 `signal`)触发 ——
+ * 两只钟的交汇:预算到,与任务被取消一样,引擎对这个 handler 的信号({@link HandlerHalt} 的 `signal`)触发 ——
  * 在跑的命令钩子的进程组被叫停(SIGTERM → {@link HOOK_KILL_GRACE_MS} → 组长还在则组 SIGKILL),这个 handler 里还没起的条目不再起。
  */
 export declare const DEFAULT_SETTINGS_HOOKS_BUDGET_MS: number;
@@ -103,7 +110,7 @@ export type SupportedHookEntryType = {
 }[HookEntryType];
 /** 本仓会真跑的条目类型闭集(契约 {@link HOOK_ENTRY_TYPES} 的次序)—— 拒句 `supported: …` 的词表与 {@link RunnableHookEntry} 的类型都出自这一张表。 */
 export declare const SUPPORTED_HOOK_ENTRY_TYPES: readonly SupportedHookEntryType[];
-/** 本 runner 会真跑的条目(契约 `HookEntry` 取表态为 `true` 的那几型;command 条目另带本仓读的两只 wire 键 `args` / `plugin`,见 `command-spawn.ts`)。 */
+/** 本 runner 会真跑的条目(契约 `HookEntry` 取表态为 `true` 的那几型;command 条目另带本仓读的 wire 键 `plugin`,见 `command-spawn.ts`)。 */
 export type RunnableHookEntry = {
     [T in SupportedHookEntryType]: T extends "command" ? RunnableCommandHookEntry : Extract<HookEntry, {
         type: T;
@@ -115,7 +122,7 @@ export interface RunnableMatcherGroup {
     source?: HookGroupSource;
     hooks: RunnableHookEntry[];
 }
-/** 受理面通过后的 hooks 配置:每个事件下的条目都是本仓会跑的型 —— 执行侧({@link createSettingsHooksRegistration})只收这一型,「不认识的类型」到不了它手里。 */
+/** 受理面通过后的 hooks 配置:每个事件下的条目都是本仓会跑的型 —— 执行侧({@link createSettingsHooksRegistrations})只收这一型,「不认识的类型」到不了它手里。 */
 export type RunnableHooksConfig = Partial<Record<HookEventName, RunnableMatcherGroup[]>>;
 /** 分类器点名的一块(被剔的块或整份被拒的理由):码 + 坐标 + 坏字段。 */
 export type HooksRefusalPiece = HooksDroppedPiece | HooksRejection;
@@ -324,11 +331,12 @@ export interface UnnamedHooksRefusalIssue {
     readonly reason: "unnamed_refusal";
     readonly path: ConfigPath;
 }
-/** 本仓读的 wire 键(契约分类器不认、会剥掉的那三只)。 */
-export type HooksWireKey = "source" | "plugin" | "args";
+/** 本仓读的 wire 键(契约分类器不认、会剥掉的那两只)。 */
+export type HooksWireKey = "source" | "plugin";
 /**
- * 本仓的 wire 键形错(`path` 指那只键:组的 `source` / command 条目的 `plugin` / `args`)。这三只键分类器不认(它对未知键一律剥除),
- * 由 {@link parseHooksConfig} 在分类器装上的同一坐标上读 —— 形错 = 拒,**不**再被静默剥掉(剥掉 `source` = 托管组落进非托管道;剥掉 `args` = exec 形只剩可执行名)。
+ * 本仓的 wire 键形错(`path` 指那只键:组的 `source` / command 条目的 `plugin`)。这两只键分类器不认(它对未知键一律剥除),
+ * 由 {@link parseHooksConfig} 在分类器装上的同一坐标上读 —— 形错 = 拒,**不**再被静默剥掉(剥掉 `source` = 托管组落进非托管道;剥掉 `plugin` = 插件上下文不在)。
+ * (`args` 自契约包 19.0.0 起由分类器承运,形错是分类器的块码,不在这里。)
  */
 export interface HooksWireKeyIssue {
     readonly reason: "wire_key_invalid";
@@ -444,10 +452,11 @@ export declare function hooksCoordinate(path: ConfigPath): string;
  *    一块被剔(`loaded-partial`)或整份被拒(`rejected`)都是拒 —— wire 面「剔掉坏块、其余照装」会让写的人以为生效的钩子无声消失(分类器的宽松粒度是读设置文件的宿主用的)。
  *    拒的判决 = 分类器给的**码 + 坐标 + 坏字段**({@link HooksPieceIssue};分类器不写句子,句子与 400 体的机读位由 {@link buildHooksRefusal} 铸)。
  *  · **本仓不执行的条目类型整份拒**:分类器受理契约的全部五型,而本仓只跑 {@link SUPPORTED_HOOK_ENTRY_TYPES}。含其余类型的配置整份拒,不留跳过臂。
- *  · **本仓的 wire 键**(分类器不认、会剥掉的三只):组上的 `source`(来源闭集,`hook-source.ts`)、command 条目上的 `plugin` / `args`(执行上下文,`command-spawn.ts`)——
+ *  · **本仓的 wire 键**(分类器不认、会剥掉的两只):组上的 `source`(来源闭集,`hook-source.ts`)、command 条目上的 `plugin`(插件上下文,`command-spawn.ts`)——
  *    在分类器装上的**同一坐标**上读原值(分类器只在 `loaded` 时放行,装上的件与原值逐位对齐),形错 ⇒ {@link HooksWireKeyIssue}。
- *    `plugin` / `args` 只在 command 条目上有义。值为 `undefined` 与缺席同读(与分类器读可选字段同一口径)。
- *  · **读者不携带的键**(分类器不认的字段、非 command 条目上的 `plugin` / `args`、组上的拼错键):本读者的可跑形里没有它们(读法照分类器)。
+ *    `plugin` 只在 command 条目上有义。值为 `undefined` 与缺席同读(与分类器读可选字段同一口径)。
+ *    契约字段(含 19.0.0 起承运的 `args` / `onFailure`)随分类器装上的条目整条到达,本读者不再读第二遍原值。
+ *  · **读者不携带的键**(分类器不认的字段、非 command 条目上的 `plugin`、契约只给别的型的字段(如 http 条目上的 `args`)、组上的拼错键):本读者的可跑形里没有它们(读法照分类器)。
  *    「写了却被剥掉」在 FRESH 提交面由键闭集门的第三个实例拒(`task-settings.ts` 的 `hooksKeyIssue`,词表 = 本函数交回的可跑形,400 `request.body_shape`);
  *    续跑重放腿不过那道门,存量体按受理时的读法重放(剥掉,不砖停驻任务)。
  *  · **服务侧上限**(广度闸;契约本身不设量纲)。exec 形的命令行(`command` + 各 `args`)计入 `command` 帽;插件上下文一道总字符帽。
@@ -485,7 +494,7 @@ export declare function hookMatcherMatches(matcher: string | undefined, value: s
  *  「交替/正则」是 matcher 字段的文法——本实现名部走 hookMatcherMatches 属**超集**(alternation 也认),
  *  如实登记不收窄;②250 的 `if` 已扩到 prompt/agent/http/mcp_tool 条目(本 runner 只翻 command,不涉)。 */
 export declare function hookIfMatches(cond: string, payload: unknown): true | "not_matched" | "unevaluable" | "over_budget";
-/** createSettingsHooksRegistration 的装配上下文(payload 的 CC-verbatim 字段来源)。 */
+/** createSettingsHooksRegistrations 的装配上下文(payload 的 CC-verbatim 字段来源)。 */
 export interface HookRunnerContext {
     logger: Logger;
     sessionId: string;
@@ -520,6 +529,11 @@ export interface HookRunnerContext {
      * `[]` = 没有层写名单(不限,与引擎外的参照实现「名单未设 ⇒ 不限」同读)。今天唯一的层来源是请求的 `settings`(`task-settings.ts` 的 `httpHookAllowlist`,源 `flagSettings`)。
      */
     httpHookAllowlistLayers: readonly HttpHookAllowlistLayer[];
+    /**
+     * 部署座在**任务座之下**挂了链成员的站点式样(引擎的准入记录读出,`boot/deployment-mods.ts` 的 `belowTaskChainPatternsOf`)。必填:每个装配点都要说 ——
+     * `[]` = 任务座之下没有部署座的链成员(部署注册只在任务座之上、只有观察者,或没有部署注册)。读者 = {@link managedTightenOnlyOn}(托管车道在这些站上只许收紧)。
+     */
+    belowTaskChainPatterns: readonly string[];
 }
 /** 阶段三b 模型调用载体契约(prompt=直连一次 completion;agent=runTask 收敛后的 final text)。
  *  返回 ok/text 或 ok:false/error——载体自己兜超时(timeoutMs 是硬顶,载体可更严),绝不 throw。 */
@@ -604,6 +618,48 @@ export declare const PERMISSIVE_VERDICT_EVENTS: {
     readonly PreModelSwitch: false;
     readonly PostModelSwitch: false;
 };
+/**
+ * 条目 `onFailure: "block"` 在哪些事件上**生效**(`true` = 这一条在这个事件上被选中却没给出裁决 ⇒ 按 exit 2 算,见 {@link blocksOnFailure})。
+ * 一条读法 = 参照实现 CC 2.1.309(`cli309.js:263822`:`kGe(e,n) = yGe(e) && !_Ge.has(n)`,`_Ge` = Stop / SubagentStop / TaskCompleted / TeammateIdle —— 「该停的停不下」比「守卫起不来」更糟的四站);
+ * 本服务一处偏离:观察站 StopFailure / PostCompact 取 `false` —— 本服务里这两站的 exit 2 无处兑现(观察站骨架把它记成故障帧),按 exit 2 算只会把原故障帧(成因 / 退出码)改写掉、
+ * 结局仍是放行,与参照实现在这两站「阻断了也无物可阻」同一结局。壳属事件本服务不跑,按参照实现取值(哪天挪进引擎属主,缺省方向是生效 = 失效关闭)。
+ * 按事件名穷举(`satisfies Record<HookEventName, boolean>`,与 {@link PERMISSIVE_VERDICT_EVENTS} 同形):契约加一个事件而这里没表态 = 编译红。
+ */
+export declare const ON_FAILURE_BLOCK_EVENTS: {
+    readonly PreToolUse: true;
+    readonly PostToolUse: true;
+    readonly PostToolUseFailure: true;
+    readonly PostToolBatch: true;
+    readonly Notification: true;
+    readonly UserPromptSubmit: true;
+    readonly UserPromptExpansion: true;
+    readonly SessionStart: true;
+    readonly SessionEnd: true;
+    readonly Stop: false;
+    readonly StopFailure: false;
+    readonly SubagentStart: true;
+    readonly SubagentStop: false;
+    readonly PreCompact: true;
+    readonly PostCompact: false;
+    readonly PermissionRequest: true;
+    readonly PermissionDenied: true;
+    readonly Setup: true;
+    readonly TeammateIdle: false;
+    readonly TaskCreated: true;
+    readonly TaskCompleted: false;
+    readonly Elicitation: true;
+    readonly ElicitationResult: true;
+    readonly ConfigChange: true;
+    readonly WorktreeCreate: true;
+    readonly WorktreeRemove: true;
+    readonly InstructionsLoaded: true;
+    readonly CwdChanged: true;
+    readonly FileChanged: true;
+    readonly MessageDisplay: true;
+    readonly DirectoryAdded: true;
+    readonly PreModelSwitch: true;
+    readonly PostModelSwitch: true;
+};
 /**
  * hook 上下文片段 → 喂给模型的单串。**所有** `additionalContext` 聚合点的唯一属主(此前是同一个
  * `contexts.join("\n")` 表达式抄在二十余处,总量帽无处可挂 —— 那正是漂移成因)。
@@ -655,20 +711,25 @@ export interface LlmHookExtra {
     transcript?: string;
 }
 /**
- * 律一 · 把校验过的 {@link RunnableHooksConfig} 铸成**一张** mods 注册 `settings.hooks`(任务座;档缺席 = `user`)。
- * 没有可挂的条目 → undefined(`TaskSpec.mods` 不铸)。`budgetMs` = {@link settingsHooksBudgetMs} 的读数(调用方交)。
+ * 律一 · 把校验过的 {@link RunnableHooksConfig} 铸成任务座上的 mods 注册 —— **一条车道一张**(车道 = `hook-source.ts` 的 {@link hookLaneOf}):
+ * 托管车道 `settings.hooks.managed`(托管插件相 + 托管策略相)在前、非托管车道 `settings.hooks` 在后({@link LANE_CHAIN_ORDER});没有组的车道不铸,两道都空 ⇒ `[]`(`TaskSpec.mods` 不铸)。
+ * 没有托管组的请求只得到非托管那一张,与分道之前逐字同(名字、挂站、预算、`once` 键)。`budgetMs` = {@link settingsHooksBudgetMs} 的读数(调用方交),两张各带一份同值。
+ *
+ * 一条规则:**车道是引擎的注册,不是一只 handler 里的分支** —— 每张注册自带引擎的 handler 预算、本服务的事件墙钟、LLM 条数、`once` 账与未跑成账本,两道之间不共用任何一只钟。
+ * 托管车道外层挂(`wrapClassic`):先把事件交下去(非托管车道、更下方的注册与引擎核心先答完,托管的表在这段停着),再在答回来的那份上跑自己的两相并折叠 ——
+ * 托管判的因此恒是要执行的那一份,非托管吃光自己的预算也挤不掉它(拒站上非托管失败 = 派发 fail-closed 终局;其余站引擎跳过非托管,托管照跑)。
  *
  * 构造约束(每一条都有引擎侧的硬理由):
  *  · `register` 同步、只读本注册自己的配置、不按腿分支 —— 返回 thenable 即 `config.mods_invalid`;委派子代把父的任务座当自己的派发,
  *    两条腿挂的是同一套 handler,父链才塌进子代的 phase 1(否则多一次约束判定);
- *  · `once` 去重集({@link runMatchingEntries} 的 `onceFired`)在铸注册这一层、每请求一份,不放进 `register`(那是每腿一次);
+ *  · `once` 去重集({@link runMatchingEntries} 的 `onceFired`)在铸注册这一层、每请求每车道一份,不放进 `register`(那是每腿一次);
  *  · 答案全部由本仓从 CC JSON 铸,引擎在 handler 边界屏(唯一判官),本仓不预屏;
- *  · 无意见 ⇒ `next(e)`(链 handler 返回 `undefined` 是站点违约,PreToolUse / UserPromptSubmit 的失败列是 refuse ⇒ 每次都会被拒);
- *    观察站的 handler 恒返回 `undefined` —— 两条都在 {@link hangClassic} 成形;
- *  · `uses.calls: []`(必填;本仓的 handler 不调 `$`),`uses.events` 从 {@link SETTINGS_HOOK_STATIONS} 派生;
- *  · 每只翻译的第二个入参是引擎的 `next.signal`(这只 handler 的预算 ∪ 这次派发被取消;见 {@link DEFAULT_SETTINGS_HOOKS_BUDGET_MS}):
+ *  · 内层无意见 ⇒ `next(e)`;外层无可添 ⇒ 下方的答案原样作数(链 handler 返回 `undefined` 是站点违约,PreToolUse / UserPromptSubmit 的失败列是 refuse ⇒ 每次都会被拒);
+ *    观察站的 handler 恒返回 `undefined` —— 三条都在 `classic-stations.ts` 的两种挂法里成形;
+ *  · `uses.calls: []`(必填;本仓的 handler 不调 `$`),`uses.events` 从 {@link SETTINGS_HOOK_STATIONS} 派生(只挂本车道有组的事件);
+ *  · 每只翻译的第二个入参是引擎的停表({@link HandlerHalt}:`next.signal` = 这只 handler 的预算 ∪ 这次派发结束 / 被取消,成因读 `next.budget`;见 {@link DEFAULT_SETTINGS_HOOKS_BUDGET_MS}):
  *    一路贯穿到命令腿的 spawn({@link runCommandHook}),本仓不自合成第二只、不另设钟。
  */
-export declare function createSettingsHooksRegistration(config: RunnableHooksConfig, ctx: HookRunnerContext, budgetMs: number): ModRegistration<EngineDollar> | undefined;
+export declare function createSettingsHooksRegistrations(config: RunnableHooksConfig, ctx: HookRunnerContext, budgetMs: number): readonly ModRegistration<EngineDollar>[];
 export {};
 //# sourceMappingURL=hook-runner.d.ts.map