@bartolli/kmd 0.8.0 → 0.10.0

package/dist/kmd.mjs

@@ -150,7 +150,7 @@ ${issues}`);
   }
   return parsed.data;
 }
-var ScopeSchema, KindEntrySchema, WhenSchema, DedupSchema, TriggerSchema, TriggersSchema, VaultConfigSchema, BUILT_IN_KINDS;
+var ScopeSchema, KindEntrySchema, WhenSchema, DedupSchema, TriggerSchema, TriggersSchema, BuiltinHooksSchema, VaultConfigSchema, BUILT_IN_KINDS;
 var init_vault_config = __esm({
   "../db/src/vault-config.ts"() {
     "use strict";
@@ -241,6 +241,15 @@ var init_vault_config = __esm({
       }
     });
     TriggersSchema = z.record(z.string(), z.array(TriggerSchema));
+    BuiltinHooksSchema = z.strictObject({
+      resync: z.strictObject({
+        reason: z.string().min(1).optional().describe("Validate-errors preamble; the engine appends the error lines."),
+        text: z.string().min(1).optional().describe("Sync-failed note.")
+      }).optional(),
+      "handoff-gate": z.strictObject({
+        reason: z.string().min(1).optional().describe("Stop-block preamble; the engine appends the error lines.")
+      }).optional()
+    });
     VaultConfigSchema = z.strictObject({
       scopes: z.record(z.string(), ScopeSchema).describe("Scope name \u2192 entry; key = directory name under projects/."),
       kinds: z.array(KindEntrySchema).describe(
@@ -259,6 +268,9 @@ var init_vault_config = __esm({
       triggers: TriggersSchema.optional().describe(
         'Full-replace of the trigger base per scope \u2014 escape hatch. "_all" is reserved for triggers_extra.'
       ),
+      builtin_hooks: BuiltinHooksSchema.optional().describe(
+        "Message overrides for the fixed-function hooks (resync, handoff-gate) by public id."
+      ),
       triggers_extra: TriggersSchema.optional().describe(
         'Appended per scope after the engine defaults; the reserved "_all" key fires in every session.'
       )
@@ -797,15 +809,11 @@ async function syncVault(vaultRoot2) {
       }
       indexedPaths.push(path);
     }
-    let pagesDeleted = 0;
-    let linksDeleted = 0;
-    if (indexedPaths.length > 0) {
-      const placeholders = indexedPaths.map(() => "?").join(", ");
-      const pageResult = db.prepare(`DELETE FROM pages WHERE path NOT IN (${placeholders})`).run(...indexedPaths);
-      pagesDeleted = Number(pageResult.changes);
-      const linkResult = db.prepare("DELETE FROM links WHERE source_path NOT IN (SELECT path FROM pages)").run();
-      linksDeleted = Number(linkResult.changes);
-    }
+    const placeholders = indexedPaths.map(() => "?").join(", ");
+    const pageResult = indexedPaths.length > 0 ? db.prepare(`DELETE FROM pages WHERE path NOT IN (${placeholders})`).run(...indexedPaths) : db.prepare("DELETE FROM pages").run();
+    const pagesDeleted = Number(pageResult.changes);
+    const linkResult = db.prepare("DELETE FROM links WHERE source_path NOT IN (SELECT path FROM pages)").run();
+    const linksDeleted = Number(linkResult.changes);
     db.exec("INSERT INTO pages_fts(pages_fts) VALUES('rebuild')");
     setMeta(db, "vault_root", canonicalVaultRoot(vaultRoot2));
     setMeta(db, "last_synced", (/* @__PURE__ */ new Date()).toISOString());
@@ -829,7 +837,7 @@ async function runSync() {
   console.log(`sync: ${env.WIKI_VAULT} \u2192 ${resolveIndexPath(env.WIKI_VAULT)}`);
   const stats = await syncVault(env.WIKI_VAULT);
   if (stats.noPages) {
-    console.warn("no indexable pages found; skipping orphan deletion (safety)");
+    console.warn("no indexable pages found; index swept empty");
   }
   console.log(
     `done: ${stats.changed} changed, ${stats.unchanged} unchanged, ${stats.skipped} skipped, ${stats.pagesDeleted} pages deleted, ${stats.linksDeleted} link orphans cleared`
@@ -2349,6 +2357,8 @@ __export(hook_exports, {
   dedupePretoolMatches: () => dedupePretoolMatches,
   effectiveTriggers: () => effectiveTriggers,
   evaluateMatches: () => evaluateMatches,
+  explainPretool: () => explainPretool,
+  explainPrompt: () => explainPrompt,
   hookStateDir: () => hookStateDir,
   kiroIdePromptEvent: () => kiroIdePromptEvent,
   loadTriggerFile: () => loadTriggerFile,
@@ -2359,6 +2369,7 @@ __export(hook_exports, {
   parseStopEvent: () => parseStopEvent,
   renderPosttool: () => renderPosttool,
   renderPretool: () => renderPretool,
+  renderPrompt: () => renderPrompt,
   renderStop: () => renderStop,
   resolveScope: () => resolveScope,
   runHookPosttool: () => runHookPosttool,
@@ -2452,37 +2463,50 @@ function openPromptIndex(prompt) {
   db.prepare("INSERT INTO prompt_doc (text) VALUES (?)").run(prompt);
   return db;
 }
+function promptProbe(trigger, prompt, getDb) {
+  let keywords = "unset";
+  if (trigger.keywords !== void 0 && trigger.keywords.length > 0) {
+    const row = getDb().prepare("SELECT count(*) AS n FROM prompt_doc WHERE prompt_doc MATCH ?").get(keywordQuery(trigger.keywords));
+    keywords = row.n > 0 ? "hit" : "miss";
+  }
+  let intent = "unset";
+  if (trigger.intent !== void 0) {
+    intent = trigger.intent.some((pattern) => new RegExp(pattern, "i").test(prompt)) ? "hit" : "miss";
+  }
+  return { keywords, intent };
+}
+function promptHit(probe) {
+  return probe.keywords === "hit" || probe.intent === "hit";
+}
+function isInjectTrigger(trigger) {
+  return trigger.on === "prompt" && trigger.enforce === "inject" && trigger.text !== void 0;
+}
 function matchPromptTriggers(prompt, triggers) {
-  const candidates = triggers.filter(
-    (trigger) => trigger.on === "prompt" && trigger.enforce === "inject" && trigger.text !== void 0
-  );
+  const candidates = triggers.filter(isInjectTrigger);
   if (candidates.length === 0) return [];
   const matches = [];
-  let db = null;
+  const state = { db: null };
+  const getDb = () => state.db ??= openPromptIndex(prompt);
   try {
     for (const trigger of candidates) {
-      let hit = false;
-      if (trigger.keywords !== void 0 && trigger.keywords.length > 0) {
-        db ??= openPromptIndex(prompt);
-        const row = db.prepare("SELECT count(*) AS n FROM prompt_doc WHERE prompt_doc MATCH ?").get(keywordQuery(trigger.keywords));
-        hit = row.n > 0;
-      }
-      if (!hit && trigger.intent !== void 0) {
-        hit = trigger.intent.some((pattern) => new RegExp(pattern, "i").test(prompt));
-      }
-      if (hit) {
-        matches.push({
-          id: trigger.id,
-          text: trigger.text,
-          ...trigger.dedup !== void 0 && { dedup: trigger.dedup }
-        });
-      }
+      if (!promptHit(promptProbe(trigger, prompt, getDb))) continue;
+      matches.push({
+        id: trigger.id,
+        text: trigger.text,
+        ...trigger.dedup !== void 0 && { dedup: trigger.dedup }
+      });
     }
   } finally {
-    db?.close();
+    state.db?.close();
   }
   return matches;
 }
+function uniqueTexts(texts) {
+  return [...new Set(texts)];
+}
+function renderPrompt(matches) {
+  return uniqueTexts(matches.map((match) => match.text));
+}
 function parsePretoolEvent(raw) {
   const fields = eventFields(raw);
   if (fields === null) return null;
@@ -2531,32 +2555,41 @@ function pathCandidates(toolInput, cwd) {
   }
   return candidates;
 }
+function pretoolStage(trigger, toolName, toolInput, cwd) {
+  if (trigger.tool !== void 0 && trigger.tool !== toolName) return "tool";
+  if (trigger.args_match !== void 0) {
+    const serialized = JSON.stringify(toolInput ?? {});
+    if (!new RegExp(trigger.args_match).test(serialized)) return "args";
+  }
+  if (trigger.files !== void 0 && trigger.files.length > 0) {
+    const candidates = [...pathCandidates(toolInput, cwd), ...patchPaths(toolInput)];
+    const hit = trigger.files.some((glob) => {
+      const regex = globToRegExp(glob);
+      return candidates.some((candidate) => regex.test(candidate));
+    });
+    if (!hit) return "files";
+  }
+  if (pretoolText(trigger) === void 0) return "payload";
+  return "hit";
+}
+function pretoolText(trigger) {
+  return trigger.enforce === "block" ? trigger.reason : trigger.text;
+}
+function pretoolMatch(trigger) {
+  return {
+    id: trigger.id,
+    enforce: trigger.enforce,
+    text: pretoolText(trigger),
+    ...trigger.when !== void 0 && { when: trigger.when },
+    ...trigger.dedup !== void 0 && { dedup: trigger.dedup }
+  };
+}
 function matchPretoolTriggers(toolName, toolInput, triggers, cwd) {
   const matches = [];
   for (const trigger of triggers) {
     if (trigger.on !== "pretool") continue;
-    if (trigger.tool !== void 0 && trigger.tool !== toolName) continue;
-    if (trigger.args_match !== void 0) {
-      const serialized = JSON.stringify(toolInput ?? {});
-      if (!new RegExp(trigger.args_match).test(serialized)) continue;
-    }
-    if (trigger.files !== void 0 && trigger.files.length > 0) {
-      const candidates = pathCandidates(toolInput, cwd);
-      const hit = trigger.files.some((glob) => {
-        const regex = globToRegExp(glob);
-        return candidates.some((candidate) => regex.test(candidate));
-      });
-      if (!hit) continue;
-    }
-    const text = trigger.enforce === "block" ? trigger.reason : trigger.text;
-    if (text === void 0) continue;
-    matches.push({
-      id: trigger.id,
-      enforce: trigger.enforce,
-      text,
-      ...trigger.when !== void 0 && { when: trigger.when },
-      ...trigger.dedup !== void 0 && { dedup: trigger.dedup }
-    });
+    if (pretoolStage(trigger, toolName, toolInput, cwd) !== "hit") continue;
+    matches.push(pretoolMatch(trigger));
   }
   return matches;
 }
@@ -2574,18 +2607,23 @@ function evaluateMatches(matches, vaultRoot2) {
   }
   return { fired, skipped };
 }
-function evaluateWhen(when, vaultRoot2) {
-  if (typeof when === "string") return null;
+function evaluateWhenVerdict(when, vaultRoot2) {
+  if (typeof when === "string") return "unknown";
   try {
     const than = newestUpdated(vaultRoot2, when.than);
-    if (than === null) return true;
+    if (than === null) return "vacuous";
     const fresh = newestUpdated(vaultRoot2, when.fresh);
-    if (fresh === null) return false;
-    return fresh >= than;
+    if (fresh === null) return "unmet";
+    return fresh >= than ? "satisfied" : "unmet";
   } catch {
-    return null;
+    return "unknown";
   }
 }
+function evaluateWhen(when, vaultRoot2) {
+  const verdict = evaluateWhenVerdict(when, vaultRoot2);
+  if (verdict === "unknown") return null;
+  return verdict !== "unmet";
+}
 function newestUpdated(vaultRoot2, globs) {
   const regexes = globs.map(globToRegExp);
   let newest = null;
@@ -2612,26 +2650,27 @@ function readUpdated(path) {
   return null;
 }
 function renderPretool(matches, format) {
-  const block = matches.find((match) => match.enforce === "block");
-  const context = matches.filter((match) => match.enforce === "inject").map((match) => match.text);
-  const warnings = matches.filter((match) => match.enforce === "warn").map((match) => match.text);
+  const byClass = (enforce) => uniqueTexts(matches.filter((match) => match.enforce === enforce).map((match) => match.text));
+  const reasons = byClass("block");
+  const context = byClass("inject");
+  const warnings = byClass("warn");
   if (format === "claude") {
     const hookSpecificOutput = { hookEventName: "PreToolUse" };
-    if (block !== void 0) {
+    if (reasons.length > 0) {
       hookSpecificOutput.permissionDecision = "deny";
-      hookSpecificOutput.permissionDecisionReason = block.text;
+      hookSpecificOutput.permissionDecisionReason = reasons.join("\n");
     }
     if (context.length > 0) {
       hookSpecificOutput.additionalContext = context.join("\n");
     }
-    const decided = block !== void 0 || context.length > 0;
+    const decided = reasons.length > 0 || context.length > 0;
     return { stdout: decided ? JSON.stringify({ hookSpecificOutput }) : null, stderr: warnings };
   }
   if (matches.length === 0) return { stdout: null, stderr: [] };
   return {
     stdout: JSON.stringify({
-      decision: block !== void 0 ? "deny" : "none",
-      ...block !== void 0 && { reason: block.text },
+      decision: reasons.length > 0 ? "deny" : "none",
+      ...reasons.length > 0 && { reason: reasons.join("\n") },
       context,
       warnings
     }),
@@ -2651,28 +2690,46 @@ function patchPaths(toolInput) {
   }
   return paths;
 }
+function commandPaths(toolInput) {
+  if (typeof toolInput !== "object" || toolInput === null) return [];
+  const command2 = toolInput.command;
+  if (typeof command2 !== "string") return [];
+  const paths = [];
+  for (const match of command2.matchAll(COMMAND_TOKEN_RE)) {
+    const token = match[1] ?? match[2] ?? match[3];
+    for (const piece of token.split(/[;|&<>()]+/)) {
+      if (piece === "") continue;
+      if (piece === "." || piece === ".." || PATHISH_RE.test(piece)) paths.push(piece);
+    }
+  }
+  return paths;
+}
 function vaultPathTouched(toolInput, vaultRoot2, cwd) {
   const root = resolve3(vaultRoot2);
-  const candidates = [...pathCandidates(toolInput, cwd), ...patchPaths(toolInput)];
+  const candidates = [
+    ...pathCandidates(toolInput, cwd),
+    ...patchPaths(toolInput),
+    ...commandPaths(toolInput)
+  ];
   return candidates.some((candidate) => {
     const absolute = resolve3(cwd ?? ".", candidate);
     return absolute === root || absolute.startsWith(`${root}/`);
   });
 }
-function renderPosttool(findings, synced, format) {
+function renderPosttool(findings, synced, format, messages = {}) {
   if (findings.length === 0 && synced) return null;
   const lines = findings.map((f) => `${f.severity}: ${f.path} [${f.rule}] ${f.message}`);
   if (format === "claude") {
     if (hasErrors(findings)) {
       return JSON.stringify({
         decision: "block",
-        reason: `kmd validate failed \u2014 fix before the index syncs:
+        reason: `${messages.reason ?? RESYNC_REASON}:
 ${lines.join("\n")}`
       });
     }
     const hookSpecificOutput = { hookEventName: "PostToolUse" };
     const notes = [...lines];
