@sema-agent/server 7.132.0 → 7.133.0

package/dist/hooks/command-spawn.js

@@ -0,0 +1,139 @@
+import { mkdir, stat } from "node:fs/promises";
+import { isAbsoluteHostPath } from "@sema-agent/settings-schema";
+const PLUGIN_MEMBERS = new Set(["name", "root", "dataDir", "options"]);
+const OPTION_KEY = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function isRecord(v) {
+    if (v === null || typeof v !== "object" || Array.isArray(v))
+        return false;
+    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;
+    for (const k of Object.keys(raw))
+        if (!PLUGIN_MEMBERS.has(k))
+            return undefined;
+    const { name, root, dataDir, options } = raw;
+    if (typeof name !== "string" || name.length === 0 || name.includes("\0"))
+        return undefined;
+    if (!isAbsoluteHostPath(root))
+        return undefined;
+    if (dataDir !== undefined && !isAbsoluteHostPath(dataDir))
+        return undefined;
+    let opts;
+    if (options !== undefined) {
+        if (!isRecord(options))
+            return undefined;
+        const entries = Object.entries(options);
+        for (const [k, v] of entries)
+            if (!OPTION_KEY.test(k) || typeof v !== "string" || v.includes("\0"))
+                return undefined;
+        opts = Object.fromEntries(entries);
+    }
+    return { name, root: root, ...(dataDir !== undefined ? { dataDir: dataDir } : {}), ...(opts !== undefined ? { options: opts } : {}) };
+}
+export function hookPluginChars(p) {
+    return p.name.length + p.root.length + (p.dataDir?.length ?? 0) + Object.entries(p.options ?? {}).reduce((n, [k, v]) => n + k.length + v.length, 0);
+}
+export function commandLineChars(entry) {
+    return entry.command.length + (entry.args ?? []).reduce((n, a) => n + 1 + a.length, 0);
+}
+export function hookPluginEnv(p) {
+    if (p === undefined)
+        return {};
+    const env = { CLAUDE_PLUGIN_ROOT: p.root };
+    if (p.dataDir !== undefined)
+        env.CLAUDE_PLUGIN_DATA = p.dataDir;
+    for (const [k, v] of Object.entries(p.options ?? {}))
+        env[`CLAUDE_PLUGIN_OPTION_${k.toUpperCase()}`] = v;
+    return env;
+}
+const CONTEXT_VARS = [
+    ["CLAUDE_PLUGIN_ROOT", "${CLAUDE_PLUGIN_ROOT}"],
+    ["CLAUDE_PLUGIN_DATA", "${CLAUDE_PLUGIN_DATA}"],
+];
+const ROOT_REF = CONTEXT_VARS[0][1];
+const SUBSTITUTION_NAMES = ["CLAUDE_PROJECT_DIR", "CLAUDE_PLUGIN_ROOT", "CLAUDE_PLUGIN_DATA"];
+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];
+    return v !== undefined && v.length > 0 ? v : undefined;
+}
+export async function planCommandSpawn(entry, cwd, requestEnv) {
+    const texts = [entry.command, ...(entry.args ?? [])];
+    const p = entry.plugin;
+    const env = composeHookEnvLayer(requestEnv, cwd, p);
+    const values = new Map([["CLAUDE_PROJECT_DIR", env.CLAUDE_PROJECT_DIR]]);
+    for (const [name, ref] of CONTEXT_VARS) {
+        const value = contextVarValue(name, env);
+        if (value !== undefined) {
+            values.set(name, value);
+            continue;
+        }
+        if (!texts.some((t) => t.includes(ref)))
+            continue;
+        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)`,
+        };
+    }
+    if (p !== undefined) {
+        const isDir = await stat(p.root).then((s) => s.isDirectory(), () => false);
+        if (!isDir)
+            return { kind: "refused", error: `plugin directory does not exist: ${p.root} (${p.name} — reinstall the plugin)` };
+        if (p.dataDir !== undefined) {
+            try {
+                await mkdir(p.dataDir, { recursive: true });
+            }
+            catch (e) {
+                return { kind: "refused", error: `plugin data directory could not be created: ${p.dataDir} (${e instanceof Error ? e.message : String(e)})` };
+            }
+        }
+    }
+    if (entry.args === undefined)
+        return { kind: "shell", command: entry.command, env };
+    const substitute = (s) => {
+        if (!s.includes("${"))
+            return s;
+        let out = "";
+        let i = 0;
+        while (i < s.length) {
+            const at = s.indexOf("${", i);
+            if (at === -1) {
+                out += s.slice(i);
+                break;
+            }
+            out += s.slice(i, at);
+            const hit = SUBSTITUTION_NAMES.find((name) => s.startsWith(refOf(name), at));
+            const v = hit === undefined ? undefined : values.get(hit);
+            if (hit !== undefined && v !== undefined) {
+                out += v;
+                i = at + refOf(hit).length;
+            }
+            else {
+                out += "${";
+                i = at + 2;
+            }
+        }
+        return out;
+    };
+    return { kind: "exec", file: substitute(entry.command), args: entry.args.map(substitute), env };
+}
+//# sourceMappingURL=command-spawn.js.map

package/dist/hooks/hook-llm.js

@@ -1,6 +1,6 @@
 import { admitRouteRequest, BrainError, joinRequestUrl, resolveRouteCredential, routeKeyOf } from "@sema-agent/core";
 import { matchCatalogModel, refusedCatalogEntry, servedModelTableLeg } from "../model-select.js";
-import { modelUnavailableMessage } from "../model-entry-refusal.js";
+import { echoModelRef, modelUnavailableMessage } from "../model-entry-refusal.js";
 import { resolveOpenaiRouteEndpoint } from "../model-route-endpoint.js";
 import { anthropicRouteRoot, brainLaneFor, routeTableOf } from "../model-provider.js";
 import { egressRedirectRefusal } from "../egress-redirect.js";
@@ -72,7 +72,7 @@ export function createHookLlm(deps) {
             return unavailable("hook model", requested);
         if (requested === config.model.id)
             return shapeFrom(config.model);
-        return unavailable("hook model", requested) ?? unresolvedPick(`hook model "${requested}" is not in this deployment's catalog`);
+        return unavailable("hook model", requested) ?? unresolvedPick(`hook model "${echoModelRef(requested)}" is not in this deployment's catalog`);
     };
     const judgeRoute = (pick, perModelKey, deploymentKey, declaredRoot) => {
         const credential = resolveRouteCredential({

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

@@ -3,8 +3,10 @@ import { type ConfigPath } from "@sema-agent/settings-schema";
 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 LimitReason } from "../limit-refusal.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;
@@ -56,14 +58,29 @@ export declare const SETTINGS_HOOK_STATIONS: {
 /** 这张注册的名字 —— wire 可见(`wiring_manifest.mods[].name`、`allowRuleShadowed[].entries`),也是 handler 失败时引擎拒句点名的扩展名。 */
 export declare const SETTINGS_HOOKS_REGISTRATION = "settings.hooks";
 /**
- * 律四 · `HOOKS_TIMEOUT_MS` 未设时本注册每个 handler 的预算(ms)= 本服务跑钩子子进程的界:单条命令超时的上限
- * {@link MAX_HOOK_TIMEOUT_SECONDS}。不是抄引擎缺省(引擎缺省是 10 s,一条跑 11 s 的 PreToolUse 钩子会因此被 fail-closed 拒)。
+ * 律四 · `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},以及每个按条目类型分派的臂)读的都是它。
  *
@@ -84,13 +101,16 @@ 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 createSettingsHooksRegistration})只收这一型,「不认识的类型」到不了它手里。 */
@@ -123,7 +143,7 @@ export type ParseHooksConfigResult = {
  *
  * 规则(一条;字面形是它的特例):{@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`(缺席 / 空 / `*` / 名字表形;契约不编、不跑调用方的正则)⇒ 两档都**直接问契约函数**、**不占求值预算**;
@@ -161,8 +181,8 @@ export type ParseHooksConfigResult = {
  * `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` 钩子)运行,
  * 多租户车道走 literal 档、零调用方正则执行 —— 受理面的 DoS 面不因此重开。
@@ -193,8 +213,9 @@ export type ParseHooksConfigResult = {
 /** 超此长度的 matcher 不在受理面读(两档同一个上限;未判,reason = oversize)。与 {@link MAX_HOOK_COMMAND_CHARS} 同量纲的服务侧防线:真实 matcher(精确名 / 交替 / `mcp__.*`)远在其内;目录全部工具名交替 ~0.5 KiB。 */
 export declare const MAX_MATCHER_EVAL_CHARS = 8192;
 /**
- * regex 档的**求值预算表**(毫秒)—— 两个数同出这一张表,判据与测试注入都不另持第二份:
+ * 正则形 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 的调用方)。
@@ -207,6 +228,8 @@ export declare const ADMISSION_MATCHER_BUDGET: {
 };
 /** 拒句里回显的 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";
 /**
@@ -219,6 +242,11 @@ export interface MatcherEvalBudget {
     readonly totalMs?: number;
     readonly now?: () => number;
 }
+/**
+ * 一次 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";
@@ -272,14 +300,17 @@ export interface UnsupportedEntryTypeIssue {
     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";
+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: LimitReason;
+    readonly reason: HooksCapReason;
     readonly limit: HooksCap;
     readonly event: HookEventName;
     readonly path: ConfigPath;
@@ -291,8 +322,19 @@ 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;
+export type HooksConfigIssue = HooksPieceIssue | UnsupportedEntryTypeIssue | HooksCapIssue | UnnamedHooksRefusalIssue | HooksWireKeyIssue;
 /** `settings.hooks` 这一面的全部拒判决:配置读者的({@link HooksConfigIssue})与 fresh 提交面 matcher 判据的({@link HooksMatcherIssue})。 */
 export type HooksIssue = HooksConfigIssue | HooksMatcherIssue;
 /**
@@ -331,13 +373,17 @@ export type HooksRefusalDetail = {
     readonly path: ConfigPath;
     readonly type: HookEntryType;
 } | {
-    readonly reason: LimitReason;
+    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 {
@@ -373,25 +419,36 @@ 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`)——
+ *    在分类器装上的**同一坐标**上读原值(分类器只在 `loaded` 时放行,装上的件与原值逐位对齐),形错 ⇒ {@link HooksWireKeyIssue}。
+ *    `plugin` / `args` 只在 command 条目上有义:别的条目上它们与任何未知键一样被分类器剥掉(CC 同形)。值为 `undefined` 与缺席同读(与分类器读可选字段同一口径)。
+ *  · **服务侧上限**(广度闸;契约本身不设量纲)。exec 形的命令行(`command` + 各 `args`)计入 `command` 帽;插件上下文一道总字符帽。
  *
  * 拒返回判决(`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 hooksMatcherIssue})问的是同一只函数。
+ * 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
@@ -399,7 +456,7 @@ 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";
+export declare function hookIfMatches(cond: string, payload: unknown): true | "not_matched" | "unevaluable" | "over_budget";
 /** createSettingsHooksRegistration 的装配上下文(payload 的 CC-verbatim 字段来源)。 */
 export interface HookRunnerContext {
     logger: Logger;
@@ -471,6 +528,49 @@ export type HookLlmCall = (opts: {
  *   · `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")` 表达式抄在二十余处,总量帽无处可挂 —— 那正是漂移成因)。
@@ -532,7 +632,9 @@ export interface LlmHookExtra {
  *  · 答案全部由本仓从 CC JSON 铸,引擎在 handler 边界屏(唯一判官),本仓不预屏;
  *  · 无意见 ⇒ `next(e)`(链 handler 返回 `undefined` 是站点违约,PreToolUse / UserPromptSubmit 的失败列是 refuse ⇒ 每次都会被拒);
  *    观察站的 handler 恒返回 `undefined` —— 两条都在 {@link hangClassic} 成形;
- *  · `uses.calls: []`(必填;本仓的 handler 不调 `$`),`uses.events` 从 {@link SETTINGS_HOOK_STATIONS} 派生。
+ *  · `uses.calls: []`(必填;本仓的 handler 不调 `$`),`uses.events` 从 {@link SETTINGS_HOOK_STATIONS} 派生;
+ *  · 每只翻译的第二个入参是引擎的 `next.signal`(这只 handler 的预算 ∪ 这次派发被取消;见 {@link DEFAULT_SETTINGS_HOOKS_BUDGET_MS}):
+ *    一路贯穿到命令腿的 spawn({@link runCommandHook}),本仓不自合成第二只、不另设钟。
  */
 export declare function createSettingsHooksRegistration(config: RunnableHooksConfig, ctx: HookRunnerContext, budgetMs: number): ModRegistration<EngineDollar> | undefined;
 export {};