@sema-agent/server 7.131.0 → 7.133.0

package/dist/hooks/classic-stations.d.ts

@@ -0,0 +1,91 @@
+/**
+ * 引擎的 `classic.*` 站 —— 本仓挂 handler 的唯一入口(core 7.52.0 起扩展点 = mods 注册,`Hooks` 记录退役)。
+ *
+ * 三件事只写在这里:
+ *  ① **事件名 → { `e` 型, 答案型 }**:core 逐个导出了每站的 `e` 型与答案型,但没有导出二者的映射(宿主侧配对是今天的唯一读法)。
+ *     这张对位表是那一配对的唯一一份;core 导出映射型的那一版,本表改读它、删掉手写的十一行。
+ *  ② **handler 怎么挂**:链成员「无意见 ⇒ `next(e)`」(链 handler 返回 `undefined` 是站点违约,refuse 站上即 fail-closed 拒),
+ *     观察者「恒返回 `undefined`」(观察者的判词不采纳、被引擎报告)。两条都在 {@link hangClassic} / {@link observeClassic} 里成形,
+ *     调用方只写「这一站我答什么」或「这一站我看什么」,不再各自记得这两条。
+ *  ③ **信号**:引擎交给每只 handler 的 `next.signal` 是「这只 handler 的预算 ∪ 这次派发被取消」的合成(core 的派发器自合成,本仓不另合成第二份)。
+ *     它是 handler 体的第二个入参 —— 触发之后 handler 不再起新事、在飞的子进程要叫停(`hooks/hook-runner.ts` 的命令钩子腿)。
+ *
+ * 站的集合 = 引擎事件表里有站的 `classic.*` 名(一条钉从 `MOD_EVENT_TABLE` 派生对拍,不手抄第二份)。
+ * 观察站(`StopFailure` / `PostCompact` / `PermissionDenied`)只许观察者:答案形是「无」,core 的迁移配方要求挂 `{ observe: true }`。
+ */
+import type { EngineDollar, On, PermissionDeniedPayload, PostCompactEvent, PostToolBatchEvent, PostToolBatchResult, PostToolUseEvent, PostToolUseFailureEvent, PostToolUseFailureResult, PostToolUseResult, PreCompactEvent, PreCompactResult, PreToolUseEvent, PreToolUseResult, StopEvent, StopFailureEvent, StopHookResult, UserPromptSubmitEvent, UserPromptSubmitResult } from "@sema-agent/core";
+/** 每一站的 `e` 型与答案型(答案 `void` = 观察站)。 */
+export interface ClassicStationTypes {
+    "classic.PreToolUse": {
+        e: PreToolUseEvent;
+        answer: PreToolUseResult;
+    };
+    "classic.PostToolUse": {
+        e: PostToolUseEvent;
+        answer: PostToolUseResult;
+    };
+    "classic.PostToolUseFailure": {
+        e: PostToolUseFailureEvent;
+        answer: PostToolUseFailureResult;
+    };
+    "classic.PostToolBatch": {
+        e: PostToolBatchEvent;
+        answer: PostToolBatchResult;
+    };
+    "classic.UserPromptSubmit": {
+        e: UserPromptSubmitEvent;
+        answer: UserPromptSubmitResult;
+    };
+    "classic.Stop": {
+        e: StopEvent;
+        answer: StopHookResult;
+    };
+    "classic.SubagentStop": {
+        e: StopEvent;
+        answer: StopHookResult;
+    };
+    "classic.StopFailure": {
+        e: StopFailureEvent;
+        answer: void;
+    };
+    "classic.PreCompact": {
+        e: PreCompactEvent;
+        answer: PreCompactResult;
+    };
+    "classic.PostCompact": {
+        e: PostCompactEvent;
+        answer: void;
+    };
+    "classic.PermissionDenied": {
+        e: PermissionDeniedPayload;
+        answer: void;
+    };
+}
+export type ClassicStation = keyof ClassicStationTypes;
+/** 每一站能挂什么:`chain` = 链成员(会作答)与观察者都可;`observe` = 只许观察者。 */
+export declare const CLASSIC_STATION_ROLE: {
+    readonly "classic.PreToolUse": "chain";
+    readonly "classic.PostToolUse": "chain";
+    readonly "classic.PostToolUseFailure": "chain";
+    readonly "classic.PostToolBatch": "chain";
+    readonly "classic.UserPromptSubmit": "chain";
+    readonly "classic.Stop": "chain";
+    readonly "classic.SubagentStop": "chain";
+    readonly "classic.StopFailure": "observe";
+    readonly "classic.PreCompact": "chain";
+    readonly "classic.PostCompact": "observe";
+    readonly "classic.PermissionDenied": "observe";
+};
+/**
+ * 一站的 handler 体:读 `e`,答这一站的答案;`undefined` = 无意见(链成员由 {@link hangClassic} 交给 `next(e)`)。
+ * `signal` = 引擎交给这只 handler 的 `next.signal`(预算到 ∪ 派发被取消;见头注 ③)。
+ */
+export type ClassicAnswer<K extends ClassicStation> = (e: ClassicStationTypes[K]["e"], signal: AbortSignal) => Promise<ClassicStationTypes[K]["answer"] | undefined>;
+/**
+ * 按站的角色挂一只 handler:链站 ⇒ 链成员 `(await answer(e)) ?? next(e)`;观察站 ⇒ 观察者(体照跑、恒返回 `undefined`)。
+ * `e` 的型由 {@link ClassicStationTypes} 给(引擎交来的是本站的 `e`;配对见头注 ①)。
+ */
+export declare function hangClassic<K extends ClassicStation>(on: On<EngineDollar>, station: K, answer: ClassicAnswer<K>): void;
+/** 挂一只观察者(任何站都可):拿分离副本、不进链、恒返回 `undefined`;`signal` 同 {@link ClassicAnswer}。 */
+export declare function observeClassic<K extends ClassicStation>(on: On<EngineDollar>, station: K, watch: (e: ClassicStationTypes[K]["e"], signal: AbortSignal) => void | Promise<void>): void;
+//# sourceMappingURL=classic-stations.d.ts.map

