ppxans-harness 2.4.0 → 3.2.0

package/src/edit/editblock.js

@@ -0,0 +1,266 @@
+// src/edit/editblock.js — aider 风格 SEARCH/REPLACE 编辑块
+// 解析 LLM 输出的编辑块, 应用 (精确/去首尾空行/模糊匹配), 生成回灌提示。
+// 纯 Node、零依赖、ESM。
+
+import { strict as assert } from "node:assert";
+
+// ---- 解析: 容错处理围栏/冒号/反引号/多块 ----
+// 块格式:
+//   <<<<<<< SEARCH
+//   [path/to/file.js]
+//   旧代码
+//   =======
+//   新代码
+//   >>>>>>> REPLACE
+export function parseEditBlocks(text) {
+  const blocks = [];
+  const lines = String(text || "").split(/\r?\n/);
+  let state = "seek"; // seek | path | search | replace
+  let cur = null;
+
+  const trimFence = (s) => s.replace(/^`+|`+$/g, "").trim();
+
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    const line = trimFence(raw);
+
+    if (state === "seek") {
+      if (/^<{5,}\s*SEARCH/i.test(line)) {
+        cur = { path: null, search: "", replace: "" };
+        state = "path";
+      }
+      continue;
+    }
+
+    if (state === "path") {
+      // 第一行即路径 (可能带 [] 或反引号围栏)
+      let p = line.replace(/[\[\]`]/g, "").replace(/^[\s:]+|[\s:]+$/g, "").trim();
+      cur.path = p || null;
+      state = "search";
+      continue;
+    }
+
+    if (state === "search") {
+      if (/^={5,}/.test(line)) {
+        state = "replace";
+        continue;
+      }
+      if (/^>{5,}/.test(line)) {
+        // 异常: 缺少 divider, 放弃当前块
+        cur = null;
+        state = "seek";
+        continue;
+      }
+      cur.search += (cur.search ? "\n" : "") + raw;
+      continue;
+    }
+
+    if (state === "replace") {
+      if (/^>{5,}/.test(line)) {
+        blocks.push(finalize(cur));
+        cur = null;
+        state = "seek";
+        continue;
+      }
+      cur.replace += (cur.replace ? "\n" : "") + raw;
+      continue;
+    }
+  }
+  return blocks;
+}
+
+function finalize(block) {
+  return { path: block.path, search: block.search, replace: block.replace };
+}
+
+// ---- 工具函数 ----
+function stripEdgeBlanks(s) {
+  const lines = String(s).split("\n");
+  while (lines.length && lines[0].trim() === "") lines.shift();
+  while (lines.length && lines[lines.length - 1].trim() === "") lines.pop();
+  return lines.join("\n");
+}
+
+function countOccurrences(hay, needle) {
+  if (!needle) return 0;
+  let c = 0;
+  let i = 0;
+  while ((i = hay.indexOf(needle, i)) !== -1) {
+    c++;
+    i += needle.length;
+  }
+  return c;
+}
+
+function shortPreview(s) {
+  const one = String(s).replace(/\n/g, " ").slice(0, 40);
+  return one + (String(s).length > 40 ? "…" : "");
+}
+
+// 模糊匹配计划: 按行 trim 后逐行滑动窗口, 统计命中次数并给出替换方案
+function fuzzyPlan(content, search, replace) {
+  const cLines = content.split("\n");
+  const sLines = search.split("\n").map((l) => l.trim()).filter((l) => l.length > 0);
+  if (sLines.length === 0) return null;
+  const n = sLines.length;
+  let first = null;
+  let count = 0;
+  for (let i = 0; i + n <= cLines.length; i++) {
+    let ok = true;
+    for (let j = 0; j < n; j++) {
+      if (cLines[i + j].trim() !== sLines[j]) {
+        ok = false;
+        break;
+      }
+    }
+    if (ok) {
+      count++;
+      if (first === null) first = i;
+    }
+  }
+  if (count === 0) return null;
+  return { start: first, n, repLines: replace.split("\n"), count };
+}
+
+function applyFuzzy(content, plan) {
+  const cLines = content.split("\n");
+  const out = cLines
+    .slice(0, plan.start)
+    .concat(plan.repLines, cLines.slice(plan.start + plan.n));
+  return out.join("\n");
+}
+
+// ---- 最佳匹配窗口诊断 (2026-10-02 深度优化) ----
+// not-found 时在文件里找"最像 SEARCH 的区域", 给出行号+相似度, 喂回 LLM 精准自修正,
+// 替代原先"未找到+首尾20行"的瞎蒙模式。
+// 逐行比较: 相等=1 分, 一方包含另一方=0.6 分 (容忍空格/标点微差), 空白行跳过。
+function bestMatchWindow(content, search) {
+  const cLines = String(content).split("\n");
+  const sLines = String(search).split("\n").map((l) => l.trim()).filter((l) => l.length > 0);
+  if (!sLines.length || !cLines.length) return null;
+  const norm = (s) => s.toLowerCase().replace(/\s+/g, " ");
+  const sNorm = sLines.map(norm);
+  let best = null;
+  for (let i = 0; i + sLines.length <= cLines.length; i++) {
+    let hit = 0;
+    for (let j = 0; j < sLines.length; j++) {
+      const a = norm(cLines[i + j]);
+      if (!a && !sNorm[j]) { hit += 1; continue; }
+      if (a === sNorm[j]) hit += 1;
+      else if (a && (a.includes(sNorm[j]) || sNorm[j].includes(a))) hit += 0.6;
+    }
+    const score = hit / sLines.length;
+    if (!best || score > best.score) best = { line: i + 1, score };
+    if (best.score === 1) break;
+  }
+  return best && best.score >= 0.3 ? best : null;
+}
+
+// ---- 应用单个块 ----
+// 返回 { ok, content, matched, kind, error?, search }
+export function applyEditBlock(content, block, { fuzzy = true } = {}) {
+  const search = block.search ?? "";
+  const replace = block.replace ?? "";
+  const result = { ok: false, content, matched: false, kind: "none", search };
+
+  if (!search) {
+    result.error = "搜索内容为空 (empty)";
+    result.kind = "empty";
+    return result;
+  }
+
+  const candidates = [{ s: search, r: replace, kind: "exact" }];
+  const s2 = stripEdgeBlanks(search);
+  if (s2 && s2 !== search) {
+    candidates.push({ s: s2, r: stripEdgeBlanks(replace), kind: "edge-trim" });
+  }
+  if (fuzzy) {
+    const f = fuzzyPlan(content, search, replace);
+    if (f) candidates.push({ s: null, r: null, kind: "fuzzy", plan: f });
+  }
+
+  for (const c of candidates) {
+    if (c.kind === "fuzzy") {
+      if (c.plan.count > 1) {
+        result.kind = "ambiguous";
+        result.error = `多处命中 (ambiguous): ${shortPreview(search)}`;
+        return result;
+      }
+      result.ok = true;
+      result.matched = true;
+      result.kind = "fuzzy";
+      result.content = applyFuzzy(content, c.plan);
+      return result;
+    }
+    const count = countOccurrences(content, c.s);
+    if (count === 0) continue;
+    if (count > 1) {
+      result.kind = "ambiguous";
+      result.error = `多处命中 (ambiguous): ${shortPreview(c.s)}`;
+      return result;
+    }
+    result.ok = true;
+    result.matched = true;
+    result.kind = c.kind;
+    result.content = content.replace(c.s, c.r);
+    return result;
+  }
+
+  result.kind = "not-found";
+  result.error = `未找到匹配 (not-found): ${shortPreview(search)}`;
+  const hint = bestMatchWindow(content, search);
+  if (hint) {
+    result.hint = hint;
+    result.error += ` — 最接近的位置在第 ${hint.line} 行附近 (相似度 ${Math.round(hint.score * 100)}%), 请对照该区域修正 SEARCH 块`;
+  }
+  return result;
+}
+
+// ---- 顺序应用全部块 ----
+export function applyAll(content, blocks) {
+  const results = [];
+  let cur = content;
+  for (const b of blocks) {
+    const r = applyEditBlock(cur, b);
+    results.push({ path: b.path, ...r });
+    if (r.ok) cur = r.content;
+    // 失败的块保留原内容继续, 由回灌循环修正
+  }
+  return { ok: results.every((r) => r.ok), content: cur, results };
+}
+
+// ---- 生成回灌 LLM 的失败块修复提示 (aider 回灌循环) ----
+// 2026-10-02: 失败块附最佳匹配区域摘录 (±5 行), LLM 拿着原文改 SEARCH, 不再瞎蒙
+export function formatRetryFeedback(results, fileContent = "") {
+  const failed = (results || []).filter((r) => !r.ok);
+  if (failed.length === 0) return "";
+
+  const out = [];
+  out.push("以下编辑块应用失败, 请根据当前文件内容修正后重试 (SEARCH 块必须精确匹配现有内容):");
+  const fl = String(fileContent || "").split("\n");
+  for (const f of failed) {
+    out.push(`- 文件 ${f.path || "(未知)"} 失败类型=${f.kind}: ${f.error || ""}`);
+    if (f.search) {
+      out.push("  原 SEARCH 预览: " + shortPreview(f.search));
+    }
+    // 带上最像 SEARCH 的原文区域 (±5 行), LLM 照着改即可命中
+    if (f.hint && fl.length) {
+      const lo = Math.max(0, f.hint.line - 6);
+      const hi = Math.min(fl.length, f.hint.line - 1 + 5 + 1);
+      out.push(`  当前文件第 ${lo + 1}-${hi} 行 (最接近 SEARCH 的区域):`);
+      out.push(fl.slice(lo, hi).map((l, i) => `  ${lo + i + 1} | ${l}`).join("\n"));
+    }
+  }
+  if (fileContent && !failed.some((f) => f.hint)) {
+    out.push("== 文件前 20 行 ==");
+    out.push(fl.slice(0, 20).join("\n"));
+    if (fl.length > 20) {
+      out.push("== 文件后 20 行 ==");
+      out.push(fl.slice(-20).join("\n"));
+    }
+  }
+  return out.join("\n");
+}
+
+// 供测试断言一致性 (非公开 API 也导出以便内部复用验证)
+export const __internal = { stripEdgeBlanks, countOccurrences, fuzzyPlan };

package/src/edit/snapshot.js

@@ -0,0 +1,67 @@
+// src/edit/snapshot.js — 编辑快照与回滚
+// 编辑前对目标文件做内存快照, 出错时整批回滚 (恢复修改 / 删除新建 / 重建目录)。
+// 纯 Node、零依赖、ESM。
+
+import fs from "node:fs";
+import path from "node:path";
+
+export const Snapshot = {
+  // 读取给定路径的文件内容入内存
+  // 返回 { id, entries: Map<path, {existed, content, mtime}> }
+  begin(paths = []) {
+    const entries = new Map();
+    for (const p of paths) {
+      let existed = false;
+      let content = "";
+      let mtime = 0;
+      try {
+        const stat = fs.statSync(p);
+        if (stat.isFile()) {
+          existed = true;
+          content = fs.readFileSync(p, "utf8");
+          mtime = stat.mtimeMs;
+        }
+      } catch {
+        // 文件不存在或不可读 -> existed=false
+      }
+      entries.set(p, { existed, content, mtime });
+    }
+    const id =
+      "snap-" + Date.now().toString(36) + "-" + Math.random().toString(36).slice(2, 8);
+    return { id, entries, createdAt: Date.now() };
+  },
+
+  // 快照内文件清单
+  list(snap) {
+    if (!snap || !snap.entries) return [];
+    return [...snap.entries.keys()];
+  },
+
+  // 把文件恢复到快照状态
+  //  existed=false: 删除运行期间新建的文件
+  //  existed=true : 确保目录存在, 先写临时文件再 rename 覆盖 (原子)
+  rollback(snap) {
+    if (!snap || !snap.entries) return false;
+    for (const [p, e] of snap.entries) {
+      if (!e.existed) {
+        try {
+          if (fs.existsSync(p)) fs.unlinkSync(p);
+        } catch {
+          /* 忽略删除失败 */
+        }
+      } else {
+        try {
+          const dir = path.dirname(p);
+          fs.mkdirSync(dir, { recursive: true });
+          const tmp =
+            p + ".ppx-rollback-" + Math.random().toString(36).slice(2, 10);
+          fs.writeFileSync(tmp, e.content, "utf8");
+          fs.renameSync(tmp, p);
+        } catch {
+          /* 忽略恢复失败 */
+        }
+      }
+    }
+    return true;
+  },
+};

package/src/evidence/index.js

@@ -0,0 +1,153 @@
+// src/evidence/index.js - 证据边界与看板 (吸收 oh-my-hermes / OMH 思路, 纯 JS, 零依赖)
+// 两层证据标记:
+//   PREPARED - 注入上下文的"预备材料"(如检索结果/文档), 禁止由 agent 伪造
+//   OBSERVED - 工具/环境真实产出的"观测结果", 准入时须校验来源
+// 另含: handoff manifest 哈希清单 (交接不可篡改)、goal board 只读看板、conformance 一致性核查。
+
+import crypto from "node:crypto";
+
+// 证据类型常量
+export const Evidence = Object.freeze({
+  PREPARED: "prepared",
+  OBSERVED: "observed",
+});
+
+const EVIDENCE_TYPES = new Set([Evidence.PREPARED, Evidence.OBSERVED]);
+
+// 浅拷贝对象 (不改动调用方传入的原始引用), 便于 freeze 后安全返回
+function shallowClone(data) {
+  if (data === null || typeof data !== "object") return data;
+  if (Array.isArray(data)) return [...data];
+  if (data instanceof Date) return new Date(data.getTime());
+  return { ...data };
+}
+
+// 标记为 PREPARED, 附带不可变标记并冻结
+export function markPrepared(data, { source } = {}) {
+  if (!source) throw new Error("markPrepared 需要 source 标识来源");
+  const obj = shallowClone(data);
+  Object.defineProperty(obj, "__evidence", { value: Evidence.PREPARED, enumerable: true, writable: false, configurable: false });
+  Object.defineProperty(obj, "__source", { value: String(source), enumerable: true, writable: false, configurable: false });
+  Object.defineProperty(obj, "__ts", { value: new Date().toISOString(), enumerable: true, writable: false, configurable: false });
+  return Object.freeze(obj);
+}
+
+// 标记为 OBSERVED, 附带不可变标记并冻结
+export function markObserved(data, { tool } = {}) {
+  if (!tool) throw new Error("markObserved 需要 tool 标识产出工具");
+  const obj = shallowClone(data);
+  Object.defineProperty(obj, "__evidence", { value: Evidence.OBSERVED, enumerable: true, writable: false, configurable: false });
+  Object.defineProperty(obj, "__tool", { value: String(tool), enumerable: true, writable: false, configurable: false });
+  Object.defineProperty(obj, "__ts", { value: new Date().toISOString(), enumerable: true, writable: false, configurable: false });
+  return Object.freeze(obj);
+}
+
+// 校验证据标记存在且类型合法
+export function validateEvidence(obj) {
+  if (!obj || typeof obj !== "object") {
+    return { valid: false, type: null, reason: "非对象" };
+  }
+  const t = obj.__evidence;
+  if (!EVIDENCE_TYPES.has(t)) {
+    return { valid: false, type: null, reason: "缺少合法的 __evidence 标记" };
+  }
+  if (t === Evidence.PREPARED && !obj.__source) {
+    return { valid: false, type: t, reason: "prepared 证据缺少 __source" };
+  }
+  if (t === Evidence.OBSERVED && !obj.__tool) {
+    return { valid: false, type: t, reason: "observed 证据缺少 __tool" };
+  }
+  if (typeof obj.__ts !== "string") {
+    return { valid: false, type: t, reason: "缺少 __ts 时间戳" };
+  }
+  return { valid: true, type: t, reason: "ok" };
+}
+
+// sha256 十六进制 (取前 16 位作为紧凑指纹)
+function shortHash(input) {
+  const h = crypto.createHash("sha256").update(typeof input === "string" ? input : JSON.stringify(input)).digest("hex");
+  return h.slice(0, 16);
+}
+
+// 创建交接清单 (handoff manifest): 每个条目独立哈希 + 整体摘要, 保证交接不可篡改
+export function createHandoffManifest(items = []) {
+  const entries = items.map((it) => {
+    const data = it && typeof it === "object" && "__evidence" in it ? it : it; // 兼容直接传证据对象或 {data}
+    const payload = data && typeof data === "object" && "data" in data ? data.data : data;
+    const type = (it && it.type) || (data && data.__evidence) || "unknown";
+    const source = (it && it.source) || (data && (data.__source || data.__tool)) || "unknown";
+    return {
+      hash: shortHash(payload),
+      type,
+      source,
+    };
+  });
+  const digestInput = entries.map((e) => `${e.hash}:${e.type}:${e.source}`).join("|");
+  return {
+    version: 1,
+    created_at: new Date().toISOString(),
+    entries,
+    digest: shortHash(digestInput),
+  };
+}
+
+// 目标看板 (只读状态看板, 用于多 agent 协作时统一目标可见性)
+export function createGoalBoard() {
+  const goals = new Map(); // id -> {id, title, priority, status}
+  const VALID_STATUS = new Set(["pending", "in_progress", "blocked", "done"]);
+  const PRIORITY_RANK = { P0: 0, P1: 1, P2: 2 };
+
+  const api = {
+    addGoal({ id, title, priority = "P2", status = "pending" } = {}) {
+      if (!id) throw new Error("addGoal 需要 id");
+      if (!VALID_STATUS.has(status)) status = "pending";
+      if (!PRIORITY_RANK.hasOwnProperty(priority)) priority = "P2";
+      goals.set(id, { id, title: title || id, priority, status });
+      return goals.get(id);
+    },
+    updateStatus(id, status) {
+      const g = goals.get(id);
+      if (!g) return null;
+      if (!VALID_STATUS.has(status)) throw new Error(`非法状态: ${status}`);
+      g.status = status;
+      return g;
+    },
+    list() {
+      return [...goals.values()].sort((a, b) => (PRIORITY_RANK[a.priority] - PRIORITY_RANK[b.priority]));
+    },
+    get(id) { return goals.get(id) || null; },
+    render() {
+      const lines = ["# 目标看板 (Goal Board)", ""];
+      const order = ["P0", "P1", "P2"];
+      const icon = { pending: "○", in_progress: "◑", blocked: "⛔", done: "●" };
+      for (const p of order) {
+        const items = api.list().filter((g) => g.priority === p);
+        if (items.length === 0) continue;
+        lines.push(`## ${p}`);
+        for (const g of items) {
+          const st = icon[g.status] || "?";
+          lines.push(`- [${st}] ${g.title} \`${g.id}\` (${g.status})`);
+        }
+        lines.push("");
+      }
+      return lines.join("\n").trim() + "\n";
+    },
+  };
+  return api;
+}
+
+// conformance 一致性核查: 用相同算法重算 items 哈希, 与 manifest.entries 比对
+export function conformanceCheck(manifest, items = []) {
+  const expected = manifest && manifest.entries ? manifest.entries : [];
+  const recomputed = createHandoffManifest(items).entries;
+  const mismatches = [];
+  const n = Math.max(expected.length, recomputed.length);
+  for (let i = 0; i < n; i++) {
+    const e = expected[i];
+    const r = recomputed[i];
+    if (!e || !r || e.hash !== r.hash || e.type !== r.type) {
+      mismatches.push({ index: i, expected: e ? e.hash : null, actual: r ? r.hash : null });
+    }
+  }
+  return { ok: mismatches.length === 0, mismatches, expected, actual: recomputed };
+}

