@sema-agent/server 1.323.0 → 2.0.1

package/dist/hooks/cc-stop-prompt.d.ts

@@ -1,12 +1,54 @@
+/**
+ * CC `execPromptHook` 的**逐字**移植面:两档系统提示 + `{ok, reason, impossible?}` 判词的解析与映射。
+ *
+ * ── 为什么单独一个文件 ──────────────────────────────────────────────────────────────────────────
+ * 本仓有 clay 的**提示词面锚定 CC 逐字**令(偏离仅限超集/品牌二类且需登记)。把这两段正文与它们的
+ * 判词形收在一处,才谈得上机器看守(见 `test/cc-stop-prompt.test.ts` 的字节钉)。
+ *
+ * ── 出处(我**第一手**核过,不是照抄转述)────────────────────────────────────────────────────────
+ * `sema-agent/cc-decoded` 的 `pretty220.js:609309` 起(219/218 同构)。逐字核实的四件:
+ *  · 两档判据是 **hook 事件名**:`c = r === "Stop" || r === "SubagentStop"` ⇒ 这两个事件用**完整版**,其余用简版;
+ *  · user 消息也被包装(见 {@link wrapCondition}),原文预设**会话就在上文**("transcript **above**");
+ *  · 评估者 `thinkingConfig: { type: "disabled" }` + **`tools: []`** —— 它是**纯判官**,不能自己去查;
+ *  · 会话消息**整段前置**(`s && s.length > 0 ? [...prepend(s), p] : [p]`),不是摘要。
+ * ⚠️ 语料把非 ASCII 存成 `\uXXXX` 六字符字面量(正文里那两个破折号是 `\u2014`)——**grep 真字符会全假阴**。
+ *    所以下面也用 `\u2014` 转义:源码保持 ASCII,运行时是同一个字符。
+ * ⚠️ **为什么必须自己核**:cli 报过他们移植的那段是**第三种措辞**(与 CC 220 的两个分支都不逐字相同,
+ *    应是从更早版本移植后 CC 改过而没跟)。转述会漂,语料不会。
+ */
+/** 完整版(**Stop / SubagentStop** 用)。CC `pretty220.js` 逐字。 */
 export declare const CC_STOP_PROMPT_SYSTEM_FULL = "You are evaluating a stop-condition hook in Claude Code. Read the conversation transcript carefully, then judge whether the user-provided condition is satisfied.\n\nYour response must be a JSON object with one of these shapes:\n- {\"ok\": true, \"reason\": \"<quote evidence from the transcript that satisfies the condition>\"}\n- {\"ok\": false, \"reason\": \"<quote what is missing or what blocks the condition>\"}\n- {\"ok\": false, \"impossible\": true, \"reason\": \"<explain why the condition can never be satisfied>\"}\n\nAlways include a \"reason\" field, quoting specific text from the transcript whenever possible. If the transcript does not contain clear evidence that the condition is satisfied, return {\"ok\": false, \"reason\": \"insufficient evidence in transcript\"}.\n\nOnly use {\"ok\": false, \"impossible\": true} when the condition is genuinely unachievable in this session \u2014 for example: the condition is self-contradictory, it depends on a resource or capability that is unavailable, or the assistant has explicitly tried, exhausted reasonable approaches, and stated it cannot be done. Apply your own judgment when deciding this \u2014 the assistant claiming the goal is impossible is evidence, not proof; independently confirm the condition is genuinely unachievable rather than deferring to the assistant's self-assessment. Do not use it just because the goal has not been reached yet or because progress is slow. When in doubt, return {\"ok\": false} without \"impossible\".";
+/** 简版(其余事件用)。CC `pretty220.js` 逐字。 */
 export declare const CC_STOP_PROMPT_SYSTEM_SIMPLE = "You are evaluating a hook condition in Claude Code. Judge whether the user-provided condition is met.\n\nYour response must be a JSON object with one of these shapes:\n- {\"ok\": true, \"reason\": \"<reason the condition is met>\"}\n- {\"ok\": false, \"reason\": \"<reason the condition is not met>\"}\n\nAlways include a \"reason\" field.";
+/** 事件名 → 用哪一档。CC 判据逐字:`r === "Stop" || r === "SubagentStop"`。 */
 export declare function ccPromptSystemFor(event: string): string;
+/**
+ * CC 对 user 消息的包装(**仅**完整版档位)。原文逐字,注意 "transcript **above**" ——
+ * 它预设会话已经在上文,所以调用方必须真的把会话放在前面,否则这句话本身就是在骗模型。
+ */
 export declare function wrapCondition(event: string, condition: string): string;
