kc-beta 0.5.6 → 0.6.0

package/src/agent/tools/document-chunk.js

@@ -0,0 +1,246 @@
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { BaseTool, ToolResult } from "./base.js";
+import { buildBundleTree, BundleTree } from "../bundle-tree.js";
+
+const CACHE_SUBDIR = path.join("cache", "bundles");
+
+/**
+ * Build a BundleTree (onion-peeler chunk tree with a keyword index) from
+ * a list of files. Caches the result under
+ *   <workspace>/cache/bundles/<sha256-of-bundle>.json
+ * keyed by the combined content hash, so re-chunking the same bundle is
+ * free.
+ *
+ * The bundle tree is the foundation for:
+ *   - `bundle_search` — cheap keyword RAG over the tree's leaves
+ *   - `document_classify` — reads each file's head to classify the bundle
+ *   - Group D skill_authoring context auto-attach (reads chunks by id)
+ *
+ * PDFs are extracted with per-page resolution via pdfjs (already a KC
+ * dependency). Other formats go in as single-page blocks, which still
+ * benefits from the chunker's header-based splitting.
+ */
+export class DocumentChunkTool extends BaseTool {
+  constructor(workspace) {
+    super();
+    this._workspace = workspace;
+  }
+
+  get name() { return "document_chunk"; }
+
+  get description() {
+    return (
+      "Build a searchable BundleTree from a list of regulation / reference documents. " +
+      "Produces a hierarchical chunk tree (max ~2000 tokens per leaf) with a " +
+      "keyword index for RAG. Result is cached by content hash — repeated calls " +
+      "on the same bundle are free. Use bundle_search afterward to look up evidence by keyword."
+    );
+  }
+
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        paths: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "Paths to input files (PDFs, .md, .txt). Relative to the chosen scope.",
+        },
+        scope: {
+          type: "string",
+          enum: ["workspace", "project"],
+          description: "Which directory to resolve paths against. Default 'workspace'.",
+        },
+        max_tokens_per_chunk: {
+          type: "integer",
+          description: "Max tokens per leaf chunk. Default 2000 (≈5000 chars CJK).",
+        },
+        force_refresh: {
+          type: "boolean",
+          description: "Ignore cache and re-chunk. Default false.",
+        },
+      },
+      required: ["paths"],
+    };
+  }
+
+  async execute(input) {
+    const paths = Array.isArray(input.paths) ? input.paths : [];
+    const scope = input.scope || "workspace";
+    const maxTokens = Number.isFinite(input.max_tokens_per_chunk)
+      ? input.max_tokens_per_chunk : 2000;
+    const forceRefresh = input.force_refresh === true;
+
+    if (paths.length === 0) return new ToolResult("No paths provided", true);
+    if (scope === "project" && !this._workspace.projectDir) {
+      return new ToolResult("No project directory available", true);
+    }
+
+    // Resolve + stat every path up front so cache key is based on actual files
+    const resolved = [];
+    for (const p of paths) {
+      let abs;
+      try {
+        abs = scope === "project"
+          ? this._workspace.resolveProjectPath(p)
+          : this._workspace.resolvePath(p);
+      } catch (e) { return new ToolResult(`Path error (${p}): ${e.message}`, true); }
+      if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) {
+        return new ToolResult(`File not found: ${p}`, true);
+      }
+      resolved.push({ requested: p, abs });
+    }
+
+    const cacheKey = this._hashBundle(resolved, maxTokens);
+    const cacheDir = path.join(this._workspace.cwd, CACHE_SUBDIR);
+    const cachePath = path.join(cacheDir, `${cacheKey}.json`);
+
+    if (!forceRefresh && fs.existsSync(cachePath)) {
+      try {
+        const tree = BundleTree.fromJSON(JSON.parse(fs.readFileSync(cachePath, "utf-8")));
+        return new ToolResult(this._summarize(tree, cachePath, /*cached*/ true));
+      } catch {
+        // Fall through to rebuild; corrupt cache is self-healing.
+      }
+    }
+
+    // Parse each file into { source_file, total_pages, blocks: [{page, markdown}] }
+    const parsedFiles = [];
+    for (const { requested, abs } of resolved) {
+      try {
+        parsedFiles.push(await this._parseOne(requested, abs));
+      } catch (e) {
+        parsedFiles.push({
+          source_file: path.basename(abs),
+          total_pages: 0,
+          blocks: [],
+          parse_error: `${e.name || "Error"}: ${e.message}`,
+        });
+      }
+    }
+
+    const tree = buildBundleTree(parsedFiles, { maxTokensPerChunk: maxTokens });
+
+    // Write cache
+    try {
+      fs.mkdirSync(cacheDir, { recursive: true });
+      fs.writeFileSync(cachePath, JSON.stringify(tree.toJSON()), "utf-8");
+    } catch {
+      // Cache write failure is non-fatal; the tree is still valid in memory
+      // for this turn. Next turn will just re-chunk.
+    }
+
+    return new ToolResult(this._summarize(tree, cachePath, /*cached*/ false));
+  }
+
+  /**
+   * Produce a concise summary output. Full tree is on disk; we show the
+   * outline + leaf stats so the agent knows what's inside without dumping
+   * every chunk into the LLM turn.
+   */
+  _summarize(tree, cachePath, cached) {
+    const files = tree.files();
+    const leaves = tree.allLeaves();
+    const totalTokens = leaves.reduce((n, ch) => n + (ch.tokens || 0), 0);
+    const rel = path.relative(this._workspace.cwd, cachePath) || cachePath;
+    const lines = [
+      `${cached ? "Reused cached" : "Built new"} BundleTree → ${rel}`,
+      `Files: ${files.length} · Leaves: ${leaves.length} · ~${totalTokens} tokens indexed`,
+      `Keyword index: ${Object.keys(tree.keyword_index).length} tokens`,
+      "",
+      "Outline:",
+      tree.outline(4),
+      "",
+      `Next step: use \`bundle_search\` with keywords to look up evidence by chunk_id.`,
+      `Cache key: ${path.basename(cachePath)}`,
+    ];
+    return lines.join("\n");
+  }
+
+  _hashBundle(resolved, maxTokens) {
+    const h = crypto.createHash("sha256");
+    h.update(`max_tokens:${maxTokens}\n`);
+    for (const { abs } of resolved) {
+      try {
+        const stat = fs.statSync(abs);
+        h.update(`${abs}|${stat.size}|${stat.mtimeMs}\n`);
+      } catch { h.update(`${abs}|?|?\n`); }
+    }
+    return h.digest("hex").slice(0, 16);
+  }
+
+  async _parseOne(requestedRelPath, absPath) {
+    const baseName = path.basename(absPath);
+    const suffix = path.extname(absPath).toLowerCase();
+
+    if (suffix === ".pdf") {
+      const blocks = await this._parsePdfPages(absPath);
+      return {
+        source_file: baseName,
+        total_pages: blocks.length || 1,
+        blocks: blocks.length > 0 ? blocks : [{ page: 1, markdown: "" }],
+      };
+    }
+
+    if (suffix === ".md" || suffix === ".txt") {
+      const txt = fs.readFileSync(absPath, "utf-8");
+      return {
+        source_file: baseName,
+        total_pages: 1,
+        blocks: [{ page: 1, markdown: txt }],
+      };
+    }
+
+    // For other formats (.docx, .xlsx, etc): read as UTF-8 best-effort.
+    // Upstream agent should call document_parse first and then document_chunk
+    // on the parsed output directly — current MVP keeps the tool surface small.
+    try {
+      const txt = fs.readFileSync(absPath, "utf-8");
+      return {
+        source_file: baseName,
+        total_pages: 1,
+        blocks: [{ page: 1, markdown: txt }],
+      };
+    } catch {
+      return {
+        source_file: baseName, total_pages: 0, blocks: [],
+        parse_error: `Unsupported format '${suffix}'. Run document_parse first and use its output, or stick to .pdf / .md / .txt.`,
+      };
+    }
+  }
+
+  async _parsePdfPages(absPath) {
+    const pdfjsLib = await import("pdfjs-dist/legacy/build/pdf.mjs");
+    const data = new Uint8Array(fs.readFileSync(absPath));
+    const doc = await pdfjsLib.getDocument({ data, useSystemFonts: true }).promise;
+    const blocks = [];
+    try {
+      for (let i = 0; i < doc.numPages; i++) {
+        let pageText = "";
+        try {
+          const page = await doc.getPage(i + 1);
+          const content = await page.getTextContent();
+          // Preserve line breaks reasonably well: group items by rough y-coord.
+          let lastY = null;
+          const out = [];
+          for (const item of content.items) {
+            const y = item.transform?.[5];
+            if (lastY !== null && Math.abs(y - lastY) > 2) out.push("\n");
+            else if (out.length > 0 && !out[out.length - 1].endsWith(" "))
+              out.push(" ");
+            out.push(item.str || "");
+            lastY = y;
+          }
+          pageText = out.join("").replace(/\s+\n/g, "\n").trim();
+        } catch { pageText = ""; }
+        blocks.push({ page: i + 1, markdown: pageText });
+      }
+    } finally {
+      try { await doc.destroy?.(); } catch { /* ignore */ }
+    }
+    return blocks;
+  }
+}

