@sema-agent/server 7.147.0 → 7.148.0

package/dist/hooks/classic-stations.js

@@ -35,13 +35,6 @@ export function hangClassic(on, station, answer) {
         observeClassic(on, station, async (e, halt) => void (await answer(e, halt, undefined)));
         return;
     }
-    on(station, async (_$, e, next) => (await withHalt(next, (halt) => answer(e, halt, undefined))) ?? next(e));
-}
-export function wrapClassic(on, station, answer) {
-    if (CLASSIC_STATION_ROLE[station] === "observe") {
-        hangClassic(on, station, answer);
-        return;
-    }
     on(station, async (_$, e, next) => {
         const below = await next(e);
         return (await withHalt(next, (halt) => answer(e, halt, below))) ?? below;

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

@@ -1,3 +1,4 @@
+import { type Model } from "@sema-agent/core";
 import type { ModelKeyRef } from "../key-resolver.js";
 import type { ServiceConfig } from "../config-types.js";
 import type { HookLlmCall, HookLlmFailureCode } from "./hook-runner.js";
@@ -24,12 +25,15 @@ import type { HookLlmCall, HookLlmFailureCode } from "./hook-runner.js";
  * ([ref] 的 (a) 路已兑现:core 7.53.0 [ref] 根导出了那只判官 `brainLaneOf(model, routes)` —— `createRoutingBrain` 对每个请求问的就是它;
  * 本仓自写的合取 `dispatchBrainLane` 随之退役,本调用点与另三处一并改问它。)
  */
-export type HookModelPick = {
+export type HookModelPick = 
+/** `model` = 选中的**条目本身**(名字 / 地址之外的第三样东西:推理席位的方言读它的 `reasoning` / `compat` / `thinkingLevelMap`;`catalogRef` 只是它的名)。 */
+{
     ok: true;
     catalogRef: string;
     providerModelId: string;
     baseUrl: string;
     api: "openai-completions" | "anthropic-messages";
+    model: Model;
 }
 /** 选不出来的那一臂自带失败码([ref]):两个载体(prompt 直连 / agent 子代理)共用这一只选模闸,同一只判词同一个码。 */
  | {

package/dist/hooks/hook-llm.js

@@ -1,11 +1,12 @@
-import { admitRouteRequest, BrainError, joinRequestUrl, resolveRouteCredential, routeKeyOf } from "@sema-agent/core";
+import { admitRouteRequest, applyReasoningToRequest, AUTO_MODE_CLASSIFIER_LOW_REASONING_BUDGET_TOKENS, BrainError, joinRequestUrl, lowestReasoningSeat, mergeReasoningHeaders, resolveRouteCredential, routeKeyOf } from "@sema-agent/core";
 import { matchCatalogModel, refusedCatalogEntry, servedModelTableLeg } from "../model-select.js";
 import { echoModelRef, modelUnavailableMessage } from "../model-entry-refusal.js";
 import { resolveOpenaiRouteEndpoint } from "../model-route-endpoint.js";
 import { anthropicLaneCredentialOf } from "../model-route-gap.js";
 import { anthropicRouteRoot, brainLaneFor, routeTableOf } from "../model-provider.js";
-import { egressRedirectRefusal } from "../egress-redirect.js";
+import { EgressRedirectRefusedError, createEgressFetch } from "../egress-redirect.js";
 import { buildDisplaySafeRefusal, redactSecrets } from "../trace/redact.js";
+import { readUpstreamJson } from "../upstream-body.js";
 const unresolvedPick = (error) => ({ ok: false, error, code: "model_unresolved" });
 export function buildHookFailureText(raw) {
     if (raw === "")
@@ -52,10 +53,10 @@ export function createHookLlm(deps) {
         const lane = brainLaneFor(m.provider, routeTableOf(config));
         switch (lane) {
             case "anthropic":
-                return { ok: true, catalogRef, providerModelId, baseUrl: m.baseUrl || anthropicRouteBaseUrl(), api: "anthropic-messages" };
+                return { ok: true, catalogRef, providerModelId, baseUrl: m.baseUrl || anthropicRouteBaseUrl(), api: "anthropic-messages", model: m };
             case "gateway": {
                 const endpoint = resolveOpenaiRouteEndpoint(catalogRef, m, config.gatewayBaseUrl, servedModelTableLeg(config));
-                return endpoint.ok ? { ok: true, catalogRef, providerModelId, baseUrl: endpoint.baseUrl, api: "openai-completions" } : unresolvedPick(endpoint.refusal);
+                return endpoint.ok ? { ok: true, catalogRef, providerModelId, baseUrl: endpoint.baseUrl, api: "openai-completions", model: m } : unresolvedPick(endpoint.refusal);
             }
         }
     };
@@ -108,8 +109,8 @@ export function createHookLlm(deps) {
         }
         return { ok: true, credential, admission };
     };
-    const fetchImpl = deps.fetchImpl ?? fetch;
-    const callLlm = async ({ prompt, model, timeoutMs, system, maxOutputTokens }) => {
+    const fetchImpl = createEgressFetch("declare the final endpoint as this route's base URL", deps.fetchImpl);
+    const callLlm = async ({ prompt, model, timeoutMs, system, maxOutputTokens, reasoningSeat }) => {
         const pick = hookModelFor(model);
         if (!pick.ok)
             return pick;
@@ -127,9 +128,12 @@ export function createHookLlm(deps) {
                     return { ok: false, error: `per-model key resolution for "${pick.catalogRef}" failed — refusing to fall back to the shared route credential (${String(e)})`, code: "credential_custody_failed" };
                 }
             }
+            const wireModel = { ...pick.model, api: pick.api };
+            const seat = reasoningSeat === "lowest" ? lowestReasoningSeat(wireModel) : undefined;
+            const thinkingRoom = seat === "low" ? AUTO_MODE_CLASSIFIER_LOW_REASONING_BUDGET_TOKENS : 0;
             let url;
             let headers;
-            let body;
+            let request;
             let admitted;
             let declaredRoot;
             if (pick.api === "anthropic-messages") {
@@ -146,9 +150,9 @@ export function createHookLlm(deps) {
                     "anthropic-version": config.anthropic?.version ?? "2023-06-01",
                     ...(routed.credential.source === "per-model" ? { "x-api-key": routed.credential.apiKey ?? "" } : routeCredentialHeader(routeCredential)),
                 };
-                const want = maxOutputTokens ?? 1024;
+                const want = (maxOutputTokens ?? 1024) + thinkingRoom;
                 const maxTokens = Math.min(config.models[pick.catalogRef]?.maxTokens ?? want, want);
-                body = JSON.stringify({ model: pick.providerModelId, max_tokens: maxTokens, ...(system ? { system } : {}), messages: [{ role: "user", content: prompt }] });
+                request = { model: pick.providerModelId, max_tokens: maxTokens, ...(system ? { system } : {}), messages: [{ role: "user", content: prompt }] };
             }
             else {
                 declaredRoot = config.gatewayBaseUrl;
@@ -159,8 +163,14 @@ export function createHookLlm(deps) {
                 const hookKey = routed.credential.apiKey;
                 url = joinRequestUrl(pick.baseUrl, "/chat/completions");
                 headers = { "content-type": "application/json", ...(hookKey ? { authorization: `Bearer ${hookKey}` } : {}) };
-                body = JSON.stringify({ model: pick.providerModelId, ...(maxOutputTokens !== undefined ? { max_tokens: maxOutputTokens } : {}), messages: [...(system ? [{ role: "system", content: system }] : []), { role: "user", content: prompt }], stream: false });
+                request = { model: pick.providerModelId, ...(maxOutputTokens !== undefined ? { max_tokens: maxOutputTokens + thinkingRoom } : {}), messages: [...(system ? [{ role: "system", content: system }] : []), { role: "user", content: prompt }], stream: false };
             }
+            if (seat !== undefined) {
+                const applied = applyReasoningToRequest({ api: pick.api, model: wireModel, level: seat, body: request });
+                request = applied.body;
+                mergeReasoningHeaders(headers, applied.headers);
+            }
+            const body = JSON.stringify(request);
             try {
                 admitted();
             }
@@ -168,15 +178,12 @@ export function createHookLlm(deps) {
                 return gateRefusal(pick, e, declaredRoot);
             }
             phase = "transport";
-            const r = await fetchImpl(url, { method: "POST", headers, body, signal: ac.signal, redirect: "manual" });
-            const redirected = egressRedirectRefusal(r, "declare the final endpoint as this route's base URL");
-            if (redirected !== undefined)
-                return { ok: false, error: `hook llm ${redirected}`, code: "redirect_refused" };
+            const r = await fetchImpl(url, { method: "POST", headers, body, signal: ac.signal });
             if (!r.ok)
                 return { ok: false, error: `hook llm HTTP ${r.status}`, code: "bad_response" };
             let answered;
             try {
-                answered = await r.json();
+                answered = await readUpstreamJson(r);
             }
             catch (e) {
                 if (ac.signal.aborted || e?.name !== "SyntaxError")
@@ -197,6 +204,8 @@ export function createHookLlm(deps) {
             return typeof text === "string" ? { ok: true, text } : { ok: false, error: "hook llm returned no content", code: "no_content" };
         }
         catch (e) {
+            if (e instanceof EgressRedirectRefusedError)
+                return { ok: false, error: `hook llm ${e.message}`, code: "redirect_refused" };
             const cause = e?.cause;
             return {
                 ok: false,

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

@@ -5,7 +5,7 @@ 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 { HookManagedUnrun, HookNoticeObservation } from "../fleet/fleet-bus.js";
-import { LIMIT_REASONS, type LimitMeasure } from "../limit-refusal.js";
+import { LIMIT_REASONS, type LimitFacts, type LimitMeasure } from "../limit-refusal.js";
 import { type UrlCredentialRefusal } from "../url-credential-refusal.js";
 import { type HookGroupSource } from "./hook-source.js";
 import { type RunnableCommandHookEntry } from "./command-spawn.js";
@@ -40,22 +40,22 @@ 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.*` 站。
+ * 律二 · **事件对位只有一张表,一事件一站**:引擎属主的每个 `settings.hooks` 事件 → 它挂的那一个 `classic.*` 站(同名站)。
  * 注册的 `uses.events`、点亮了哪些站,全从这张表派生;契约加一个引擎属主事件 ⇒ 本表缺键 ⇒ tsc 红(那一刻补一行翻译),
  * 所以运行期没有「引擎属主却没点亮」这一臂。每个站名在引擎事件表里都有站(钉从 `MOD_EVENT_TABLE` 派生对拍:只选无站名的注册 prepare 即拒)。
- * `Stop` 挂两站:引擎把委派子代的停车点叫 `classic.SubagentStop`(续跑的子代同读),而旧座在每条腿都跑 ——
- * 挂两个名字使用户的 `Stop` 条目触达不变(契约把 `SubagentStop` 判给壳;两张属主表对齐之前不收窄)。
+ * `Stop` 只挂 `classic.Stop`(主任务那条腿的停车点;参照实现 CC 2.1.316 同读:停车点按子代身份二选一,`cli316.js:272748` `h ? "SubagentStop" : "Stop"`):委派子代结束时引擎升的是 `classic.SubagentStop`,
+ * 它对位的是契约里**壳属主**的 `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"];
+    readonly PreToolUse: "classic.PreToolUse";
+    readonly PostToolUse: "classic.PostToolUse";
+    readonly PostToolUseFailure: "classic.PostToolUseFailure";
+    readonly PostToolBatch: "classic.PostToolBatch";
+    readonly UserPromptSubmit: "classic.UserPromptSubmit";
+    readonly Stop: "classic.Stop";
+    readonly StopFailure: "classic.StopFailure";
+    readonly PreCompact: "classic.PreCompact";
+    readonly PostCompact: "classic.PostCompact";
 };
 /**
  * **一条车道一张注册**:每张的名字 —— wire 可见(`wiring_manifest.mods[].name`、`allowRuleShadowed[].entries`、问因项 `askReasons[].registration`),
@@ -70,7 +70,7 @@ export declare const SETTINGS_HOOKS_REGISTRATIONS: {
  *
  * **这只数是引擎的钟,不是本服务跑钩子子进程的墙钟。** 引擎对 `budgetMs` 的定义(core `ModRegistration.budgetMs` 的注释,逐字)是
  * "Each handler's own time" —— 每个 handler 自己的时间:一只在 handler 等 `next` / `$` 调用时暂停的钟(core 的 `SelfBudget`),
- * 到点 ⇒ 这个 handler 失败(PreToolUse / UserPromptSubmit 上 fail-closed 拒,其余站跳过)。托管车道是外层、先等 `next`:它的表在非托管车道跑的那段停着 ——
+ * 到点 ⇒ 这个 handler 失败(PreToolUse / UserPromptSubmit 上 fail-closed 拒,其余站跳过)。每张车道注册都先等 `next`(折叠挂法):托管排在非托管之上,它的表在非托管车道跑的那段停着 ——
  * 非托管条目吃光的只是非托管那张的预算,托管车道照跑;托管车道自己的预算用尽 ⇒ 撞上的托管条目记未跑成(`budget_exhausted`)。命令钩子子进程自己的墙钟另有两只,都在本文件:
  * 单条命令的 `timeout`(上限 {@link MAX_HOOK_TIMEOUT_SECONDS})与一个事件里一条车道同步条目的总墙钟({@link MAX_HOOK_EVENT_TOTAL_SECONDS},到点不再起下一条)。
  *
@@ -187,7 +187,7 @@ export type ParseHooksConfigResult = {
  * 良性求值 ~0.1 ms,灾难形(指数级)吃满预算也跑不完 —— 两者相差数个数量级,取值给足余量(1 000 ms),让忙机上的调度停顿也跨不过这条线。
  * **另有一只受理总额度**([ref];同一张表的 `.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`(更具体)。一次受理的最坏占用 ≤ 总额度 + 一次求值的额度。
+ * `reason: budget_exceeded`({@link BudgetExceededMatcherIssue},点名越线的那一组与总额度)。单次超时先到、先判 `over_budget`(更具体)。一次受理的最坏占用 ≤ 总额度 + 一次求值的额度。
  * 总额度这一只读钟,但良性设置离它近三个数量级(一份最大的良性配置 —— 3 工具事件 × 16 组 —— 总耗时在毫秒级),所以良性设置的结局仍不随机器忙闲翻转;只有求值总耗时逼近总额度的病态设置才可能落在边界两侧。
  * **超时 ⇒ 确定拒绝**:`400 request.field_invalid`({@link OverBudgetMatcherIssue}),句子点名**哪一只 matcher**(事件 + 组下标,不回显原字节)与**预算**;**按配置顺序遇到的第一只超时 / 命中别名的 matcher 定结局**。
  * 为什么是拒绝而不是放行:运行期 {@link hookMatcherMatches} 在**每次工具调用**里问同一只带预算的口([ref] 起;此前是裸调、无预算)—— 一只在受理面连目录里几个短名字都求不完的 matcher 放进去,
@@ -197,7 +197,7 @@ export type ParseHooksConfigResult = {
  * 多租户车道走 literal 档、零调用方正则执行 —— 受理面的 DoS 面不因此重开。
  *
  * 🔴 **编不过的正则 = 确定的拒绝**([ref] 收尾;与超预算同类 —— 确定性的坏配置,结局只取决于配置):`"regex"` 档遇契约 `hookMatcherForm` 答 `invalid`(或求值时契约函数答 `"invalid"`)⇒
- * `400 request.field_invalid`({@link InvalidRegexMatcherIssue}),句子点名**哪一只 matcher**(事件 + 组下标 + 原文〔超 {@link MATCHER_ECHO_CHARS} 字符截断〕)与引擎的编译错误句;机读位 `detail` 只有闭集三键 + 坐标 `path`(那一组的 `matcher`)。
+ * `400 request.field_invalid`({@link InvalidRegexMatcherIssue}),句子点名**哪一只 matcher**(事件 + 组下标 + 原文〔超 {@link MATCHER_ECHO_CHARS} 字符截断〕)与引擎的编译错误句;机读位只有 `field`(那一组的 `matcher` 的坐标)+ 闭集三键(`reason` / `event` / `groupIndex`)。
  * 受理面与运行期问**同一只判**:契约把"编不过"答成 `invalid`,运行期 {@link hookMatcherMatches} 因此不跑那一组(并记 `hook_matcher_invalid`),受理面因此拒 —— 本仓不加第二个判官
  * (编译错误句只是诊断文字,见 {@link matcherCompileSentence};拒不拒由契约函数一个人说了算)。为什么是拒绝而不是放行:放行 = 用户以为在生效的钩子(含会真拦的 PreToolUse deny 钩子)
  * 在每次工具调用里都**悄悄不跑**,硬破坏三句要求的「响亮」没有着落;`"literal"` 档(多租户车道,hooks 不装配)= 不适用,与正则形同一行表。resume 重放不判(照旧采纳、该组不跑)。
@@ -213,10 +213,10 @@ export type ParseHooksConfigResult = {
  * 拒放集合相对 7.113.0 的一处放宽(披露在 CHANGELOG / MIGRATION):超过上限的字面别名 matcher 7.113.0 拒(当时字面判不设上限),自 7.114.0 两档都判未判、受理。
  *
  * 错误句:死别名与超预算两形只回显**目录里的**别名与正名 / 位置(闭集字符串与数字),不回显调用方的原字节([ref] 姿势);编不过一形**点名那只 matcher 的原文**(截断到 {@link MATCHER_ECHO_CHARS} 字符)与引擎的编译错误句 ——
- * 调用方要改的就是这一串,且它本来就是调用方自己送来的;机读位 `detail` 仍不带这两段。
+ * 调用方要改的就是这一串,且它本来就是调用方自己送来的;机读位仍不带这两段。
  *
  * 🔴 **判决是数据,句子与体的机读位同出一只铸点**([ref];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` 的函数(配置读者的拒同经它),
+ * {@link OverBudgetMatcherIssue} 的 event / groupIndex / budgetMs,{@link BudgetExceededMatcherIssue} 的 event / groupIndex / totalMs,{@link InvalidRegexMatcherIssue} 的 event / groupIndex〔+ 句子用的 matcher / compileError〕,以 `reason` 区分)而不是句子;{@link buildHooksRefusal} 是**唯一**把它铸成拒句 + 根上机读事实(`field` + `reason` + 判决键)的函数(配置读者的拒同经它),
  * 受理门只取它的返回、**不解析句子**。体上多出的两键让三端不必解析英文就能把这只拒与普通提交失败分流、提示用户改 matcher;死别名那一句逐字同 7.114.0、零新码。
  */
 /** 超此长度的 matcher 不在受理面读(两档同一个上限;未判,reason = oversize)。与 {@link MAX_HOOK_COMMAND_CHARS} 同量纲的服务侧防线:真实 matcher(精确名 / 交替 / `mcp__.*`)远在其内;目录全部工具名交替 ~0.5 KiB。 */
@@ -226,7 +226,7 @@ export declare const MAX_MATCHER_EVAL_CHARS = 8192;
  *  · `budgetMs` = **每一次**正则形求值各一份的固定墙钟额度([ref];vm `timeout`)。**不共享、额度不随受理里别的 matcher 缩水、这一份不读钟**;字面形不占它。
  *    **运行期读同一个数**([ref];{@link hookMatcherMatches} 每次现读本对象):运行期每次工具调用对正则形 matcher 的每次求值也各拿这一份,超了 ⇒ 该组按选中处理并登记,不另设运行期额度。
  *    良性求值 ~0.1 ms;灾难回溯(指数级)吃满它也跑不完 ⇒ 这只 matcher 被 400 拒(`over_budget`)。取值是「良性求值之上数个数量级」的余量 —— 小了,忙机上的调度停顿会把良性 matcher 读成灾难(受理结局随负载翻转,正是 [ref] 要根除的形)。
- *  · `totalMs` = **一次受理**里所有已完成的正则形求值的**耗时之和**的总额度([ref]):之和一旦超过它 ⇒ `400`,`detail.reason = budget_exceeded`。每次求值的额度只界住「一只 matcher 不会无限算」,
+ *  · `totalMs` = **一次受理**里所有已完成的正则形求值的**耗时之和**的总额度([ref]):之和一旦超过它 ⇒ `400`,`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` 的病态设置才可能。
@@ -280,7 +280,7 @@ export interface BudgetExceededMatcherIssue {
 }
 /**
  * 一条受理面判决(纯数据)· 正则编不过([ref] 收尾):`event` 事件下第 `groupIndex` 组(从 0 起)的 matcher 在契约包的读法下答 `invalid`。
- * `matcher` = 那只 matcher 的原文、`compileError` = 引擎的编译错误句(各自截到 {@link MATCHER_ECHO_CHARS} 字符):**只供铸拒句用**,机读位 `detail` 不带它们。
+ * `matcher` = 那只 matcher 的原文、`compileError` = 引擎的编译错误句(各自截到 {@link MATCHER_ECHO_CHARS} 字符):**只供铸拒句用**,机读位不带它们。
  */
 export interface InvalidRegexMatcherIssue {
     readonly reason: "invalid_regex";
@@ -347,64 +347,65 @@ export interface HooksWireKeyIssue {
 export type HooksConfigIssue = HooksPieceIssue | UnsupportedEntryTypeIssue | HooksCapIssue | UnnamedHooksRefusalIssue | HooksWireKeyIssue;
 /** `settings.hooks` 这一面的全部拒判决:配置读者的({@link HooksConfigIssue})与 fresh 提交面 matcher 判据的({@link HooksMatcherIssue})。 */
 export type HooksIssue = HooksConfigIssue | HooksMatcherIssue;
+/** 本服务在这一面**自铸**的 `reason` 词(其余是契约包分类器的码原样,与帽的量纲词 —— 那一张表在 `limit-refusal.ts`):`trace/self-minted-wire.ts` 的 `hooksRefusalReason` 集按它穷举。 */
+export type HooksServerRefusalReason = Exclude<HooksIssue["reason"], HooksDroppedPieceCode | HooksRejectionCode | HooksCapReason>;
 /**
- * 400 体上的 `detail`(按 `reason` 分形;每一形都带 `path` —— 判决所在的坐标,契约分类器的段形,相对请求体的 `settings` 对象,用户文本段过 `outgoingPath`)。
- * matcher 四形另带它们各自的键(`event` / `alias` / `canonical`,`event` / `groupIndex` / `budgetMs`,`event` / `groupIndex` / `totalMs`,`event` / `groupIndex`)。
+ * 400 体上的机读事实(摊在拒体根上,按 `reason` 分形)。每一形都带 `field` = 判决所在处在请求体里的坐标({@link hooksFieldCoordinate}:`settings` 起、方括号形、
+ * 用户文本段过回显口径)—— 拒句里的坐标是同一只串。matcher 四形另带同一判决的类型化分量 `event` / `groupIndex`(与 `field` 同一铸点同一判决派生,权威定位 = `field`)
+ * 与各自的键(`alias` / `canonical`,`budgetMs`,`totalMs`);帽两形 ≡ 请求体其余各处的帽(`limit-refusal.ts` 的 {@link limitFacts}:`field` / `reason` / `count` / `cap`)。
  */
-export type HooksRefusalDetail = {
+export type HooksRefusalFacts = {
+    readonly field: string;
     readonly reason: "dead_alias";
     readonly event: HookEventName;
+    readonly groupIndex: number;
     readonly alias: string;
     readonly canonical: string;
-    readonly path: ConfigPath;
 } | {
+    readonly field: string;
     readonly reason: "over_budget";
     readonly event: HookEventName;
     readonly groupIndex: number;
     readonly budgetMs: number;
-    readonly path: ConfigPath;
 } | {
+    readonly field: string;
     readonly reason: "budget_exceeded";
     readonly event: HookEventName;
     readonly groupIndex: number;
     readonly totalMs: number;
-    readonly path: ConfigPath;
 } | {
+    readonly field: string;
     readonly reason: "invalid_regex";
     readonly event: HookEventName;
     readonly groupIndex: number;
-    readonly path: ConfigPath;
 } | {
+    readonly field: string;
     readonly reason: HooksDroppedPieceCode | HooksRejectionCode;
-    readonly path: ConfigPath;
     readonly key?: string;
 } | {
+    readonly field: string;
     readonly reason: "unsupported_entry_type";
-    readonly path: ConfigPath;
     readonly type: HookEntryType;
-} | {
+} | (LimitFacts & {
     readonly reason: HooksCapReason;
-    readonly path: ConfigPath;
-    readonly count: number;
-    readonly cap: number;
-} | {
+}) | {
+    readonly field: string;
     readonly reason: "unnamed_refusal";
-    readonly path: ConfigPath;
 } | {
+    readonly field: string;
     readonly reason: "wire_key_invalid";
-    readonly path: ConfigPath;
     readonly key: HooksWireKey;
 };
-/** {@link buildHooksRefusal} 的返回(纯数据):拒句 + 400 体上的两个机读位。`field` 恒为字面 `"settings.hooks"`。 */
+/** {@link buildHooksRefusal} 的返回(纯数据):拒句 + 400 体根上的机读事实。 */
 export interface HooksRefusal {
     readonly message: string;
-    readonly field: "settings.hooks";
-    readonly detail: HooksRefusalDetail;
+    readonly facts: HooksRefusalFacts;
 }
 /**
- * 判决 → 拒句 + 机读位 —— `settings.hooks` 这一面**拒句与机读位的唯一铸点**(配置读者的拒与 fresh 提交面的 matcher 拒同经这里;受理门 `admission.ts` 用返回值填 400 体,
- * 不从句子里反解字段)。句子:死别名逐字 = 7.114.0 的那一句(`test/hooks-alias-matcher-s995.test.ts` R7 冻结);超预算点名**哪一只**(事件 + 组下标 + `matcher`)与**预算**,不回显 matcher 原字节([ref] 姿势);
- * 分类器的一块 = 坐标 + 码 + 释义(+ 坏键);服务侧上限的几句逐字 = 7.131.0。`reason` 闭集穷举(多一形 = 这里编译红)。
+ * 判决 → 拒句 + 机读事实 —— `settings.hooks` 这一面**拒句与机读位的唯一铸点**(配置读者的拒与 fresh 提交面的 matcher 拒同经这里;受理门 `admission.ts` 用返回值填 400 体,
+ * 不从句子里反解字段)。`field` 一律是判决所在处的坐标({@link hooksFieldCoordinate});句子里点名坐标的臂写的就是这一只串。句子:死别名逐字 = 7.114.0 的那一句
+ * (`test/hooks-alias-matcher-s995.test.ts` R7 冻结);超预算点名**哪一只**(坐标)与**预算**,不回显 matcher 原字节([ref] 姿势);
+ * 分类器的一块 = 坐标 + 码 + 释义(+ 坏键);服务侧上限的几句逐字 = 7.131.0(帽律:已有句不改、只加机读位)。`reason` 闭集穷举(多一形 = 这里编译红)。
  */
 export declare function buildHooksRefusal(issue: HooksIssue): HooksRefusal;
 /**
@@ -434,17 +435,20 @@ export interface HooksUrlCredentialIssue {
 export declare function hooksUrlCredentialIssue(config: RunnableHooksConfig): HooksUrlCredentialIssue | undefined;
 /**
  * {@link hooksUrlCredentialIssue} 的判决 → 拒句 + 机读位。`field` 是这一条 `url` 在请求体里的全坐标(`settings.hooks.<事件>[g].hooks[h].url`,与封签位、本族别的 `field` 同一种写法),
- * 出路指到同一条的 `headers`。机读位的形与 MCP / A2A / 搜索后端三座同一只铸点(`url-credential-refusal.ts`),所以**不**走上面 {@link buildHooksRefusal} 的 `field:"settings.hooks"` + `detail` 形 ——
- * 那一形按 `detail.reason` 分形、属于配置读者与 matcher 判据;「URL 带凭据」是跨座位的一个事实,消费端按 `reason` 穷举读一次。
+ * 出路指到同一条的 `headers`。机读位的形与 MCP / A2A / 搜索后端三座同一只铸点(`url-credential-refusal.ts`);坐标与 {@link buildHooksRefusal} 同一只写法({@link hooksFieldCoordinate})——
+ * 「URL 带凭据」是跨座位的一个事实,消费端按 `reason` 穷举读一次。
  */
 export declare function buildHooksUrlCredentialRefusal(issue: HooksUrlCredentialIssue): UrlCredentialRefusal;
 /**
  * 坐标的出门段:事件名等键段是用户文本 ⇒ 先过 {@link outgoingPath}(凭据形不原样回显),每个串段再过调用方串的唯一回显口径(`caller-text-echo.ts`:剥控制 / 双向字符、截到 64 字 + …)——
- * 一只 100 KB 的未知键不把拒体撑大、也不在句子里夹看不见的字符。400 体的 `detail.path` 与拒句里的坐标读的都是它。
+ * 一只 100 KB 的未知键不把拒体撑大、也不在句子里夹看不见的字符。
  */
 export declare function hooksOutgoingPath(path: ConfigPath): ConfigPath;
-/** 坐标出门形:`settings.` + 契约包唯一的 stringify 点({@link formatConfigPath})作用在 {@link hooksOutgoingPath} 上。 */
-export declare function hooksCoordinate(path: ConfigPath): string;
+/**
+ * hooks 面本服务产出的**一切坐标**(400 体的 `field`、拒句里的坐标、键闭集拒的 `unknownKeys`、一次性迁移重读日志的被剥坐标)的唯一写法:
+ * hooks 面请求坐标的 stringify({@link fieldCoordinate},`settings` 起、方括号形)作用在 {@link hooksOutgoingPath} 上。
+ */
+export declare function hooksFieldCoordinate(path: ConfigPath): string;
 /**
  * 把 wire 上的 untrusted `settings.hooks` 判成 {@link RunnableHooksConfig} + 服务侧上限 —— **hooks 配置在本仓的唯一入口**。
  *
@@ -461,7 +465,7 @@ export declare function hooksCoordinate(path: ConfigPath): string;
  *    续跑重放腿不过那道门,存量体按受理时的读法重放(剥掉,不砖停驻任务)。
  *  · **服务侧上限**(广度闸;契约本身不设量纲)。exec 形的命令行(`command` + 各 `args`)计入 `command` 帽;插件上下文一道总字符帽。
  *
- * 拒返回判决(`issue`)与它的句子(`error`)而不 throw —— submit 路径 400 fail-loud(体带 `field: "settings.hooks"` + `detail`)、resume 防御路径 warn-drop(hooks 整只不采纳),由调用方选;
+ * 拒返回判决(`issue`)与它的句子(`error`)而不 throw —— submit 路径 400 fail-loud(体根上带判决所在处的坐标 `field` + `reason` + 判决键)、resume 防御路径 warn-drop(hooks 整只不采纳),由调用方选;
  * **读者、判决与句子两腿同一只**,后果按腿分。
  */
 export declare function parseHooksConfig(raw: unknown): ParseHooksConfigResult;
@@ -531,7 +535,7 @@ export interface HookRunnerContext {
     httpHookAllowlistLayers: readonly HttpHookAllowlistLayer[];
     /**
      * 部署座在**任务座之下**挂了链成员的站点式样(引擎的准入记录读出,`boot/deployment-mods.ts` 的 `belowTaskChainPatternsOf`)。必填:每个装配点都要说 ——
-     * `[]` = 任务座之下没有部署座的链成员(部署注册只在任务座之上、只有观察者,或没有部署注册)。读者 = {@link managedTightenOnlyOn}(托管车道在这些站上只许收紧)。
+     * `[]` = 任务座之下没有部署座的链成员(部署注册只在任务座之上、只有观察者,或没有部署注册)。读者 = PreToolUse 翻译的只许收紧({@link chainsBelowTaskOn};请求钩子两条车道在这些站上只许收紧)。
      */
     belowTaskChainPatterns: readonly string[];
 }
@@ -553,6 +557,11 @@ export type HookLlmCall = (opts: {
      *  anthropic 形走 Messages API 的**顶层 `system` 字段**,openai 形走**前置的一条 system 消息**,
      *  两边同一语义。缺席 ⇒ 与此前逐位相同(无 system)。 */
     system?: string;
+    /** 这次调用是**只要答案**的席位(会话标题那一类:一行产出,不值一段思考):载体按这只模型在**这条线上**能写的最低思考档发 ——
+     *  线上有关闭拼法 ⇒ `off`,否则 `low` —— 键由 core 的唯一方言表铸(`applyReasoningToRequest`),本载体不抄方言;输出帽 =
+     *  答案额度(`maxOutputTokens` / 载体缺省)+ 该档思考要的额度(`off` ⇒ 0,`low` ⇒ 引擎分类器席同一个常量)。
+     *  缺席 ⇒ 不写任何推理键(网关缺省),请求体与此前逐位相同。agent 载体不消费(它的预算是 `limits`,不是单次 completion 的帽)。 */
+    reasoningSeat?: "lowest";
 }) => Promise<{
     ok: true;
     text: string;
@@ -684,8 +693,8 @@ export declare function buildHookContext(parts: readonly string[]): string | und
  *    (契约只定"POST 输入";端点回非 JSON → 忽略,与 command 同姿势),板上已请壳确认 CC-exact。
  *  - 非 2xx → code=HTTP status(≥100,永远不会撞 exit-2 的阻断语义)→ 非阻断 warn 记账。
  *  - 超时/网络错 → timedOut / spawnError 同款,非阻断。
- * 🔒 redirect:"error"——插值出的 Authorization 头绝不跟着重定向跨源;URL 指向哪由用户配置负责
- * (hook 跑在单用户 host lane=用户自己机器,与 command 条目跑任意 sh 同一 class ② 信任面)。
+ * 🔒 重定向不跟(出口 {@link httpHookFetch}:`redirect: "manual"`,3xx 即拒)——插值出的 Authorization 头与请求体绝不跟着重定向走;URL 指向哪由用户配置负责
+ * (hook 跑在单用户 host lane=用户自己机器,与 command 条目跑任意 sh 同一 class ② 信任面)。拒句经 `spawnError` 进既有的 hook 失败账(`spawn_failed`),不是静默放行。
  */
 /**
  * 阶段三b:跑一条 `prompt`/`agent` 条目(design/HOOKS-PHASE3B-PROMPT-AGENT.md)。两者共此函数——
@@ -713,19 +722,20 @@ export interface LlmHookExtra {
 /**
  * 律一 · 把校验过的 {@link RunnableHooksConfig} 铸成任务座上的 mods 注册 —— **一条车道一张**(车道 = `hook-source.ts` 的 {@link hookLaneOf}):
  * 托管车道 `settings.hooks.managed`(托管插件相 + 托管策略相)在前、非托管车道 `settings.hooks` 在后({@link LANE_CHAIN_ORDER});没有组的车道不铸,两道都空 ⇒ `[]`(`TaskSpec.mods` 不铸)。
- * 没有托管组的请求只得到非托管那一张,与分道之前逐字同(名字、挂站、预算、`once` 键)。`budgetMs` = {@link settingsHooksBudgetMs} 的读数(调用方交),两张各带一份同值。
+ * 没有托管组的请求只得到非托管那一张,与分道之前逐字同(名字、挂站、预算、`once` 账)。`budgetMs` = {@link settingsHooksBudgetMs} 的读数(调用方交),两张各带一份同值。
  *
  * 一条规则:**车道是引擎的注册,不是一只 handler 里的分支** —— 每张注册自带引擎的 handler 预算、本服务的事件墙钟、LLM 条数、`once` 账与未跑成账本,两道之间不共用任何一只钟。
- * 托管车道外层挂(`wrapClassic`):先把事件交下去(非托管车道、更下方的注册与引擎核心先答完,托管的表在这段停着),再在答回来的那份上跑自己的两相并折叠 ——
- * 托管判的因此恒是要执行的那一份,非托管吃光自己的预算也挤不掉它(拒站上非托管失败 = 派发 fail-closed 终局;其余站引擎跳过非托管,托管照跑)。
+ * 两条车道同一种挂法(折叠,`classic-stations.ts` 的 `hangClassic`):先把事件交下去(下方的注册与引擎核心先答完,这一张的表在这段停着),再在答回来的那份上跑自己的相并折叠 ——
+ * 托管排在非托管之上,判的因此恒是要执行的那一份,非托管吃光自己的预算也挤不掉它(拒站上非托管失败 = 派发 fail-closed 终局;其余站引擎跳过非托管,托管照跑);
+ * 非托管同样在下方(技能座的注册、部署 `append` 档)答完之后判:下方的否决恒作数,它的放行只对它亲见的那份参数作数。
  *
  * 构造约束(每一条都有引擎侧的硬理由):
  *  · `register` 同步、只读本注册自己的配置、不按腿分支 —— 返回 thenable 即 `config.mods_invalid`;委派子代把父的任务座当自己的派发,
  *    两条腿挂的是同一套 handler,父链才塌进子代的 phase 1(否则多一次约束判定);
- *  · `once` 去重集({@link runMatchingEntries} 的 `onceFired`)在铸注册这一层、每请求每车道一份,不放进 `register`(那是每腿一次);
+ *  · `once` 账({@link OnceSpent})在铸注册这一层、每请求每车道一份,不放进 `register`(那是每腿一次);
  *  · 答案全部由本仓从 CC JSON 铸,引擎在 handler 边界屏(唯一判官),本仓不预屏;
- *  · 内层无意见 ⇒ `next(e)`;外层无可添 ⇒ 下方的答案原样作数(链 handler 返回 `undefined` 是站点违约,PreToolUse / UserPromptSubmit 的失败列是 refuse ⇒ 每次都会被拒);
- *    观察站的 handler 恒返回 `undefined` —— 三条都在 `classic-stations.ts` 的两种挂法里成形;
+ *  · 无可添 ⇒ 下方的答案原样作数(链 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}),本仓不自合成第二只、不另设钟。