+/** CC 的判词形:`{ ok, reason, impossible? }`(zod 原文:impossible = "only meaningful when ok is false")。 */
 export interface CcPromptVerdict {
     ok: boolean;
     reason?: string;
     impossible?: boolean;
 }
+/**
+ * 解析模型判词。**解析不出来 ⇒ `undefined`**(= 无判决),绝不臆测成 `ok:false` ——
+ * 🔴 Stop 钩子的 `ok:false` **等于拦住停止**,把"读不懂"当成"没满足"会让一次解析失败变成一次拦停。
+ */
 export declare function parseCcVerdict(text: string): CcPromptVerdict | undefined;
+/**
+ * CC 条件评估者的**输出额度**。
+ *
+ * 🔴 为什么不能用载体缺省(1024):CC 的系统提示**明确要求**评估者
+ * 「quote evidence from the transcript」——判词天然带引文;而**推理档模型的 thinking 与输出共用**这份额度。
+ * cli 的 live 围栏实测两种失败形,**同一根因**:①判词 JSON 被截断(`{"ok": true, "reason": "The first user…` 然后没了)
+ * ②一个字都没吐出来(thinking 吃光)。**两种都导致判词整条被丢弃 ⇒ fail-open(该拦没拦)** ——
+ * 而用户设 `enforced` 的全部意义就是「没达成别停」,这正是守卫在最需要它的时候静默失效。
+ *
+ * 4096 的取法:判词本身是个小 JSON + 一段引文(几百 token 足够),其余留给 thinking;
+ * 同时它安全地低于所有在用模型的输出硬顶(超硬顶会让整请求 400)。
+ */
 export declare const CC_EVALUATOR_MAX_OUTPUT_TOKENS = 4096;
 //# sourceMappingURL=cc-stop-prompt.d.ts.map

package/dist/hooks/cc-stop-prompt.js

@@ -1,3 +1,22 @@
+/**
+ * CC `execPromptHook` 的**逐字**移植面:两档系统提示 + `{ok, reason, impossible?}` 判词的解析与映射。
+ *
+ * ── 为什么单独一个文件 ──────────────────────────────────────────────────────────────────────────
+ * 本仓有 clay 的**提示词面锚定 CC 逐字**令(偏离仅限超集/品牌二类且需登记)。把这两段正文与它们的
+ * 判词形收在一处,才谈得上机器看守(见 `test/cc-stop-prompt.test.ts` 的字节钉)。
+ *
+ * ── 出处(我**第一手**核过,不是照抄转述)────────────────────────────────────────────────────────
+ * `sema-agent/cc-decoded` 的 `pretty220.js:609309` 起(219/218 同构)。逐字核实的四件:
+ *  · 两档判据是 **hook 事件名**:`c = r === "Stop" || r === "SubagentStop"` ⇒ 这两个事件用**完整版**,其余用简版;
+ *  · user 消息也被包装(见 {@link wrapCondition}),原文预设**会话就在上文**("transcript **above**");
+ *  · 评估者 `thinkingConfig: { type: "disabled" }` + **`tools: []`** —— 它是**纯判官**,不能自己去查;
+ *  · 会话消息**整段前置**(`s && s.length > 0 ? [...prepend(s), p] : [p]`),不是摘要。
+ * ⚠️ 语料把非 ASCII 存成 `\uXXXX` 六字符字面量(正文里那两个破折号是 `\u2014`)——**grep 真字符会全假阴**。
+ *    所以下面也用 `\u2014` 转义:源码保持 ASCII,运行时是同一个字符。
+ * ⚠️ **为什么必须自己核**:cli 报过他们移植的那段是**第三种措辞**(与 CC 220 的两个分支都不逐字相同,
+ *    应是从更早版本移植后 CC 改过而没跟)。转述会漂,语料不会。
+ */
+/** 完整版(**Stop / SubagentStop** 用)。CC `pretty220.js` 逐字。 */
 export const CC_STOP_PROMPT_SYSTEM_FULL = `You are evaluating a stop-condition hook in Claude Code. Read the conversation transcript carefully, then judge whether the user-provided condition is satisfied.
 
 Your response must be a JSON object with one of these shapes:
@@ -8,6 +27,7 @@ Your response must be a JSON object with one of these shapes:
 Always include a "reason" field, quoting specific text from the transcript whenever possible. If the transcript does not contain clear evidence that the condition is satisfied, return {"ok": false, "reason": "insufficient evidence in transcript"}.
 
 Only use {"ok": false, "impossible": true} when the condition is genuinely unachievable in this session \u2014 for example: the condition is self-contradictory, it depends on a resource or capability that is unavailable, or the assistant has explicitly tried, exhausted reasonable approaches, and stated it cannot be done. Apply your own judgment when deciding this \u2014 the assistant claiming the goal is impossible is evidence, not proof; independently confirm the condition is genuinely unachievable rather than deferring to the assistant's self-assessment. Do not use it just because the goal has not been reached yet or because progress is slow. When in doubt, return {"ok": false} without "impossible".`;
