@sema-agent/server 7.131.0 → 7.133.0

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

@@ -1,8 +1,12 @@
-import { type HookEntry, type HookEntryType, type HookEventName, type HooksDroppedPiece, type HooksRejection } from "@sema-agent/settings-schema/hooks";
+import { type HookEntry, type HookEntryType, type HookEventName, type HooksDroppedPiece, type HooksDroppedPieceCode, type HooksRejection, type HooksRejectionCode } from "@sema-agent/settings-schema/hooks";
 import { type ConfigPath } from "@sema-agent/settings-schema";
-import type { Hooks } from "@sema-agent/core";
+import { ENGINE_OWNED_HOOK_EVENTS } from "@sema-agent/settings-schema/hooks";
+import type { EngineDollar, ModRegistration } from "@sema-agent/core";
 import type { Logger } from "../observability/logger.js";
-import type { HookNoticeObservation } from "../fleet/fleet-bus.js";
+import type { HookManagedUnrun, HookNoticeObservation } from "../fleet/fleet-bus.js";
+import { LIMIT_REASONS, type LimitMeasure } from "../limit-refusal.js";
+import { type HookGroupSource } from "./hook-source.js";
+import { type RunnableCommandHookEntry } from "./command-spawn.js";
 /** 服务侧防线上限(契约本身不设量纲;不设界=单请求可塞任意大配置/任意长命令)。超界=校验错(fail-loud)。 */
 export declare const MAX_HOOK_ENTRIES_PER_EVENT = 32;
 export declare const MAX_HOOK_COMMAND_CHARS = 8192;
@@ -21,8 +25,7 @@ export declare const MAX_HOOK_OUTPUT_BYTES: number;
  * 一次事件里所有 hook 上下文片段**聚合后**喂给模型的总量上限(字符)。
  *
  * 为什么单条帽不够:一次事件最多 {@link MAX_HOOK_ENTRIES_PER_EVENT} 条(parseHooksConfig 的广度闸),
- * 每条最多推两段(`decision:"block"` 的 reason + `hookSpecificOutput.additionalContext`),
- * {@link composeHooks} 再把部署槽与 task 槽的**成品**拼一次 —— 单条 4096 相乘后一次注入可达 ~256KB,
+ * 每条最多推两段(`decision:"block"` 的 reason + `hookSpecificOutput.additionalContext`)—— 单条 4096 相乘后一次注入可达 ~256KB,
  * 而这些字符是**逐次工具调用**进模型可见文本的(core `hooks.js` 的 preToolContext / `prepare-task.js`
  * 的 tool_result 追加 / `runtask.js` 的 Stop follow-up),不是日志。
  *
@@ -32,6 +35,52 @@ export declare const MAX_HOOK_OUTPUT_BYTES: number;
  * 且 4096 的单条帽保证**前两条**钩子的话仍整段进得去(截断是配置广度的代价,不是常态)。
  */
 export declare const MAX_HOOK_CONTEXT_TOTAL_CHARS = 10000;