package/src/evolve/playbook.js

@@ -6,9 +6,12 @@
 //   - 门禁回滚: 任何进化必须过回归基准才 commit, 否则自动 rollback
 // 仅借鉴思想, 源码自研。核心合并/裁剪/门禁纯代码 (可测), LLM 提炼教训走可选 adapter (无 LLM 时跳过)。
 // 与 LearningService.refine (失败→经验库) 互补: refine 沉淀经验, playbook 反哺系统提示词 (零 token 成本时为空)。
-import fs from "node:fs";
+// ⚠ 接线状态 (2026-09-17 核对): 已由 evolvePlugin 装配为 ctx.provide("playbook"), 但**无内置消费方**
+//   —— 没有代码把 playbook bullets 注入 system prompt, 也没有代码在对话后产生 delta 操作。
+//   属"引擎就绪、链路未接"; 待接入 (注入 + delta 生成) 才算生效。
+import { shortId } from "../utils/id.js";
 import path from "node:path";
-import { ensureDir, readText, writeText } from "../utils/store.js";
+import { ensureDir, readJson, writeJson } from "../utils/store.js";
 
 // ---- 词法相似度 (grow-and-refine 用, 零依赖) ----
 // 英文/空格分隔 → 词级 Jaccard; 中文等 CJK 连续串 → 字符 bigram Dice (单 token 时退化)。