package/src/agent/tools/document-classify.js

@@ -0,0 +1,311 @@
+import fs from "node:fs";
+import path from "node:path";
+import { BaseTool, ToolResult } from "./base.js";
+import { BundleTree } from "../bundle-tree.js";
+import { LLMClient } from "../llm-client.js";
+
+const CACHE_SUBDIR = path.join("cache", "bundles");
+
+// Keep in sync with applicable_product_types / report_types arrays the
+// extraction pipeline uses when writing rules/catalog.json.
+const PRODUCT_TYPES = [
+  "公募产品", "私募产品", "现金管理类",
+  "理财产品", "信托计划", "保险资管产品",
+];
+const REPORT_TYPES = ["季报", "中报", "年报"];
+
+const CLASSIFIER_SYSTEM = [
+  "你是资管产品文档分类助理。用户提供一份文档包（一至多份文件，来自同一只",
+  "资管产品 / 合同 / 公司），你需要判断：",
+  "1. 产品类型（product_type）— 只能从以下取值中选一个：",
+  `   ${PRODUCT_TYPES.join(", ")}`,
+  "   若无法确定，填空字符串 \"\"。现金管理类优先于公募/私募（它是独立披露类别）。",
+  "2. 报告类型（report_type）— 只能从以下取值中选一个：",
+  `   ${REPORT_TYPES.join(", ")}`,
+  "   若文档是定期公告/定期报告但未明确周期，按季报处理。若无法确定，填 \"\"。",
+  "3. confidence — \"高\"/\"中\"/\"低\"",
+  "4. reasoning — 一句话说明判断依据，≤60 字",
+  "",
+  "严格按 JSON 输出，不要包裹代码块：",
+  "{\"product_type\":\"...\",\"report_type\":\"...\",\"confidence\":\"...\",\"reasoning\":\"...\"}",
+].join("\n");
+
+// Balanced-brace scan with string-awareness, for parsing LLM JSON even when
+// extra prose surrounds it. Mirrors classifier.py's `_parse_classifier_response`.
+const SMART_QUOTE_REPAIR = new Map([
+  ["\u201c", '"'], ["\u201d", '"'],
+  ["\u2018", "'"], ["\u2019", "'"],
+  ["\uff02", '"'], ["\uff1a", ":"], ["\uff0c", ","],
+]);
+
+function repairSmartQuotes(s) {
+  return s.replace(/[\u201c\u201d\u2018\u2019\uff02\uff1a\uff0c]/g,
+    (c) => SMART_QUOTE_REPAIR.get(c) || c);
+}
+
+function extractJsonObject(raw) {
+  if (!raw) return null;
+  let candidate = raw.trim();
+  // Strip ```json fences if present
+  const fence = candidate.match(/```(?:json)?\s*([\s\S]+?)```/);
+  if (fence) candidate = fence[1].trim();
+
+  const start = candidate.indexOf("{");
+  if (start < 0) return null;
+  let depth = 0, end = -1, inStr = false, esc = false;
+  for (let i = start; i < candidate.length; i++) {
+    const c = candidate[i];
+    if (esc) { esc = false; continue; }
+    if (inStr) {
+      if (c === "\\") esc = true;
+      else if (c === '"') inStr = false;
+      continue;
+    }
+    if (c === '"') inStr = true;
+    else if (c === "{") depth++;
+    else if (c === "}") {
+      depth--;
+      if (depth === 0) { end = i + 1; break; }
+    }
+  }
+  if (end < 0) return null;
+  const objStr = candidate.slice(start, end);
+  // Try: raw → strip trailing commas → strip + repair smart quotes
+  for (const attempt of [
+    objStr,
+    objStr.replace(/,\s*([}\]])/g, "$1"),
+    repairSmartQuotes(objStr.replace(/,\s*([}\]])/g, "$1")),
+  ]) {
+    try {
+      const obj = JSON.parse(attempt);
+      if (obj && typeof obj === "object") return obj;
+    } catch { /* try next */ }
+  }
+  return null;
+}
+
+/**
+ * Classify a BundleTree's product/report type in one LLM call, with a
+ * keyword-based fallback when the LLM is unreachable or returns unparseable
+ * output. The classification is cached alongside the BundleTree under
+ *   <workspace>/cache/bundles/<hash>.classification.json
+ * so successive calls on the same bundle are free.
+ *
+ * Used by the Group D applicability pre-filter: rules whose
+ * `applicable_product_types` / `report_types` don't overlap with the
+ * bundle classification can be skipped without a skill_authoring turn.
+ */
+export class DocumentClassifyTool extends BaseTool {
+  constructor(workspace, config) {
+    super();
+    this._workspace = workspace;
+    this._config = config;
+  }
+
+  get name() { return "document_classify"; }
+
+  get description() {
+    return (
+      "Classify a bundle's product type (公募/私募/现金管理类/...) and report type " +
+      "(季报/中报/年报) via a one-shot worker-LLM call over each file's first " +
+      "~5000 chars. Falls back to keyword matching on LLM failure. Requires a " +
+      "prior `document_chunk` call. Result is cached per bundle."
+    );
+  }
+
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        cache_key: {
+          type: "string",
+          description:
+            "BundleTree cache file name. Omit to use the most recently built bundle.",
+        },
+        force_refresh: {
+          type: "boolean",
+          description: "Re-classify even if a cached classification exists.",
+        },
+      },
+    };
+  }
+
+  async execute(input) {
+    const cacheKey = input?.cache_key || "";
+    const forceRefresh = input?.force_refresh === true;
+
+    const cacheDir = path.join(this._workspace.cwd, CACHE_SUBDIR);
+    if (!fs.existsSync(cacheDir)) {
+      return new ToolResult(
+        "No bundle cache found. Call `document_chunk` first.",
+        true,
+      );
+    }
+
+    let treePath;
+    if (cacheKey) {
+      treePath = path.join(cacheDir, cacheKey.endsWith(".json") ? cacheKey : `${cacheKey}.json`);
+      if (!fs.existsSync(treePath)) {
+        return new ToolResult(`BundleTree cache not found: ${cacheKey}`, true);
+      }
+    } else {
+      treePath = this._findMostRecentCache(cacheDir);
+      if (!treePath) return new ToolResult("No bundle cache found.", true);
+    }
+
+    const classificationPath = treePath.replace(/\.json$/, ".classification.json");
+    if (!forceRefresh && fs.existsSync(classificationPath)) {
+      try {
+        const cached = JSON.parse(fs.readFileSync(classificationPath, "utf-8"));
+        return new ToolResult(this._formatResult(cached, treePath, /*cached*/ true));
+      } catch { /* fall through */ }
+    }
+
+    let tree;
+    try {
+      tree = BundleTree.fromJSON(JSON.parse(fs.readFileSync(treePath, "utf-8")));
+    } catch (e) {
+      return new ToolResult(`Corrupt bundle cache: ${e.message}`, true);
+    }
+
+    // Try LLM first; fall back to keyword matching
+    const result = (await this._classifyLlm(tree)) || this._classifyKeyword(tree);
+
+    // Persist
+    try {
+      fs.writeFileSync(classificationPath, JSON.stringify(result, null, 2), "utf-8");
+    } catch { /* non-fatal */ }
+
+    return new ToolResult(this._formatResult(result, treePath, /*cached*/ false));
+  }
+
+  async _classifyLlm(tree) {
+    // Use conductor config for classification. The main-LLM config is always
+    // available; the worker LLM tier is phase-gated (distill-only) and
+    // classification runs during extraction, so we intentionally use the
+    // conductor here even though the AMC Python version uses a worker call.
+    const apiKey = this._config?.llmApiKey || "";
+    const baseUrl = this._config?.llmBaseUrl || "";
+    const model = this._config?.kcModel || "";
+    if (!apiKey || !baseUrl || !model) return null;
+
+    // Build prompt: each file's head (up to 5000 chars), concatenated
+    const fileBlocks = [];
+    const files = tree.files();
+    for (const f of files) {
+      const src = f.source_file || f.title || "(未命名文件)";
+      let text = "";
+      for (const cid of tree.leaves_order) {
+        const ch = tree.chunks[cid];
+        if (!ch || ch.source_file !== src) continue;
+        text += (ch.content || "") + "\n\n";
+        if (text.length >= 5000) break;
+      }
+      fileBlocks.push(`【文件名】${src}\n【前 5000 字预览】\n${text.slice(0, 5000).trim()}`);
+    }
+    const userMsg =
+      `=== 文档包（共 ${fileBlocks.length} 份文件）===\n\n` +
+      fileBlocks.join("\n\n---\n\n") +
+      "\n\n按格式输出 JSON。";
+
+    const client = new LLMClient({
+      apiKey, baseUrl,
+      authType: this._config?.authType || "bearer",
+      apiFormat: this._config?.apiFormat || "openai",
+    });
+    let resp;
+    try {
+      resp = await client.chat({
+        model,
+        messages: [
+          { role: "system", content: CLASSIFIER_SYSTEM },
+          { role: "user", content: userMsg },
+        ],
+        maxTokens: 400,
+      });
+    } catch {
+      return null;
+    }
+
+    const content = resp?.choices?.[0]?.message?.content || "";
+    const parsed = extractJsonObject(content);
+    if (!parsed) return null;
+
+    const product = String(parsed.product_type || "").trim();
+    const report = String(parsed.report_type || "").trim();
+    const confidence = String(parsed.confidence || "").trim() || "中";
+    const reasoning = String(parsed.reasoning || "").trim().slice(0, 200);
+
+    return {
+      product_type: product,
+      report_type: report,
+      confidence,
+      reasoning,
+      source: "llm",
+      model,
+    };
+  }
+
+  _classifyKeyword(tree) {
+    const out = {
+      product_type: "",
+      report_type: "",
+      confidence: "低",
+      reasoning: "关键字规则匹配（LLM 分类不可用时的兜底）",
+      source: "keyword_fallback",
+    };
+    let head = "";
+    for (const cid of tree.leaves_order.slice(0, 8)) {
+      const ch = tree.chunks[cid];
+      head += "\n" + (ch?.content || "");
+      if (head.length > 6000) break;
+    }
+    if (head.includes("现金管理") || head.includes("摊余成本法")) {
+      out.product_type = "现金管理类";
+    } else if (head.includes("公募")) out.product_type = "公募产品";
+    else if (head.includes("私募") || head.includes("合格投资者")) out.product_type = "私募产品";
+    else if (head.includes("理财")) out.product_type = "理财产品";
+    else if (head.includes("信托")) out.product_type = "信托计划";
+    else if (head.includes("保险")) out.product_type = "保险资管产品";
+
+    if (head.includes("年度报告") || head.includes("年报")) out.report_type = "年报";
+    else if (head.includes("半年度") || head.includes("中报")) out.report_type = "中报";
+    else if (head.includes("季度") || head.includes("季报") ||
+             head.includes("第4 季度") || head.includes("第3 季度"))
+      out.report_type = "季报";
+    else if (head.includes("定期公告") || head.includes("定期报告"))
+      out.report_type = "季报";
+
+    return out;
+  }
+
+  _formatResult(cls, treePath, cached) {
+    const rel = path.relative(this._workspace.cwd, treePath) || treePath;
+    return [
+      `${cached ? "Cached" : "Fresh"} classification · bundle ${path.basename(treePath)}`,
+      `  product_type : ${cls.product_type || "(unknown)"}`,
+      `  report_type  : ${cls.report_type || "(unknown)"}`,
+      `  confidence   : ${cls.confidence || "?"}`,
+      `  source       : ${cls.source}${cls.model ? ` · ${cls.model}` : ""}`,
+      `  reasoning    : ${cls.reasoning || "(none)"}`,
+      "",
+      `Persisted to ${rel.replace(/\.json$/, ".classification.json")}.`,
+    ].join("\n");
+  }
+
+  _findMostRecentCache(cacheDir) {
+    let entries;
+    try { entries = fs.readdirSync(cacheDir); }
+    catch { return null; }
+    const candidates = entries
+      .filter((n) => n.endsWith(".json") && !n.endsWith(".classification.json"))
+      .map((n) => {
+        const full = path.join(cacheDir, n);
+        try { return { full, mtime: fs.statSync(full).mtimeMs }; }
+        catch { return null; }
+      })
+      .filter(Boolean)
+      .sort((a, b) => b.mtime - a.mtime);
+    return candidates[0]?.full || null;
+  }
+}