+/** 契约里**引擎属主**的 `settings.hooks` 事件(契约包的九员字面量元组;壳属主的事件引擎不跑,owner-single)。 */
+export type EngineOwnedHookEvent = (typeof ENGINE_OWNED_HOOK_EVENTS)[number];
+/**
+ * 律二 · **事件对位只有一张表**:引擎属主的每个 `settings.hooks` 事件 → 它挂的 `classic.*` 站。
+ * 注册的 `uses.events`、点亮了哪些站,全从这张表派生;契约加一个引擎属主事件 ⇒ 本表缺键 ⇒ tsc 红(那一刻补一行翻译),
+ * 所以运行期没有「引擎属主却没点亮」这一臂。每个站名在引擎事件表里都有站(钉从 `MOD_EVENT_TABLE` 派生对拍:只选无站名的注册 prepare 即拒)。
+ * `Stop` 挂两站:引擎把委派子代的停车点叫 `classic.SubagentStop`(续跑的子代同读),而旧座在每条腿都跑 ——
+ * 挂两个名字使用户的 `Stop` 条目触达不变(契约把 `SubagentStop` 判给壳;两张属主表对齐之前不收窄)。
+ */
+export declare const SETTINGS_HOOK_STATIONS: {
+    readonly PreToolUse: readonly ["classic.PreToolUse"];
+    readonly PostToolUse: readonly ["classic.PostToolUse"];
+    readonly PostToolUseFailure: readonly ["classic.PostToolUseFailure"];
+    readonly PostToolBatch: readonly ["classic.PostToolBatch"];
+    readonly UserPromptSubmit: readonly ["classic.UserPromptSubmit"];
+    readonly Stop: readonly ["classic.Stop", "classic.SubagentStop"];
+    readonly StopFailure: readonly ["classic.StopFailure"];
+    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)。
+ *
+ * **这只数是引擎的钟,不是本服务跑钩子子进程的墙钟。** 引擎对 `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},到点不再起下一条)。
+ *
+ * 缺省取单条命令超时的上限 {@link MAX_HOOK_TIMEOUT_SECONDS} × 1000(两只钟起点不同:引擎的钟在 handler 起跑时就开始走,命令的 `timeout` 钟要等 shell 解析和 spawn 之后,
+ * 同一 handler 里串行的几条还共用这一只钟 —— 配到 600 s 的命令跑满时预算会先到)。不是抄引擎缺省(10 s):一条跑 11 s 的 PreToolUse 钩子会因此被 fail-closed 拒。
+ *
+ * 两只钟的交汇:预算到,与任务被取消一样,引擎对这个 handler 的信号({@link ClassicAnswer} 的 `signal`)触发 ——
+ * 在跑的命令钩子的进程组被叫停(SIGTERM → {@link HOOK_KILL_GRACE_MS} → 组长还在则组 SIGKILL),这个 handler 里还没起的条目不再起。
+ */
+export declare const DEFAULT_SETTINGS_HOOKS_BUDGET_MS: number;
+/** 时限的唯一读法:`HOOKS_TIMEOUT_MS` 设了就是它(`0` 按字面 = 零预算);未设 ⇒ {@link DEFAULT_SETTINGS_HOOKS_BUDGET_MS}。 */
+export declare function settingsHooksBudgetMs(config: {
+    readonly hooksTimeoutMs?: number | undefined;
+}): number;
+/**
+ * 命令钩子的进程组被叫停(预算到 / 任务取消)时,SIGTERM 之后给它收尾的宽限(ms):到点组长还在就补一发组 SIGKILL(组长在宽限内退了则不再发)。
+ * 零旋钮 —— 命令要的收尾窗长于此值的,在命令里自己兜(trap 里快速落盘)。
+ */
+export declare const HOOK_KILL_GRACE_MS = 1000;
 /**
  * 本仓对契约每一种 hook 条目类型的表态 —— **一张表**:受理面({@link parseHooksConfig})与执行侧({@link RunnableHookEntry},以及每个按条目类型分派的臂)读的都是它。
  *
@@ -52,26 +101,38 @@ export type SupportedHookEntryType = {
 }[HookEntryType];
 /** 本仓会真跑的条目类型闭集(契约 {@link HOOK_ENTRY_TYPES} 的次序)—— 拒句 `supported: …` 的词表与 {@link RunnableHookEntry} 的类型都出自这一张表。 */
 export declare const SUPPORTED_HOOK_ENTRY_TYPES: readonly SupportedHookEntryType[];
-/** 本 runner 会真跑的条目(契约 `HookEntry` 取表态为 `true` 的那几型)。 */
-export type RunnableHookEntry = Extract<HookEntry, {
-    type: SupportedHookEntryType;
-}>;
-/** 一个匹配器组,条目只含 {@link RunnableHookEntry}。 */
+/** 本 runner 会真跑的条目(契约 `HookEntry` 取表态为 `true` 的那几型;command 条目另带本仓读的两只 wire 键 `args` / `plugin`,见 `command-spawn.ts`)。 */
+export type RunnableHookEntry = {
+    [T in SupportedHookEntryType]: T extends "command" ? RunnableCommandHookEntry : Extract<HookEntry, {
+        type: T;
+    }>;
+}[SupportedHookEntryType];
+/** 一个匹配器组,条目只含 {@link RunnableHookEntry}。`source` = 这一组是谁写的(wire 键,闭集见 `hook-source.ts`;缺席 = 非托管),决定它在哪一相跑。 */
 export interface RunnableMatcherGroup {
     matcher?: string;
+    source?: HookGroupSource;
     hooks: RunnableHookEntry[];
 }
-/** 受理面通过后的 hooks 配置:每个事件下的条目都是本仓会跑的型 —— 执行侧({@link createTaskHooks})只收这一型,「不认识的类型」到不了它手里。 */
+/** 受理面通过后的 hooks 配置:每个事件下的条目都是本仓会跑的型 —— 执行侧({@link createSettingsHooksRegistration})只收这一型,「不认识的类型」到不了它手里。 */
 export type RunnableHooksConfig = Partial<Record<HookEventName, RunnableMatcherGroup[]>>;
 /** 分类器点名的一块(被剔的块或整份被拒的理由):码 + 坐标 + 坏字段。 */
 export type HooksRefusalPiece = HooksDroppedPiece | HooksRejection;
-export interface ParseHooksConfigResult {
-    config?: RunnableHooksConfig;
-    /** 人可读的第一条拒因(HTTP 层用它 400 fail-loud;resume 防御路径用它 warn)。 */
-    error?: string;
-    /** 拒因来自**分类器**时,它点名的每一块(数据,文档序);本仓自己的拒(条目类型 / 服务侧上限)不带这一位。一次性迁移读它按名剥键(`stored-request-hooks-m20.ts`)—— 迁移不另起读者。 */
-    pieces?: readonly HooksRefusalPiece[];
-}
+/**
+ * {@link parseHooksConfig} 的返回:受理 ⇒ `config`;拒 ⇒ `issue`(判决数据,受理门经 {@link buildHooksRefusal} 铸 400 体的句子与机读位)+ `error`(同一只铸点给的句子,
+ * resume 防御路径用它 warn)+ 拒因来自**分类器**时的 `pieces`(它点名的每一块,文档序;本仓自己的拒 —— 条目类型 / 服务侧上限 —— 不带这一位。一次性迁移读它按名剥键
+ * (`stored-request-hooks-m20.ts`)—— 迁移不另起读者)。
+ */
+export type ParseHooksConfigResult = {
+    readonly config: RunnableHooksConfig;
+    readonly issue?: undefined;
+    readonly error?: undefined;
+    readonly pieces?: undefined;
+} | {
+    readonly config?: undefined;
+    readonly issue: HooksConfigIssue;
+    readonly error: string;
+    readonly pieces?: readonly HooksRefusalPiece[];
+};
 /**
  * 🔴 **S-924 → S-995(clay [ref] ③;八病审计 SG H6-d;test 7.112.0 验收 OBS ①)—— 工具事件的 matcher 选中了工具**别名**、却选不中它的正名 ⇒ fresh 提交面响亮拒。**
  *
@@ -80,14 +141,14 @@ export interface ParseHooksConfigResult {
  * ⇒ **永不命中、一句话都没有**(post 两事件自 7.107.0 / core 7.36.0 起如此,PreToolUse 一直如此)。静默不命中 = 写的人以为在生效的 hook
  * 其实没跑,硬破坏三句要求的「响亮」没有着落。7.112.0(S-924)只拒**字面**别名;同一个错误写成 `^ListPeers$` / `ListPeers.*` / `(ListPeers)` 照样 200(S-995)。
  *
- * 规则(一条;字面形是它的特例):{@link toolMatcherIssue} 对 core 静态目录里**每一条退役别名**问「这只 matcher 选不选它 / 选不选它的正名」:
+ * 规则(一条;字面形是它的特例):{@link hooksMatcherIssue} 对 core 静态目录里**每一条退役别名**问「这只 matcher 选不选它 / 选不选它的正名」:
  * matcher **命中别名 ∧ 不命中它的正名** ⇒ `400 request.field_invalid`(`admission.ts` fresh 门)。「选不选」**只有一只读法**:契约包的 `hookMatcherSelects`
- * (名字表 / 空 / `*` / 正则三形都由它答;正则形**不锚定**,与壳同形;运行期 {@link hookMatcherMatches} 问的也是它,本仓不留副本)。按**一条顺序**判(两档共用,7.114.0 修复轮):
+ * (名字表 / 空 / `*` / 正则三形都由它答;正则形**不锚定**,与壳同形;运行期 {@link hookMatcherMatches} 问的也是它 —— 经同一只带预算的求值口,本仓不留副本)。按**一条顺序**判(两档共用,7.114.0 修复轮):
  *  ① **长度上限**:超 {@link MAX_MATCHER_EVAL_CHARS} 的 matcher 两档都不读 ⇒ 未判(reason = oversize);
  *  ② **形只问契约包的 `hookMatcherForm`**(与 `hookMatcherSelects` 同一只解析步,本仓不留形判),闭集三词、两档一张表:
  *     · `literal`(缺席 / 空 / `*` / 名字表形;契约不编、不跑调用方的正则)⇒ 两档都**直接问契约函数**、**不占求值预算**;
  *     · `regex` ⇒ **`"regex"` 档**(hooks 会被采纳的车道,`taskHooksHonored`)把**同一只契约函数**经 `node:vm` 的 `timeout` 带**每次求值各一份固定预算**调用({@link matcherSelectsWithin};
- *       预算**不共享**、不随同一受理里别的 matcher 耗尽、不读钟 —— S-1455);**超时 ⇒ 这只 matcher 是灾难回溯 ⇒ `400 request.field_invalid` 拒**(见下「预算与结局」);
+ *       每次求值的额度**不共享**、不随同一受理里别的 matcher 缩水、这一份不读钟 —— S-1455;另有一只受理总额度,见下「预算与结局」);**超时 ⇒ 这只 matcher 是灾难回溯 ⇒ `400 request.field_invalid` 拒**(见下「预算与结局」);
  *       **`"literal"` 档**(多租户车道:hooks 整只被 resolveSpec 忽略)= **不适用**:该车道没有被守的对象(hooks 不装配),不判、不算未判、不登记 —— **零调用方正则执行**
  *       (7.112.0 的字面判保留:裸 `ListPeers` / `Read|ListPeers` 照旧 400);
  *     · `invalid`(编不过)⇒ `"regex"` 档 = **`400 request.field_invalid` 拒**(判决 `invalid_regex`,见下「预算与结局」;不进求值 —— 形判已答「读不了」);`"literal"` 档 = 不适用(同上)。
@@ -111,23 +172,29 @@ export interface ParseHooksConfigResult {
  *  · **不在本规则内**:两边都选不中的 matcher(大小写错 / 词内空白 / 纯错字;目录之外的 MCP / 嵌入方工具名同样「选不中目录里任何名」,受理面无从区分错字与它们)=
  *    **「选不到目录里任何名」另一类,候设计(台账另立号,主会话裁)**。
  *
- * 🔴 **预算与结局(S-1455;受理结局只取决于配置,不取决于机器忙闲)**:regex 档每一次求值(一只正则形 matcher 对一个名字的一次问)各拿**一份固定的墙钟预算**
- * {@link ADMISSION_MATCHER_EVAL_BUDGET_MS}(vm `timeout`,从这次求值开始计)—— **不共享**(此前一次受理共用 100 ms,忙机上会被吃光 ⇒
- * 同一份设置忙机偶尔被收下、闲机恒 400),不随同一受理里 matcher 的个数耗尽,判据里**没有时钟**(没有「截止线」可被调度停顿越过)。预算只防**灾难回溯**:
+ * 🔴 **预算与结局(S-1455 / S-1503;良性设置的受理结局只取决于配置,不取决于机器忙闲)**:regex 档每一次求值(一只正则形 matcher 对一个名字的一次问)各拿**一份固定的墙钟预算**
+ * {@link ADMISSION_MATCHER_BUDGET}`.budgetMs`(vm `timeout`,从这次求值开始计)—— **不共享**(此前一次受理共用 100 ms,忙机上会被吃光 ⇒
+ * 同一份设置忙机偶尔被收下、闲机恒 400),额度不随同一受理里 matcher 的个数缩水,这一份**不读钟**(没有「截止线」可被调度停顿越过)。预算只防**灾难回溯**:
  * 良性求值 ~0.1 ms,灾难形(指数级)吃满预算也跑不完 —— 两者相差数个数量级,取值给足余量(1 000 ms),让忙机上的调度停顿也跨不过这条线。
+ * **另有一只受理总额度**(S-1503;同一张表的 `.totalMs`,5 000 ms):每次求值的额度界得住「一只 matcher 不会无限算」,界不住「刚好低于它的病态 matcher × 别名数 × 2 × 组数」(3 事件 × 16 组 × 1 别名 × 2 = 96 次,
+ * 每次 0.99 s 就是 96 s 的事件循环占用)。一次受理里所有**已完成**的正则形求值的耗时之和(一只单调钟逐次累加;字面形与非工具事件不进 vm、不计)一旦**超过**总额度 ⇒ 同码 `400`,
+ * `detail.reason = budget_exceeded`({@link BudgetExceededMatcherIssue},点名越线的那一组与总额度)。单次超时先到、先判 `over_budget`(更具体)。一次受理的最坏占用 ≤ 总额度 + 一次求值的额度。
+ * 总额度这一只读钟,但良性设置离它近三个数量级(一份最大的良性配置 —— 3 工具事件 × 16 组 —— 总耗时在毫秒级),所以良性设置的结局仍不随机器忙闲翻转;只有求值总耗时逼近总额度的病态设置才可能落在边界两侧。
  * **超时 ⇒ 确定拒绝**:`400 request.field_invalid`({@link OverBudgetMatcherIssue}),句子点名**哪一只 matcher**(事件 + 组下标,不回显原字节)与**预算**;**按配置顺序遇到的第一只超时 / 命中别名的 matcher 定结局**。
- * 为什么是拒绝而不是放行:运行期 {@link hookMatcherMatches} 在**每次工具调用**里直接问同一只契约函数、**没有任何预算** —— 一只在受理面都跑不完的 matcher 放进去,
- * 每次调用都会把事件循环卡住;放行 = 把一个确定的坏配置推迟成运行期的随机卡死。这条拒不是「越界即拒」的新检测面:被拒的恰是**无法被求值**的 matcher,与 `hook_matcher_invalid`(编不过 ⇒ 该组不跑)同属「这只 matcher 不可用」,
+ * 为什么是拒绝而不是放行:运行期 {@link hookMatcherMatches} 在**每次工具调用**里问同一只带预算的口(S-1017 起;此前是裸调、无预算)—— 一只在受理面连目录里几个短名字都求不完的 matcher 放进去,
+ * 运行期每次调用都要白烧一整份预算(超预算的组按选中处理并登记,守卫不丢,但每次调用卡一份预算);放行 = 把一个确定的坏配置推迟成运行期每次调用的卡顿。这条拒不是「越界即拒」的新检测面:被拒的恰是**无法被求值**的 matcher,与 `hook_matcher_invalid`(编不过 ⇒ 该组不跑)同属「这只 matcher 不可用」,
  * 只是编不过的运行期自己安全地不跑它,跑不完的不行。
- * 总用时的上界:首个超时即拒、不再往下求值;未超时的求值各自 < 预算。regex 档只在单用户车道(`taskHooksHonored`,hooks 会装配的那条;调用方就是进程属主,本来就能配任意 `command` 钩子)运行,
+ * 总用时的上界:首个超时 / 总额度越线即拒、不再往下求值;未超时的求值各自 < 预算,其和 ≤ 总额度 + 一次求值的额度。regex 档只在单用户车道(`taskHooksHonored`,hooks 会装配的那条;调用方就是进程属主,本来就能配任意 `command` 钩子)运行,
  * 多租户车道走 literal 档、零调用方正则执行 —— 受理面的 DoS 面不因此重开。
  *
  * 🔴 **编不过的正则 = 确定的拒绝**(S-1455 收尾;与超预算同类 —— 确定性的坏配置,结局只取决于配置):`"regex"` 档遇契约 `hookMatcherForm` 答 `invalid`(或求值时契约函数答 `"invalid"`)⇒
- * `400 request.field_invalid`({@link InvalidRegexMatcherIssue}),句子点名**哪一只 matcher**(事件 + 组下标 + 原文〔超 {@link MATCHER_ECHO_CHARS} 字符截断〕)与引擎的编译错误句;机读位 `detail` 只有闭集三键。
+ * `400 request.field_invalid`({@link InvalidRegexMatcherIssue}),句子点名**哪一只 matcher**(事件 + 组下标 + 原文〔超 {@link MATCHER_ECHO_CHARS} 字符截断〕)与引擎的编译错误句;机读位 `detail` 只有闭集三键 + 坐标 `path`(那一组的 `matcher`)。
  * 受理面与运行期问**同一只判**:契约把"编不过"答成 `invalid`,运行期 {@link hookMatcherMatches} 因此不跑那一组(并记 `hook_matcher_invalid`),受理面因此拒 —— 本仓不加第二个判官
  * (编译错误句只是诊断文字,见 {@link matcherCompileSentence};拒不拒由契约函数一个人说了算)。为什么是拒绝而不是放行:放行 = 用户以为在生效的钩子(含会真拦的 PreToolUse deny 钩子)
  * 在每次工具调用里都**悄悄不跑**,硬破坏三句要求的「响亮」没有着落;`"literal"` 档(多租户车道,hooks 不装配)= 不适用,与正则形同一行表。resume 重放不判(照旧采纳、该组不跑)。
- * 🔴 **边界(如实披露)**:判据只守三个工具事件(`matcherReadsWireToolName`)—— 写在别的带 matcher 的事件(`StopFailure` 的 `error` 词 / `PreCompact`·`PostCompact` 的 `trigger` 词)上的坏 matcher 仍受理、运行期该组不跑并记 `hook_matcher_invalid`。
+ * 🔴 **形判对所有事件同一判**(S-1472;此前只守三个工具事件,写在 `StopFailure` 的 `error` 词 / `PreCompact`·`PostCompact` 的 `trigger` 词上的坏 matcher 受理、运行期该组不跑并记 `hook_matcher_invalid`;壳跑的事件〔如 `SessionStart`〕由壳按同一只契约函数处置):
+ * 「这一串是不是一只读得了的 matcher」是**串的形**问题,不是事件的问题 —— `hookMatcherForm` 答 `invalid` ⇒ `400`,**不论写在 33 个契约事件里的哪一个**(含 matcher 被忽略的 `UserPromptSubmit` / `Stop` / `PostToolBatch`:规则里没有「事件类」这个维度,
+ * 也就没有一张按事件类分档的表)。死别名问(「选中别名而选不中正名」)只对 matcher 匹配**工具 wire 名**的事件(上面的三个工具事件)才问 —— 别的事件上 matcher 匹配的不是工具名,没有「别名」可言;这一问不占别的事件的求值预算。
  *
  * 🔴 **「未判」臂过 `recordFailOpen`**(F 类 tag `MATCHER_UNJUDGED_TAG`;主会话裁,CLAUDE.md「合法 F 类回退走登记 tag」):一只 matcher 没能被判 ⇒ 照旧受理 + 登记一笔,
  * detail = `event=… reason=… matcherChars=…`(**不带 matcher 原字节**,S-716 姿势)。现在只剩一种 reason:
@@ -139,32 +206,52 @@ export interface ParseHooksConfigResult {
  * 错误句:死别名与超预算两形只回显**目录里的**别名与正名 / 位置(闭集字符串与数字),不回显调用方的原字节(S-716 姿势);编不过一形**点名那只 matcher 的原文**(截断到 {@link MATCHER_ECHO_CHARS} 字符)与引擎的编译错误句 ——
  * 调用方要改的就是这一串,且它本来就是调用方自己送来的;机读位 `detail` 仍不带这两段。
  *
- * 🔴 **判决是数据,句子与体的机读位同出一只铸点**(S-1025;client-core 请托,additive):{@link toolMatcherIssue} 回 {@link ToolMatcherIssue}(闭集三形:{@link DeadToolMatcherIssue} 的 event / alias / canonical,
- * {@link OverBudgetMatcherIssue} 的 event / groupIndex / budgetMs,{@link InvalidRegexMatcherIssue} 的 event / groupIndex〔+ 句子用的 matcher / compileError〕,以 `reason` 区分)而不是句子;{@link buildToolMatcherRefusal} 是**唯一**把它铸成拒句 + `field` + `detail` 的函数,
+ * 🔴 **判决是数据,句子与体的机读位同出一只铸点**(S-1025;client-core 请托,additive):{@link hooksMatcherIssue} 回 {@link HooksMatcherIssue}(闭集四形:{@link DeadToolMatcherIssue} 的 event / alias / canonical,
+ * {@link OverBudgetMatcherIssue} 的 event / groupIndex / budgetMs,{@link BudgetExceededMatcherIssue} 的 event / groupIndex / totalMs,{@link InvalidRegexMatcherIssue} 的 event / groupIndex〔+ 句子用的 matcher / compileError〕,以 `reason` 区分)而不是句子;{@link buildHooksRefusal} 是**唯一**把它铸成拒句 + `field` + `detail` 的函数(配置读者的拒同经它),
  * 受理门只取它的返回、**不解析句子**。体上多出的两键让三端不必解析英文就能把这只拒与普通提交失败分流、提示用户改 matcher;死别名那一句逐字同 7.114.0、零新码。
  */
 /** 超此长度的 matcher 不在受理面读(两档同一个上限;未判,reason = oversize)。与 {@link MAX_HOOK_COMMAND_CHARS} 同量纲的服务侧防线:真实 matcher(精确名 / 交替 / `mcp__.*`)远在其内;目录全部工具名交替 ~0.5 KiB。 */
 export declare const MAX_MATCHER_EVAL_CHARS = 8192;
 /**
- * regex 档**每一次正则形求值各一份**的墙钟预算(毫秒;S-1455)。**不共享、不随受理里 matcher 的个数耗尽、判据里不读钟**;字面形不占它。
- * 良性求值 ~0.1 ms;灾难回溯(指数级)吃满它也跑不完 ⇒ 这只 matcher 被 400 拒。取值是「良性求值之上数个数量级」的余量 —— 小了,忙机上的调度停顿会把良性 matcher 读成灾难(受理结局随负载翻转,正是 S-1455 要根除的形)。
+ * 正则形 matcher 的**求值预算表**(毫秒)—— 两个数同出这一张表,判据与测试注入都不另持第二份(名字里的 `ADMISSION` 是历史:`budgetMs` 自 S-1017 起**受理面与运行期共用**,`totalMs` 只属受理面):
+ *  · `budgetMs` = **每一次**正则形求值各一份的固定墙钟额度(S-1455;vm `timeout`)。**不共享、额度不随受理里别的 matcher 缩水、这一份不读钟**;字面形不占它。
+ *    **运行期读同一个数**(S-1017;{@link hookMatcherMatches} 每次现读本对象):运行期每次工具调用对正则形 matcher 的每次求值也各拿这一份,超了 ⇒ 该组按选中处理并登记,不另设运行期额度。
+ *    良性求值 ~0.1 ms;灾难回溯(指数级)吃满它也跑不完 ⇒ 这只 matcher 被 400 拒(`over_budget`)。取值是「良性求值之上数个数量级」的余量 —— 小了,忙机上的调度停顿会把良性 matcher 读成灾难(受理结局随负载翻转,正是 S-1455 要根除的形)。
+ *  · `totalMs` = **一次受理**里所有已完成的正则形求值的**耗时之和**的总额度(S-1503):之和一旦超过它 ⇒ `400`,`detail.reason = budget_exceeded`。每次求值的额度只界住「一只 matcher 不会无限算」,
+ *    界不住「刚好低于它的病态 matcher × 别名数 × 2 × 组数」—— 今天 3 事件 × 16 组 × 1 别名 × 2 = 96 次,每次 0.99 s 可占住事件循环 96 s(单用户车道上持 token 的调用方)。
+ *    总额度读一只单调钟、**只累加已完成求值的耗时**(`performance.now`),求值本身不被它缩短(每次求值的额度仍是固定的 `budgetMs`),所以一次受理最坏占用 ≤ `totalMs` + `budgetMs`。
+ *    取值同一条余量律:一份最大的良性配置(3 工具事件 × 16 组)的总耗时实测约 9 ms,离 `totalMs` 近三个数量级 —— 良性设置的结局不随机器忙闲翻转;只有求值总耗时逼近 `totalMs` 的病态设置才可能。
  */
-export declare const ADMISSION_MATCHER_EVAL_BUDGET_MS = 1000;
-/** 拒句里回显的 matcher 原文 / 引擎编译错误句各自的字符上限(截断记号 `…(总长)` 由 `clip` 铸;S-1455 收尾)。真实 matcher 远在其内;上限只防一只 8 KiB 的坏 matcher 把拒句撑成一屏。 */
+export declare const ADMISSION_MATCHER_BUDGET: {
+    readonly budgetMs: 1000;
+    readonly totalMs: 5000;
+};
+/** 拒句里回显的 matcher 原文 / 引擎编译错误句、运行期 `hook_matcher_invalid` 日志行的 `matcher` 字段,各自的字符上限(都过回显的一只口径 `echoCallerText`,截断记号 `…`;S-1455 收尾 / S-1735)。真实 matcher 远在其内;上限只防一只 8 KiB 的坏 matcher 把拒句撑成一屏。 */
 export declare const MATCHER_ECHO_CHARS = 200;
+/** 运行期 `hook_entries_skipped` 日志行的 `if` 字段(配置写的权限规则表达式)的字符上限;与 matcher 同口径(`echoCallerText`),截断记号 `…`。 */
+export declare const IF_ECHO_CHARS = 200;
 /** 受理面判据的求值深度(见上头注):`"regex"` = 契约字面形直接问、正则形带预算问同一只契约函数;`"literal"` = 7.112.0 的字面判(只判契约字面形,零调用方正则执行;正则形 / 编不过的形不适用)。 */
 export type MatcherEvalDepth = "regex" | "literal";
 /**
- * **仅供测试注入**的求值预算(生产调用点不传 ⇒ 每次求值的预算 = {@link ADMISSION_MATCHER_EVAL_BUDGET_MS})。让「灾难形被拒」这类格子能用小额度(毫秒级)跑,不必等满生产预算。
- * 只有预算额度、**没有时钟**:判据本身不读钟(S-1455),测试也就没有「在第几次读钟时预算已尽」可造 —— 求值次序、调度停顿都不改变结局。
+ * **仅供测试注入**的求值预算(生产调用点不传 ⇒ 两个数都读 {@link ADMISSION_MATCHER_BUDGET},钟 = `performance.now`)。让「灾难形被拒」「总额度被推过」这类格子能用小额度或假钟跑,不必等满生产预算。
+ * 键名与那张表一致:`budgetMs` = 每次求值的额度,`totalMs` = 受理总额度;`now` = 总额度累加用的钟(缺席 ⇒ `performance.now`)—— 每次求值前后各读一次,差即这次求值的耗时。
+ * 每次求值的额度是 vm `timeout`、不读钟;钟只服务总额度。字面形求值与非工具事件不进 vm、**不读钟**。
  */
 export interface MatcherEvalBudget {
     readonly budgetMs?: number;
+    readonly totalMs?: number;
+    readonly now?: () => number;
 }
-/** 一条受理面判决(纯数据)· 死别名:`event` 事件下的某只 matcher 选中了退役别名 `alias`、却选不中它的正名 `canonical`。`alias` / `canonical` 恒取自 core 静态目录(闭集字符串,不含调用方原字节)。 */
+/**
+ * 一次 matcher 求值的答案(闭集四词;**受理面与运行期同一张**):`true` 选中 · `false` 不选 · `"invalid"` 契约答编不过 · `"over_budget"` 这一次求值没在预算内结束(灾难回溯)。
+ * 处置它的 switch 都是穷举的(加一词 = 这里加、每个处置点编译红)。
+ */
+export type MatcherAnswer = boolean | "invalid" | "over_budget";
+/** 一条受理面判决(纯数据)· 死别名:`event` 事件下第 `groupIndex` 组(从 0 起)的 matcher 选中了退役别名 `alias`、却选不中它的正名 `canonical`。`alias` / `canonical` 恒取自 core 静态目录(闭集字符串,不含调用方原字节)。 */
 export interface DeadToolMatcherIssue {
     readonly reason: "dead_alias";
     readonly event: HookEventName;
+    readonly groupIndex: number;
     readonly alias: string;
     readonly canonical: string;
 }
@@ -175,6 +262,13 @@ export interface OverBudgetMatcherIssue {
     readonly groupIndex: number;
     readonly budgetMs: number;
 }
+/** 一条受理面判决(纯数据)· 受理总额度用尽(S-1503):`event` 事件下第 `groupIndex` 组(从 0 起)的 matcher 求完之后,本次受理里所有已完成正则形求值的耗时之和超过了 `totalMs`。三键都是闭集 / 数字,不含调用方原字节。 */
+export interface BudgetExceededMatcherIssue {
+    readonly reason: "budget_exceeded";
+    readonly event: HookEventName;
+    readonly groupIndex: number;
+    readonly totalMs: number;
+}
 /**
  * 一条受理面判决(纯数据)· 正则编不过(S-1455 收尾):`event` 事件下第 `groupIndex` 组(从 0 起)的 matcher 在契约包的读法下答 `invalid`。
  * `matcher` = 那只 matcher 的原文、`compileError` = 引擎的编译错误句(各自截到 {@link MATCHER_ECHO_CHARS} 字符):**只供铸拒句用**,机读位 `detail` 不带它们。
@@ -186,68 +280,175 @@ export interface InvalidRegexMatcherIssue {
     readonly matcher: string;
     readonly compileError: string;
 }
-/** 受理面判据的判决(闭集三形,`reason` 区分;每一形都是 400 拒):死别名 · 求值超预算 · 正则编不过。 */
-export type ToolMatcherIssue = DeadToolMatcherIssue | OverBudgetMatcherIssue | InvalidRegexMatcherIssue;
-/** {@link buildToolMatcherRefusal} 的返回(纯数据):拒句 + 400 体上的两个机读位。`field` 恒为字面 `"settings.hooks"`;`detail` 与 {@link ToolMatcherIssue} 同键(按 `reason` 分形,逐个挑出,不 spread)。 */
-export interface ToolMatcherRefusal {
+/** 受理面判据的判决(闭集四形,`reason` 区分;每一形都是 400 拒):死别名 · 单次求值超预算 · 受理总额度用尽 · 正则编不过。 */
+export type HooksMatcherIssue = DeadToolMatcherIssue | OverBudgetMatcherIssue | BudgetExceededMatcherIssue | InvalidRegexMatcherIssue;
+/**
+ * `settings.hooks` 受理面读者({@link parseHooksConfig})的拒判决(纯数据;闭集按 `reason` 分形,与 {@link HooksMatcherIssue} 合起来是这一面**全部**的拒):
+ *  · 分类器点名的一块({@link HooksPieceIssue}):`reason` = 契约包的码(`HOOKS_REJECTION_CODES` / `HOOKS_DROPPED_PIECE_CODES`,原样、不改拼法)、`path` = 分类器的坐标、`key` = 这一块上让它坏的那个键;
+ *  · 本仓不执行的条目类型({@link UnsupportedEntryTypeIssue});
+ *  · 服务侧上限({@link HooksCapIssue}):`reason` = 撞帽的量纲(`over_cap` 条数 / `too_long` 字符数,与请求体其余各处的帽同一张表);
+ *  · 分类器说拒却一块都没点名({@link UnnamedHooksRefusalIssue}:契约漂移,fail-closed)。
+ */
+export interface HooksPieceIssue {
+    readonly reason: HooksDroppedPieceCode | HooksRejectionCode;
+    readonly path: ConfigPath;
+    readonly key?: string;
+}
+/** 本仓不执行的条目类型(`path` 指那一条的 `type`)。 */
+export interface UnsupportedEntryTypeIssue {
+    readonly reason: "unsupported_entry_type";
+    readonly path: ConfigPath;
+    readonly type: HookEntryType;
+}
+/** hooks 的服务侧上限只有条数与字符数两种量纲(没有字节帽):`reason` 的词随量纲从 {@link LIMIT_REASONS} 取,本面的读者穷举读这两个词。 */
+type HooksCapMeasure = Extract<LimitMeasure, "entries" | "characters">;
+type HooksCapReason = (typeof LIMIT_REASONS)[HooksCapMeasure];
+/** 服务侧上限的哪一条(只供铸句;机读位只出 `reason` / `path` / `count` / `cap`)。帽的量纲与数在 {@link HOOKS_CAPS} 一张表。 */
+type HooksCap = "matcher_groups" | "event_entries" | "command" | "url" | "headers" | "header_chars" | "allowed_env_vars" | "plugin";
+/**
+ * 服务侧上限撞帽:`path` = 撞帽处的坐标(组数 ⇒ 那个事件;一个事件的条目总数 ⇒ 第一条超出的条目;命令 / URL ⇒ 那个字段;header 条数 / 总字符数 ⇒ `headers`;
+ * `allowedEnvVars` ⇒ 那个字段),`count` = 送来的量,`cap` = 帽,`reason` 由量纲定。
+ */
+export interface HooksCapIssue {
+    readonly reason: HooksCapReason;
+    readonly limit: HooksCap;
+    readonly event: HookEventName;
+    readonly path: ConfigPath;
+    readonly count: number;
+    readonly cap: number;
+}
+/** 分类器说「不是 loaded」却一块都没点名 / `loaded` 却没有 `hooks`:契约漂移 —— 响亮地拒(fail-closed),不把「说不出理由」当受理。 */
+export interface UnnamedHooksRefusalIssue {
+    readonly reason: "unnamed_refusal";
+    readonly path: ConfigPath;
+}
+/** 本仓读的 wire 键(契约分类器不认、会剥掉的那三只)。 */
+export type HooksWireKey = "source" | "plugin" | "args";
+/**
+ * 本仓的 wire 键形错(`path` 指那只键:组的 `source` / command 条目的 `plugin` / `args`)。这三只键分类器不认(它对未知键一律剥除),
+ * 由 {@link parseHooksConfig} 在分类器装上的同一坐标上读 —— 形错 = 拒,**不**再被静默剥掉(剥掉 `source` = 托管组落进非托管道;剥掉 `args` = exec 形只剩可执行名)。
+ */
+export interface HooksWireKeyIssue {
+    readonly reason: "wire_key_invalid";
+    readonly path: ConfigPath;
+    readonly key: HooksWireKey;
+}
+/** 受理面 hooks 配置读者的拒判决。 */
+export type HooksConfigIssue = HooksPieceIssue | UnsupportedEntryTypeIssue | HooksCapIssue | UnnamedHooksRefusalIssue | HooksWireKeyIssue;
+/** `settings.hooks` 这一面的全部拒判决:配置读者的({@link HooksConfigIssue})与 fresh 提交面 matcher 判据的({@link HooksMatcherIssue})。 */
+export type HooksIssue = HooksConfigIssue | HooksMatcherIssue;
+/**
+ * 400 体上的 `detail`(按 `reason` 分形;每一形都带 `path` —— 判决所在的坐标,契约分类器的段形,相对请求体的 `settings` 对象,用户文本段过 `outgoingPath`)。
+ * matcher 四形另带它们各自的键(`event` / `alias` / `canonical`,`event` / `groupIndex` / `budgetMs`,`event` / `groupIndex` / `totalMs`,`event` / `groupIndex`)。
+ */
+export type HooksRefusalDetail = {
+    readonly reason: "dead_alias";
+    readonly event: HookEventName;
+    readonly alias: string;
+    readonly canonical: string;
+    readonly path: ConfigPath;
+} | {
+    readonly reason: "over_budget";
+    readonly event: HookEventName;
+    readonly groupIndex: number;
+    readonly budgetMs: number;
+    readonly path: ConfigPath;
+} | {
+    readonly reason: "budget_exceeded";
+    readonly event: HookEventName;
+    readonly groupIndex: number;
+    readonly totalMs: number;
+    readonly path: ConfigPath;
+} | {
+    readonly reason: "invalid_regex";
+    readonly event: HookEventName;
+    readonly groupIndex: number;
+    readonly path: ConfigPath;
+} | {
+    readonly reason: HooksDroppedPieceCode | HooksRejectionCode;
+    readonly path: ConfigPath;
+    readonly key?: string;
+} | {
+    readonly reason: "unsupported_entry_type";
+    readonly path: ConfigPath;
+    readonly type: HookEntryType;
+} | {
+    readonly reason: HooksCapReason;
+    readonly path: ConfigPath;
+    readonly count: number;
+    readonly cap: number;
+} | {
+    readonly reason: "unnamed_refusal";
+    readonly path: ConfigPath;
+} | {
+    readonly reason: "wire_key_invalid";
+    readonly path: ConfigPath;
+    readonly key: HooksWireKey;
+};
+/** {@link buildHooksRefusal} 的返回(纯数据):拒句 + 400 体上的两个机读位。`field` 恒为字面 `"settings.hooks"`。 */
+export interface HooksRefusal {
     readonly message: string;
     readonly field: "settings.hooks";
-    readonly detail: {
-        readonly reason: "dead_alias";
-        readonly event: HookEventName;
-        readonly alias: string;
-        readonly canonical: string;
-    } | {
-        readonly reason: "over_budget";
-        readonly event: HookEventName;
-        readonly groupIndex: number;
-        readonly budgetMs: number;
-    } | {
-        readonly reason: "invalid_regex";
-        readonly event: HookEventName;
-        readonly groupIndex: number;
-    };
+    readonly detail: HooksRefusalDetail;
 }
 /**
- * 判决 → 拒句 + 机读位。**拒句的唯一铸点**:死别名的句子逐字 = 7.114.0 的那一句(`test/hooks-alias-matcher-s995.test.ts` R7 冻结);受理门 `admission.ts` 用返回值填 400 体,
- * 不从句子里反解字段。超预算的句子点名**哪一只**(事件 + 组下标 + `matcher`)与**预算**,不回显 matcher 原字节(S-716 姿势);`reason` 闭集穷举(多一形 = 这里编译红)。
+ * 判决 → 拒句 + 机读位 —— `settings.hooks` 这一面**拒句与机读位的唯一铸点**(配置读者的拒与 fresh 提交面的 matcher 拒同经这里;受理门 `admission.ts` 用返回值填 400 体,
+ * 不从句子里反解字段)。句子:死别名逐字 = 7.114.0 的那一句(`test/hooks-alias-matcher-s995.test.ts` R7 冻结);超预算点名**哪一只**(事件 + 组下标 + `matcher`)与**预算**,不回显 matcher 原字节(S-716 姿势);
+ * 分类器的一块 = 坐标 + 码 + 释义(+ 坏键);服务侧上限的几句逐字 = 7.131.0。`reason` 闭集穷举(多一形 = 这里编译红)。
  */
-export declare function buildToolMatcherRefusal(issue: ToolMatcherIssue): ToolMatcherRefusal;
+export declare function buildHooksRefusal(issue: HooksIssue): HooksRefusal;
 /**
- * fresh 提交面专用判据(S-924 / S-995 / S-1455):配置里第一条「该拒」的工具事件 matcher 的判决数据({@link ToolMatcherIssue}):「永远打不中」(死别名)或「求值超预算」(灾难回溯);没有 ⇒ undefined。
- * 拒句与 400 体的机读位由 {@link buildToolMatcherRefusal} 从这份数据铸(S-1025)。**按配置顺序(事件 → 组)遇到的第一条定结局**;结局只取决于配置,不取决于求值次序之外的任何东西(无共享预算、无时钟)。
+ * fresh 提交面专用判据(S-924 / S-995 / S-1455 / S-1472 / S-1503):配置里第一条「该拒」的 matcher 的判决数据({@link HooksMatcherIssue}):「永远打不中」(死别名,只属工具事件)· 「编不过」(任何事件)· 「单次求值超预算」(灾难回溯)· 「受理总额度用尽」;没有 ⇒ undefined。
+ * 拒句与 400 体的机读位由 {@link buildHooksRefusal} 从这份数据铸(S-1025)。**按配置顺序(事件 → 组)遇到的第一条定结局**;良性设置的结局只取决于配置(每次求值的额度固定、不共享;总额度离良性设置近三个数量级,见头注「预算与结局」)。
  * 入参是 {@link parseHooksConfig} 已校验过的配置;`depth` 由调用点按车道定(见头注:`taskHooksHonored(config) ? "regex" : "literal"`)。
  * `budget` **仅供测试注入**({@link MatcherEvalBudget});生产调用点只传前两个实参。
  * **只有 `admission.ts` 的 fresh 提交门调它** —— resume 重放不调(理由见上面的头注)。未判的 matcher 过 `recordFailOpen`(tag `MATCHER_UNJUDGED_TAG`);超预算的不是未判,是拒。
  */
-export declare function toolMatcherIssue(config: RunnableHooksConfig, depth: MatcherEvalDepth, budget?: MatcherEvalBudget): ToolMatcherIssue | undefined;
-/** 坐标出门形:`settings.` + 契约包唯一的 stringify 点({@link formatConfigPath}),事件名等键段是用户文本 ⇒ 先过 {@link outgoingPath}(凭据形不原样回显)。 */
+export declare function hooksMatcherIssue(config: RunnableHooksConfig, depth: MatcherEvalDepth, budget?: MatcherEvalBudget): HooksMatcherIssue | undefined;
+/**
+ * 坐标的出门段:事件名等键段是用户文本 ⇒ 先过 {@link outgoingPath}(凭据形不原样回显),每个串段再过调用方串的唯一回显口径(`caller-text-echo.ts`:剥控制 / 双向字符、截到 64 字 + …)——
+ * 一只 100 KB 的未知键不把拒体撑大、也不在句子里夹看不见的字符。400 体的 `detail.path` 与拒句里的坐标读的都是它。
+ */
+export declare function hooksOutgoingPath(path: ConfigPath): ConfigPath;
+/** 坐标出门形:`settings.` + 契约包唯一的 stringify 点({@link formatConfigPath})作用在 {@link hooksOutgoingPath} 上。 */
 export declare function hooksCoordinate(path: ConfigPath): string;
 /**
  * 把 wire 上的 untrusted `settings.hooks` 判成 {@link RunnableHooksConfig} + 服务侧上限 —— **hooks 配置在本仓的唯一入口**。
  *
  *  · **一只读者**:合不合法只问契约包的 {@link classifyHooksConfig}(入参是 `{ hooks: raw }`,与契约 zod 面 `HooksConfig` 是同一读法的投影)。本仓只收 `loaded`:
  *    一块被剔(`loaded-partial`)或整份被拒(`rejected`)都是拒 —— wire 面「剔掉坏块、其余照装」会让写的人以为生效的钩子无声消失(分类器的宽松粒度是读设置文件的宿主用的)。
- *    拒句 = 分类器给的**码 + 坐标 + 坏字段**经 {@link hooksPieceRefusal} 铸(分类器不写句子)。
+ *    拒的判决 = 分类器给的**码 + 坐标 + 坏字段**({@link HooksPieceIssue};分类器不写句子,句子与 400 体的机读位由 {@link buildHooksRefusal} 铸)。
  *  · **本仓不执行的条目类型整份拒**:分类器受理契约的全部五型,而本仓只跑 {@link SUPPORTED_HOOK_ENTRY_TYPES}。含其余类型的配置整份拒,不留跳过臂。
- *  · **服务侧上限**(广度闸;契约本身不设量纲)。
+ *  · **本仓的 wire 键**(分类器不认、会剥掉的三只):组上的 `source`(来源闭集,`hook-source.ts`)、command 条目上的 `plugin` / `args`(执行上下文,`command-spawn.ts`)——
+ *    在分类器装上的**同一坐标**上读原值(分类器只在 `loaded` 时放行,装上的件与原值逐位对齐),形错 ⇒ {@link HooksWireKeyIssue}。
+ *    `plugin` / `args` 只在 command 条目上有义:别的条目上它们与任何未知键一样被分类器剥掉(CC 同形)。值为 `undefined` 与缺席同读(与分类器读可选字段同一口径)。
+ *  · **服务侧上限**(广度闸;契约本身不设量纲)。exec 形的命令行(`command` + 各 `args`)计入 `command` 帽;插件上下文一道总字符帽。
  *
- * 错误返回 error 字符串而不 throw——submit 路径 400 fail-loud、resume 防御路径 warn-drop(hooks 整只不采纳),由调用方选;**读者与句子两腿同一只**,后果按腿分。
+ * 拒返回判决(`issue`)与它的句子(`error`)而不 throw —— submit 路径 400 fail-loud(体带 `field: "settings.hooks"` + `detail`)、resume 防御路径 warn-drop(hooks 整只不采纳),由调用方选;
+ * **读者、判决与句子两腿同一只**,后果按腿分。
  */
 export declare function parseHooksConfig(raw: unknown): ParseHooksConfigResult;
 /**
- * 运行期的 matcher 读法席位:**问契约包的 `hookMatcherSelects`,别无其它**(壳与服务端都问这一只,谁都不留副本;读法全文见它的头注,这里不重述)。
+ * 运行期的 matcher 读法席位:**问契约包的 `hookMatcherSelects`,经受理面同一只带预算的求值口({@link matcherSelectsBy})**(壳与服务端都问这一只契约函数,谁都不留副本;读法全文见它的头注,这里不重述)。
  * 三形(名字表 / 空 `*` 缺省 / 不锚定的 JS 正则)与「编不过 ⇒ `"invalid"`」都由它答;**对所有带 matcher 的事件同一只读法**(工具事件 / StopFailure 的 `error` 词 /
- * PreCompact·PostCompact 的 `trigger` 词 / `if` 条件的名部),不按事件分档。`"invalid"` ⇒ 该组不跑(fail-closed 到「不跑」),由调用方记账一次(`hook_matcher_invalid`);
- * 受理面({@link toolMatcherIssue})问的是同一只函数。
+ * PreCompact·PostCompact 的 `trigger` 词 / `if` 条件的名部),不按事件分档。
+ *
+ * 🔴 **预算(S-1017)**:求法与受理面 `"regex"` 档同一格表({@link MATCHER_EVALUATION}):字面形(名字表 / 空 / `*` / 缺省)直接问契约函数,不进 vm、不占额度;
+ * 正则形**每一次求值**进 vm、各拿一份固定的 {@link ADMISSION_MATCHER_BUDGET}`.budgetMs`(不共享、不读钟、不新造第二只预算常量)。受理面只对 core 目录里的别名 / 正名这几个短名字求过值,
+ * 运行期要对**任意别的工具名**求值 —— 受理过了的 matcher 在某个名字上灾难回溯,不能再同步占住事件循环。
+ * 四个答案(闭集,{@link MatcherAnswer}),调用方各用一条穷举 switch 处置({@link matcherGroupSelected} / {@link hookIfMatches}):
+ *  · `true` / `false` —— 选中 / 不选;
+ *  · `"invalid"` —— 该组不跑(fail-closed 到「不跑」),调用方记账一次(`hook_matcher_invalid`);
+ *  · `"over_budget"` —— 这一次求值没在预算内结束 ⇒ **按选中处理 + 登记**(`hook_matcher_over_budget` 一行日志 + `matcher_over_budget` 一帧):不选 = 守卫 hook 被静默放过 = fail-open,
+ *    所以方向是「多跑」不是「少跑」;不静默 —— 每次发生各登记一次,一直在坏就一直说。
  */
-export declare function hookMatcherMatches(matcher: string | undefined, value: string): boolean | "invalid";
+export declare function hookMatcherMatches(matcher: string | undefined, value: string): MatcherAnswer;
 /** `if` 条目条件(CC-exact,对照 CC 2.1.187/198 实测行为核验的真语义,两版一致):
  *  值 = permission-rule 模式(`ToolName` 或 `ToolName(arg-模式)`),【不是】表达式语言——按当前工具调用
  *  求值:名部走 permission matcher(交替/正则同 matcher 字段),括号内 arg-模式(`*` 通配)匹配工具输入的
  *  主字符串(Bash=command,文件工具=file_path/path)。CC 行为逐条目:不匹配 → 跳过该条目(记日志);
  *  非工具事件(payload 无 tool_name)→ "cannot be evaluated" 跳过;解析失败 → 跳过。返回:
- *  true=跑 / "not_matched" / "unevaluable"(调用方分别记账;跳过永不静默)。
+ *  true=跑 / "not_matched" / "unevaluable"(调用方分别记账;跳过永不静默)/ "over_budget"(S-1017:名部求值没在预算内结束 ⇒ 调用方按**选中**处理 + 登记,见 {@link hookMatcherMatches})。
  *
  *  2.1.250 复核([ref],2026-08-30;语料=sema-internal `blueprints/cc-decoded/cli250.js`):求值器与 220
  *  逐字同构——五种工具事件之外「cannot be evaluated for non-tool event」跳过、「Skipping hook due to if
@@ -255,8 +456,8 @@ export declare function hookMatcherMatches(matcher: string | undefined, value: s
  *  本实现同向。差异登记(不改行为):①250 证据里名部=**规范化后等值比对**(`vd(toolName)!==o`),
  *  「交替/正则」是 matcher 字段的文法——本实现名部走 hookMatcherMatches 属**超集**(alternation 也认),
  *  如实登记不收窄;②250 的 `if` 已扩到 prompt/agent/http/mcp_tool 条目(本 runner 只翻 command,不涉)。 */
-export declare function hookIfMatches(cond: string, payload: unknown): true | "not_matched" | "unevaluable";
-/** createTaskHooks 的装配上下文(payload 的 CC-verbatim 字段来源)。 */
+export declare function hookIfMatches(cond: string, payload: unknown): true | "not_matched" | "unevaluable" | "over_budget";
+/** createSettingsHooksRegistration 的装配上下文(payload 的 CC-verbatim 字段来源)。 */
 export interface HookRunnerContext {
     logger: Logger;
     sessionId: string;
@@ -280,7 +481,7 @@ export interface HookRunnerContext {
     onHookNotice?: (n: HookNoticeObservation) => void;
     /** Stop × `type:"prompt"` 是否把**会话 transcript** 交给评估者(CC `execPromptHook` 形)。
      *  缺省(undefined)= **开**。`false` ⇒ 整条路不启用(prompt 条目在 Stop 上被跳过并记账)——
-     *  部署侧的显式逃生口(`SEMA_STOP_PROMPT_TRANSCRIPT=0`)。见 `hooks.stop` 里那段三问。 */
+     *  部署侧的显式逃生口(`SEMA_STOP_PROMPT_TRANSCRIPT=0`)。见 Stop 翻译里那段三问。 */
     stopPromptTranscript?: boolean;
     /** asyncRewake wake 管道(契约:Background + wake the model on exit 2)。部署组装:live 腿=同 session
      *  的 TaskStream.steer(下个 turn 边界注入);返回 false=没有活流可投(任务已结束/挂起/别副本)——
@@ -314,19 +515,75 @@ export type HookLlmCall = (opts: {
     code?: HookLlmFailureCode;
 }>;
 /** 失败判别码(B8:判别一律走码,禁按 error 文案分支——v3.1 批2,统检第二波 high)。error 仍是给人看的
- *  自由文本;code 是给控制流的。缺席=未分类失败(不重试、不特判)。 */
-export type HookLlmFailureCode = "no_content" | "hard_timeout" | "redirect_refused";
+ *  自由文本;code 是给控制流的。缺席=未分类失败(不重试、不特判)。
+ *
+ *  🔴 **一类真因一个码**(S-1635;闭集 —— 消费方的 `switch` 无兜底分支,加一个码而不表态 = 编译错误):码是**成因族**的名字,铸点是直连载体
+ *  (`hook-llm.ts` 的 `callLlm` / `hookModelFor`)的每一个失败臂,消费方(会话标题器的 fail-open 标签表)据此区分「该改哪里」,不读 `error` 文案:
+ *   · `model_unresolved`:这只模型在本部署上选不出来 —— 目录里没有 / 条目不可用 / 网关腿解析不出端点(改目录或网关配置)
+ *   · `route_refused`:路由核验拒发 —— key↔URL 不配对,或 foreign 端点无 per-model key(改路由 / 凭据配置;零请求)
+ *   · `credential_custody_failed`:per-model key 托管读不出(密封 key 中毒 / 解密失败;不回落共享凭据,零请求)
+ *   · `redirect_refused`:端点回了 3xx、直连请求按律不跟随(`egress-redirect.ts`;把网关 URL 改成最终地址)
+ *   · `bad_response`:端点答了,但不是可用的 completion —— 非 2xx 状态,或 2xx 而 body 不是 JSON
+ *   · `no_content`:端点答了合法 JSON,里面没有文本(CC 评估者路对它重试一次)
+ *   · `unreachable`:连不上 / 网络层失败 / 超时(没有应答)
+ *  载体层面的整体硬顶(`hard_timeout`)不在这里:它由 runner 自己的 `Promise.race` 铸、只在 runner 内部读,不是载体的失败码。 */
+export type HookLlmFailureCode = "model_unresolved" | "route_refused" | "credential_custody_failed" | "redirect_refused" | "bad_response" | "no_content" | "unreachable";
+/** 托管相「未跑成」的原因闭集(= 帧 `hook_managed_unrun.reason`;每个词对应一条既有的跳过 / 故障臂,见 `fleet-bus.ts` 的 {@link HookManagedUnrun})。 */
+export type ManagedUnrunReason = HookManagedUnrun["reason"];
+/**
+ * 有放行 / 改写判词的事件(翻译器读 `permissionDecision: "allow"` / `updatedInput` 的那一个:PreToolUse)。判词不可信这条律(否决算数,放行与改写不作数)
+ * 只在这里有东西可不采信 ⇒ 只在这里铸 `distrust`;别的事件没有放行词,判词照收,不发「放行与改写不作数」的帧(那会说一件没发生的事)。
+ * 按事件名穷举(`satisfies Record<HookEventName, boolean>`,与 `HOOK_EVENT_OWNER` / `HOOK_EVENT_MATCHER_FIELD` 同形):契约加一个事件而这里没表态 = 编译红 ——
+ * 不缺省倒向「照收放行」(安全轴的闭集律)。壳属事件不在本服务跑,恒 `false`。
+ */
+export declare const PERMISSIVE_VERDICT_EVENTS: {
+    readonly PreToolUse: true;
+    readonly PostToolUse: false;
+    readonly PostToolUseFailure: false;
+    readonly PostToolBatch: false;
+    readonly Notification: false;
+    readonly UserPromptSubmit: false;
+    readonly UserPromptExpansion: false;
+    readonly SessionStart: false;
+    readonly SessionEnd: false;
+    readonly Stop: false;
+    readonly StopFailure: false;
+    readonly SubagentStart: false;
+    readonly SubagentStop: false;
+    readonly PreCompact: false;
+    readonly PostCompact: false;
+    readonly PermissionRequest: false;
+    readonly PermissionDenied: false;
+    readonly Setup: false;
+    readonly TeammateIdle: false;
+    readonly TaskCreated: false;
+    readonly TaskCompleted: false;
+    readonly Elicitation: false;
+    readonly ElicitationResult: false;
+    readonly ConfigChange: false;
+    readonly WorktreeCreate: false;
+    readonly WorktreeRemove: false;
+    readonly InstructionsLoaded: false;
+    readonly CwdChanged: false;
+    readonly FileChanged: false;
+    readonly MessageDisplay: false;
+    readonly DirectoryAdded: false;
+    readonly PreModelSwitch: false;
+    readonly PostModelSwitch: false;
+};
 /**
  * hook 上下文片段 → 喂给模型的单串。**所有** `additionalContext` 聚合点的唯一属主(此前是同一个
  * `contexts.join("\n")` 表达式抄在二十余处,总量帽无处可挂 —— 那正是漂移成因)。
  *
- * 三条语义,都是承重的:
+ * 四条语义,都是承重的:
  *  1. **顺序保留、只截尾**:先来的钩子先说话;一旦装不下就停,后面的条目一律不再挤进来(哪怕更短)。
  *     按长度重排会让"第 3 条钩子的话"随别人的长度忽隐忽现,排障时无从复现。
  *  2. **截断可见**:尾巴挂一行标记说明省了几条、丢了多少字符。静默丢弃会让 hook 作者以为自己的
  *     context 生效了,而模型那头根本没见过 —— 这类"以为配好了"的缺席比长文本本身更贵。
  *  3. **标记不计预算**:与 core `truncateError` / CC `A7e` 同姿势(marker 不占那 10k),否则帽值的
  *     含义会随标记文案长度漂。
+ *  4. **一片 = 一条钩子发言,标记只写不读**:输入只来自钩子(不可信文本),本函数的成品不会被再聚合一次
+ *     (跨记录的合成器随 core 7.52.0 退役:部署两张注册是观察者,不出答案)。钩子自己吐出的同形文字就是普通内容。
  */
 export declare function buildHookContext(parts: readonly string[]): string | undefined;
 /**
@@ -365,23 +622,20 @@ export interface LlmHookExtra {
     transcript?: string;
 }
 /**
- * 把校验过的 {@link RunnableHooksConfig} 翻成 core `Hooks` 回调(阶段二:engine-owned 9 事件全点亮)。
- * 没有可点亮的条目 → undefined(spec 不挂 hooks,deps 路径原样)。
- */
-export declare function createTaskHooks(config: RunnableHooksConfig, ctx: HookRunnerContext): Hooks | undefined;
-/**
- * 把部署级 hooks 基线(deps.hooks,如 TOOL_TRACE 观测)折进 task 级 hooks——core 是整槽覆盖
- * (`spec.hooks ?? deps.hooks`),不折叠就静默 shadow 部署观测(runtask gateBaseline 注释点名的坑)。
- * 语义:部署槽先跑(观测看到原始输入/输出),task 槽后跑;结果合并:
- *  - preToolUse:每一槽的结果**先过 core 的 hook 席收据** `receiveHookResult`(S-971,core 7.39.0 #1274)—— 引擎拒的载体 ⇒ 交回引擎的拒绝体
- *    (短路,引擎按自己的 fail-closed 拒处置);收下的 ⇒ 折它的冻结副本:deny > ask > allow 折叠;updatedInput 串行线程(部署重写喂给 task 槽);context 拼接。
- *  - postToolUse/postToolUseFailure/postToolBatch:双跑,additionalContext 拼接,updatedOutput 取
- *    后者(task 槽)优先。
- *  - userPromptSubmit/stop:部署 block 优先短路(不再跑 task 槽),否则双跑、context 拼接、task block 生效。
- *  - preCompact:双跑,block 部署优先,additionalInstructions 拼接。
- *  - stopFailure/postCompact(observe-only void):顺序双跑,无返回可折。
- * 单在则透传。
+ * 律一 · 把校验过的 {@link RunnableHooksConfig} 铸成**一张** mods 注册 `settings.hooks`(任务座;档缺席 = `user`)。
+ * 没有可挂的条目 → undefined(`TaskSpec.mods` 不铸)。`budgetMs` = {@link settingsHooksBudgetMs} 的读数(调用方交)。
+ *
+ * 构造约束(每一条都有引擎侧的硬理由):
+ *  · `register` 同步、只读本注册自己的配置、不按腿分支 —— 返回 thenable 即 `config.mods_invalid`;委派子代把父的任务座当自己的派发,
+ *    两条腿挂的是同一套 handler,父链才塌进子代的 phase 1(否则多一次约束判定);
+ *  · `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}):
+ *    一路贯穿到命令腿的 spawn({@link runCommandHook}),本仓不自合成第二只、不另设钟。
  */
-export declare function composeHooks(deployment: Hooks | undefined, task: Hooks): Hooks;
+export declare function createSettingsHooksRegistration(config: RunnableHooksConfig, ctx: HookRunnerContext, budgetMs: number): ModRegistration<EngineDollar> | undefined;
 export {};
 //# sourceMappingURL=hook-runner.d.ts.map