@sema-agent/server 1.323.0 → 2.0.1

package/dist/hooks/hook-runner.js

@@ -1,24 +1,89 @@
+/**
+ * hooks hook-runner — hooks 支持的 service 半场,阶段二。
+ *
+ * 契约 = `@sema-agent/registry-core/hooks`(0.1.51,30 事件全集、CC 2.1.198 逐字形状);runner 把
+ * `TaskRequest.settings.hooks` 里的 **command 类型** 条目翻成 core `TaskSpec.hooks`(types §hooks,
+ * 9 个 engine-owned 回调 core 1.254 已收满)的进程内回调。
+ *
+ * 阶段二范围(engine-owned 9 事件全点亮;加事件=纯实现不动契约):
+ *  - 事件:PreToolUse/PostToolUse(阶段一,语义不动)+ UserPromptSubmit/Stop/StopFailure/
+ *    PostToolUseFailure/PostToolBatch/PreCompact/PostCompact(阶段二)。matcher 按契约
+ *    HOOK_EVENT_MATCHER_FIELD:null 事件(UserPromptSubmit/Stop/PostToolBatch)matcher 被忽略、
+ *    全条目都跑;StopFailure 对 error(AssistantTurnError 枚举)、PreCompact/PostCompact 对 trigger、
+ *    PostToolUseFailure 对 tool_name 匹配。core 回调面是 observe-only 的事件(StopFailure/PostCompact)
+ *    的决策类输出记 `hook_result_unsupported`,warn 不吞。
+ *  - shell-owned 事件(其余 21 个)的配置到达引擎=正常(壳自己跑,owner-single):记一条
+ *    `hook_events_shell_owned` debug 可见,不告警;engine-owned 且未点亮的事件(阶段二后=空集,
+ *    机制保留防契约扩容)才记 `hook_events_not_fired` warn,绝不静默。
+ *  - 条目类型:`command`(bash 族)+ `http`(阶段三a,见 {@link runHttpHook}——POST 输入 JSON、
+ *    2xx JSON body 走同一 SyncHookOutput 决策面)。`prompt`/`agent`(需模型调用设计:默认模型/用量
+ *    归属/catalog 门=阶段三b 挂账)与 `shell:"powershell"` 跳过(`hook_entries_skipped` 记账);
+ *    `async` 支持为 fire-and-forget;`asyncRewake` = async + exit 2 时经 ctx.wake 唤醒模型(live
+ *    TaskStream steer 注入;无活流/无管道则记账降级);`if` 条件=CC-exact permission-rule 模式
+ *    (见 {@link hookIfMatches}:不匹配/评不出→跳过该条目记账,对照 CC 2.1.187/198 实测行为核验);
+ *    `statusMessage` 是壳 UI 字段、服务端无面。
+ *
+ * 🔒 安全边界(design/107 class ② 能力授予):hook 命令跑在 **worker host**(server 进程环境),不在
+ * 沙箱——与 CC 语义一致(CC hooks 跑在用户机器上,哪怕工具在远端执行)。因此挂载点(main.ts)用
+ * **单用户闸** `requirePrincipal !== true`,与 MCP 注入/shellEnv/scheduler 同一姿势;多租户 lane
+ * 收到 hooks 配置只警告忽略(`task_hooks_ignored`),绝不执行。
+ *
+ * 🔒 整槽覆盖陷阱(core runtask `spec.hooks ?? deps.hooks`):task 级 hooks 一旦挂上会 shadow 部署级
+ * hooks(TOOL_TRACE 观测就挂在 deps.hooks)。{@link composeHooks} 把部署基线折进 task hooks——部署槽
+ * 先跑(观测在前,看到真实执行),用户槽后跑,结果按槽语义合并。
+ *
+ * CC exit-code 语义(与 CC 对齐):
+ *  - exit 0:stdout 若是 JSON → SyncHookOutput(decision/hookSpecificOutput/continue);非 JSON → 忽略。
+ *  - exit 2:阻断——PreToolUse → deny;UserPromptSubmit → block 提交;Stop → block 停止(继续干活);
+ *    PreCompact → block 本次压缩(stderr 均作为模型/追溯可读原因);PostToolUse/PostToolUseFailure/
+ *    PostToolBatch → 调用已落地无从阻断,stderr 作为 additionalContext 反馈给模型;observe-only 事件
+ *    (StopFailure/PostCompact)无阻断面,按 hook 故障记账。
+ *  - 其他 exit / 超时:非阻断,警告记录(hook 故障绝不误伤任务)。
+ */
 import { spawn } from "node:child_process";
 import { hostShell, resolveHostShell } from "../plugins/host-platform.js";
 import { HooksConfig, DEFAULT_HOOK_TIMEOUT_SECONDS, HOOK_EVENT_OWNER, } from "@sema-agent/registry-core/hooks";
 import { redactSecrets } from "../trace/redact.js";
 import { ccPromptSystemFor, wrapCondition, parseCcVerdict, CC_EVALUATOR_MAX_OUTPUT_TOKENS } from "./cc-stop-prompt.js";
 import { renderBranchTranscript } from "./branch-transcript.js";
+/** 服务侧防线上限(契约本身不设量纲;不设界=单请求可塞任意大配置/任意长命令)。超界=校验错(fail-loud)。 */
+// S1([1870]):hook 的 shell 与 host lane 同源(core getShellConfig,bash 优先)。模块装载即预热
+// 解析(fire-and-forget;未解析先到的 spawn 拿 sh 兜底=修前字节形,解析后恒 bash)。
 void resolveHostShell().catch(() => undefined);
 export const MAX_HOOK_ENTRIES_PER_EVENT = 32;
 export const MAX_HOOK_COMMAND_CHARS = 8_192;
+/** 单条 hook 超时上限(秒;条目可自设 timeout,但被此值夹住——一个 86400 的 timeout 会挂死工具门)。 */
 export const MAX_HOOK_TIMEOUT_SECONDS = 600;
+/** 一次 hook 事件(一次 pre/post 调用)所有同步条目的墙钟总预算(秒;32 条 × 单条 600s
+ *  最坏可串行卡住工具门 ~320min。到点后不再起后续条目,记账降级)。 */
 export const MAX_HOOK_EVENT_TOTAL_SECONDS = 120;
+/** 一次事件的 matcher 组数上限(配置广度的另一维,防组数爆炸)。 */
 export const MAX_HOOK_MATCHER_GROUPS = 16;
+/** http 条目的 header 条数 / allowedEnvVars 个数上限(构造放大面)。 */
 export const MAX_HOOK_HTTP_HEADERS = 32;
+/** hook 进程 stdout/stderr 各自的采集上限(字节)——防输出洪泛打爆内存/日志。 */
 export const MAX_HOOK_OUTPUT_BYTES = 1024 * 1024;
+/** 喂给模型的 deny 原因/additionalContext 的单条长度上限(字符)。 */
 const MAX_HOOK_FEEDBACK_CHARS = 4_096;
+/** PostToolUse payload 里 tool_response 文本投影的上限(字符)——工具结果可能是 MB 级。 */
 const MAX_TOOL_RESPONSE_CHARS = 32_768;
+/** stdin payload 里 tool_input JSON 投影的上限(字符;巨大 tool_input 经 JSON.stringify 造成
+ *  内存/阻塞放大——超限替换为截断标记)。 */
 const MAX_TOOL_INPUT_CHARS = 262_144;
+/**
+ * command hook 不再继承完整 `process.env`——worker 进程环境里有模型/DB/service-auth 令牌,
+ * 全量透传等于把它们交给任务侧 hook 命令。改成基础运行时 env 的 allowlist(PATH/HOME/SHELL/终端/locale)+
+ * CC 约定注入(CLAUDE_PROJECT_DIR)。用户自己要给 hook 的变量走 settings.env(shellEnv,同样单用户闸),
+ * 不靠继承服务进程密钥。
+ */
 const HOOK_ENV_ALLOWLIST = [
     "PATH", "HOME", "SHELL", "USER", "LOGNAME", "TERM", "TZ",
     "LANG", "LC_ALL", "LC_CTYPE", "LC_MESSAGES", "TMPDIR",
 ];