package/dist/hooks/classic-stations.js

@@ -0,0 +1,27 @@
+export const CLASSIC_STATION_ROLE = {
+    "classic.PreToolUse": "chain",
+    "classic.PostToolUse": "chain",
+    "classic.PostToolUseFailure": "chain",
+    "classic.PostToolBatch": "chain",
+    "classic.UserPromptSubmit": "chain",
+    "classic.Stop": "chain",
+    "classic.SubagentStop": "chain",
+    "classic.StopFailure": "observe",
+    "classic.PreCompact": "chain",
+    "classic.PostCompact": "observe",
+    "classic.PermissionDenied": "observe",
+};
+export function hangClassic(on, station, answer) {
+    if (CLASSIC_STATION_ROLE[station] === "observe") {
+        observeClassic(on, station, async (e, signal) => void (await answer(e, signal)));
+        return;
+    }
+    on(station, async (_$, e, next) => (await answer(e, next.signal)) ?? next(e));
+}
+export function observeClassic(on, station, watch) {
+    on(station, async (_$, e, next) => {
+        await watch(e, next.signal);
+        return undefined;
+    }, { observe: true });
+}
+//# sourceMappingURL=classic-stations.js.map

package/dist/hooks/command-spawn.d.ts

@@ -0,0 +1,57 @@
+import type { CommandHookEntry } from "@sema-agent/settings-schema/hooks";
+/** command 条目的插件上下文(wire 键 `plugin`)。 */
+export interface HookPluginContext {
+    readonly name: string;
+    readonly root: string;
+    readonly dataDir?: string;
+    readonly options?: Readonly<Record<string, string>>;
+}
+/** 本仓会跑的 command 条目:契约形 + 本仓读的两只 wire 键。 */
+export type RunnableCommandHookEntry = CommandHookEntry & {
+    readonly args?: readonly string[];
+    readonly plugin?: HookPluginContext;
+};
+/** 受理面:`args` 合形(串数组、元素无 NUL)⇒ 拷贝;否则 `undefined`。 */
+export declare function readHookArgs(raw: unknown): string[] | undefined;
+/** 受理面:`plugin` 合形 ⇒ 拷贝;否则 `undefined`。路径与 `skills[i].baseDir` 同一只判(契约包 `isAbsoluteHostPath`:绝对、无 `..` 段、无 NUL、有长度上限);不做存在性检查(那是执行面的事)。 */
+export declare function readHookPlugin(raw: unknown): HookPluginContext | undefined;
+/** 插件上下文的总字符数(服务侧上限 `plugin` 帽的量):名 + 根 + 数据目录 + 各选项的键与值。 */
+export declare function hookPluginChars(p: HookPluginContext): number;
+/** 命令行的字符数(服务侧上限 `command` 帽的量):`command` 加上 exec 形每个元素(各计一个分隔)。 */
+export declare function commandLineChars(entry: {
+    readonly command: string;
+    readonly args?: readonly string[];
+}): number;
+/** 插件上下文 → 它注入的环境变量(无 `plugin` ⇒ 空)。 */
+export declare function hookPluginEnv(p: HookPluginContext | undefined): Record<string, string>;
+/**
+ * 起法:shell 形交回命令串(shell 由调用点落定),exec 形交回可执行名与参数,起不来交回真因(进调用点的 `spawnError`)。
+ * `env` = 这条 hook 的**有效环境层**({@link composeHookEnvLayer} 的产物;调用点铺在基础 allowlist 之上,不再自己合并任何一层)。
+ */
+export type CommandSpawnPlan = {
+    readonly kind: "shell";
+    readonly command: string;
+    readonly env: Readonly<Record<string, string>>;
+} | {
+    readonly kind: "exec";
+    readonly file: string;
+    readonly args: readonly string[];
+    readonly env: Readonly<Record<string, string>>;
+} | {
+    readonly kind: "refused";
+    readonly error: string;
+};
+/**
+ * 一条 command hook 的**有效环境层**(基础 allowlist 之上的那一层)—— **唯一铺法**,后铺者赢:`CLAUDE_PROJECT_DIR` 的缺省(`cwd`,hook 的工作目录;请求没写它才取)< 请求 `settings.env`(`requestEnv`;
+ * 请求自己写了 `CLAUDE_PROJECT_DIR` 就是它,空串也照用)< 条目自己的插件上下文({@link hookPluginEnv})。键的枚举顺序 = 请求的键在前、`CLAUDE_PROJECT_DIR` 缺省时接后、插件键最后。调用点传**原料**(工作目录与请求 env),不预先取舍 `CLAUDE_PROJECT_DIR`。
+ * 「有没有值」的判据、exec 形的占位替换、shell 形子进程的环境都读这一个对象(见文件头);http 条目的 `$NAME` 插值取环境也走这一只(无插件上下文)。
+ */
+export declare function composeHookEnvLayer(requestEnv: Readonly<Record<string, string>> | undefined, cwd: string, plugin: HookPluginContext | undefined): Record<string, string> & {
+    CLAUDE_PROJECT_DIR: string;
+};
+/**
+ * 一条 command 条目的起法(规则见文件头)。`cwd` = 本次 hook 的工作目录(`CLAUDE_PROJECT_DIR` 的缺省值);`requestEnv` = 请求 `settings.env`(hook 环境的一层;**必传**:没有就显式传 `undefined`,
+ * 漏传是编译红,不会静默丢掉请求给的 env),合并与读法见 {@link composeHookEnvLayer} / {@link contextVarValue}。有副作用的只有两步,都只在条目带 `plugin` 时发生:读插件根是否是目录、建数据目录(CC 同:注入即建)。
+ */
+export declare function planCommandSpawn(entry: RunnableCommandHookEntry, cwd: string, requestEnv: Readonly<Record<string, string>> | undefined): Promise<CommandSpawnPlan>;
+//# sourceMappingURL=command-spawn.d.ts.map

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.d.ts