+/** 简版(其余事件用)。CC `pretty220.js` 逐字。 */
 export const CC_STOP_PROMPT_SYSTEM_SIMPLE = `You are evaluating a hook condition in Claude Code. Judge whether the user-provided condition is met.
 
 Your response must be a JSON object with one of these shapes:
@@ -15,16 +35,26 @@ Your response must be a JSON object with one of these shapes:
 - {"ok": false, "reason": "<reason the condition is not met>"}
 
 Always include a "reason" field.`;
+/** 事件名 → 用哪一档。CC 判据逐字:`r === "Stop" || r === "SubagentStop"`。 */
 export function ccPromptSystemFor(event) {
     return event === "Stop" || event === "SubagentStop" ? CC_STOP_PROMPT_SYSTEM_FULL : CC_STOP_PROMPT_SYSTEM_SIMPLE;
 }
+/**
+ * CC 对 user 消息的包装(**仅**完整版档位)。原文逐字,注意 "transcript **above**" ——
+ * 它预设会话已经在上文,所以调用方必须真的把会话放在前面,否则这句话本身就是在骗模型。
+ */
 export function wrapCondition(event, condition) {
     if (event !== "Stop" && event !== "SubagentStop")
         return condition;
     return `Based on the conversation transcript above, has the following stopping condition been satisfied? Answer based on transcript evidence only.\n\nCondition: ${condition}`;
 }