@@ -58,7 +61,7 @@ export function applyDelta(playbook, ops = [], { maxBullets = 200 } = {}) {
       // 新增前查重: 与已有 bullet 词法相似 > 0.6 视为重复, 拒收 (grow-and-refine)
       const dup = pb.bullets.find((b) => lexicalSimilarity(b.content, content) > 0.6);
       if (dup) { rejected.push({ op, reason: "重复: " + dup.id }); continue; }
-      const id = op.id || ("b" + Date.now().toString(36) + Math.random().toString(36).slice(2, 5));
+      const id = op.id || shortId("b", 5);
       const kind = ["strategy", "pitfall", "domain"].includes(op.kind) ? op.kind : "strategy";
       pb.bullets.push({ id, kind, content, counters: { helpful: 0, harmful: 0 }, evidence_ref: op.evidence_ref || null, createdAt: Date.now() });
       applied.push({ op: "ADD", id });
@@ -141,12 +144,8 @@ export class PlaybookStore {
   }
 
   _load() {
-    try {
-      if (fs.existsSync(this.file)) {
-        const d = JSON.parse(fs.readFileSync(this.file, "utf8"));
-        if (d && Array.isArray(d.bullets)) return d;
-      }
-    } catch {}
+    const d = readJson(this.file, null);
+    if (d && Array.isArray(d.bullets)) return d;
     return { base: "", bullets: [], version: 1 };
   }
 
@@ -159,7 +158,7 @@ export class PlaybookStore {
 
   save(pb = this._playbook) {
     this._playbook = pb;
-    writeText(this.file, JSON.stringify(pb, null, 2));
+    writeJson(this.file, pb);
     return pb;
   }
 

package/src/hooks/index.js

@@ -0,0 +1,113 @@
+// src/hooks/index.js — 钩子链 (吸收 claude-code 六事件)
+// 纯 JS、事件驱动注册、超时熔断、单钩子异常不中断链。
+
+// claude-code 钩子事件 (PreToolUse 可否决/改参, PostToolUse 可附加上下文)
+export const HOOK_EVENTS = [
+  "PreToolUse",
+  "PostToolUse",
+  "PreCompact",
+  "PostCompact",
+  "SessionStart",
+  "SessionStop",
+  "SubagentStop",
+];
+
+// 创建钩子注册表
+export function createHookRegistry() {
+  const _hooks = new Map(); // event -> [{ fn, priority, timeoutMs }]
+
+  // 注册钩子, 返回解绑函数
+  function on(event, fn, opts = {}) {
+    if (!HOOK_EVENTS.includes(event)) {
+      throw new Error("未知钩子事件: " + event);
+    }
+    if (typeof fn !== "function") {
+      throw new Error("钩子 fn 必须是函数");
+    }
+    const entry = {
+      fn,
+      priority: opts.priority ?? 100,
+      timeoutMs: opts.timeoutMs ?? 3000,
+    };
+    if (!_hooks.has(event)) _hooks.set(event, []);
+    _hooks.get(event).push(entry);
+    return function unbind() {
+      const arr = _hooks.get(event);
+      if (!arr) return;
+      const i = arr.indexOf(entry);
+      if (i >= 0) arr.splice(i, 1);
+    };
+  }
+
+  // 触发事件: 按 priority 升序依次 await 执行
+  async function emit(event, payload = {}) {
+    const list = (_hooks.get(event) || []).slice().sort((a, b) => a.priority - b.priority);
+    const results = [];
+    let blocked = false;
+    let blockReason = null;
+    const additionalContext = [];
+
+    for (const h of list) {
+      let res = null;
+      let err = null;
+      let timedOut = false;
+      try {
+        // 2026-09-18 修复: 定时器句柄必须保存并在竞速结束后清理 —— 原实现每次 emit
+        //   都留一个活定时器, 钩子正常完成后仍把事件循环挂住 timeoutMs (默认 3s)
+        let timer;
+        const timeout = new Promise((_, reject) => {
+          timer = setTimeout(() => reject(new Error("hook timeout")), h.timeoutMs);
+        });
+        try {
+          res = await Promise.race([Promise.resolve().then(() => h.fn(payload)), timeout]);
+        } finally { clearTimeout(timer); }
+      } catch (e) {
+        err = e && e.message ? e.message : String(e);
+        if (/timeout/i.test(err)) timedOut = true;
+      }
+
+      if (err) {
+        results.push({ error: err, timedOut });
+        continue;
+      }
+      results.push({ result: res });
+
+      // PreToolUse: 可否决
+      if (event === "PreToolUse" && res && res.decision === "block") {
+        blocked = true;
+        if (!blockReason) blockReason = res.reason || "被钩子否决";
+      }
+      // PostToolUse: 收集附加上下文
+      if (event === "PostToolUse" && res && res.additionalContext != null) {
+        additionalContext.push(res.additionalContext);
+      }
+    }
+
+    return { blocked, reason: blockReason, results, additionalContext };
+  }
+
+  return { on, emit, events: HOOK_EVENTS.slice() };
+}
+
+// 生成人类可读的一行日志描述
+export function describeHookEvent(event, payload = {}) {
+  const tool = payload.tool || payload.toolName || payload.name || "?";
+  switch (event) {
+    case "PreToolUse":
+      return `PreToolUse: 工具=${tool}`;
+    case "PostToolUse":
+      return `PostToolUse: 工具=${tool}`;
+    case "PreCompact":
+      return `PreCompact: 压缩前 (${payload.reason || "manual"})`;
+    case "PostCompact":
+      return `PostCompact: 压缩后`;
+    case "SessionStart":
+      return `SessionStart: 会话启动 (${payload.sessionId || "?"})`;
+    case "SessionStop":
+      return `SessionStop: 会话停止 (${payload.sessionId || "?"})`;
+    case "SubagentStop":
+      return `SubagentStop: 子代理=${payload.agent || payload.agentId || "?"}`;
+    default:
+      return `Hook(${event})`;
+  }
+}