@@ -1,6 +1,6 @@
 import type { ModelKeyRef } from "../key-resolver.js";
 import type { ServiceConfig } from "../config-types.js";
-import type { HookLlmCall } from "./hook-runner.js";
+import type { HookLlmCall, HookLlmFailureCode } from "./hook-runner.js";
 /**
  * hookLlm(prompt 条目/session titler 的模型载体)= 直连一次非流式 completion,从 main.ts 抽出成可注入
  * 单元(fetchImpl/keyResolver 可假),因为这条 wire 在每个默认部署上都活(titler),必须可单测。
@@ -16,13 +16,13 @@ import type { HookLlmCall } from "./hook-runner.js";
  *
  * 🔴 **选线 = 引擎主路由同一只判词**(S-1630):「这只模型走 openai-completions 还是 anthropic-messages」不是本面的事,
  * 是引擎主路由的事 —— `brain.ts` 按 `model.provider` 在「anthropic 路由(仅当 ANTHROPIC 凭据把它装上)/ 网关栈」之间选,
- * 路由没装时整台机器只有网关这一只 brain,**连 `provider:"anthropic"` 的模型也落网关**(`dispatchBrainLane` 的合取,
+ * 路由没装时整台机器只有网关这一只 brain,**连 `provider:"anthropic"` 的模型也落网关**(判词 `brainLaneFor` = 引擎 `brainLaneOf` 对装上的路由表的答案,
  * 端点判官 / 降级腿 / 启动摘要读的是同一只)。本面此前自己按 `provider === "anthropic"` / `api === "anthropic-messages"`
  * 字面判线 ⇒ 在 `MODEL_PROVIDER=anthropic` 而只配了网关的部署上,主请求去网关、标题与 hooks 的 llm 面却要找一条没装的
  * anthropic 路由,整条拒发(零请求,只落 fail-open 标签)。现在本面只问那一只判词,不留第二个读法 —— 含 `api` 词:
  * 引擎不按 `api` 选线(core 的 `createRoutingBrain` 缺省按 `provider` 键),settings-schema 的 `ModelEntry` 又强制两个词同真同假。
- * (core 目前只导出 `createRoutingBrain` 这个组合子,没有「给定模型与已装路由 → 哪条腿 / 哪个根」的判官;它导出之日,
- * `dispatchBrainLane` 连同本调用点一并改为问它。)
+ * (S-1630 的 (a) 路已兑现:core 7.53.0 #1842 根导出了那只判官 `brainLaneOf(model, routes)` —— `createRoutingBrain` 对每个请求问的就是它;
+ * 本仓自写的合取 `dispatchBrainLane` 随之退役,本调用点与另三处一并改问它。)
  */
 export type HookModelPick = {
     ok: true;
@@ -30,9 +30,12 @@ export type HookModelPick = {
     providerModelId: string;
     baseUrl: string;
     api: "openai-completions" | "anthropic-messages";
-} | {
+}
+/** 选不出来的那一臂自带失败码(S-1635):两个载体(prompt 直连 / agent 子代理)共用这一只选模闸,同一只判词同一个码。 */
+ | {
     ok: false;
     error: string;
+    code: Extract<HookLlmFailureCode, "model_unresolved">;
 };
 /**
  * 🔴 **hook 失败展示文本的唯一铸点**(S-494;`build*` = 返回纯数据的一只纯函数)。

package/dist/hooks/hook-llm.js

@@ -1,10 +1,11 @@
-import { adjudicateModelRoute, joinRequestUrl, resolveRouteCredential, routeKeyOf, routeRefusalText } from "@sema-agent/core";
+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 { dispatchBrainLane } from "../model-provider.js";
+import { anthropicRouteRoot, brainLaneFor, routeTableOf } from "../model-provider.js";
 import { egressRedirectRefusal } from "../egress-redirect.js";
 import { buildDisplaySafeRefusal, redactSecrets } from "../trace/redact.js";
+const unresolvedPick = (error) => ({ ok: false, error, code: "model_unresolved" });
 export function buildHookFailureText(raw) {
     if (raw === "")
         return raw;
@@ -15,68 +16,86 @@ export function buildHookFailureText(raw) {
         return `[hook failure text withheld: redactor threw ${err instanceof Error ? err.name : typeof err}]`;
     }
 }
+const ROUTE_REFUSAL_CODES = {
+    "route.credential_mismatch": true,
+    "route.credential_missing": true,
+    "route.credential_origin_mismatch": true,
+    "route.credential_answer_conflict": true,
+};
+const ROUTE_REFUSAL_LEAD = "[invalid_request] ";
+function gateRefusal(pick, e, declaredRoot) {
+    const raw = e instanceof Error ? e.message : String(e);
+    const text = e instanceof BrainError && raw.startsWith(ROUTE_REFUSAL_LEAD) ? raw.slice(ROUTE_REFUSAL_LEAD.length) : raw;
+    const code = Object.keys(ROUTE_REFUSAL_CODES).find((c) => text.startsWith(`${c}:`)) ?? "unclassified";
+    return {
+        ok: false,
+        code: "route_refused",
+        error: `hook model "${pick.catalogRef}" cannot be routed (${code}) — ` + buildDisplaySafeRefusal(text, [pick.baseUrl, declaredRoot ?? ""]),
+    };
+}
 export function createHookLlm(deps) {
     const { config, metrics } = deps;
-    const anthropicRouteBaseUrl = () => config.anthropic?.baseUrl || "https://api.anthropic.com";
-    const shapeFrom = (catalogRef, m, providerModelId) => {
-        const lane = dispatchBrainLane(m?.provider, config.anthropic !== undefined);
+    const anthropicRouteBaseUrl = () => anthropicRouteRoot(config.anthropic ?? {});
+    const shapeFrom = (m, providerModelId = m.id) => {
+        const catalogRef = m.name;
+        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" };
             case "gateway": {
                 const endpoint = resolveOpenaiRouteEndpoint(catalogRef, m, config.gatewayBaseUrl, servedModelTableLeg(config));
-                return endpoint.ok ? { ok: true, catalogRef, providerModelId, baseUrl: endpoint.baseUrl, api: "openai-completions" } : { ok: false, error: endpoint.refusal };
+                return endpoint.ok ? { ok: true, catalogRef, providerModelId, baseUrl: endpoint.baseUrl, api: "openai-completions" } : unresolvedPick(endpoint.refusal);
             }
         }
     };
     const hookModelFor = (requested) => {
-        const shape = (ref) => shapeFrom(ref, config.models[ref], config.models[ref]?.id ?? ref);
+        const ownEntry = (ref) => (Object.hasOwn(config.models, ref) ? config.models[ref] : undefined);
         const unavailable = (field, ref) => {
-            if (config.models[ref] !== undefined)
+            if (ownEntry(ref) !== undefined)
                 return undefined;
             const hit = refusedCatalogEntry(ref, config.modelRefusals);
-            return hit === undefined ? undefined : { ok: false, error: modelUnavailableMessage(field, ref, hit.name, hit.refusal) };
+            return hit === undefined ? undefined : unresolvedPick(modelUnavailableMessage(field, ref, hit.name, hit.refusal));
         };
         if (requested === undefined) {
             const sum = config.roles.summarize;
             const roleModel = typeof sum === "string" ? sum : sum && typeof sum === "object" && "model" in sum && typeof sum.model === "string" ? sum.model : undefined;
-            if (roleModel !== undefined)
-                return unavailable("summarize role model", roleModel) ?? (config.models[roleModel] ? shape(roleModel) : shapeFrom(config.model.id, config.model, roleModel));
-            return shapeFrom(config.model.id, config.model, config.model.id);
+            if (roleModel !== undefined) {
+                const entry = ownEntry(roleModel);
+                return unavailable("summarize role model", roleModel) ?? (entry ? shapeFrom(entry) : shapeFrom(config.model, roleModel));
+            }
+            return shapeFrom(config.model);
         }
-        if (config.models[requested])
-            return shape(requested);
+        const matchedKey = matchCatalogModel(requested, config.models, config.modelRefusals);
+        if (matchedKey !== undefined)
+            return shapeFrom(config.models[matchedKey]);
         if (Object.hasOwn(config.modelRefusals ?? {}, requested))
             return unavailable("hook model", requested);
-        const byId = matchCatalogModel(requested, config.models, config.modelRefusals);
-        if (byId !== undefined)
-            return shape(byId);
         if (requested === config.model.id)
-            return shapeFrom(requested, config.model, requested);
-        return unavailable("hook model", requested) ?? { ok: false, error: `hook model "${requested}" is not in this deployment's catalog` };
+            return shapeFrom(config.model);
+        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({
             ...(perModelKey !== undefined ? { optionsApiKey: perModelKey } : {}),
             ...(deploymentKey !== undefined ? { configApiKey: deploymentKey } : {}),
         });
-        const verdict = adjudicateModelRoute({ id: pick.catalogRef, baseUrl: pick.baseUrl }, credential, { ...(declaredRoot !== undefined ? { baseUrl: declaredRoot } : {}) });
-        if (!verdict.ok) {
-            return {
-                ok: false,
-                error: `hook model "${pick.catalogRef}" cannot be routed (${verdict.code}) — ` +
-                    buildDisplaySafeRefusal(routeRefusalText(verdict), [pick.baseUrl, declaredRoot ?? ""]),
-            };
+        let admission;
+        try {
+            admission = admitRouteRequest({ id: pick.catalogRef, baseUrl: pick.baseUrl }, credential, { ...(declaredRoot !== undefined ? { baseUrl: declaredRoot } : {}) });
         }
-        if (verdict.posture === "keyless" && routeKeyOf(pick.baseUrl) !== routeKeyOf(declaredRoot)) {
+        catch (e) {
+            return gateRefusal(pick, e, declaredRoot);
+        }
+        if (credential.source === "absent" && routeKeyOf(pick.baseUrl) !== routeKeyOf(declaredRoot)) {
             return {
                 ok: false,
+                code: "route_refused",
                 error: `hook model "${pick.catalogRef}" points at ${pick.baseUrl}, which this deployment did not declare as its own endpoint, ` +
                     `and no per-model credential resolved — refusing to send the prompt there (it embeds user content; an unauthenticated ` +
                     `request still hands that content to whoever operates that URL)`,
             };
         }
-        return { ok: true, credential };
+        return { ok: true, credential, admission };
     };
     const fetchImpl = deps.fetchImpl ?? fetch;
     const callLlm = async ({ prompt, model, timeoutMs, system, maxOutputTokens }) => {
@@ -85,6 +104,7 @@ export function createHookLlm(deps) {
             return pick;
         const ac = new AbortController();
         const t = setTimeout(() => ac.abort(), timeoutMs);
+        let phase = "assemble";
         try {
             const keyResolver = deps.getKeyResolver();
             let perModelKey;
@@ -93,17 +113,21 @@ export function createHookLlm(deps) {
                     perModelKey = (await keyResolver({ name: pick.catalogRef }))?.apiKey;
                 }
                 catch (e) {
-                    return { ok: false, error: `per-model key resolution for "${pick.catalogRef}" failed — refusing to fall back to the shared route credential (${String(e)})` };
+                    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" };
                 }
             }
             let url;
             let headers;
             let body;
+            let admitted;
+            let declaredRoot;
             if (pick.api === "anthropic-messages") {
                 const routeBase = anthropicRouteBaseUrl();
+                declaredRoot = routeBase;
                 const routed = judgeRoute(pick, perModelKey, config.anthropic?.authToken ?? config.anthropic?.apiKey, routeBase);
                 if (!routed.ok)
                     return routed;
+                admitted = routed.admission;
                 url = joinRequestUrl(pick.baseUrl, "/v1/messages");
                 headers = {
                     "content-type": "application/json",
@@ -121,29 +145,47 @@ export function createHookLlm(deps) {
                 body = JSON.stringify({ model: pick.providerModelId, max_tokens: maxTokens, ...(system ? { system } : {}), messages: [{ role: "user", content: prompt }] });
             }
             else {
+                declaredRoot = config.gatewayBaseUrl;
                 const routed = judgeRoute(pick, perModelKey, config.gatewayApiKey, config.gatewayBaseUrl);
                 if (!routed.ok)
                     return routed;
+                admitted = routed.admission;
                 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 });
             }
+            try {
+                admitted();
+            }
+            catch (e) {
+                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" };
             if (!r.ok)
-                return { ok: false, error: `hook llm HTTP ${r.status}` };
+                return { ok: false, error: `hook llm HTTP ${r.status}`, code: "bad_response" };
+            let answered;
+            try {
+                answered = await r.json();
+            }
+            catch (e) {
+                if (ac.signal.aborted || e?.name !== "SyntaxError")
+                    throw e;
+                return { ok: false, error: "hook llm answered with a body that is not JSON", code: "bad_response" };
+            }
             let text;
             if (pick.api === "anthropic-messages") {
-                const j = (await r.json());
-                const parts = (Array.isArray(j.content) ? j.content : []).filter((b) => b?.type === "text" && typeof b.text === "string").map((b) => b.text);
+                const j = answered;
+                const parts = (Array.isArray(j?.content) ? j.content : []).filter((b) => b?.type === "text" && typeof b.text === "string").map((b) => b.text);
                 text = parts.length > 0 ? parts.join("") : undefined;
             }
             else {
-                const j = (await r.json());
-                text = j.choices?.[0]?.message?.content ?? undefined;
+                const j = answered;
+                text = j?.choices?.[0]?.message?.content ?? undefined;
             }
             metrics.inc("hook_llm_calls_total", { type: "prompt" });
             return typeof text === "string" ? { ok: true, text } : { ok: false, error: "hook llm returned no content", code: "no_content" };
@@ -153,6 +195,7 @@ export function createHookLlm(deps) {
             return {
                 ok: false,
                 error: ac.signal.aborted ? "hook llm timeout" : `hook llm request to ${pick.baseUrl} failed: ${String(e)}${cause ? ` (${String(cause)})` : ""}`,
+                code: ac.signal.aborted || phase === "transport" ? "unreachable" : "route_refused",
             };
         }
         finally {