+/** hook 可见的 env = 净化基础 allowlist + CLAUDE_PROJECT_DIR + 请求自带的 `settings.env`(shellEnv,
+ *  同一单用户闸)——上面注释承诺的"用户变量走 settings.env"通道在这里真兑现(阶段三补齐:
+ *  之前 hookEnv 没接 shellEnv,承诺是空头的)。shellEnv 后铺(用户显式给的赢基础值);服务进程密钥
+ *  永远不在这张表里。http 条目的 $NAME 插值也从这张表取(见 {@link runHttpHook})。 */
 function hookEnv(ctx) {
     const env = { CLAUDE_PROJECT_DIR: ctx.cwd };
     for (const k of HOOK_ENV_ALLOWLIST) {
@@ -28,6 +93,9 @@ function hookEnv(ctx) {
     }
     return { ...env, ...ctx.shellEnv };
 }
+/** 阶段二点亮的事件 = engine-owned 9 事件全集。与契约 ENGINE_OWNED_HOOK_EVENTS 今天相等但故意独立
+ *  声明:契约扩容(新增 engine-owned 事件)时 `hook_events_not_fired` 机制自动把缺口暴露出来,而不是
+ *  静默装作点亮。shell-owned 事件不进此表(壳自己跑,owner-single)。 */
 const LIT_EVENTS = [
     "PreToolUse",
     "PostToolUse",
@@ -39,6 +107,10 @@ const LIT_EVENTS = [
     "PreCompact",
     "PostCompact",
 ];
+/** core BrainErrorCode(auth/rate_limit/invalid_request/server/network/http,brain/errors 单一来源)→
+ *  契约 AssistantTurnError(CC SDKAssistantMessageError 枚举)。network/http 在 CC 枚举里没有对应
+ *  类别 → "unknown"(不妄断编造类别;原始人话错误走 error_details)。StopFailure 的 matcher 对映射
+ *  【后】的枚举值匹配(契约 HOOK_EVENT_MATCHER_FIELD.StopFailure = "error" = payload 字段)。 */
 const BRAIN_TO_TURN_ERROR = {
     auth: "authentication_failed",
     rate_limit: "rate_limit",
@@ -49,6 +121,10 @@ const BRAIN_TO_TURN_ERROR = {
 function toAssistantTurnError(errorKind) {
     return (errorKind !== undefined ? BRAIN_TO_TURN_ERROR[errorKind] : undefined) ?? "unknown";
 }
+/**
+ * 把 wire 上的 untrusted `settings.hooks` 校验成契约 {@link HooksConfig} + 服务侧上限。
+ * 错误返回 error 字符串而不 throw——submit 路径 400 fail-loud、resume 防御路径 warn-drop,由调用方选。
+ */
 export function parseHooksConfig(raw) {
     const parsed = HooksConfig.safeParse(raw);
     if (!parsed.success) {
@@ -60,6 +136,7 @@ export function parseHooksConfig(raw) {
         if (!groups)
             continue;
         if (groups.length > MAX_HOOK_MATCHER_GROUPS) {
+            // 广度维:组数不设界=条目 cap 可被"多组少条"绕开一半(每组重复扫 matcher)。
             return { error: `settings.hooks.${event}: ${groups.length} matcher groups exceeds cap ${MAX_HOOK_MATCHER_GROUPS}` };
         }
         let entries = 0;
@@ -70,6 +147,7 @@ export function parseHooksConfig(raw) {
                     return { error: `settings.hooks.${event}: command exceeds ${MAX_HOOK_COMMAND_CHARS} chars` };
                 }
                 if (entry.type === "http") {
+                    // headers/allowedEnvVars 不设界=插值与 fetch header 构造前的内存放大面。
                     if (entry.url.length > MAX_HOOK_COMMAND_CHARS) {
                         return { error: `settings.hooks.${event}: url exceeds ${MAX_HOOK_COMMAND_CHARS} chars` };
                     }
@@ -93,6 +171,8 @@ export function parseHooksConfig(raw) {
     }
     return { config };
 }
+/** CC matcher 语义:精确名、`a|b` 交替、或 JS 正则(锚定全匹配,防 "Bash" 误配 "BashOutput");
+ *  空/`*`/缺省匹配一切;非法正则 → 该条不匹配(fail-closed 到"不跑",由调用方记账一次)。 */
 export function hookMatcherMatches(matcher, value) {
     if (matcher === undefined || matcher === "" || matcher === "*")
         return true;
@@ -105,13 +185,21 @@ export function hookMatcherMatches(matcher, value) {
         return "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 function hookIfMatches(cond, payload) {
+    // glob→`.*` 拼正则有回溯放大面(长模式×多星号×长主字符串)——模式长度与星号数设上限,
+    // 超限=unevaluable(跳过记账;正常 permission-rule 远在限内)。
     if (cond.length > 500 || (cond.match(/\*/g)?.length ?? 0) > 16)
         return "unevaluable";
     const p = (payload ?? {});
     const toolName = typeof p.tool_name === "string" ? p.tool_name : undefined;
     if (!toolName)
-        return "unevaluable";
+        return "unevaluable"; // CC:非工具事件上 if 无法求值 → 跳过(非静默,调用方记账)
     const m = /^([^(]+?)(?:\((.*)\))?$/s.exec(cond.trim());
     if (!m)
         return "unevaluable";
@@ -122,12 +210,13 @@ export function hookIfMatches(cond, payload) {
         return "not_matched";
     const spec = m[2];
     if (spec === undefined || spec === "*" || spec === "")
-        return true;
+        return true; // 纯名 / Tool(*) = 名中即中
     const input = p.tool_input;
     const primary = input && (typeof input.command === "string" ? input.command : typeof input.file_path === "string" ? input.file_path : typeof input.path === "string" ? input.path : undefined);
     if (primary === undefined)
-        return "unevaluable";
+        return "unevaluable"; // 该工具无主字符串可配(CC 同样评不出来)
     try {
+        // glob(`*`)→ 锚定正则;其余字符按字面转义(permission specifier 不是裸正则)。
         const re = new RegExp(`^${spec.split("*").map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join(".*")}$`);
         return re.test(primary) ? true : "not_matched";
     }
@@ -135,21 +224,27 @@ export function hookIfMatches(cond, payload) {
         return "unevaluable";
     }
 }
+/** 阶段三b:LLM 条目(prompt+agent 合计)每事件上限——config 滥写不至于把一个工具门拖进 N 次模型调用。 */
 const MAX_LLM_ENTRIES_PER_EVENT = 4;
+/** prompt 条目默认超时(一次判定调用;entry.timeout 覆盖,MAX_HOOK_TIMEOUT_SECONDS 仍是硬顶)。 */
 const DEFAULT_PROMPT_HOOK_TIMEOUT_SECONDS = 30;
+/** agent 条目默认超时(读-only 子代理跑到收敛)。 */
 const DEFAULT_AGENT_HOOK_TIMEOUT_SECONDS = 120;
 function clip(s, n) {
     return s.length > n ? `${s.slice(0, n)}…(${s.length})` : s;
 }
+/** 跑一条 command hook:sh -c,stdin=payload JSON(CC-verbatim),超时 SIGKILL,输出各限 1MiB。 */
 function runCommandHook(entry, payload, ctx) {
     return new Promise((resolve) => {
         const timeoutMs = Math.min(entry.timeout ?? DEFAULT_HOOK_TIMEOUT_SECONDS, MAX_HOOK_TIMEOUT_SECONDS) * 1000;
         let child;
         try {
-            const sh = hostShell();
+            // detached=true 建独立进程组:超时击杀用负 pid 连孙进程一起收(否则 SIGKILL 只杀 sh,一个
+            // `sleep 30` 孙进程抓着继承的 stdout 管道,`close` 事件要等它退出——单测实抓的挂死)。
+            const sh = hostShell(); // S1:不再硬编码 /bin/sh(Debian=dash 静默错字节),host 同源 bash
             child = spawn(sh.shell, [...sh.args, entry.command], {
                 cwd: ctx.cwd,
-                env: hookEnv(ctx),
+                env: hookEnv(ctx), // allowlist+shellEnv,不透传服务进程密钥
                 stdio: ["pipe", "pipe", "pipe"],
                 detached: true,
             });
@@ -173,14 +268,14 @@ function runCommandHook(entry, payload, ctx) {
             timedOut = true;
             try {
                 if (child.pid)
-                    process.kill(-child.pid, "SIGKILL");
+                    process.kill(-child.pid, "SIGKILL"); // 整组击杀(见 spawn 注释)
                 else
                     child.kill("SIGKILL");
             }
             catch {
                 child.kill("SIGKILL");
             }
-            settle(null);
+            settle(null); // 超时=非阻断故障,立即返回,不等孙进程放开管道
         }, timeoutMs);
         child.stdout?.on("data", (d) => {
             if (stdout.length < MAX_HOOK_OUTPUT_BYTES)
@@ -198,20 +293,29 @@ function runCommandHook(entry, payload, ctx) {
             }
         });
         child.on("close", (code) => settle(code));
+        // stdin=hook 输入 JSON(CC 语义)。EPIPE(hook 不读 stdin 就退出)吞掉——不是错误。
+        // 巨大 tool_input 经 boundedToolInputPayload 截断防内存放大。
         child.stdin?.on("error", () => { });
         child.stdin?.end(`${JSON.stringify(boundedToolInputPayload(payload))}\n`);
     });
 }
+/** async 条目:fire-and-forget(不等待、不消费输出、不参与决策)。仍加 detached 进程组 +
+ *  timeout 整组击杀——否则一个每次工具调用都 spawn 的 async hook 会在长任务里无限堆积不退出的后台进程。
+ *
+ *  asyncRewake(契约:Background + wake the model on exit 2,implies async):与纯 async 的唯一差别=
+ *  捕获 stderr(有界)+ close 时 code===2 → ctx.wake(stderr)——CC 的 exit-2-语义在同步条目是"stderr 是给
+ *  模型的阻断理由",搬到后台即"stderr 是给模型的唤醒消息"。投递走部署组装的 wake 管道(live TaskStream
+ *  steer,下个 turn 边界注入);没有活流(任务已结束/挂起)或 wake 缺席 ⇒ warn 记账不重试。 */
 function fireAsyncCommandHook(entry, payload, ctx, event) {
     try {
         const rewake = entry.asyncRewake === true;
         const timeoutMs = Math.min(entry.timeout ?? DEFAULT_HOOK_TIMEOUT_SECONDS, MAX_HOOK_TIMEOUT_SECONDS) * 1000;
-        const sh = hostShell();
+        const sh = hostShell(); // S1:同上,async hook 腿同源
         const child = spawn(sh.shell, [...sh.args, entry.command], {
             cwd: ctx.cwd,
-            env: hookEnv(ctx),
+            env: hookEnv(ctx), // allowlist+shellEnv,不透传服务进程密钥
             stdio: ["pipe", "ignore", rewake ? "pipe" : "ignore"],
-            detached: true,
+            detached: true, // 进程组隔离,超时可整组收
         });
         const timer = setTimeout(() => {
             try {
@@ -231,19 +335,22 @@ function fireAsyncCommandHook(entry, payload, ctx, event) {
                 if (stderr.length < MAX_HOOK_OUTPUT_BYTES)
                     stderr += d.toString("utf8").slice(0, MAX_HOOK_OUTPUT_BYTES - stderr.length);
             });
+            // pipe 的 socket 句柄会 hold 事件循环——unref 让慢 hook 不拖进程关停(数据事件照收,
+            // 超时路径的进程组 SIGKILL 会触发 close 收尾)。
             child.stderr?.unref?.();
         }
         child.on("error", () => clearTimeout(timer));
         child.on("close", (code) => {
             clearTimeout(timer);
             if (!rewake || code !== 2)
-                return;
+                return; // 契约:只有 exit 2 唤醒
             const text = stderr.trim();
             if (!ctx.wake) {
                 ctx.logger.warn("hook_async_rewake_dropped", { event, reason: "no_wake_pipeline" });
                 return;
             }
             if (!text) {
+                // exit 2 但 stderr 空:没内容可注入——记账(与同步条目 exit-2-无-stderr 的空理由同类,不造消息)。
                 ctx.logger.warn("hook_async_rewake_dropped", { event, reason: "empty_stderr" });
                 return;
             }
@@ -259,6 +366,7 @@ function fireAsyncCommandHook(entry, payload, ctx, event) {
         child.unref();
     }
     catch {
+        /* fire-and-forget:spawn 失败不影响任务 */
     }
 }
 async function runLlmHook(entry, payload, ctx, extra) {
@@ -269,7 +377,12 @@ async function runLlmHook(entry, payload, ctx, extra) {
     const timeoutMs = Math.min(entry.timeout ?? defSec, MAX_HOOK_TIMEOUT_SECONDS) * 1000;
     const args = clip(JSON.stringify(boundedToolInputPayload(payload)), MAX_TOOL_INPUT_CHARS);
     const substituted = entry.prompt.split("$ARGUMENTS").join(args);
+    // Stop×prompt(CC 形):会话 transcript 在前、被包装过的条件在后 —— 顺序是承重的,
+    // 因为 CC 的包装句逐字写着 "Based on the conversation transcript **above**"。
+    // CC 形:transcript 在前,条件被 CC 的包装句包起来("Based on the conversation transcript **above**…")。
+    // 顺序是承重的 —— 包装句逐字预设会话在上文,放反了那句话本身就是在骗模型。
     const prompt = extra ? `${extra.transcript}\n\n---\n\n${wrapCondition("Stop", substituted)}` : substituted;
+    // 载体外再包一层硬顶:契约说载体自己兜超时,但一个部署组装 bug 不该能挂死工具门(纵深)。
     const hardTop = new Promise((r) => setTimeout(() => r({ ok: false, error: "__hook_llm_hard_timeout__" }), timeoutMs + 5_000).unref?.());
     const invoke = () => Promise.race([
         call({
@@ -281,9 +394,14 @@ async function runLlmHook(entry, payload, ctx, extra) {
         hardTop,
     ]).catch((e) => ({ ok: false, error: String(e) }));
     let res = await invoke();
+    // 🔴 **"一个字都没吐出来"重试一次**(仅 CC 评估者路)。这个失败形的后果是**判词被丢弃 ⇒ fail-open**
+    // (该拦没拦),而它是**瞬态**的(推理档模型偶尔把额度用在 thinking 上)。
+    // ⚠️ 只重试**无内容**,不重试"有内容但读不懂" —— 后者重试一次多半还是读不懂,而且那一格按设计就该放行。
     if (extra && !res.ok && res.error.includes("returned no content")) {
         ctx.logger.warn("hook_llm_no_content_retry", { event: "Stop" });
         res = await invoke();
+        // 重试之后**仍然**没有内容 ⇒ 这一轮的守卫确实没能评估。发观测帧(纯 observe,不改变运行)——
+        // 方向仍是 fail-open,但用户/壳侧要能知道「这轮没看住」,否则那个放行与「已达成」无法区分。
         if (!res.ok && res.error.includes("returned no content")) {
             ctx.onHookNotice?.({ kind: "hook_decision_unavailable", event: "Stop", reason: "no_content", detail: "carrier returned no content (after one retry)" });
         }
@@ -298,9 +416,14 @@ async function runLlmHook(entry, payload, ctx, extra) {
 async function runHttpHook(entry, payload, ctx) {
     const timeoutMs = Math.min(entry.timeout ?? DEFAULT_HOOK_TIMEOUT_SECONDS, MAX_HOOK_TIMEOUT_SECONDS) * 1000;
     const allowed = new Set(entry.allowedEnvVars ?? []);
+    // 插值源=hookEnv(净化 allowlist + shellEnv),【不是】裸 process.env——否则任务
+    // 配置可用 allowedEnvVars 点名服务密钥(MODEL_GATEWAY_KEY 等)插进 header 发往任意 URL。用户要给
+    // webhook 的 token 走同请求 settings.env(shellEnv),与 command hook 的 env 姿势同一单源。
     const envSource = hookEnv(ctx);
     const headers = { "content-type": "application/json" };
     for (const [k, v] of Object.entries(entry.headers ?? {})) {
+        // $NAME 插值:只认 allowedEnvVars 列出【且】在 hookEnv 表里的名字;其余原样保留(不是插值点,
+        // fail-closed 到字面)。
         headers[k] = v.replace(/\$([A-Za-z_][A-Za-z0-9_]*)/g, (whole, name) => {
             if (!allowed.has(name))
                 return whole;
@@ -318,6 +441,8 @@ async function runHttpHook(entry, payload, ctx) {
             signal: ac.signal,
             redirect: "error",
         });
+        // body 有界读取(不 res.text() 一口吞——恶意/故障端点可回无限流)。按【字节】
+        // 计预算并先截 Uint8Array 再 decode(字符计数挡不住单个巨 chunk 的先行分配),收尾 flush decoder。
         let body = "";
         const reader = res.body?.getReader();
         if (reader) {
@@ -338,6 +463,9 @@ async function runHttpHook(entry, payload, ctx) {
             await reader.cancel().catch(() => undefined);
         }
         if (res.ok) {
+            // CC-exact 定谳:http hook 是硬 JSON 契约(≠ command 的 plainText 优雅降级)。
+            //  - 空 body → 特判 `{}` 成功(无决策,干净放行);
+            //  - 非空且非 JSON → non-blocking error 记账(不吞成静默通过),stdout 置空让折叠无决策。
             const trimmed = body.trim();
             if (trimmed === "")
                 return { code: 0, stdout: "{}", stderr: "", timedOut: false };
@@ -347,6 +475,7 @@ async function runHttpHook(entry, payload, ctx) {
             }
             return { code: 0, stdout: body, stderr: "", timedOut: false };
         }
+        // 非 2xx 不 parse body,`HTTP ${status} from ${url}` non-blocking(exit-2 阻断语义不撞)。
         return { code: res.status, stdout: "", stderr: body, timedOut: false };
     }
     catch (e) {
@@ -358,6 +487,9 @@ async function runHttpHook(entry, payload, ctx) {
         clearTimeout(timer);
     }
 }
+/** 输入截断的单值形式:一个 tool_input 值若 stringify 超上限/不可序列化,换成截断/占位标记。
+ *  返回原引用=没动(调用方以此保住常态零拷贝)。PostToolBatch 的 tool_calls[].tool_input 逐条走这里
+ *  (顶层 {@link boundedToolInputPayload} 只看 payload.tool_input,批量形状会绕过它)。 */
 function boundedInputValue(v) {
     let s;
     try {
@@ -370,6 +502,8 @@ function boundedInputValue(v) {
         return v;
     return { __truncated__: true, chars: s.length };
 }
+/** stdin payload 若 stringify 超上限,把 tool_input 替换成截断标记(防内存/阻塞放大)。
+ *  只在真的超限时重建对象——常态零拷贝。 */
 function boundedToolInputPayload(payload) {
     if (!payload || typeof payload !== "object")
         return payload;
@@ -379,6 +513,7 @@ function boundedToolInputPayload(payload) {
     const bounded = boundedInputValue(p.tool_input);
     return bounded === p.tool_input ? payload : { ...p, tool_input: bounded };
 }
+/** stdout 的 SyncHookOutput 宽松读取(exit 0 且可解析才有意义;形状错就当没有——CC 同姿势)。 */
 function parseHookStdout(stdout) {
     const t = stdout.trim();
     if (!t.startsWith("{"))
@@ -391,9 +526,18 @@ function parseHookStdout(stdout) {
         return undefined;
     }
 }
-async function runMatchingEntries(event, groups, matchValue, payload, ctx, onceFired, deadlineAt, keyBase, llmExtra) {
+/** 一次事件里跑一组匹配条目的公共骨架:once 去重、if 忽略记账、类型/shell 跳过记账、async 旁路。
+ *  返回每条【同步 command 条目】的运行结果 + 该条目引用(供事件专属的语义映射)。 */
+async function runMatchingEntries(event, groups, matchValue, payload, ctx, onceFired, 
+/** 深度维:本次事件的墙钟截止(epoch ms)——32 条 × 单条 600s 最坏串行卡工具门 ~320min;
+ *  到点后不再起【同步】条目(async 旁路不占墙钟照常),记账降级。 */
+deadlineAt, 
+/** once 去重键的组维前缀——PreToolUse 逐组合成单组数组调用时必须传真实组号,否则跨组键碰撞。 */
+keyBase, 
+/** Stop×prompt 的额外输入(CC 系统提示 + 会话 transcript)。缺席 ⇒ prompt 条目按此前逐位不变。 */
+llmExtra) {
     const results = [];
-    let llmEntries = 0;
+    let llmEntries = 0; // 阶段三b:prompt+agent 合计每事件 cap(config 滥写不至于一个门 N 次模型调用)
     let gi = -1;
     for (const group of groups) {
         gi++;
@@ -411,10 +555,12 @@ async function runMatchingEntries(event, groups, matchValue, payload, ctx, onceF
             if (entry.once && onceFired.has(onceKey))
                 continue;
             if (entry.type !== "command" && entry.type !== "http" && entry.type !== "prompt" && entry.type !== "agent") {
+                // registry-core 未来新增条目类型的前向降级:跳过记账可见,绝不静默。
                 ctx.logger.warn("hook_entries_skipped", { event, type: entry.type, reason: "type_not_supported" });
                 continue;
             }
             if (entry.type === "prompt" || entry.type === "agent") {
+                // 阶段三b:载体缺席(部署没组装模型面)/每事件 LLM cap——都跳过记账可见,非阻断。
                 const carrier = entry.type === "prompt" ? ctx.hookLlm : ctx.hookAgent;
                 if (!carrier) {
                     ctx.logger.warn("hook_entries_skipped", { event, type: entry.type, reason: "llm_carrier_unavailable" });
@@ -430,6 +576,8 @@ async function runMatchingEntries(event, groups, matchValue, payload, ctx, onceF
                 continue;
             }
             if (entry.if !== undefined) {
+                // CC-exact(对照 CC 2.1.187/198 实测行为核验,两版一致):if=permission-rule 模式,按当前工具求值;不匹配/评不出
+                // → 跳过【该条目】并记日志(CC 行为;取代早期"语义未定忽略照跑"的保守占位)。
                 const iv = hookIfMatches(entry.if, payload);
                 if (iv !== true) {
                     ctx.logger.warn("hook_entries_skipped", { event, type: entry.type, reason: iv === "unevaluable" ? "if_unevaluable" : "if_not_matched", if: clip(entry.if, 200) });
@@ -437,15 +585,20 @@ async function runMatchingEntries(event, groups, matchValue, payload, ctx, onceF
                 }
             }
             if (entry.type === "command" && (entry.async || entry.asyncRewake)) {
+                // asyncRewake:wake 管道就位后不再降级——exit 2 唤醒在 fireAsyncCommandHook 内兑现(无管道时它自记账)。
                 if (entry.once)
                     onceFired.add(onceKey);
                 fireAsyncCommandHook(entry, payload, ctx, event);
                 continue;
             }
             if (Date.now() > deadlineAt) {
+                // 事件墙钟预算耗尽——剩余同步条目不再起,警告记账(与超时同姿势:非阻断降级)。
                 ctx.logger.warn("hook_event_deadline_exceeded", { event, budgetSec: MAX_HOOK_EVENT_TOTAL_SECONDS });
                 return results;
             }
+            // once 标记必须在 deadline 检查【后】——预算耗尽被跳过的 once 条目没真跑过,
+            // 标了=下次事件永久哑火(可能是安全阻断钩子)。标在 spawn 尝试前:spawn 失败也算消耗
+            // (once=一次尝试;失败已 warn 记账,重试语义交给用户重发配置)。
             if (entry.once)
                 onceFired.add(onceKey);
             if (entry.type === "prompt" || entry.type === "agent")
@@ -459,28 +612,47 @@ async function runMatchingEntries(event, groups, matchValue, payload, ctx, onceF
             }
             if (run.timedOut) {
                 ctx.logger.warn("hook_command_timeout", { event, timeoutSec: Math.min(entry.timeout ?? DEFAULT_HOOK_TIMEOUT_SECONDS, MAX_HOOK_TIMEOUT_SECONDS) });
-                continue;
+                continue; // CC:超时=非阻断故障
             }
             results.push({ entry, run });
         }
     }
     return results;
 }
+/** payload 公共字段(CC BaseHookInput;transcript_path 服务端无壳 jsonl → 空串,契约只定字段名)。 */
 function basePayload(ctx) {
     return {
         session_id: ctx.sessionId,
+        // 🔴 **恒空串,而且它有真实后果**(cli 黑板 [1730] 的 live 取证):CC 用这个键让 **command 形**钩子
+        // (一个能读磁盘的脚本)自己去读会话 JSONL。本服务是**无状态副本、hook 跑在服务端**,这里
+        // **没有那样一个本地文件** ⇒ 给不出真路径。
+        // 后果不是"少个字段":用 `type:"prompt"` 写「基于会话状态判断」的钩子,其载体(server 自己发起的
+        // 模型调用)对本会话**完全是瞎的** —— cli 真跑实录:模型回「I don't have direct access to your
+        // file system…」这类散文 ⇒ `parseHookStdout` 拿不到 decision ⇒ **一次都不拦**。整类 prompt 条件钩子
+        // 在这个输入面下**结构上不可能工作**。
+        // ⚠️ 正确的修**不是**把路径填上(prompt 载体要的是**内容**不是路径),而是给载体喂会话内容;
+        // 那是行为面新增(送多少 / 脱敏口径 / token 记账 / 旋钮 / 喂不到时诚实降级),按本仓规矩先答三问,
+        // 不在这里顺手改。**键本身保留**是为了 payload 形状与 CC 对位(CC 恒发这个键)——
+        // 值为空是一处**已登记的**偏离,不是遗漏。见 test/hook-transcript-path-gap.test.ts。
         transcript_path: "",
         cwd: ctx.cwd,
         ...(ctx.permissionMode ? { permission_mode: ctx.permissionMode } : {}),
     };
 }
+/** matcher=null 事件(契约 HOOK_EVENT_MATCHER_FIELD 为 null:UserPromptSubmit/Stop/PostToolBatch)的
+ *  契约语义 = matcher 被忽略、每个条目都跑——把组上的 matcher 抹掉再进公共骨架(否则拿空串当
+ *  matchValue 会让带 matcher 的条目 fail-closed 漏跑,违背"忽略"语义)。 */
 function ignoreMatchers(groups) {
     return groups.map((g) => (g.matcher === undefined ? g : { ...g, matcher: undefined }));
 }
+/** observe-only 事件(StopFailure/PostCompact——core 回调面返回 void,契约也没定这两个事件的输出面)
+ *  的公共收尾:命令照常跑(通知型价值在副作用),非零 exit 记账;stdout 里的决策类输出无处落 →
+ *  `hook_result_unsupported` warn 不吞(别让用户以为 block/decision 生效了)。 */
 async function runObserveOnlyEvent(event, groups, matchValue, payload, ctx, onceFired) {
     const singles = await runMatchingEntries(event, groups, matchValue, payload, ctx, onceFired, Date.now() + MAX_HOOK_EVENT_TOTAL_SECONDS * 1000);
     for (const { run } of singles) {
         if (run.code !== 0) {
+            // 含 exit 2:这两个事件没有 CC 阻断面,非零一律按 hook 故障记账(非阻断原则)。
             ctx.logger.warn("hook_command_failed", { event, code: run.code, stderr: clip(run.stderr, 300) });
             continue;
         }
@@ -494,12 +666,19 @@ async function runObserveOnlyEvent(event, groups, matchValue, payload, ctx, once
         }
     }
 }
+/**
+ * 把校验过的 {@link HooksConfig} 翻成 core `Hooks` 回调(阶段二:engine-owned 9 事件全点亮)。
+ * 没有可点亮的条目 → undefined(spec 不挂 hooks,deps 路径原样)。
+ */
 export function createTaskHooks(config, ctx) {
     const configured = Object.keys(config).filter((e) => (config[e]?.length ?? 0) > 0);
+    // engine-owned 且本 runner 未点亮的事件(阶段二后=空集,契约扩容时自动复活)才是缺口 → warn。
     const dark = configured.filter((e) => HOOK_EVENT_OWNER[e] === "engine" && !LIT_EVENTS.includes(e));
     if (dark.length > 0) {
         ctx.logger.warn("hook_events_not_fired", { events: dark, phase: 2 });
     }
+    // shell-owned 事件的配置到达引擎=正常(owner-single:壳自己跑,引擎绝不 double-fire)——
+    // debug 可见记账,不告警(warn 会把合法配置读成缺口)。
     const shellOwned = configured.filter((e) => HOOK_EVENT_OWNER[e] === "shell");
     if (shellOwned.length > 0) {
         ctx.logger.debug("hook_events_shell_owned", { events: shellOwned });
@@ -528,7 +707,9 @@ export function createTaskHooks(config, ctx) {
             let rewritten = false;
             let asked;
             const contexts = [];
-            const deadlineAt = Date.now() + MAX_HOOK_EVENT_TOTAL_SECONDS * 1000;
+            const deadlineAt = Date.now() + MAX_HOOK_EVENT_TOTAL_SECONDS * 1000; // 跨全部组的事件级预算
+            // 逐条串行(deny 立即短路;updatedInput 串进后续条目 payload——确定性优先,CC 的并行聚合语义
+            // 在 deny/ask/allow 折叠上与此等价)。
             let gi = -1;
             for (const group of pre) {
                 gi++;
@@ -549,12 +730,13 @@ export function createTaskHooks(config, ctx) {
                 const singles = await runMatchingEntries("PreToolUse", [{ ...group, matcher: undefined }], toolName, payload, ctx, onceFired, deadlineAt, `PreToolUse:${gi}`);
                 for (const { run } of singles) {
                     if (run.code === 2) {
+                        // CC:exit 2 = 阻断,stderr 喂给模型
                         const reason = clip(run.stderr.trim(), MAX_HOOK_FEEDBACK_CHARS) || "blocked by a PreToolUse hook";
                         return { action: "deny", message: reason, ...(contexts.length ? { additionalContext: contexts.join("\n") } : {}) };
                     }
                     if (run.code !== 0) {
                         ctx.logger.warn("hook_command_failed", { event: "PreToolUse", code: run.code, stderr: clip(run.stderr, 300) });
-                        continue;
+                        continue; // 非阻断
                     }
                     const out = parseHookStdout(run.stdout);
                     if (!out)
@@ -563,6 +745,7 @@ export function createTaskHooks(config, ctx) {
                         ctx.logger.warn("hook_system_message", { event: "PreToolUse", message: clip(out.systemMessage, 500) });
                     if (out.continue === false) {
                         const reason = clip(typeof out.stopReason === "string" ? out.stopReason : "hook requested stop", MAX_HOOK_FEEDBACK_CHARS);
+                        // core 的 preToolUse seam 无"终止整个 run"能力(阶段一诚实近似:deny 本次调用)。
                         return { action: "deny", message: reason, ...(contexts.length ? { additionalContext: contexts.join("\n") } : {}) };
                     }
                     if (out.decision === "block") {
@@ -592,6 +775,9 @@ export function createTaskHooks(config, ctx) {
                 }
             }
             if (asked !== undefined) {
+                // ask 不短路(后续条目可能 deny——deny > ask 已由上面的立即返回保证),折叠成最终 ask。
+                // ask 也携带改写(PermissionResult 的 ask 变体同样接受 updatedInput)——否则
+                // "改写 + 请示"组合在 approve 后执行的是【原始】args,钩子的 redact/clamp 被静默丢弃。
                 return {
                     action: "ask",
                     message: asked,
@@ -606,7 +792,7 @@ export function createTaskHooks(config, ctx) {
                     ...(contexts.length ? { additionalContext: contexts.join("\n") } : {}),
                 };
             }
-            return undefined;
+            return undefined; // 无意见(≠ allow 短路;core 门照常裁决)
         };
         hooks.preToolUse = preToolUseHook;
     }
@@ -621,12 +807,14 @@ export function createTaskHooks(config, ctx) {
                 hook_event_name: "PostToolUse",
                 tool_name: toolName,
                 tool_input: input,
+                // 有界文本投影(契约字段是 unknown;整个 details 图可能 MB 级且含不可序列化句柄)。
                 tool_response: { isError: output.isError, text: clip(responseText, MAX_TOOL_RESPONSE_CHARS) },
                 tool_use_id: tctx.toolCallId,
             };
             const singles = await runMatchingEntries("PostToolUse", post, toolName, payload, ctx, onceFired, Date.now() + MAX_HOOK_EVENT_TOTAL_SECONDS * 1000);
             for (const { run } of singles) {
                 if (run.code === 2) {
+                    // CC:PostToolUse exit 2 = stderr 作为反馈喂给模型(工具已执行,无从阻断)
                     const fb = clip(run.stderr.trim(), MAX_HOOK_FEEDBACK_CHARS);
                     if (fb)
                         contexts.push(fb);
@@ -642,6 +830,7 @@ export function createTaskHooks(config, ctx) {
                 if (typeof out.systemMessage === "string")
                     ctx.logger.warn("hook_system_message", { event: "PostToolUse", message: clip(out.systemMessage, 500) });
                 if (out.continue === false) {
+                    // core postToolUse seam 无 run 终止能力;记账可见(阶段一缺口),不吞。
                     ctx.logger.warn("hook_continue_false_unsupported", { event: "PostToolUse" });
                 }
                 if (out.decision === "block" && typeof out.reason === "string")
@@ -652,6 +841,8 @@ export function createTaskHooks(config, ctx) {
                     if (typeof h.additionalContext === "string")
                         contexts.push(clip(h.additionalContext, MAX_HOOK_FEEDBACK_CHARS));
                     if (h.updatedMCPToolOutput !== undefined) {
+                        // CC 把它限定在 MCP 工具的输出重写;core PostToolUseResult.updatedOutput 期望 content 数组,
+                        // 语义不同型 → 阶段一不映射,记账可见。
                         ctx.logger.warn("hook_updated_mcp_output_unsupported", { event: "PostToolUse" });
                     }
                 }
@@ -661,6 +852,8 @@ export function createTaskHooks(config, ctx) {
         hooks.postToolUse = postToolUseHook;
     }
     if (postFailure) {
+        // CC 语义类比 PostToolUse:调用已失败无从阻断——exit 2 的 stderr / decision:block 的 reason 都折成
+        // additionalContext 反馈给模型(core 回调面就是 additionalContext-only,CC-exact)。
         const postToolUseFailureHook = async (toolName, input, f, tctx) => {
             const contexts = [];
             const payload = {
@@ -669,7 +862,9 @@ export function createTaskHooks(config, ctx) {
                 tool_name: toolName,
                 tool_input: input,
                 tool_use_id: tctx.toolCallId,
+                // 契约 error=模型面错误文本;有界截断(失败结果可能带 MB 级 tool 输出,同 tool_response 姿势)。
                 error: clip(f.error, MAX_TOOL_RESPONSE_CHARS),
+                // core isInterrupt 是宽任意-abort 语义(⊇ CC is_interrupt),原样透传——契约字段名 CC-verbatim。
                 is_interrupt: f.isInterrupt,
             };
             const singles = await runMatchingEntries("PostToolUseFailure", postFailure, toolName, payload, ctx, onceFired, Date.now() + MAX_HOOK_EVENT_TOTAL_SECONDS * 1000);
@@ -705,6 +900,9 @@ export function createTaskHooks(config, ctx) {
         hooks.postToolUseFailure = postToolUseFailureHook;
     }
     if (postBatch) {
+        // matcher=null 事件:契约语义=matcher 被忽略、全条目跑。core 回调面支持 additionalContext(一次性
+        // 注入在 turn 边界)→ exit 2 stderr / decision:block reason 都折进去;契约没定 PostToolBatch 的
+        // hookSpecificOutput 变体 → 出现即记账不吞。
         const postToolBatchHook = async (calls) => {
             const contexts = [];
             const payload = {
@@ -712,8 +910,10 @@ export function createTaskHooks(config, ctx) {
                 hook_event_name: "PostToolBatch",
                 tool_calls: calls.map((c) => ({
                     tool_name: c.toolName,
+                    // 逐条截断(顶层 boundedToolInputPayload 只看 payload.tool_input,批量形状会绕过它)。
                     tool_input: boundedInputValue(c.input),
                     tool_use_id: c.toolCallId,
+                    // core 的 response 已是有界文本 digest;投影成与 PostToolUse tool_response 同形({isError,text})。
                     tool_response: { isError: c.isError, ...(c.response !== undefined ? { text: clip(c.response, MAX_TOOL_RESPONSE_CHARS) } : {}) },
                 })),
             };
@@ -746,8 +946,12 @@ export function createTaskHooks(config, ctx) {
         hooks.postToolBatch = postToolBatchHook;
     }
     if (promptSubmit) {
+        // matcher=null 事件(全条目跑)。CC:exit 2 = 阻断本次提交(stderr=模型可读理由;core 语义=task 以
+        // 此理由 fail);decision:"block"+reason 同;hookSpecificOutput.additionalContext 注入在 prompt 前。
         const userPromptSubmitHook = async (prompt) => {
             const contexts = [];
+            // prompt 是用户任意长输入(粘贴大文件),不设界=绕过 stdin 放大防线——与
+            // tool_input 同一上限截断。
             const payload = { ...basePayload(ctx), hook_event_name: "UserPromptSubmit", prompt: clip(prompt, MAX_TOOL_INPUT_CHARS) };
             const singles = await runMatchingEntries("UserPromptSubmit", ignoreMatchers(promptSubmit), "", payload, ctx, onceFired, Date.now() + MAX_HOOK_EVENT_TOTAL_SECONDS * 1000);
             for (const { run } of singles) {
@@ -765,6 +969,7 @@ export function createTaskHooks(config, ctx) {
                 if (typeof out.systemMessage === "string")
                     ctx.logger.warn("hook_system_message", { event: "UserPromptSubmit", message: clip(out.systemMessage, 500) });
                 if (out.continue === false) {
+                    // continue:false=终止整个 run;userPromptSubmit 的 block 语义正是"任务带理由收场"——同义直映射。
                     const reason = clip(typeof out.stopReason === "string" ? out.stopReason : "hook requested stop", MAX_HOOK_FEEDBACK_CHARS);
                     return { block: reason, ...(contexts.length ? { additionalContext: contexts.join("\n") } : {}) };
                 }
@@ -784,16 +989,40 @@ export function createTaskHooks(config, ctx) {
         hooks.userPromptSubmit = userPromptSubmitHook;
     }
     if (stopEntries) {
+        // matcher=null 事件(全条目跑)。CC:exit 2 = 阻断停止(stderr=继续干活的理由,模型再来一轮);
+        // decision:"block"+reason 同。防环(cap 8/stopHookActive)由 core 管,runner 只翻译。
         const stopHook = async (sctx) => {
             const payload = { ...basePayload(ctx), hook_event_name: "Stop", stop_hook_active: sctx.stopHookActive };
+            // ── Stop × `type:"prompt"` 的 CC 形(逐字文案见 cc-stop-prompt.ts;渲染与证据面判据见 branch-transcript.ts)──
+            // core 1.419 起 `StopHookContext.getBranch()` 交出本次运行的会话分支;没有它,一个"基于会话状态判断"的
+            // 条件钩子**结构上不可能工作**(cli live 实证:模型只会回「I don't have direct access…」这类散文)。
+            //
+            // 🔴 **证据面为空时不进这条路**,这一条是承重的:CC 的提示词**明确指示**模型在证据不足时回
+            // `{"ok": false, "reason": "insufficient evidence in transcript"}`,而 Stop 的 `ok:false` = **拦住停止**。
+            // 那**不是解析失败**(解析会成功、判词有效),所以解析层的任何防线都救不了 —— 唯一的防线是不启动它。
+            // 判据挂在**最终送进模型的那段文本**上,不是挂在 `getBranch` 的存在性上(core [1758]:
+            // 访问器在、返回 `[]`、或者被我们自己的过滤渲没了,是同一个后果,后者还是纯自伤)。
+            //
+            // ── 三问(行为面新增)──
+            //  · 谁需要:任何用 `type:"prompt"` 写「基于会话状态判断」的 Stop 条件钩子 —— 这是**整类**,不是某个功能;
+            //  · 谁被伤:①会话内容多进一次**已经在发生**的模型调用(增量是 transcript 的 token,不是新增一次调用);
+            //    ②今天"从不拦"的钩子会开始按配置拦 —— 那**正是操作方配置它要做的事**,不是意外;
+            //  · 什么补偿:`SEMA_STOP_PROMPT_TRANSCRIPT=0` 显式关;transcript 走 `redactSecrets` 与 fleet 行同纪律;
+            //    上限 `BRANCH_TRANSCRIPT_MAX_CHARS` 且截断**明说**;最坏情况仍被 core 的 `STOP_HOOK_BLOCK_CAP=8` 兜住。
             let llmExtra;
             const wantsPrompt = stopEntries.some((g) => g.hooks.some((h) => h.type === "prompt"));
             if (wantsPrompt) {
                 if (ctx.stopPromptTranscript === false) {
+                    // 旋钮关 ⇒ **整条路不启用**(而不是"退回旧的、送裸条件进去")。
+                    // 选这个语义而不是"逐位退回旧行为":旧行为是**已知失效**的(评估者对会话是瞎的),
+                    // 退回它等于留下一条"看起来在跑、永远给不出判决"的路 —— 而那正是这次要修掉的东西。
+                    // 关掉就干净地不跑,并记账可见。
                     ctx.logger.warn("hook_entries_skipped", { event: "Stop", type: "prompt", reason: "stop_prompt_transcript_disabled" });
                     ctx.onHookNotice?.({ kind: "hook_decision_unavailable", event: "Stop", reason: "skipped", detail: "transcript disabled" });
                 }
                 else {
+                    // ⚠️ `getBranch()` **抛错**与「分支为空」是两回事(引擎故障 vs 一条还没内容的分支),
+                    //    记成同一个原因会让排障时分不清该看哪一边。分开记。
                     let branch;
                     try {
                         branch = await sctx.getBranch?.();
@@ -806,18 +1035,43 @@ export function createTaskHooks(config, ctx) {
                         llmExtra = { system: ccPromptSystemFor("Stop"), transcript: rendered.text };
                     }
                     else {
+                        // 诚实降级:**跳过 prompt 条目**(记账可见),而不是"送个空会话进去看看模型怎么说"。
                         ctx.logger.warn("hook_entries_skipped", { event: "Stop", type: "prompt", reason: `stop_prompt_no_evidence:${rendered.reason}` });
                         ctx.onHookNotice?.({ kind: "hook_decision_unavailable", event: "Stop", reason: "skipped", detail: `no evidence: ${rendered.reason}` });
                     }
                 }
             }
             const stopGroups = ignoreMatchers(stopEntries);
+            // 拿不到证据面(或旋钮关)⇒ 把 **prompt** 条目滤掉;其余类型(command/http/agent)照跑 ——
+            // 证据面判据只管"需要会话才能判"的那一类,不该让整个 Stop 事件停摆。
+            // 滤在这里而不是在骨架里:骨架是跨事件公共的,这条判据是 Stop×prompt 专属。
             const effectiveGroups = llmExtra || !wantsPrompt
                 ? stopGroups
                 : stopGroups.map((g) => ({ ...g, hooks: g.hooks.filter((h) => h.type !== "prompt") })).filter((g) => g.hooks.length > 0);
             const singles = await runMatchingEntries("Stop", effectiveGroups, "", payload, ctx, onceFired, Date.now() + MAX_HOOK_EVENT_TOTAL_SECONDS * 1000, undefined, llmExtra);
+            // CC 是并行聚合后 continue:false【全局】压过 block("就让它停")——block 若
+            // 短路返回,后到条目的 continue:false 就没机会翻案。改成跑完整匹配集再折叠:首个 block 记下,
+            // 任一 continue:false 最终放行。
             let block;
             let sawContinueFalse = false;
+            // ⚠️⚠️ **这个通道带副作用,别随手用**(亲验 core 源码,两版都读过):
+            //    `additionalContext` **单独出现**(无 block)时,引擎返回的是**非空** follow-up 消息
+            //    (`agent-harness.js:506` 的 `getFollowUpMessages`)⇒ **这一轮不结束**。
+            //    · **core < 1.422**:`if (!result?.block)` 那支还会把 `consecutiveBlocks` **清零**
+            //      —— 不是"不计入上限",是**抵消掉之前累积的** ⇒ 任何**能持续为真**的条件走这个通道,
+            //      会造出一条 `STOP_HOOK_BLOCK_CAP` **完全管不住**的循环(最坏烧完 maxTurns 缺省 1000)。
+            //    · **core ≥ 1.422(本仓下限)**:改成 `if (messages.length === 0 && !result?.block)`
+            //      ⇒ **任何非空反馈都计数、不再清零**(与 CC 2.1.220 一致)⇒ 最坏被 cap 8 兜住。
+            //    ⚠️ 即便有了 cap,**这个通道仍然会让这一轮不结束** —— 它在功能上与 block 同效(该停的没停),
+            //    只是多了个上限。所以判据不变:**我们自己不得用它去"顺便告知一声"**;
+            //    命令形钩子作者**显式**这么配是他自己的选择(CC 对位)。
+            //    🔴 本仓把 core 下限提到 `^1.422.0` 正是为了这条 —— 因为 command 形的透传是**我们 1.277.3 加的**,
+            //    是我们引入了这个曝露面(见 `test/core-dependency-floor.test.ts` 顶注第二条理由)。
+            // 🔴 `StopHookResult` 是 `{ block?, additionalContext? }` 两个**解耦**的字段(core `core/hooks.d.ts:67`):
+            //    `additionalContext` 注入给模型但**不计入**连续 block 上限(CC 2.1.201 对位)。此前本折叠只产出
+            //    `block`,于是一条「只想补上下文、不想拦停」的 Stop 钩子输出被**静默丢弃** —— 而紧邻的
+            //    UserPromptSubmit 折叠一直是带上它的(同一个 `hookSpecificOutput.additionalContext` 形)。
+            //    对 `/goal` 这类用法这正是常见形(「还差验收用例」既可以拦、也可以只提醒),所以按同构补齐。
             const contexts = [];
             for (const { entry, run } of singles) {
                 if (run.code === 2) {
@@ -829,11 +1083,32 @@ export function createTaskHooks(config, ctx) {
                     ctx.logger.warn("hook_command_failed", { event: "Stop", code: run.code, stderr: clip(run.stderr, 300) });
                     continue;
                 }
+                // CC 形的 prompt 条目回的是 `{ok, reason, impossible?}`,不是 `{decision}` —— 分开解析。
+                // 🔴 `parseCcVerdict` 解析不出来 ⇒ undefined ⇒ **无判决**(继续下一条),绝不臆测成 ok:false:
+                //    Stop 的 ok:false = 拦停,把"读不懂"当成"没满足"会让一次解析失败变成一次拦停。
+                // ⚠️ **两种判词形都认**,而且它们**无歧义**:CC 形有 `ok`,既有形有 `decision`/`continue`/`hookSpecificOutput`,
+                //    两者的键不重叠。只认 CC 形会**破坏**已经按既有形写好的 prompt 钩子(那是对既有配置的回归),
+                //    而只认既有形就没有 CC 对位。⇒ 先试 CC 形;不是 CC 形就**落到下面的既有解析**,不早退。
                 if (llmExtra && entry.type === "prompt" && parseCcVerdict(run.stdout)) {
                     const v = parseCcVerdict(run.stdout);
                     if (v.ok)
-                        continue;
+                        continue; // 条件已达成 ⇒ 不拦
                     if (v.impossible) {
+                        // 🔴 第三态:**永远不可能达成** ⇒ **真 fail-open:既不 block,也不注入** —— 理由只进日志。
+                        //
+                        // ⚠️ 我第一版把理由走了 `additionalContext`,想的是"静默放行会让用户以为钩子没生效"。
+                        // **那个选择是错的**,core [1766] 指出、我亲读 core 源码核实(1.419.0):
+                        //   · `additionalContext` 单独出现 ⇒ 引擎返回**非空** follow-up 消息
+                        //     (`agent-harness.js:506` 的 `getFollowUpMessages`)⇒ **这一轮不结束**;
+                        //   · 它**不计入** `STOP_HOOK_BLOCK_CAP`,而且 `runtask.js` 里 `if (!result?.block)` 那支
+                        //     会把 `consecutiveBlocks` **清零** —— 不是"不计入",是**抵消掉之前累积的**。
+                        // ⇒ 一个**能持续为真**的 `impossible`(模型这段时间就是这么判)会:注入 → 续跑 → 又到停车点 →
+                        //   又 impossible → 又注入 → 计数又清零……**专为兜住「该停而不停」建的那个上限,在这条道上保护为零**,
+                        //   最坏情况被 `maxTurns`(缺省 1000)或墙钟兜住 = **把整个预算烧完**,而且**看起来是在忙不是卡住**。
+                        //
+                        // ⇒ 教训:**别用一个「带副作用的通道」去传递信息**。我要传的是"钩子判定不可达",
+                        //   而我选的通道本身会让运行继续 —— 那正是 `impossible` 要防的事。
+                        //   用户想知道"钩子为什么没生效"应该去日志里找,而不是靠一条让运行继续下去的注入来暗示。
                         ctx.logger.warn("hook_stop_condition_impossible", { event: "Stop", reason: clip(v.reason?.trim() ?? "", 500) });
                         continue;
                     }
@@ -843,6 +1118,8 @@ export function createTaskHooks(config, ctx) {
                 }
                 const out = parseHookStdout(run.stdout);
                 if (!out) {
+                    // 🔴 **两种形都解析不出来 ⇒ 无判决**(绝不臆测成"没满足")。prompt 条目单独记账:
+                    // 模型回散文是这条路最常见的失败形,静默丢弃会让排障无从下手。
                     if (llmExtra && entry.type === "prompt") {
                         ctx.logger.warn("hook_llm_unparsed_verdict", { event: "Stop", head: clip(run.stdout.trim(), 200) });
                         ctx.onHookNotice?.({ kind: "hook_decision_unavailable", event: "Stop", reason: "unparsed" });
@@ -863,6 +1140,8 @@ export function createTaskHooks(config, ctx) {
                         contexts.push(clip(h.additionalContext, MAX_HOOK_FEEDBACK_CHARS));
                 }
             }
+            // continue:false > block(CC 全局优先序)——「就让它停」。⚠️ 此时 additionalContext 也一并丢弃:
+            // 本 run 已经要结束了,注入给"模型的下一轮"的上下文没有下一轮可去。
             if (sawContinueFalse)
                 return undefined;
             if (block === undefined && contexts.length === 0)
@@ -875,12 +1154,16 @@ export function createTaskHooks(config, ctx) {
         hooks.stop = stopHook;
     }
     if (stopFailureEntries) {
+        // observe-only(core 回调 void,契约无 StopFailure 输出面);matcher 对契约 error 枚举匹配
+        // (BRAIN_TO_TURN_ERROR 映射后的值);原始人话错误进 error_details(契约可选字段)。
         const stopFailureHook = async (fctx) => {
             const turnError = toAssistantTurnError(fctx.errorKind);
             const payload = {
                 ...basePayload(ctx),
                 hook_event_name: "StopFailure",
                 error: turnError,
+                // brain 错误串可能回显 provider 的 Authorization/token/URL 凭据——脱敏后再截断
+                // (与 elicitation/project-memory 同用 trace/redact 单源)。
                 ...(fctx.error ? { error_details: clip(redactSecrets(fctx.error), MAX_HOOK_FEEDBACK_CHARS) } : {}),
             };
             await runObserveOnlyEvent("StopFailure", stopFailureEntries, turnError, payload, ctx, onceFired);
@@ -888,16 +1171,20 @@ export function createTaskHooks(config, ctx) {
         hooks.stopFailure = stopFailureHook;
     }
     if (preCompactEntries) {
+        // matcher 对 trigger 匹配。core 的 trigger 可为 "forced"(契约枚举只有 auto|manual 的超集)——原样
+        // 透传(matcher "*" 仍可见);block 在 forced 上由 core 忽略并 trace(其契约注明),runner 不重复裁决。
         const preCompactHook = async (pctx) => {
             const payload = {
                 ...basePayload(ctx),
                 hook_event_name: "PreCompact",
                 trigger: pctx.trigger,
+                // 契约 custom_instructions 是 nullable 必填(CC-verbatim)——没有就送 null,不缺字段。
                 custom_instructions: pctx.customInstructions ?? null,
             };
             const singles = await runMatchingEntries("PreCompact", preCompactEntries, pctx.trigger, payload, ctx, onceFired, Date.now() + MAX_HOOK_EVENT_TOTAL_SECONDS * 1000);
             for (const { run } of singles) {
                 if (run.code === 2) {
+                    // CC:exit 2 = 阻断本次压缩(stderr=理由,core trace 记录)。
                     return { block: clip(run.stderr.trim(), MAX_HOOK_FEEDBACK_CHARS) || "blocked by a PreCompact hook" };
                 }
                 if (run.code !== 0) {
@@ -910,6 +1197,7 @@ export function createTaskHooks(config, ctx) {
                 if (typeof out.systemMessage === "string")
                     ctx.logger.warn("hook_system_message", { event: "PreCompact", message: clip(out.systemMessage, 500) });
                 if (out.continue === false) {
+                    // "终止整个 run"≠"跳过这次压缩"——不偷换成 block,记账可见。
                     ctx.logger.warn("hook_continue_false_unsupported", { event: "PreCompact" });
                 }
                 if (out.decision === "block") {
@@ -921,6 +1209,8 @@ export function createTaskHooks(config, ctx) {
         hooks.preCompact = preCompactHook;
     }
     if (postCompactEntries) {
+        // observe-only(core 回调 void,契约无 PostCompact 输出面);matcher 对 trigger 匹配;
+        // compact_summary 有界截断(压缩摘要可长)。core 的 tokensBefore/After 契约无字段 → 宁缺毋滥。
         const postCompactHook = async (cctx) => {
             const payload = {
                 ...basePayload(ctx),
@@ -934,6 +1224,18 @@ export function createTaskHooks(config, ctx) {
     }
     return hooks;
 }
+/**
+ * 把部署级 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 function composeHooks(deployment, task) {
     if (!deployment)
         return task;
@@ -962,6 +1264,7 @@ export function composeHooks(deployment, task) {
                 }
             }
             if (asked) {
+                // ask 槽自己没带改写、但前面槽已改写 → 把线程中的改写挂上,approve 才执行改写后 args。
                 const askedUpdated = asked.updatedInput;
                 return {
                     ...asked,
@@ -1022,6 +1325,8 @@ export function composeHooks(deployment, task) {
         };
     }
     if (d.stop || t.stop) {
+        // 与 userPromptSubmit 同折叠:部署 block 优先短路;否则双跑、additionalContext(CC 2.1.201,与
+        // block 解耦)拼接、task 的 block 生效——`rt ?? rd` 会把"rd 有 context、rt 有 block"折丢一侧。
         out.stop = async (sctx) => {
             const rd = d.stop ? await d.stop(sctx) : undefined;
             if (rd?.block)
@@ -1034,6 +1339,7 @@ export function composeHooks(deployment, task) {
         };
     }
     if (d.preCompact || t.preCompact) {
+        // 双跑(部署观测也想看到每次压缩);block 部署优先,additionalInstructions 拼接(core 语义=追加)。
         out.preCompact = async (pctx) => {
             const rd = d.preCompact ? await d.preCompact(pctx) : undefined;
             const rt = t.preCompact ? await t.preCompact(pctx) : undefined;
@@ -1048,6 +1354,9 @@ export function composeHooks(deployment, task) {
         };
     }
     for (const slot of ["stopFailure", "postCompact", "permissionDenied"]) {
+        // observe-only void 槽:两侧都在=顺序双跑(部署先),无返回可折;单在则透传。
+        // permissionDenied(core 1.257 新增,gate deny 短路观测)也走这里——createTaskHooks 不产它
+        // (PermissionDenied 是 shell-owned 事件),但部署侧 tracer 未来若设它,整槽覆盖不透传就会被 shadow。
         const ds = d[slot];
         const ts = t[slot];
         if (ds && ts) {