package/src/agent/tools/document-parse.js

@@ -113,8 +113,15 @@ export class DocumentParseTool extends BaseTool {
 
     if (result) return new ToolResult(this._formatOutput(result, "pdfjs (low quality)", resolved));
 
+    // A7: Original message implied worker-LLM setup was missing which
+    // confused users in early phases (BOOTSTRAP/EXTRACTION) where the
+    // worker LLM is intentionally inactive anyway. Clearer phrasing: name
+    // exactly what's needed and where to set it, and why.
+    const ocrHint = this._ocrModel
+      ? `Tried pdfjs / VLM (${this._ocrModel}) / MineRU; all failed — the file may be encrypted, corrupted, or an unsupported format.`
+      : `pdfjs extraction failed. Set VLM_TIER1 in the workspace .env to enable OCR fallback for image-based / scanned PDFs.`;
     return new ToolResult(
-      `Could not extract text from ${pathStr}. Configure OCR models in .env for image-based documents.`,
+      `Could not extract text from ${pathStr}. ${ocrHint}`,
       true,
     );
   }

package/src/agent/tools/phase-advance.js

@@ -14,9 +14,18 @@ const VALID_PHASES = new Set(Object.values(Phase));
  * asks). Description kept short to minimize system-prompt budget cost.
  */
 export class PhaseAdvanceTool extends BaseTool {
-  constructor(advanceFn) {
+  /**
+   * @param {(to: string, reason: string, opts: {force?: boolean}) => boolean} advanceFn
+   * @param {() => string} getCurrentPhaseFn - H1: lets the tool read the
+   *   engine's phase BEFORE the call, so it can distinguish "already there"
+   *   (silent no-op, informational) from "non-adjacent refusal" (actionable).
+   *   Before H1 both cases returned the same confusing "Either you're already
+   *   there, or transition is non-adjacent" message.
+   */
+  constructor(advanceFn, getCurrentPhaseFn) {
     super();
     this._advance = advanceFn;
+    this._getCurrentPhase = getCurrentPhaseFn || (() => null);
   }
 
   get name() { return "phase_advance"; }
@@ -47,14 +56,28 @@ export class PhaseAdvanceTool extends BaseTool {
   async execute(input) {
     const to = input.to;
     if (!VALID_PHASES.has(to)) return new ToolResult(`Unknown phase: ${to}`, true);
-    const advanced = this._advance(to, input.reason || "agent request", { force: !!input.force });
-    if (!advanced) {
-      // Either already in target phase, or non-adjacent without force
+
+    const beforePhase = this._getCurrentPhase();
+    // H1: short-circuit the "already in target" case with an informational
+    // message — the agent was trying to advance correctly, engine just
+    // auto-advanced ahead of it (common when _maybeAutoAdvance fires on a
+    // criteria flip). Treat as success, not refusal.
+    if (beforePhase && beforePhase === to) {
       return new ToolResult(
-        `Did not advance to ${to}. Either you're already there, or the transition is non-adjacent (set force:true to override).`,
-        false,
+        `Already in phase ${to} (engine auto-advanced earlier via criteria flip or prior explicit call). Proceed with phase-appropriate work.`,
       );
     }
-    return new ToolResult(`Advanced to ${to}${input.force ? " (forced)" : ""}`);
+
+    const advanced = this._advance(to, input.reason || "agent request", { force: !!input.force });
+    if (advanced) {
+      return new ToolResult(`Advanced${beforePhase ? ` from ${beforePhase}` : ""} to ${to}${input.force ? " (forced)" : ""}`);
+    }
+
+    // Truly refused — non-adjacent transition without force, or terminal-phase
+    // forward attempt. Give the actionable hint.
+    return new ToolResult(
+      `Did not advance to ${to}. Transition is non-adjacent${beforePhase ? ` (currently in ${beforePhase})` : ""} — set force:true to override, or advance to the immediate-next phase first.`,
+      false,
+    );
   }
 }

package/src/agent/tools/registry.js

@@ -52,4 +52,14 @@ export class ToolRegistry {
   get size() {
     return this._tools.size;
   }
+
+  /** F5: tool names currently registered. */
+  names() {
+    return Array.from(this._tools.keys()).sort();
+  }
+
+  /** F5: lookup a specific tool — used by diagnostics/UI. */
+  get(name) {
+    return this._tools.get(name);
+  }
 }

package/src/agent/tools/rule-catalog.js

@@ -85,11 +85,25 @@ export class RuleCatalogTool extends BaseTool {
     const ruleId = input.rule_id || "";
     const data = input.data || {};
 
+    // read operations don't need the lock — they're read-only
     if (op === "list") return this._list();
     if (op === "read") return this._read(ruleId || data.id || "");
-    if (op === "create") return this._create(data);
-    if (op === "update") return this._update(ruleId || data.id || "", data);
-    if (op === "delete") return this._delete(ruleId || data.id || "");
+
+    // B9: write operations acquire the catalog lock so concurrent engines
+    // (main + subagents + sandbox_exec-via-workspace_file) serialize their
+    // read-modify-write on catalog.json. Without this, two writers can
+    // both read N rules, one writes N+1, the other writes N+1 of its own,
+    // and one write is silently lost — exactly what we saw in session
+    // 6304673afaa0 thrashing catalog rule counts.
+    if (op === "create") {
+      return this._workspace.withFileLock("rules/catalog.json", () => this._create(data));
+    }
+    if (op === "update") {
+      return this._workspace.withFileLock("rules/catalog.json", () => this._update(ruleId || data.id || "", data));
+    }
+    if (op === "delete") {
+      return this._workspace.withFileLock("rules/catalog.json", () => this._delete(ruleId || data.id || ""));
+    }
     // More helpful than "Unknown operation: " — tells the agent exactly what's
     // allowed and what shape to call with next time (observed in v0.5.3 E2E
     // where GLM-5.1 sent input: {} 38+ times without learning).