@fenglimg/fabric-cli 2.0.0-rc.36 → 2.0.0-rc.38

package/templates/hooks/knowledge-hint-broad.cjs

@@ -47,14 +47,8 @@
  */
 
 const { spawnSync } = require("node:child_process");
-const {
-  existsSync,
-  mkdirSync,
-  readdirSync,
-  readFileSync,
-  writeFileSync,
-} = require("node:fs");
-const { dirname, join } = require("node:path");
+const { existsSync, readdirSync, readFileSync } = require("node:fs");
+const { join } = require("node:path");
 
 // rc.16 TASK-003: shared banner-i18n lib (resolves fabric_language config and
 // renders localized banner text). Mirror of the wiring in fabric-hint.cjs
@@ -62,6 +56,18 @@ const { dirname, join } = require("node:path");
 // readFabricLanguage(cwd) and threaded into renderBanner — no fs in render path.
 const { renderBanner, readFabricLanguage } = require("./lib/banner-i18n.cjs");
 const { resolveOpaqueSummaries } = require("./lib/summary-fallback.cjs");
+// v2.0.0-rc.37 NEW-19: shared fabric-config reader + sidecar I/O. Replaces the
+// five per-key readFileSync+parse config readers (one parse per fire now) and
+// the bespoke last-emit sidecar helpers. The L78 "refactor into lib/ if a
+// third hook needs it" note is now realised.
+const {
+  readConfigNumber,
+  readConfigBoolean,
+} = require("./lib/config-cache.cjs");
+const { readTextState, writeTextState } = require("./lib/state-store.cjs");
+// v2.0.0-rc.37 NEW-30: shared client detection (replaces the inline
+// CLAUDE_PROJECT_DIR single-bit check below).
+const { isClaudeCode } = require("./lib/client-adapter.cjs");
 
 // -----------------------------------------------------------------------------
 // rc.12: SessionStart broad-menu is now unconditionally emitted on every
@@ -80,7 +86,6 @@ const FABRIC_DIR_REL = ".fabric";
 // cannot `require` each other. If a third hook ever needs the same logic,
 // refactor into packages/cli/templates/hooks/lib/. Keep these values in sync
 // with packages/cli/templates/hooks/fabric-hint.cjs.