+/**
+ * 解析模型判词。**解析不出来 ⇒ `undefined`**(= 无判决),绝不臆测成 `ok:false` ——
+ * 🔴 Stop 钩子的 `ok:false` **等于拦住停止**,把"读不懂"当成"没满足"会让一次解析失败变成一次拦停。
+ */
 export function parseCcVerdict(text) {
     const raw = text.trim();
+    // 模型常把 JSON 包在 ```json 围栏或散文里 —— 取第一个平衡的 {...} 块。
     const start = raw.indexOf("{");
     if (start < 0)
         return undefined;
@@ -38,7 +68,7 @@ export function parseCcVerdict(text) {
                 try {
                     const o = JSON.parse(raw.slice(start, i + 1));
                     if (typeof o.ok !== "boolean")
-                        return undefined;
+                        return undefined; // 没有 ok ⇒ 不是判词
                     return {
                         ok: o.ok,
                         ...(typeof o.reason === "string" ? { reason: o.reason } : {}),
@@ -53,5 +83,17 @@ export function parseCcVerdict(text) {
     }
     return undefined;
 }
+/**
+ * CC 条件评估者的**输出额度**。
+ *
+ * 🔴 为什么不能用载体缺省(1024):CC 的系统提示**明确要求**评估者
+ * 「quote evidence from the transcript」——判词天然带引文;而**推理档模型的 thinking 与输出共用**这份额度。
+ * cli 的 live 围栏实测两种失败形,**同一根因**:①判词 JSON 被截断(`{"ok": true, "reason": "The first user…` 然后没了)
+ * ②一个字都没吐出来(thinking 吃光)。**两种都导致判词整条被丢弃 ⇒ fail-open(该拦没拦)** ——
+ * 而用户设 `enforced` 的全部意义就是「没达成别停」,这正是守卫在最需要它的时候静默失效。
+ *
+ * 4096 的取法:判词本身是个小 JSON + 一段引文(几百 token 足够),其余留给 thinking;
+ * 同时它安全地低于所有在用模型的输出硬顶(超硬顶会让整请求 400)。
+ */
 export const CC_EVALUATOR_MAX_OUTPUT_TOKENS = 4096;
 //# sourceMappingURL=cc-stop-prompt.js.map

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

@@ -1,6 +1,19 @@
 import type { Model } from "@sema-agent/core";
 import type { ServiceConfig } from "../config-types.js";
 import type { HookLlmCall } from "./hook-runner.js";
+/**
+ * hookLlm(prompt 条目/session titler 的模型载体)= 直连一次非流式 completion,从 main.ts 抽出成可注入
+ * 单元(fetchImpl/keyResolver 可假),因为这条 wire 在每个默认部署上都活(titler),必须可单测。
+ *
+ * api 形分派(2026-07-15,黑板 [851]③b 真缺陷修):被选模型按 `Model.api` 分家 ——
+ *  - `openai-completions` ⇒ POST {base}/chat/completions(现状,字节不变);
+ *  - `anthropic-messages` ⇒ POST {base}/v1/messages(x-api-key / Authorization: Bearer + anthropic-version
+ *    头,messages 数组,回包取 content[].text)。此前 hookLlm 只会说 openai 形且缺省 baseUrl 恒落
+ *    `config.gatewayBaseUrl`(缺省 http://127.0.0.1:8000/v1)——anthropic 单路由部署(主模型
+ *    provider=anthropic 走 ANTHROPIC_BASE_URL,没配 MODEL_GATEWAY_BASEURL)下 titler 每会话打死
+ *    localhost:8000 ⇒ `session_title_failed: TypeError: fetch failed`;即使端点活着,anthropic-messages
+ *    模型也不能用 /chat/completions 形调。
+ */
 export type HookModelPick = {
     ok: true;
     catalogRef: string;
@@ -11,12 +24,14 @@ export type HookModelPick = {
     ok: false;
     error: string;
 };
+/** The live object `createHookLlm` produces — model-pick resolution + the direct completion call, both capturing the hot-refreshed keyResolver/fetchImpl in closure. */
 export interface HookLlm {
     hookModelFor: (requested?: string) => HookModelPick;
     hookLlm: HookLlmCall;
 }
 export declare function createHookLlm(deps: {
     config: ServiceConfig;
+    /** 与 brain 同一 hot-refreshed per-model key 面(main.ts 热应用会整个换引用,故取函数不取值)。 */
     getKeyResolver: () => ((model: Model) => Promise<{
         apiKey: string;
     } | undefined>) | undefined;

package/dist/hooks/hook-llm.js

@@ -1,6 +1,15 @@
 export function createHookLlm(deps) {
     const { config, metrics } = deps;
+    // anthropic 路由自己的 baseUrl(与 core createAnthropicBrain 同一解析链:model.baseUrl || config.baseUrl
+    // || 官方缺省)。路由未装(无 ANTHROPIC 凭据 ⇒ config.anthropic 缺席)⇒ undefined,分派据此判
+    // 「这个部署有没有 anthropic 腿」。
     const anthropicRouteBaseUrl = () => config.anthropic ? config.anthropic.baseUrl || "https://api.anthropic.com" : undefined;
+    // catalog KEY(name)≠ provider model id——registry 热应用后两者可分叉。分别返回:
+    // `catalogRef`(hookAgent 用,core resolveModel 按 deps.models 键解析;也是 keyResolver 的查键)与
+    // `providerModelId`+`baseUrl`+`api`(hookLlm 直连用)。baseUrl 缺省按 api 分家:openai 形落主网关
+    // (现状);anthropic 形落 anthropic 路由自己的 baseUrl——provider=anthropic 的模型在 brain 路由里
+    // 从不走 openai 网关,titler 兜到 gatewayBaseUrl 缺省值即上述每会话必现 fetch failed 的根因。
+    // anthropic 形两头都缺(模型无 per-model baseUrl 且路由未装)= 一句话诚实 fail,说清缺什么配置。
     const shapeFrom = (catalogRef, m, providerModelId) => {
         const api = m?.api === "anthropic-messages" || m?.provider === "anthropic" ? "anthropic-messages" : "openai-completions";
         if (api === "anthropic-messages") {
@@ -15,11 +24,16 @@ export function createHookLlm(deps) {
         }
         return { ok: true, catalogRef, providerModelId, baseUrl: m?.baseUrl || config.gatewayBaseUrl, api };
     };
+    // 默认=summarize 角色(cheap tier,council/压缩同款;缺角色→主模型);entry.model 覆盖须命中部署
+    // catalog(单用户=自家目录全开,与 workflow 模型 allowlist 同纪律),未命中=该条目 fail(非阻断记账)。
+    // ({select} 形态诚实落主模型——hook 是廉价判定调用,不值得拉 select 机制。)
     const hookModelFor = (requested) => {
         const shape = (ref) => shapeFrom(ref, config.models[ref], config.models[ref]?.id ?? ref);
         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;
+            // 角色名不在目录 ⇒ 当作主模型路由上的 raw provider id(主 brain 家族就是它的真实服务面),
+            // 形状/缺省 baseUrl 跟主模型走,不再无条件钉死 openai 网关。
             if (roleModel !== undefined)
                 return config.models[roleModel] ? shape(roleModel) : shapeFrom(config.model.id, config.model, roleModel);
             return shapeFrom(config.model.id, config.model, config.model.id);
@@ -38,7 +52,16 @@ export function createHookLlm(deps) {
         const ac = new AbortController();
         const t = setTimeout(() => ac.abort(), timeoutMs);
         try {
+            // 🔴 key resolution (2026-07-13 — the session titler widened this face from
+            // "deployments that configured hooks" to EVERY default deployment): per-model key (sealed-box custody /
+            // apiKeyEnv, via the SAME hot-refreshed keyResolver the brain uses) WINS; the MAIN gateway key rides ONLY
+            // to the main gateway's own baseUrl — a roster model pointing at a FOREIGN provider must NEVER receive
+            // the main key (credential exfiltration to whoever operates that URL). Foreign + no per-model key ⇒ the
+            // request goes out UNAUTHENTICATED (the provider 401s = honest failure, nothing leaked).
             const keyResolver = deps.getKeyResolver();
+            // 🔴 custody fail-closed(交叉评审 F1):resolver 抛错(sealed key 中毒/解密失败)≠「没配 per-model
+            // key」——吞成 undefined 会让 same-route 模型静默回落共享路由凭据照发。抛错=本次调用整体 fail,
+            // 不发任何请求(抽取前的内联版就有这个吞错,借抽取一并修死)。
             let perModelKey;
             if (keyResolver) {
                 try {
@@ -48,6 +71,9 @@ 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)})` };
                 }
             }
+            // URL-normalized comparison (lens-A re-review: raw string compare false-negatives on host case /
+            // default-port forms and would strand the MAIN gateway without its own key — an availability bug in
+            // the safe direction, still a bug). new URL lowercases the host and drops a default port.
             const normUrl = (u) => {
                 try {
                     const x = new URL(u);
@@ -61,6 +87,10 @@ export function createHookLlm(deps) {
             let headers;
             let body;
             if (pick.api === "anthropic-messages") {
+                // anthropic 腿的同路纪律 = openai 腿 sameGateway 的镜像:anthropic 路由自己的凭据(authToken 压过
+                // apiKey,brain.ts 同序)只随路由自己的 baseUrl 走;per-model key 恒胜(x-api-key,core brain 的
+                // 同一注入位)。🔴 TRUE fail-closed 同款:foreign anthropic 端点无 per-model key ⇒ 连 prompt 都
+                // 不发(prompt 内嵌用户内容,未认证发射同样把数据外泄给该 URL 的运营方)。
                 const routeBase = anthropicRouteBaseUrl();
                 const sameRoute = routeBase !== undefined && normUrl(pick.baseUrl) === normUrl(routeBase);
                 if (!perModelKey && !sameRoute) {
@@ -69,6 +99,8 @@ export function createHookLlm(deps) {
                 url = `${pick.baseUrl.replace(/\/+$/, "")}/v1/messages`;
                 headers = {
                     "content-type": "application/json",
+                    // anthropic-version 缺省与 core brain 一致;纯 per-model 端点(路由未装但 per-model key 在)
+                    // 也带版本头,取同一缺省。
                     "anthropic-version": config.anthropic?.version ?? "2023-06-01",
                     ...(perModelKey
                         ? { "x-api-key": perModelKey }
@@ -78,18 +110,31 @@ export function createHookLlm(deps) {
                                 ? { "x-api-key": config.anthropic.apiKey }
                                 : {}),
                 };
+                // Messages API 必带 max_tokens:钳 1024 上限(交叉评审 F2)——hook 是廉价判定调用(titler 产出
+                // 一行标题),永远用不到更多;且 [854]③a 后 model.maxTokens 缺省抬到 32000,原样发给小输出上限的
+                // anthropic 形模型会整请求被拒(max_tokens 超模型硬顶=400),标题腿没必要陪这个险。
+                // 缺省 1024 是为 titler 那类"一行标题"调的;调用方可用 `maxOutputTokens` 声明自己需要更多
+                // (见该字段旁注:CC 评估者被要求引用转录,推理档的 thinking 还与输出共用额度)。
+                // 上限仍钳在模型自己的 maxTokens 以内 —— 超模型硬顶会整请求 400,这条原因没变。
                 const want = maxOutputTokens ?? 1024;
                 const maxTokens = Math.min(config.models[pick.catalogRef]?.maxTokens ?? want, want);
+                // `system` 走 Messages API 的**顶层字段**(不是一条 role:"system" 消息 —— anthropic 形不接受那个角色)。
                 body = JSON.stringify({ model: pick.providerModelId, max_tokens: maxTokens, ...(system ? { system } : {}), messages: [{ role: "user", content: prompt }] });
             }
             else {
                 const sameGateway = normUrl(pick.baseUrl) === normUrl(config.gatewayBaseUrl);
                 const hookKey = perModelKey ?? (sameGateway ? config.gatewayApiKey : undefined);
+                // 🔴 TRUE fail-closed (lens-A HIGH): a FOREIGN endpoint with no per-model key must not receive the
+                // REQUEST BODY either — the hook prompt embeds user content (session-titler: the objective), so an
+                // unauthenticated fire still exfiltrates data to whoever operates that URL. Refuse before fetch.
                 if (!sameGateway && !hookKey) {
                     return { ok: false, error: `hook model "${pick.catalogRef}" points at a foreign baseUrl with no per-model key — refusing to send the prompt off-gateway` };
                 }
                 url = `${pick.baseUrl.replace(/\/+$/, "")}/chat/completions`;
                 headers = { "content-type": "application/json", ...(hookKey ? { authorization: `Bearer ${hookKey}` } : {}) };
+                // `system` 在 openai 形是**前置的一条 system 消息**(与 anthropic 的顶层字段等价,两边同一语义)。
+                // openai 形此前**不发** max_tokens(用 provider 缺省)。只有调用方显式声明时才发 ——
+                // 不改 titler 那条腿的既有行为,同时让评估者能要到它需要的额度。
                 body = JSON.stringify({ model: pick.providerModelId, ...(maxOutputTokens !== undefined ? { max_tokens: maxOutputTokens } : {}), messages: [...(system ? [{ role: "system", content: system }] : []), { role: "user", content: prompt }], stream: false });
             }
             const r = await fetchImpl(url, { method: "POST", headers, body, signal: ac.signal });
@@ -109,6 +154,8 @@ export function createHookLlm(deps) {
             return typeof text === "string" ? { ok: true, text } : { ok: false, error: "hook llm returned no content" };
         }
         catch (e) {
+            // 网络层失败原样只有 "TypeError: fetch failed"(不是人话):带上端点与 cause(ECONNREFUSED 等),
+            // 一句话说清打的是哪个 URL、为什么挂——titler 的 llm_failed 记账/warn 原样透出这条。
             const cause = e?.cause;
             return {
                 ok: false,

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

@@ -3,40 +3,87 @@ import type { Hooks } from "@sema-agent/core";
 import type { Logger } from "../observability/logger.js";
 export declare const MAX_HOOK_ENTRIES_PER_EVENT = 32;
 export declare const MAX_HOOK_COMMAND_CHARS = 8192;
+/** 单条 hook 超时上限(秒;条目可自设 timeout,但被此值夹住——一个 86400 的 timeout 会挂死工具门)。 */
 export declare const MAX_HOOK_TIMEOUT_SECONDS = 600;
+/** 一次 hook 事件(一次 pre/post 调用)所有同步条目的墙钟总预算(秒;32 条 × 单条 600s
+ *  最坏可串行卡住工具门 ~320min。到点后不再起后续条目,记账降级)。 */
 export declare const MAX_HOOK_EVENT_TOTAL_SECONDS = 120;
+/** 一次事件的 matcher 组数上限(配置广度的另一维,防组数爆炸)。 */
 export declare const MAX_HOOK_MATCHER_GROUPS = 16;
+/** http 条目的 header 条数 / allowedEnvVars 个数上限(构造放大面)。 */
 export declare const MAX_HOOK_HTTP_HEADERS = 32;
+/** hook 进程 stdout/stderr 各自的采集上限(字节)——防输出洪泛打爆内存/日志。 */
 export declare const MAX_HOOK_OUTPUT_BYTES: number;
 export interface ParseHooksConfigResult {
     config?: HooksConfig;
+    /** 人可读的第一条校验错误(HTTP 层用它 400 fail-loud;resume 防御路径用它 warn)。 */
     error?: string;
 }
+/**
+ * 把 wire 上的 untrusted `settings.hooks` 校验成契约 {@link HooksConfig} + 服务侧上限。
+ * 错误返回 error 字符串而不 throw——submit 路径 400 fail-loud、resume 防御路径 warn-drop,由调用方选。
+ */
 export declare function parseHooksConfig(raw: unknown): ParseHooksConfigResult;
+/** CC matcher 语义:精确名、`a|b` 交替、或 JS 正则(锚定全匹配,防 "Bash" 误配 "BashOutput");
+ *  空/`*`/缺省匹配一切;非法正则 → 该条不匹配(fail-closed 到"不跑",由调用方记账一次)。 */
 export declare function hookMatcherMatches(matcher: string | undefined, value: string): boolean | "invalid";
+/** `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"(调用方分别记账;跳过永不静默)。 */
 export declare function hookIfMatches(cond: string, payload: unknown): true | "not_matched" | "unevaluable";
+/** createTaskHooks 的装配上下文(payload 的 CC-verbatim 字段来源)。 */
 export interface HookRunnerContext {
     logger: Logger;
     sessionId: string;
+    /** hook 命令的工作目录 + payload `cwd` + `CLAUDE_PROJECT_DIR`(host lane 的 session cwd;无则 server cwd)。 */
     cwd: string;
     permissionMode?: string;
+    /** 请求自带的 `settings.env`(单用户闸后)——hook 进程 env 与 http $NAME 插值的用户变量通道。 */
     shellEnv?: Record<string, string>;
+    /** 阶段三b:`prompt` 条目的模型调用载体(部署组装:一次非流式 completion,费用不折 task budget)。
+     *  缺席 ⇒ prompt 条目跳过记账(部署没配模型面就诚实降级,不瞎猜)。fake 可注入 ⇒ hook-runner 保持单测性。 */
     hookLlm?: HookLlmCall;
+    /** 阶段三b:`agent` 条目的子代理载体(部署组装:runTask 读-only 手 + 可重入禁 + 独立小 budget)。 */
     hookAgent?: HookLlmCall;
+    /** 一次 hook 判定**未能完成**时的观测回调(纯 observe;部署把它接到 fleet 流)。
+     *  🔴 存在的理由:方向可以 fail-open,但**不能连「我这轮没看住」都不说** —— 否则模型拿到的放行
+     *  与「已达成」无法区分,而产品刚对它承诺过「没达成不许停」。
+     *  ⚠️ 它**必须**是不改变运行的通道:`additionalContext` 不行(那个会让这一轮不结束)。缺席 ⇒ 只进日志。 */
     onHookNotice?: (n: {
         kind: "hook_decision_unavailable";
         event: string;
         reason: "no_content" | "unparsed" | "skipped";
         detail?: string;
     }) => void;
+    /** Stop × `type:"prompt"` 是否把**会话 transcript** 交给评估者(CC `execPromptHook` 形)。
+     *  缺省(undefined)= **开**。`false` ⇒ 整条路不启用(prompt 条目在 Stop 上被跳过并记账)——
+     *  部署侧的显式逃生口(`SEMA_STOP_PROMPT_TRANSCRIPT=0`)。见 `hooks.stop` 里那段三问。 */
     stopPromptTranscript?: boolean;
+    /** asyncRewake wake 管道(契约:Background + wake the model on exit 2)。部署组装:live 腿=同 session
+     *  的 TaskStream.steer(下个 turn 边界注入);返回 false=没有活流可投(任务已结束/挂起/别副本)——
+     *  调用方记账不重试(挂起腿的 pending-steer park 是后续切片)。缺席 ⇒ asyncRewake 降级纯 async(记账)。 */
     wake?: (text: string) => Promise<boolean>;
 }
+/** 阶段三b 模型调用载体契约(prompt=直连一次 completion;agent=runTask 收敛后的 final text)。
+ *  返回 ok/text 或 ok:false/error——载体自己兜超时(timeoutMs 是硬顶,载体可更严),绝不 throw。 */
 export type HookLlmCall = (opts: {
     prompt: string;
     model?: string;
     timeoutMs: number;
+    /** 本次调用需要的**输出**上限(tokens)。缺席 ⇒ 载体用它自己的缺省(1024,为 titler 那类"一行标题"
+     *  的廉价判定调好的)。
+     *  🔴 **加这个位是因为共用缺省真的咬人了**:CC 的条件评估者被提示词**明确要求**「quote evidence from
+     *  the transcript」,推理档模型的 thinking 还与输出**共用**这份额度 ⇒ 1024 会把判词截断、
+     *  甚至一个字都吐不出来 ⇒ 判词整条被丢弃 ⇒ **fail-open(该拦没拦)**。
+     *  ⇒ 判据:**给一个载体加新消费者时,要重访它为旧工况调好的每一个参数** ——
+     *  那些参数的旁注里通常写着一句"永远用不到更多",而那句话是**对旧工况**说的。 */
     maxOutputTokens?: number;
+    /** 系统提示。CC 的 `execPromptHook` 给条件评估者套一段(见 `cc-stop-prompt.ts` 的逐字移植)——
+     *  anthropic 形走 Messages API 的**顶层 `system` 字段**,openai 形走**前置的一条 system 消息**,
+     *  两边同一语义。缺席 ⇒ 与此前逐位相同(无 system)。 */
     system?: string;
 }) => Promise<{
     ok: true;
@@ -45,10 +92,52 @@ export type HookLlmCall = (opts: {
     ok: false;
     error: string;
 }>;
+/**
+ * 阶段三a:`http` 条目——契约语义 = POST hook 输入 JSON 到 `url`;headers 里的 `$NAME` 仅当 NAME 列在
+ * `allowedEnvVars` 才从 worker 进程 env 插值(配置本身绝不携带密钥值,契约同边界)。
+ *
+ * 结果折算成伪 {@link CommandRunResult},让 9 事件的既有折叠逻辑零改动复用:
+ *  - 2xx + JSON body → 同 exit-0-stdout-JSON(SyncHookOutput 决策面)。⚠️ 这是对 CC 行为的合理近似
+ *    (契约只定"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 ② 信任面)。
+ */
+/**
+ * 阶段三b:跑一条 `prompt`/`agent` 条目(design/HOOKS-PHASE3B-PROMPT-AGENT.md)。两者共此函数——
+ * 差异只在载体(prompt=ctx.hookLlm 直连一次 completion;agent=ctx.hookAgent 读-only 子代理)与默认
+ * 超时。`$ARGUMENTS` 占位符替换为 hook 输入 JSON(CC 语义;与 command stdin 同一份 payload,同
+ * 256K 截断纪律),模型输出折成伪 CommandRunResult{code:0, stdout:text} → 每个事件既有的
+ * `parseHookStdout` 决策面(SyncHookOutput)零改动继承:输出可解析 JSON=决策(allow/deny/ask/
+ * updatedInput/continue:false…),非 JSON=该事件对 plain text 的既有语义(与 command exit-0 同)。
+ * 载体失败/超时 → spawnError/timedOut 同款非阻断。可重入禁是【载体】的责任(部署组装的 runTask
+ * 不装 hooks——结构性,见 main.ts);hook-runner 自身不发模型调用,fake 载体即可单测。
+ */
+/** Stop×prompt 专用的额外输入(见 `cc-stop-prompt.ts` / `branch-transcript.ts`)。 */
 export interface LlmHookExtra {
+    /** CC 逐字的系统提示。 */
     system: string;
+    /** **会话 transcript,放在条件之前** —— CC 的包装句写的是 "transcript **above**",
+     *  所以它必须真的在上文,否则那句话本身就是在骗模型。 */
     transcript: string;
 }
+/**
+ * 把校验过的 {@link HooksConfig} 翻成 core `Hooks` 回调(阶段二:engine-owned 9 事件全点亮)。
+ * 没有可点亮的条目 → undefined(spec 不挂 hooks,deps 路径原样)。
+ */
 export declare function createTaskHooks(config: HooksConfig, ctx: HookRunnerContext): Hooks | undefined;
+/**
+ * 把部署级 hooks 基线(deps.hooks,如 TOOL_TRACE 观测)折进 task 级 hooks——core 是整槽覆盖
+ * (`spec.hooks ?? deps.hooks`),不折叠就静默 shadow 部署观测(runtask gateBaseline 注释点名的坑)。
+ * 语义:部署槽先跑(观测看到原始输入/输出),task 槽后跑;结果合并:
+ *  - preToolUse: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):顺序双跑,无返回可折。
+ * 单在则透传。
+ */
 export declare function composeHooks(deployment: Hooks | undefined, task: Hooks): Hooks;
 //# sourceMappingURL=hook-runner.d.ts.map