-    if (!synced) notes.push("kmd sync failed \u2014 index not updated; see hook stderr");
+    if (!synced) notes.push(messages.text ?? RESYNC_TEXT);
     hookSpecificOutput.additionalContext = notes.join("\n");
     return JSON.stringify({ hookSpecificOutput });
   }
@@ -2689,60 +2746,151 @@ function parseStopEvent(raw) {
     ...typeof stop_hook_active === "boolean" && { stop_hook_active }
   };
 }
-function renderStop(findings) {
+function renderStop(findings, reason) {
   const errors = findings.filter((finding) => finding.severity === "error");
   if (errors.length === 0) return null;
   const lines = errors.map((f) => `${f.severity}: ${f.path} [${f.rule}] ${f.message}`);
   return JSON.stringify({
     decision: "block",
-    reason: `kmd validate: ${errors.length} error(s) outstanding \u2014 the index sync is held. Fix them, let the posttool hook sync, then finish:
+    reason: `${reason ?? HANDOFF_GATE_REASON}:
 ${lines.join("\n")}`
   });
 }
-function dedupePretoolMatches(stateDir, sessionId, matches) {
+function dedupePretoolMatches(stateDir, sessionId, matches, persist = true) {
   const blocks = matches.filter((match) => match.enforce === "block");
   const rest = matches.filter((match) => match.enforce !== "block");
-  const fresh = dedupeMatches(stateDir, sessionId, rest);
+  const fresh = dedupeMatches(stateDir, sessionId, rest, Date.now(), persist);
   return matches.filter((match) => blocks.includes(match) || fresh.includes(match));
 }
 function hookStateDir() {
   return join10(kmdHome(), "state", "hook");
 }
-function dedupeMatches(stateDir, sessionId, matches, now = Date.now()) {
+function explainPrompt(options) {
+  const now = options.now ?? Date.now();
+  const fired = readFired(join10(options.stateDir, safeName(options.sessionId)));
+  const entries = [];
+  const rendered = [];
+  const state = { db: null };
+  const getDb = () => state.db ??= openPromptIndex(options.prompt);
+  try {
+    for (const trigger of options.triggers) {
+      if (!isInjectTrigger(trigger)) {
+        entries.push({ id: trigger.id, considered: false });
+        continue;
+      }
+      const probe = promptProbe(trigger, options.prompt, getDb);
+      const matched = promptHit(probe);
+      const entry = {
+        id: trigger.id,
+        considered: true,
+        keywords: probe.keywords,
+        intent: probe.intent,
+        matched
+      };
+      entries.push(entry);
+      if (!matched) {
+        entry.fired = false;
+        continue;
+      }
+      const key = dedupKey(trigger, now);
+      entry.dedup = key === null ? "never" : fired.has(key) ? "suppressed" : "fresh";
+      entry.fired = entry.dedup !== "suppressed";
+      if (entry.fired) rendered.push({ id: trigger.id, text: trigger.text });
+    }
+  } finally {
+    state.db?.close();
+  }
+  return { triggers: entries, output: renderPrompt(rendered) };
+}
+function explainPretool(options) {
+  const now = options.now ?? Date.now();
+  const fired = readFired(join10(options.stateDir, safeName(options.sessionId)));
+  const entries = [];
+  const rendered = [];
+  for (const trigger of options.triggers) {
+    if (trigger.on !== "pretool") {
+      entries.push({ id: trigger.id, considered: false });
+      continue;
+    }
+    const stage = pretoolStage(trigger, options.toolName, options.toolInput, options.cwd);
+    const entry = {
+      id: trigger.id,
+      enforce: trigger.enforce,
+      considered: true,
+      matcher: stage === "hit" ? "hit" : `${stage}-miss`
+    };
+    entries.push(entry);
+    if (stage !== "hit") {
+      entry.fired = false;
+      continue;
+    }
+    if (trigger.when !== void 0) {
+      entry.when = evaluateWhenVerdict(trigger.when, options.vaultRoot);
+      if (entry.when !== "unmet") {
+        entry.fired = false;
+        continue;
+      }
+    }
+    const match = pretoolMatch(trigger);
+    if (match.enforce === "block") {
+      entry.dedup = "exempt";
+    } else {
+      const key = dedupKey(match, now);
+      entry.dedup = key === null ? "never" : fired.has(key) ? "suppressed" : "fresh";
+    }
+    entry.fired = entry.dedup !== "suppressed";
+    if (entry.fired) rendered.push(match);
+  }
+  return { triggers: entries, outcome: renderPretool(rendered, options.format ?? "neutral") };
+}
+function dedupeMatches(stateDir, sessionId, matches, now = Date.now(), persist = true) {
   if (matches.length === 0) return [];
-  const file = join10(stateDir, `${sessionId.replace(/[^A-Za-z0-9._-]/g, "_")}.json`);
-  const fired = readFired(file);
+  const dir = join10(stateDir, safeName(sessionId));
+  const fired = readFired(dir);
   const fresh = [];
   const record = [];
   for (const match of matches) {
-    if (match.dedup === "never") {
+    const key = dedupKey(match, now);
+    if (key === null) {
       fresh.push(match);
       continue;
     }
-    const key = typeof match.dedup === "object" ? `${match.id}@${Math.floor(now / (match.dedup.minutes * 6e4))}` : match.id;
     if (fired.has(key)) continue;
     fresh.push(match);
     record.push(key);
   }
-  if (record.length > 0) {
-    mkdirSync4(stateDir, { recursive: true });
-    for (const key of record) {
-      fired.add(key);
+  if (persist && record.length > 0) {
+    try {
+      mkdirSync4(dir, { recursive: true });
+      for (const key of record) {
+        try {
+          writeFileSync(join10(dir, key), "", { flag: "wx" });
+        } catch (err) {
+          if (err.code !== "EEXIST") throw err;
+        }
+      }
+      pruneStale(stateDir, dir);
+    } catch (err) {
+      diag2(`dedup state not persisted: ${err instanceof Error ? err.message : String(err)}`);
     }
-    writeFileSync(file, JSON.stringify([...fired]));
-    pruneStale(stateDir, file);
   }
   return fresh;
 }
-function readFired(file) {
+function safeName(part) {
+  return part.replace(/[^A-Za-z0-9._@-]/g, "_");
+}
+function dedupKey(match, now) {
+  if (match.dedup === "never") return null;
+  return safeName(
+    typeof match.dedup === "object" ? `${match.id}@${Math.floor(now / (match.dedup.minutes * 6e4))}` : match.id
+  );
+}
+function readFired(dir) {
   try {
-    const data = JSON.parse(readFileSync(file, "utf8"));
-    if (Array.isArray(data)) {
-      return new Set(data.filter((entry) => typeof entry === "string"));
-    }
+    return new Set(readdirSync2(dir));
   } catch {
+    return /* @__PURE__ */ new Set();
   }
-  return /* @__PURE__ */ new Set();
 }
 function pruneStale(stateDir, keep) {
   try {
@@ -2750,7 +2898,7 @@ function pruneStale(stateDir, keep) {
     for (const entry of readdirSync2(stateDir)) {
       const path = join10(stateDir, entry);
       if (path !== keep && statSync(path).mtimeMs < cutoff) {
-        rmSync2(path, { force: true });
+        rmSync2(path, { recursive: true, force: true });
       }
     }
   } catch {
@@ -2764,7 +2912,9 @@ function hookInvocation() {
     options: {
       scope: { type: "string" },
       harness: { type: "string" },
-      triggers: { type: "string" }
+      triggers: { type: "string" },
+      "dry-run": { type: "boolean" },
+      explain: { type: "boolean" }
     }
   });
   const vaultRoot2 = positionals2[2] ?? process.env.WIKI_VAULT;
@@ -2776,7 +2926,9 @@ function hookInvocation() {
     vaultRoot: vaultRoot2,
     scope: typeof values2.scope === "string" ? values2.scope : process.env.WIKI_SCOPE,
     harness: values2.harness,
-    triggersFile: values2.triggers
+    triggersFile: values2.triggers,
+    dryRun: values2["dry-run"] === true || values2.explain === true,
+    explain: values2.explain === true
   };
 }
 function resolveFileTriggers(invocation) {
@@ -2814,9 +2966,26 @@ async function runHookPrompt() {
     for (const id of duplicates) {
       diag2(`duplicate trigger id "${id}" \u2014 later occurrence ignored`);
     }
+    if (invocation.explain) {
+      const trace = explainPrompt({
+        prompt: event.prompt,
+        triggers,
+        stateDir: hookStateDir(),
+        sessionId: event.session_id
+      });
+      console.log(JSON.stringify({ event: "prompt", scope: scope ?? null, duplicates, ...trace }));
+      return;
+    }
     const matches = matchPromptTriggers(event.prompt, triggers);
-    for (const match of dedupeMatches(hookStateDir(), event.session_id, matches)) {
-      console.log(match.text);
+    const fresh = dedupeMatches(
+      hookStateDir(),
+      event.session_id,
+      matches,
+      Date.now(),
+      !invocation.dryRun
+    );
+    for (const line of renderPrompt(fresh)) {
+      console.log(line);
     }
   } catch (err) {
     diag2(err instanceof Error ? err.message : String(err));
@@ -2848,13 +3017,27 @@ async function runHookPretool() {
     for (const id of duplicates) {
       diag2(`duplicate trigger id "${id}" \u2014 later occurrence ignored`);
     }
+    if (invocation.explain) {
+      const trace = explainPretool({
+        toolName: event.tool_name,
+        toolInput: event.tool_input,
+        triggers,
+        vaultRoot: vaultRoot2,
+        stateDir: hookStateDir(),
+        sessionId: event.session_id,
+        ...event.cwd !== void 0 && { cwd: event.cwd },
+        format
+      });
+      console.log(JSON.stringify({ event: "pretool", scope: scope ?? null, duplicates, ...trace }));
+      return;
+    }
     const matches = matchPretoolTriggers(event.tool_name, event.tool_input, triggers, event.cwd);
     const { fired, skipped } = evaluateMatches(matches, vaultRoot2);
     for (const id of skipped) {
       diag2(`trigger "${id}": unknown or unevaluable predicate \u2014 skipped`);
     }
     const rendered = renderPretool(
-      dedupePretoolMatches(hookStateDir(), event.session_id, fired),
+      dedupePretoolMatches(hookStateDir(), event.session_id, fired, !invocation.dryRun),
       format
     );
     for (const line of rendered.stderr) {
@@ -2871,6 +3054,10 @@ async function runHookPosttool() {
   try {
     const invocation = hookInvocation();
     if (invocation === null) return;
+    if (invocation.dryRun) {
+      diag2("--dry-run/--explain support prompt and pretool events only");
+      return;
+    }
     let format = "neutral";
     if (invocation.harness === "claude") {
       format = "claude";
@@ -2883,6 +3070,7 @@ async function runHookPosttool() {
       return;
     }
     if (!vaultPathTouched(event.tool_input, invocation.vaultRoot, event.cwd)) return;
+    const config = await loadVaultConfig(invocation.vaultRoot);
     const findings = await validateVault(invocation.vaultRoot);
     let synced = false;
     if (!hasErrors(findings)) {
@@ -2893,7 +3081,7 @@ async function runHookPosttool() {
         diag2(`sync failed: ${err instanceof Error ? err.message : String(err)}`);
       }
     }
-    const rendered = renderPosttool(findings, synced, format);
+    const rendered = renderPosttool(findings, synced, format, config.builtin_hooks?.resync ?? {});
     if (rendered !== null) {
       console.log(rendered);
     }
@@ -2905,6 +3093,10 @@ async function runHookStop() {
   try {
     const invocation = hookInvocation();
     if (invocation === null) return;
+    if (invocation.dryRun) {
+      diag2("--dry-run/--explain support prompt and pretool events only");
+      return;
+    }
     const event = parseStopEvent(await readStdin());
     if (event === null) {
       diag2("stdin is not a stop event ({session_id})");
@@ -2914,9 +3106,12 @@ async function runHookStop() {
     const config = await loadVaultConfig(invocation.vaultRoot);
     const scope = invocation.scope ?? resolveScope(config, event.cwd);
     if (scope === void 0) return;
-    const rendered = renderStop(await validateVault(invocation.vaultRoot));
+    const rendered = renderStop(
+      await validateVault(invocation.vaultRoot),
+      config.builtin_hooks?.["handoff-gate"]?.reason
+    );
     if (rendered === null) return;
-    const fired = dedupeMatches(hookStateDir(), event.session_id, [{ id: "stop-validate-gate" }]);
+    const fired = dedupeMatches(hookStateDir(), event.session_id, [{ id: "handoff-gate" }]);
     if (fired.length === 0) return;
     console.log(rendered);
   } catch (err) {
@@ -2934,7 +3129,7 @@ async function readStdin() {
 function diag2(message) {
   console.error(`kmd hook: ${message}`);
 }
-var DEFAULT_TRIGGERS, SESSION_STATE_MAX_AGE_MS, KIRO_IDE_BUCKET_MS, ALL_SCOPES_KEY, PATCH_FILE_RE;
+var DEFAULT_TRIGGERS, SESSION_STATE_MAX_AGE_MS, KIRO_IDE_BUCKET_MS, ALL_SCOPES_KEY, PATCH_FILE_RE, COMMAND_TOKEN_RE, PATHISH_RE, RESYNC_REASON, RESYNC_TEXT, HANDOFF_GATE_REASON;
 var init_hook = __esm({
   "../cli/src/hook.ts"() {
     "use strict";
@@ -2948,6 +3143,11 @@ var init_hook = __esm({
     KIRO_IDE_BUCKET_MS = 30 * 60 * 1e3;
     ALL_SCOPES_KEY = "_all";
     PATCH_FILE_RE = /^\*\*\* (?:Add|Update|Delete) File: (.+)$/gm;
+    COMMAND_TOKEN_RE = /"([^"]*)"|'([^']*)'|(\S+)/g;
+    PATHISH_RE = /[/*$]|\.(?:md|base|canvas|ya?ml)$/i;
+    RESYNC_REASON = "Edit landed; the index sync is held until these validate errors are fixed";
+    RESYNC_TEXT = "kmd sync failed \u2014 index not updated; see hook stderr";
+    HANDOFF_GATE_REASON = "Validate errors are outstanding and the index sync is held \u2014 fix them, let the resync run, then finish";
   }
 });