-const FABRIC_CONFIG_FILE = "fabric-config.json";
 const AGENTS_META_FILE = "agents.meta.json";
 const IMPORT_STATE_FILE = ".import-state.json";
 const KNOWLEDGE_CANONICAL_TYPES = [
@@ -104,11 +109,8 @@ const DEFAULT_HINT_BROAD_TOP_K = 8;
 // so the two cooldowns don't interfere.
 const DEFAULT_HINT_BROAD_COOLDOWN_HOURS = 0;
 const MS_PER_HOUR = 60 * 60 * 1000;
-const HINT_BROAD_LAST_EMIT_FILE = join(
-  ".fabric",
-  ".cache",
-  "knowledge-hint-broad-last-emit",
-);
+// v2.0.0-rc.37 NEW-19: state-store resolves this basename under .fabric/.cache/.
+const HINT_BROAD_LAST_EMIT_FILE_NAME = "knowledge-hint-broad-last-emit";
 
 // v2.0.0-rc.33 W2-6 (P0-7): when true, emit banner as
 // hookSpecificOutput.additionalContext JSON on stdout (Claude Code PreToolUse
@@ -168,16 +170,11 @@ function countCanonicalNodes(projectRoot) {
  * Any read/parse failure → default (never block on config errors).
  */
 function readUnderseedThreshold(projectRoot) {
-  const configPath = join(projectRoot, FABRIC_DIR_REL, FABRIC_CONFIG_FILE);
-  if (!existsSync(configPath)) return DEFAULT_UNDERSEED_NODE_THRESHOLD;
-  try {
-    const parsed = JSON.parse(readFileSync(configPath, "utf8"));
-    const v = parsed && parsed.underseed_node_threshold;
-    if (typeof v === "number" && Number.isFinite(v) && v > 0) return v;
-  } catch {
-    // fall through to default
-  }
-  return DEFAULT_UNDERSEED_NODE_THRESHOLD;
+  // > 0 guard via min: Number.MIN_VALUE (any positive). config-cache returns
+  // the parsed number when finite & in-range, else the default.
+  return readConfigNumber(projectRoot, "underseed_node_threshold", DEFAULT_UNDERSEED_NODE_THRESHOLD, {
+    min: Number.MIN_VALUE,
+  });
 }
 
 /**
@@ -186,18 +183,11 @@ function readUnderseedThreshold(projectRoot) {
  * schema's 1..50 range inline so a malformed config silently falls back.
  */
 function readBroadTopK(projectRoot) {
-  const configPath = join(projectRoot, FABRIC_DIR_REL, FABRIC_CONFIG_FILE);
-  if (!existsSync(configPath)) return DEFAULT_HINT_BROAD_TOP_K;
-  try {
-    const parsed = JSON.parse(readFileSync(configPath, "utf8"));
-    const v = parsed && parsed.hint_broad_top_k;
-    if (typeof v === "number" && Number.isFinite(v) && v >= 1 && v <= 50) {
-      return Math.floor(v);
-    }
-  } catch {
-    // fall through to default
-  }
-  return DEFAULT_HINT_BROAD_TOP_K;
+  return readConfigNumber(projectRoot, "hint_broad_top_k", DEFAULT_HINT_BROAD_TOP_K, {
+    min: 1,
+    max: 50,
+    floor: true,
+  });
 }
 
 /**
@@ -205,18 +195,10 @@ function readBroadTopK(projectRoot) {
  * 0 means "no cooldown" (re-emit on every SessionStart, rc.32 behavior).
  */
 function readBroadCooldownHours(projectRoot) {
-  const configPath = join(projectRoot, FABRIC_DIR_REL, FABRIC_CONFIG_FILE);
-  if (!existsSync(configPath)) return DEFAULT_HINT_BROAD_COOLDOWN_HOURS;
-  try {
-    const parsed = JSON.parse(readFileSync(configPath, "utf8"));
-    const v = parsed && parsed.hint_broad_cooldown_hours;
-    if (typeof v === "number" && Number.isFinite(v) && v >= 0 && v <= 168) {
-      return v;
-    }
-  } catch {
-    // fall through to default
-  }
-  return DEFAULT_HINT_BROAD_COOLDOWN_HOURS;
+  return readConfigNumber(projectRoot, "hint_broad_cooldown_hours", DEFAULT_HINT_BROAD_COOLDOWN_HOURS, {
+    min: 0,
+    max: 168,
+  });
 }
 
 /**
@@ -226,16 +208,7 @@ function readBroadCooldownHours(projectRoot) {
  * receives the reminder in-context. Stderr stays informational either way.
  */
 function readReminderToContext(projectRoot) {
-  const configPath = join(projectRoot, FABRIC_DIR_REL, FABRIC_CONFIG_FILE);
-  if (!existsSync(configPath)) return DEFAULT_HINT_REMINDER_TO_CONTEXT;
-  try {
-    const parsed = JSON.parse(readFileSync(configPath, "utf8"));
-    const v = parsed && parsed.hint_reminder_to_context;
-    if (typeof v === "boolean") return v;
-  } catch {
-    // fall through to default
-  }
-  return DEFAULT_HINT_REMINDER_TO_CONTEXT;
+  return readConfigBoolean(projectRoot, "hint_reminder_to_context", DEFAULT_HINT_REMINDER_TO_CONTEXT);
 }
 
 /**
@@ -244,31 +217,18 @@ function readReminderToContext(projectRoot) {
  * Returns epoch ms or null when missing/unreadable.
  */
 function readBroadLastEmit(projectRoot) {
-  const p = join(projectRoot, HINT_BROAD_LAST_EMIT_FILE);
-  if (!existsSync(p)) return null;
-  try {
-    const raw = readFileSync(p, "utf8").trim();
-    if (raw.length === 0) return null;
-    const asNum = Number(raw);
-    if (Number.isFinite(asNum) && asNum > 0) return asNum;
-    const ms = Date.parse(raw);
-    if (Number.isFinite(ms)) return ms;
-  } catch {
-    // ignore
-  }
+  const raw = readTextState(projectRoot, HINT_BROAD_LAST_EMIT_FILE_NAME);
+  if (raw === null || raw.length === 0) return null;
+  const asNum = Number(raw);
+  if (Number.isFinite(asNum) && asNum > 0) return asNum;
+  const ms = Date.parse(raw);
+  if (Number.isFinite(ms)) return ms;
   return null;
 }
 
 function writeBroadLastEmit(projectRoot, nowMs) {
-  const p = join(projectRoot, HINT_BROAD_LAST_EMIT_FILE);
-  try {
-    if (!existsSync(dirname(p))) {
-      mkdirSync(dirname(p), { recursive: true });
-    }
-    writeFileSync(p, String(nowMs));
-  } catch {
-    // Silent — sidecar failure must never block session start.
-  }
+  // Silent — sidecar failure must never block session start.
+  writeTextState(projectRoot, HINT_BROAD_LAST_EMIT_FILE_NAME, String(nowMs));
 }
 
 /**
@@ -368,18 +328,11 @@ const CLI_TIMEOUT_MS = 2000;
 const DEFAULT_SUMMARY_MAX_LEN = 80;
 
 function readSummaryMaxLen(projectRoot) {
-  const configPath = join(projectRoot, FABRIC_DIR_REL, FABRIC_CONFIG_FILE);
-  if (!existsSync(configPath)) return DEFAULT_SUMMARY_MAX_LEN;
-  try {
-    const parsed = JSON.parse(readFileSync(configPath, "utf8"));
-    const v = parsed && parsed.hint_summary_max_len;
-    if (typeof v === "number" && Number.isFinite(v) && v >= 40 && v <= 240) {
-      return Math.floor(v);
-    }
-  } catch {
-    // fall through to default
-  }
-  return DEFAULT_SUMMARY_MAX_LEN;
+  return readConfigNumber(projectRoot, "hint_summary_max_len", DEFAULT_SUMMARY_MAX_LEN, {
+    min: 40,
+    max: 240,
+    floor: true,
+  });
 }
 
 // Canonical type order — render groups in this sequence so output is stable
@@ -771,17 +724,27 @@ function main(env, stdio) {
     const summaryMaxLen = readSummaryMaxLen(cwd);
     const lines = renderSummary(resolvedPayload, summaryMaxLen);
 
-    if (recommendImport) {
-      // rc.16 TASK-003: resolve fabric_language ONCE per invocation (only when
-      // we actually need to emit the banner — keeps the no-banner path free of
-      // the extra config read). 'match-existing' / unknown variant folds to 'en'
-      // inside renderBanner per UX i18n Policy class 1.
-      const variant = readFabricLanguage(cwd);
-      lines.push(renderBanner("broadImportBanner", variant, {}));
+    // v2.0.0-rc.37 NEW-23: resolve fabric_language ONCE per emit path —
+    // shared between the (existing) broadImportBanner branch and the new
+    // 'next step' nudge tail added below. 'match-existing' / unknown variants
+    // fold to 'en' inside renderBanner per UX i18n Policy class 1.
+    const fabricLanguageForEmit = lines.length > 0 || recommendImport ? readFabricLanguage(cwd) : null;
+    if (recommendImport && fabricLanguageForEmit !== null) {
+      lines.push(renderBanner("broadImportBanner", fabricLanguageForEmit, {}));
     }
 
     if (lines.length === 0) return; // nothing to say — silent exit
 
+    // v2.0.0-rc.37 NEW-23: SessionStart 索引末尾"下一步"引导。Tail line that
+    // tells the AI what to do with the broad index it just received. Without
+    // this, the model often parses the index and moves on without ever calling
+    // fab_recall / fab_plan_context. One-line nudge, bilingual.
+    const nextStepNudge =
+      fabricLanguageForEmit === "zh-CN"
+        ? "下一步: 调 fab_recall(paths) 拿 KB 相关条目;或调 fab_plan_context 先看候选 description_index。"
+        : "Next: call fab_recall(paths) to fetch related KB entries, or fab_plan_context to preview the description_index first.";
+    lines.push(nextStepNudge);
+
     // Stderr: always emit (human-facing breadcrumb + legacy contract).
     for (const line of lines) {
       err.write(`${line}\n`);
@@ -802,11 +765,9 @@ function main(env, stdio) {
     // either polluting the terminal or crashing the host's hook-parsing
     // pipeline. CLAUDE_PROJECT_DIR is set by CC when invoking hooks (see
     // packages/cli/templates/hooks/configs/claude-code.json sigil paths);
-    // its presence is the single-bit "this is Claude Code" signal.
-    const isClaudeCode =
-      typeof process.env.CLAUDE_PROJECT_DIR === "string" &&
-      process.env.CLAUDE_PROJECT_DIR.length > 0;
-    const reminderToContext = readReminderToContext(cwd) && isClaudeCode;
+    // its presence is the single-bit "this is Claude Code" signal (now via
+    // the shared client-adapter, rc.37 NEW-30).
+    const reminderToContext = readReminderToContext(cwd) && isClaudeCode();
     if (reminderToContext && !(env && env.skipStdout === true)) {
       try {
         const envelope = {
@@ -867,7 +828,7 @@ module.exports = {
     DEFAULT_HINT_BROAD_TOP_K,
     DEFAULT_HINT_BROAD_COOLDOWN_HOURS,
     DEFAULT_HINT_REMINDER_TO_CONTEXT,
-    HINT_BROAD_LAST_EMIT_FILE,
+    HINT_BROAD_LAST_EMIT_FILE_NAME,
   },
 };
 

package/templates/hooks/knowledge-hint-narrow.cjs

@@ -71,6 +71,7 @@ const {
   mkdirSync,
   readFileSync,
   renameSync,
+  statSync,
   writeFileSync,
 } = require("node:fs");
 const { dirname, join } = require("node:path");
@@ -80,6 +81,10 @@ const { dirname, join } = require("node:path");
 // entry's .md `## Summary` section. Caches results in
 // `.fabric/.cache/summary-fallback.json` keyed by revision_hash.
 const { resolveOpaqueSummaries } = require("./lib/summary-fallback.cjs");
+// v2.0.0-rc.37 NEW-17: shared sidecar I/O for the plan-context-hint result
+// cache (skips a redundant CLI cold-start spawn when the same path-set is
+// re-edited within a session and the knowledge graph hasn't changed).
+const { readJsonState, writeJsonState } = require("./lib/state-store.cjs");
 
 // -----------------------------------------------------------------------------
 // CONSTANTS
@@ -148,6 +153,9 @@ const EDIT_TOOL_NAMES = new Set(["Edit", "Write", "MultiEdit"]);
 // are duplicated inline. Keep these in sync if the schema changes.
 const FABRIC_DIR_REL = ".fabric";
 const FABRIC_CONFIG_FILE = "fabric-config.json";
+// rc.37 NEW-17: derived index the server rewrites on any knowledge edit; its
+// mtime is the cheap freshness token for the plan-context-hint result cache.
+const AGENTS_META_FILE = "agents.meta.json";
 
 // W2-1 (P0-9): narrow TopK upper bound. Five matches the per-Edit hint
 // "terse banner" UX: any more and the model's working memory bloats.
@@ -350,7 +358,7 @@ function extractPaths(toolInput) {
  *     POSIX) is atomic at the OS level, so concurrent PreToolUse fires
  *     from parallel sessions interleave cleanly without partial writes.
  */
-function appendEditIntentToLedger(projectRoot, now, paths, toolName) {
+function appendEditIntentToLedger(projectRoot, now, paths, toolName, sessionId) {
   try {
     const fabricDir = join(projectRoot, EVENTS_LEDGER_DIR_REL);
     // No .fabric/ → project not initialised. Bail before any write.
@@ -375,12 +383,20 @@ function appendEditIntentToLedger(projectRoot, now, paths, toolName) {
     const tsMs = now instanceof Date ? now.getTime() : Number(now);
     const ledgerEntryId = `hook:${randomUUID()}`;
     const intent = typeof toolName === "string" && toolName.length > 0 ? toolName : "edit";
+    // rc.38 UX-8 (C): thread the REAL payload session_id (never the synthetic
+    // fallback) so doctor cite-coverage's expected_but_missed arm can correlate
+    // this edit against the same session's assistant_turn cite lines. Omitting
+    // it (the rc.35 oversight) left the correlation key undefined → missed
+    // permanently 0 → cite_compliance_rate structurally pinned at 100%.
+    const validSessionId =
+      typeof sessionId === "string" && sessionId.length > 0 ? sessionId : null;
     const lines = pathList
       .map((p) => JSON.stringify({
         kind: "fabric-event",
         id: `event:${randomUUID()}`,
         ts: tsMs,
         schema_version: 1,
+        ...(validSessionId ? { session_id: validSessionId } : {}),
         event_type: "edit_intent_checked",
         path: p,
         compliant: true,
@@ -777,6 +793,84 @@ function invokePlanContextHint(cwd, paths) {
   return null;
 }
 
+// -----------------------------------------------------------------------------
+// v2.0.0-rc.37 NEW-17 — plan-context-hint result cache (per-session).
+//
+// Each PreToolUse fire is a separate process, so "in-memory" caching means a
+// per-session sidecar of the CLI result keyed on the edited path-set. A repeat
+// edit to the same file(s) — common during iterative work on one module —
+// re-reads the cached result instead of paying another `fabric plan-context-
+// hint` cold-start spawn (~50-150ms). MultiEdit's N paths already collapse to
+// ONE spawn (extractPaths dedupes + invokePlanContextHint joins --paths); this
+// cache extends that win across fires within a stable knowledge graph.
+//
+// Freshness: the cache is invalidated wholesale when `.fabric/agents.meta.json`
+// mtime changes (the derived index the server rewrites on any knowledge edit).
+// This is a cheap stat — no spawn — so the freshness check itself is ~free.
+// -----------------------------------------------------------------------------
+
+// Bound the per-session result map so a long stable session editing many
+// distinct files can't grow the sidecar without limit.
+const NARROW_RESULT_CACHE_MAX_ENTRIES = 50;
+
+function metaFreshnessToken(cwd) {
+  try {
+    const metaPath = join(cwd, FABRIC_DIR_REL, AGENTS_META_FILE);
+    if (!existsSync(metaPath)) return null;
+    return statSync(metaPath).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+function narrowResultCacheFileName(sessionId) {
+  const safe = String(sessionId || "anonymous").replace(/[^A-Za-z0-9_.-]/g, "-");
+  return `narrow-result-cache-${safe}.json`;
+}
+
+// Order-independent key for a path-set (sorted + NUL-joined so [a,b] and [b,a]
+// hit the same cache slot).
+function pathSetKey(paths) {
+  return [...paths].sort().join("");
+}
+
+// Returns the cached cliPayload for `paths` iff the cache's meta token matches
+// the current knowledge-graph freshness, else null (caller spawns the CLI).
+function readNarrowResultCache(cwd, sessionId, paths, metaToken) {
+  if (metaToken === null) return null;
+  const cache = readJsonState(
+    cwd,
+    narrowResultCacheFileName(sessionId),
+    (parsed) => parsed && typeof parsed === "object" && parsed.results && typeof parsed.results === "object",
+  );
+  if (!cache || cache.meta_token !== metaToken) return null;
+  const hit = cache.results[pathSetKey(paths)];
+  return hit && typeof hit === "object" ? hit : null;
+}
+
+// Persist `cliPayload` under the path-set key. Resets the map when the meta
+// token changed (stale graph) and caps the map size (FIFO-ish: drop oldest
+// insertion-order keys). Best-effort — never throws.
+function writeNarrowResultCache(cwd, sessionId, paths, metaToken, cliPayload) {
+  if (metaToken === null) return;
+  const fileName = narrowResultCacheFileName(sessionId);
+  const prior = readJsonState(
+    cwd,
+    fileName,
+    (parsed) => parsed && typeof parsed === "object" && parsed.results && typeof parsed.results === "object",
+  );
+  const results =
+    prior && prior.meta_token === metaToken && prior.results ? { ...prior.results } : {};
+  results[pathSetKey(paths)] = cliPayload;
+  const keys = Object.keys(results);
+  if (keys.length > NARROW_RESULT_CACHE_MAX_ENTRIES) {
+    for (const stale of keys.slice(0, keys.length - NARROW_RESULT_CACHE_MAX_ENTRIES)) {
+      delete results[stale];
+    }
+  }
+  writeJsonState(cwd, fileName, { meta_token: metaToken, results });
+}
+
 // -----------------------------------------------------------------------------
 // v2.0.0-rc.33 W2 — fabric-config readers + per-file dedup-window sidecar.
 //
@@ -1163,7 +1257,15 @@ function main(env, stdio) {
       // events.jsonl ledger so doctor cite-coverage's editsTouched metric
       // sees actual edit signals. Best-effort — failure is swallowed inside
       // appendEditIntentToLedger and does not block the hook.
-      appendEditIntentToLedger(cwd, now, paths, toolName);
+      // rc.38 UX-8 (C): pass the REAL payload session_id (not resolveSessionId,
+      // which would substitute a synthetic per-process id that matches no
+      // assistant_turn and would inflate expected_but_missed with false
+      // positives under --client=all). null when the client omits session_id.
+      const payloadSessionId =
+        payload && typeof payload === "object" && typeof payload.session_id === "string"
+          ? payload.session_id
+          : null;
+      appendEditIntentToLedger(cwd, now, paths, toolName, payloadSessionId);
     }
 
     // E2 path is conditional on a recognized tool + extractable paths.
@@ -1189,12 +1291,37 @@ function main(env, stdio) {
       }
     }
 
+    // Resolve session id up-front (needed for the rc.37 NEW-17 result cache
+    // key, and reused by the E3 emit-gate below).
+    const sessionId = resolveSessionId(payload, env);
+
     // Test seam: env.cliResult short-circuits the CLI spawn so unit tests
     // can feed canned plan-context-hint JSON without a built CLI binary.
-    const cliPayload =
-      env && env.cliResult !== undefined
-        ? env.cliResult
-        : invokePlanContextHint(cwd, paths);
+    //
+    // rc.37 NEW-17: when not in test-seam mode, first consult the per-session
+    // result cache keyed on the edited path-set. A hit (same paths, unchanged
+    // knowledge-graph mtime) skips the redundant `fabric plan-context-hint`
+    // cold-start spawn. Misses spawn the CLI then populate the cache. The
+    // env.skipResultCache seam disables both read+write for tests asserting
+    // raw spawn behaviour.
+    let cliPayload;
+    if (env && env.cliResult !== undefined) {
+      cliPayload = env.cliResult;
+    } else {
+      const useResultCache = !(env && env.skipResultCache === true);
+      const metaToken = useResultCache ? metaFreshnessToken(cwd) : null;
+      const cached = useResultCache
+        ? readNarrowResultCache(cwd, sessionId, paths, metaToken)
+        : null;
+      if (cached !== null) {
+        cliPayload = cached;
+      } else {
+        cliPayload = invokePlanContextHint(cwd, paths);
+        if (useResultCache && cliPayload !== null && cliPayload !== undefined) {
+          writeNarrowResultCache(cwd, sessionId, paths, metaToken, cliPayload);
+        }
+      }
+    }
     if (cliPayload === null || cliPayload === undefined) return;
 
     // Protocol v2 (rc.18 TASK-005): wire field is `entries`, no v1 shim.
@@ -1249,7 +1376,7 @@ function main(env, stdio) {
     // can add the counter increment either here (before the early return)
     // or inside applyEmitGate when render === false.
     // -------------------------------------------------------------------------
-    const sessionId = resolveSessionId(payload, env);
+    // sessionId already resolved up-front (rc.37 NEW-17) for the result cache.
     const currentRevisionHash =
       typeof cliPayload.revision_hash === "string" ? cliPayload.revision_hash : "";
     // Test seam: env.cacheSeed short-circuits the on-disk cache read so unit
@@ -1418,6 +1545,12 @@ module.exports = {
   writeNarrowDedupWindow,
   applyNarrowDedupWindow,
   readSummaryMaxLen,
+  // v2.0.0-rc.37 NEW-17 — plan-context-hint result cache exports for tests.
+  metaFreshnessToken,
+  narrowResultCacheFileName,
+  pathSetKey,
+  readNarrowResultCache,
+  writeNarrowResultCache,
   CONSTANTS: {
     CLI_TIMEOUT_MS,
     SUMMARY_MAX_LEN: DEFAULT_SUMMARY_MAX_LEN,

package/templates/hooks/lib/cite-line-parser.cjs

@@ -35,10 +35,16 @@ const FULL_RE =
 const CHAINED_FROM_ID_RE = /chained-from\s+(K[TP]-[A-Z]+-\d+)/i;
 
 const ALLOWED_TAGS = new Set([
+  // v2.0.0-rc.37 NEW-1: new simplified 2-state tag set ([applied] / [dismissed]).
+  // Old 4-state tags (planned / recalled / chained-from) accepted for
+  // backward compat — they continue to parse and count toward cite-coverage
+  // so in-flight workspaces don't lose their existing audit signal.
+  "applied",
+  "dismissed",
+  // Legacy tags (rc ≤36).
   "planned",
   "recalled",
   "chained-from",
-  "dismissed",
   "none",
 ]);
 

package/templates/hooks/lib/client-adapter.cjs

@@ -0,0 +1,106 @@
+/**
+ * v2.0.0-rc.37 NEW-30: shared client-protocol adapter for hook scripts.
+ *
+ * The three host clients (Claude Code / Codex CLI / Cursor) differ in how a
+ * hook surfaces context back to the model:
+ *   - Claude Code reads a stdout JSON envelope
+ *     ({ hookSpecificOutput: { hookEventName, additionalContext } }).
+ *   - Codex CLI and Cursor read plain stderr text.
+ * Each hook had its own copy of the detect-client + read-stdin + pick-channel
+ * logic (fabric-hint.detectClient, cite-policy-evict.isClaudeCode + readStdinJson,
+ * knowledge-hint-broad inline CLAUDE_PROJECT_DIR check). This module is the
+ * single canonical implementation so the protocol choice lives in one place.
+ *
+ * Provides:
+ *   - detectClient(dirnameHint?) → 'cc' | 'codex' | 'cursor' | undefined
+ *       3-tier: FABRIC_HINT_CLIENT env override → CLAUDE_PROJECT_DIR (cc) →
+ *       __dirname path heuristic (.claude / .codex / .cursor). dirnameHint
+ *       defaults to this lib's own dir (which still lives under the client
+ *       dir, e.g. .claude/hooks/lib), so the heuristic stays accurate.
+ *   - isClaudeCode() → boolean   (CLAUDE_PROJECT_DIR present)
+ *   - readStdinJson({ timeoutMs }) → Promise<object | null>
+ *       Async stdin JSON reader; null on parse error / closed stdin / timeout.
+ *   - emitContext(text, { client, eventName, streams, forceStderr }) → void
+ *       Standardised output: Claude Code → stdout JSON envelope; Codex/Cursor
+ *       → plain stderr. forceStderr pins stderr even on Claude Code (used for
+ *       SessionStart one-shot reminders). Best-effort — never throws.
+ *
+ * Never-throw contract (KT-DEC-0007): every path degrades silently rather than
+ * blocking the host's main flow.
+ */
+
+function isClaudeCode() {
+  return (
+    typeof process.env.CLAUDE_PROJECT_DIR === "string" &&
+    process.env.CLAUDE_PROJECT_DIR.length > 0
+  );
+}
+
+function detectClient(dirnameHint) {
+  const envClient = process.env.FABRIC_HINT_CLIENT;
+  if (typeof envClient === "string" && envClient.length > 0) {
+    const normalised = envClient.trim().toLowerCase();
+    if (normalised === "cc" || normalised === "codex" || normalised === "cursor") {
+      return normalised;
+    }
+  }
+  if (isClaudeCode()) return "cc";
+  // Path heuristic against the caller's directory (defaults to this lib's dir,
+  // which sits under the client root, e.g. .codex/hooks/lib).
+  const dir = typeof dirnameHint === "string" && dirnameHint.length > 0 ? dirnameHint : __dirname;
+  try {
+    if (dir.includes(".claude/") || dir.includes(".claude\\")) return "cc";
+    if (dir.includes(".codex/") || dir.includes(".codex\\")) return "codex";
+    if (dir.includes(".cursor/") || dir.includes(".cursor\\")) return "cursor";
+  } catch {
+    // fall through
+  }
+  return undefined;
+}
+
+function readStdinJson(opts) {
+  const { timeoutMs = 1000 } = opts || {};
+  return new Promise((resolve) => {
+    let buffer = "";
+    process.stdin.on("data", (chunk) => {
+      buffer += chunk;
+    });
+    process.stdin.on("end", () => {
+      try {
+        resolve(JSON.parse(buffer));
+      } catch {
+        resolve(null);
+      }
+    });
+    process.stdin.on("error", () => resolve(null));
+    // Defensive timeout: if stdin never closes (host bug), give up.
+    setTimeout(() => resolve(null), timeoutMs).unref();
+  });
+}
+
+function emitContext(text, opts) {
+  const { client, eventName = "UserPromptSubmit", streams = {}, forceStderr = false } = opts || {};
+  const stdout = streams.stdout || process.stdout;
+  const stderr = streams.stderr || process.stderr;
+  const useStdoutEnvelope =
+    !forceStderr && (client === "cc" || (client === undefined && isClaudeCode()));
+  try {
+    if (useStdoutEnvelope) {
+      const envelope = {
+        hookSpecificOutput: { hookEventName: eventName, additionalContext: text },
+      };
+      stdout.write(`${JSON.stringify(envelope)}\n`);
+    } else {
+      stderr.write(`${text}\n`);
+    }
+  } catch {
+    // best-effort — never throw
+  }
+}
+
+module.exports = {
+  isClaudeCode,
+  detectClient,
+  readStdinJson,
+  emitContext,
+};