eminiar 0.8.1 → 0.9.1

package/dist/hook.js

@@ -5917,7 +5917,11 @@ var CATEGORIES = {
   intent: 4,
   data: 4,
   tool_call: 4,
-  session_start: 4
+  session_start: 4,
+  /** A proactive recall decision (fired or quiet) and what it showed; never in the guide. */
+  recall: 4,
+  /** A routing decision (allow / annotate / deny) for one native call; never in the guide. */
+  routing: 4
 };
 var GUIDE_ORDER = [
   { title: "Last Request", categories: ["user_prompt"] },
@@ -26082,7 +26086,12 @@ var ConfigSchema = external_exports.object({
     /** Before WebSearch / WebFetch: the indexed doc pages that already answer it. */
     onWeb: external_exports.boolean().default(true),
     maxMemories: external_exports.number().int().min(0).max(10).default(3),
-    maxDocs: external_exports.number().int().min(0).max(10).default(2)
+    maxDocs: external_exports.number().int().min(0).max(10).default(2),
+    /**
+     * Prompts after which an item already shown in this context window may be injected
+     * again when it matches (0 = once per context window only).
+     */
+    repeatAfter: external_exports.number().int().min(0).max(1e3).default(10)
   }).prefault({}),
   docs: external_exports.object({
     /** Project-relative manifest of documentation sources (`em_docs`); commit it. */
@@ -26975,6 +26984,8 @@ var PROMPT_FILLER = /* @__PURE__ */ new Set([
 ]);
 var MAX_TERMS = 16;
 var RECALL_CATEGORY = "recall";
+var DEFAULT_REPEAT_AFTER = 10;
+var NAME_MATCH_RATIO = 0.3;
 function promptTerms(prompt) {
   const body = prompt.replace(/^\s*\/\S+/, " ");
   return parseQuery(body).terms.filter((t) => t.length >= 3 && !PROMPT_FILLER.has(t) && !/^\d+$/.test(t)).slice(0, MAX_TERMS);
@@ -26982,26 +26993,50 @@ function promptTerms(prompt) {
 function requiredMatches(termCount) {
   return Math.min(3, Math.max(2, Math.ceil(termCount * 0.2)));
 }
-function shownKeys(db, sessionId) {
+function shownKeys(db, sessionId, repeatAfter = DEFAULT_REPEAT_AFTER) {
   const events = db.eventsBySession(sessionId, {
-    categories: [RECALL_CATEGORY, "session_start"]
+    categories: [RECALL_CATEGORY, "session_start", "user_prompt"]
   });
-  const out = /* @__PURE__ */ new Set();
+  const shownAt = /* @__PURE__ */ new Map();
+  let prompts = 0;
   for (const e of events) {
     if (e.category === "session_start") {
-      out.clear();
+      shownAt.clear();
+      prompts = 0;
+      continue;
+    }
+    if (e.category === "user_prompt") {
+      prompts++;
       continue;
     }
     try {
-      for (const k of JSON.parse(e.payload).keys ?? []) out.add(k);
+      for (const k of JSON.parse(e.payload).keys ?? [])
+        shownAt.set(k, prompts);
     } catch {
     }
   }
+  const out = /* @__PURE__ */ new Set();
+  for (const [k, at] of shownAt) if (repeatAfter <= 0 || prompts - at < repeatAfter) out.add(k);
   return out;
 }
-function recordShown(db, sessionId, keys) {
-  if (!keys.length) return;
-  db.eventInsert({ sessionId, category: RECALL_CATEGORY, priority: 4, payload: { keys } });
+function recordShown(db, sessionId, keys, info = { path: "prompt" }) {
+  if (!keys.length && !info.trace) return;
+  const t = info.trace;
+  db.eventInsert({
+    sessionId,
+    category: RECALL_CATEGORY,
+    priority: 4,
+    payload: {
+      keys,
+      path: info.path,
+      ...t ? {
+        terms: t.terms,
+        need: t.need,
+        candidates: t.candidates.length,
+        gated: t.candidates.filter((c) => c.outcome !== "shown").slice(0, 6).map((c) => `${c.key} ${c.outcome}${c.why ? ` (${c.why})` : ""}`)
+      } : {}
+    }
+  });
 }
 function clip2(s, max) {
   const t = s.replace(/\s+/g, " ").trim();
@@ -27024,16 +27059,53 @@ function kindRank(kind) {
   const i = KIND_ORDER.indexOf(kind);
   return i === -1 ? KIND_ORDER.length : i;
 }
+function sharedTerms(terms, ...texts) {
+  const hay = texts.join("\n").toLowerCase();
+  return terms.filter((t) => {
+    const base = t.replace(/\*$/, "").toLowerCase();
+    return !!base && new RegExp(`(?<![\\p{L}\\p{N}_])${escapeRe(base)}`, "u").test(hay);
+  });
+}
+function nameTerms(m) {
+  const slug = (m.name ?? "").split("/").pop() ?? "";
+  let tags = [];
+  try {
+    tags = m.tags ? JSON.parse(m.tags) : [];
+  } catch {
+  }
+  return [...slug.toLowerCase().split(/[-._]+/), ...tags.map((t) => t.toLowerCase())].filter(
+    (t) => t.length >= 4
+  );
+}
+function namesMemory(term, names) {
+  const t = term.replace(/\*$/, "");
+  if (t.length < 4) return false;
+  return names.some((n) => t === n || t.includes(n) || n.includes(t));
+}
+function qualifies(matched, need, termCount, m, text) {
+  if (matched.length >= need) return { ok: true };
+  if (m?.name && text?.toLowerCase().includes(m.name)) return { ok: true, why: "named" };
+  if (m && matched.length >= 1 && matched.length / Math.max(1, termCount) >= NAME_MATCH_RATIO) {
+    const names = nameTerms(m);
+    const hit = matched.find((t) => namesMemory(t, names));
+    if (hit) return { ok: true, why: `slug/tag "${hit}"` };
+  }
+  return { ok: false, why: `${matched.length}/${need} terms` };
+}
 async function recallForText(db, text, opts = {}) {
   const maxMemories = opts.maxMemories ?? 3;
   const maxDocs = opts.maxDocs ?? 2;
   const terms = promptTerms(text);
-  if (terms.length < 2 || maxMemories <= 0 && maxDocs <= 0) return { text: "", keys: [] };
+  const trace = opts.trace ? { path: opts.path ?? "prompt", terms, need: 0, candidates: [] } : void 0;
+  const quiet = () => ({ text: "", keys: [], trace });
+  if (terms.length < 2 || maxMemories <= 0 && maxDocs <= 0) return quiet();
   const need = opts.minMatches ?? requiredMatches(terms.length);
+  if (trace) trace.need = need;
   const query = terms.join(" ");
-  const seen = opts.sessionId ? shownKeys(db, opts.sessionId) : /* @__PURE__ */ new Set();
+  const seen = opts.sessionId ? shownKeys(db, opts.sessionId, opts.repeatAfter) : /* @__PURE__ */ new Set();
   const lines = [];
   const keys = [];
+  const note = (c) => trace?.candidates.push(c);
   if (maxMemories > 0) {
     const r = await search(db, query, {
       mode: "lexical",
@@ -27042,14 +27114,38 @@ async function recallForText(db, text, opts = {}) {
       filters: { source: "memory" }
     });
     let n = 0;
+    const considered = /* @__PURE__ */ new Set();
     for (const h of r.hits) {
-      if (n >= maxMemories) break;
-      if (h.matched.length < need) continue;
       const uri = h.chunk.document.uri;
       const name = uri?.startsWith("memory:") ? uri.slice(7) : void 0;
       const m = name ? db.memoryGetByName(name) : void 0;
       const key = `memory:${name}`;
-      if (!m?.name || !live(m) || !specific(m) || seen.has(key) || keys.includes(key)) continue;
+      if (!m?.name || considered.has(key)) continue;
+      considered.add(key);
+      const label = `${m.name} [${m.kind}]`;
+      const matched = sharedTerms(terms, m.name, m.content, m.tags ?? "");
+      if (!live(m)) {
+        note({ key, label, matched, outcome: "skipped", why: m.status ?? "retired" });
+        continue;
+      }
+      if (!specific(m)) {
+        note({ key, label, matched, outcome: "skipped", why: "onboarding" });
+        continue;
+      }
+      const q = qualifies(matched, need, terms.length, m, text);
+      if (!q.ok) {
+        note({ key, label, matched, outcome: "gated", why: q.why });
+        continue;
+      }
+      if (seen.has(key)) {
+        note({ key, label, matched, outcome: "seen", why: q.why });
+        continue;
+      }
+      if (n >= maxMemories) {
+        note({ key, label, matched, outcome: "over-limit", why: q.why });
+        continue;
+      }
+      note({ key, label, matched, outcome: "shown", why: q.why });
       lines.push(`- memory ${m.name} [${m.kind}]: ${gist(m)}`);
       keys.push(key);
       n++;
@@ -27064,28 +27160,62 @@ async function recallForText(db, text, opts = {}) {
     let n = 0;
     const docsSeen = /* @__PURE__ */ new Set();
     for (const h of r.hits) {
-      if (n >= maxDocs) break;
-      if (h.matched.length < need) continue;
       const d = h.chunk.document;
       const key = `doc:${d.id}`;
-      if (docsSeen.has(d.id) || seen.has(key)) continue;
+      if (docsSeen.has(d.id)) continue;
       docsSeen.add(d.id);
+      const label = `${d.source} \u203A ${clip2(d.title, 60)}`;
+      const matched = sharedTerms(terms, h.chunk.title, h.chunk.body);
+      if (matched.length < need) {
+        note({ key, label, matched, outcome: "gated", why: `${matched.length}/${need} terms` });
+        continue;
+      }
+      if (seen.has(key)) {
+        note({ key, label, matched, outcome: "seen" });
+        continue;
+      }
+      if (n >= maxDocs) {
+        note({ key, label, matched, outcome: "over-limit" });
+        continue;
+      }
+      note({ key, label, matched, outcome: "shown" });
       lines.push(`- ${d.source} \u203A ${clip2(d.title, 80)}: ${clip2(h.snippet, 160)}`);
       keys.push(key);
       n++;
     }
   }
-  if (!lines.length) return { text: "", keys: [] };
+  if (!lines.length) return quiet();
   return {
     text: [
       "eminiar recall \u2014 project memories and indexed docs that match this request (check them before deciding; superseded ones are omitted):",
       ...lines,
       'Full text: em_memory {action:"read", name} for a memory, em_docs {action:"lookup", query} for docs; em_recall {query} searches further.'
     ].join("\n"),
-    keys
+    keys,
+    trace
   };
 }
-function mentionsFile(m, rel) {
+var SYMBOL_KINDS = [
+  "function",
+  "class",
+  "method",
+  "interface",
+  "trait",
+  "type",
+  "enum",
+  "variable"
+];
+function fileSymbols(db, rel) {
+  try {
+    return db.graphFindNodes({ path: rel, kinds: SYMBOL_KINDS, limit: 400 }).filter((n) => n.path === rel).map((n) => n.name);
+  } catch {
+    return [];
+  }
+}
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function linksFile(m, rel) {
   if (!m.node_ids) return false;
   try {
     return JSON.parse(m.node_ids).some((id) => fileOf(id) === rel);
@@ -27093,23 +27223,50 @@ function mentionsFile(m, rel) {
     return false;
   }
 }
+function bodyNamesPath(body, rel) {
+  return new RegExp(`(?:^|[^\\w/.-]|\\./)${escapeRe(rel)}(?![\\w-])`, "m").test(body);
+}
+function symbolMentionPattern(symbols) {
+  const names = [...new Set(symbols)].filter((s) => /^[A-Za-z_$][\w$]{4,}$/.test(s));
+  if (!names.length) return void 0;
+  const alt = names.map(escapeRe).join("|");
+  return new RegExp(`(?:[\`#.](?:${alt})(?!\\w)|(?<!\\w)(?:${alt})\\()`);
+}
 function memoriesForFile(db, rel, opts = {}) {
-  const linked = db.memoryList({ limit: 1e3 }).filter((m) => live(m) && specific(m) && mentionsFile(m, rel)).sort((a, b) => kindRank(a.kind) - kindRank(b.kind));
-  if (!linked.length) return { text: "", keys: [] };
-  const seen = opts.sessionId ? shownKeys(db, opts.sessionId) : /* @__PURE__ */ new Set();
+  const symRe = opts.symbols?.length ? symbolMentionPattern(opts.symbols) : void 0;
+  const how = (m) => {
+    if (linksFile(m, rel)) return "related";
+    if (bodyNamesPath(m.content, rel)) return "names the path";
+    if (symRe?.test(m.content)) return "names a symbol";
+    return void 0;
+  };
+  const trace = opts.trace ? { path: "file", terms: [rel], need: 0, candidates: [] } : void 0;
+  const linked = db.memoryList({ limit: 1e3 }).map((m) => ({ m, why: how(m) })).filter((x) => !!x.why && live(x.m) && specific(x.m)).sort((a, b) => kindRank(a.m.kind) - kindRank(b.m.kind));
+  if (!linked.length) return { text: "", keys: [], trace };
+  const seen = opts.sessionId ? shownKeys(db, opts.sessionId, opts.repeatAfter) : /* @__PURE__ */ new Set();
   const lines = [];
   const keys = [];
-  for (const m of linked) {
-    if (lines.length >= (opts.max ?? 3)) break;
+  for (const { m, why } of linked) {
     const key = `memory:${m.name}`;
-    if (!m.name || seen.has(key)) continue;
+    const label = `${m.name} [${m.kind}]`;
+    if (!m.name) continue;
+    if (seen.has(key)) {
+      trace?.candidates.push({ key, label, matched: [rel], outcome: "seen", why });
+      continue;
+    }
+    if (lines.length >= (opts.max ?? 3)) {
+      trace?.candidates.push({ key, label, matched: [rel], outcome: "over-limit", why });
+      continue;
+    }
+    trace?.candidates.push({ key, label, matched: [rel], outcome: "shown", why });
     lines.push(`${m.name} [${m.kind}]: ${gist(m, 140)}`);
     keys.push(key);
   }
-  if (!lines.length) return { text: "", keys: [] };
+  if (!lines.length) return { text: "", keys: [], trace };
   return {
     text: `eminiar memory: ${rel} is covered by ${lines.join(" \xB7 ")} \u2014 respect it (em_memory {action:"read", name} for the full text) or update the memory if this change overrides it.`,
-    keys
+    keys,
+    trace
   };
 }
 var RISKY = 0.3;
@@ -27125,22 +27282,32 @@ function riskLine(path2, f) {
   return `${path2} is bug-prone (${parts.join("; ")})`;
 }
 function fileContext(db, rel, opts = {}) {
-  const key = `file:${rel}`;
-  if (opts.sessionId && shownKeys(db, opts.sessionId).has(key)) return { text: "", keys: [] };
+  const seen = opts.sessionId ? shownKeys(db, opts.sessionId, opts.repeatAfter) : /* @__PURE__ */ new Set();
   const lines = [];
-  const f = readFileRisk(db)[rel];
-  const risk = f ? riskLine(rel, f) : void 0;
-  if (risk)
-    lines.push(
-      `eminiar history: ${risk}. em_history {action:"file", path:"${rel}"} shows those fixes; keep the behaviour they restored covered by a test.`
-    );
-  const fanIn = db.metricsGet([fileId(rel)])[0]?.fan_in ?? 0;
-  if (fanIn >= FAN_IN)
-    lines.push(
-      `eminiar graph: ${rel} is imported by ${fanIn} files; em_graph_impact {node:"${fileId(rel)}"} lists them before you change an exported signature.`
-    );
+  const keys = [];
+  const histKey = `hist:${rel}`;
+  if (!seen.has(histKey)) {
+    const f = readFileRisk(db)[rel];
+    const risk = f ? riskLine(rel, f) : void 0;
+    if (risk) {
+      lines.push(
+        `eminiar history: ${risk}. em_history {action:"file", path:"${rel}"} shows those fixes; keep the behaviour they restored covered by a test.`
+      );
+      keys.push(histKey);
+    }
+  }
+  const fanKey = `fanin:${rel}`;
+  if (opts.edit && !seen.has(fanKey)) {
+    const fanIn = db.metricsGet([fileId(rel)])[0]?.fan_in ?? 0;
+    if (fanIn >= FAN_IN) {
+      lines.push(
+        `eminiar graph: ${rel} is imported by ${fanIn} files; em_graph_impact {node:"${fileId(rel)}"} lists them before you change an exported signature.`
+      );
+      keys.push(fanKey);
+    }
+  }
   if (!lines.length) return { text: "", keys: [] };
-  return { text: lines.join("\n"), keys: [key] };
+  return { text: lines.join("\n"), keys };
 }
 function commitContext(db, files) {
   if (!files.length) return "";
@@ -27197,7 +27364,7 @@ async function recallForError(db, error62, opts = {}) {
   const terms = promptTerms(error62.slice(0, 600)).filter((t) => !ERROR_FILLER.has(t));
   if (terms.length < 3) return { text: "", keys: [] };
   const need = Math.max(3, Math.ceil(terms.length * 0.4));
-  const seen = opts.sessionId ? shownKeys(db, opts.sessionId) : /* @__PURE__ */ new Set();
+  const seen = opts.sessionId ? shownKeys(db, opts.sessionId, opts.repeatAfter) : /* @__PURE__ */ new Set();
   const past = [];
   const keys = [];
   const r = await search(db, terms.join(" "), {
@@ -27223,8 +27390,10 @@ async function recallForError(db, error62, opts = {}) {
     maxMemories: opts.maxMemories ?? 2,
     maxDocs: 0,
     sessionId: opts.sessionId,
+    repeatAfter: opts.repeatAfter,
     // error text is wordy (paths, module names): the same proportional bar as past errors
-    minMatches: need
+    minMatches: need,
+    path: "error"
   });
   const memLines = mem.text.split("\n").filter((l) => l.startsWith("- memory "));
   if (!past.length && !memLines.length) return { text: "", keys: [] };
@@ -28720,10 +28889,13 @@ var userPromptSubmit = async (input2) => {
     const r = await recallForText(db, input2.prompt, {
       maxMemories: recall.maxMemories,
       maxDocs: recall.maxDocs,
-      sessionId
+      sessionId,
+      repeatAfter: recall.repeatAfter,
+      trace: true,
+      path: "prompt"
     });
+    recordShown(db, sessionId, r.keys, { path: "prompt", trace: r.trace });
     if (!r.text) return void 0;
-    recordShown(db, sessionId, r.keys);
     return {
       hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: r.text }
     };
@@ -28773,11 +28945,12 @@ var postToolUseFailure = async (input2) => {
     try {
       const r = await recallForError(db, input2.error, {
         sessionId,
-        maxMemories: Math.min(2, recall.maxMemories)
+        maxMemories: Math.min(2, recall.maxMemories),
+        repeatAfter: recall.repeatAfter
       });
       if (r.text) {
         recalled = r.text;
-        recordShown(db, sessionId, r.keys);
+        recordShown(db, sessionId, r.keys, { path: "error" });
       }
     } catch {
     }
@@ -28948,6 +29121,7 @@ var preCompact = (input2) => {
 // src/hooks/routing.ts
 init_esm_shims();
 import { realpathSync as realpathSync4, statSync as statSync4 } from "fs";
+import { homedir as homedir4 } from "os";
 import { extname as extname2, join as join11, relative as relative4, resolve as resolve3 } from "path";
 
 // src/docs/manifest.ts
@@ -29011,7 +29185,7 @@ function parseRule(raw) {
   if (!m) return void 0;
   return { raw, tool: m[1], pattern: m[2] };
 }
-function escapeRe(s) {
+function escapeRe2(s) {
   return s.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
 }
 var readRegexCache = /* @__PURE__ */ new Map();
@@ -29020,7 +29194,7 @@ function readRegex(pattern) {
   if (!re) {
     if (readRegexCache.size >= 1024) readRegexCache.clear();
     re = new RegExp(
-      `^${pattern.split("**").map((seg) => seg.split("*").map(escapeRe).join("[^/]*")).join(".*")}$`
+      `^${pattern.split("**").map((seg) => seg.split("*").map(escapeRe2).join("[^/]*")).join(".*")}$`
     );
     readRegexCache.set(pattern, re);
   }
@@ -29245,6 +29419,26 @@ function fitBudget(lines, budget) {
   return out.length > budget ? `${out.slice(0, budget - 1)}\u2026` : out;
 }
 
+// src/session/routing-stats.ts
+init_esm_shims();
+var ROUTING_CATEGORY = "routing";
+function recordRouting(db, sessionId, e) {
+  db.eventInsert({
+    sessionId,
+    category: ROUTING_CATEGORY,
+    priority: 4,
+    tool: e.tool,
+    payload: {
+      tool: e.tool,
+      decision: e.decision,
+      ...e.target ? { target: e.target } : {},
+      ...e.rule ? { rule: e.rule } : {},
+      ...e.why ? { why: e.why } : {},
+      ...e.head ? { head: e.head.slice(0, 120) } : {}
+    }
+  });
+}
+
 // src/session/server-alive.ts
 init_esm_shims();
 import { existsSync as existsSync7, mkdirSync as mkdirSync4, readdirSync, rmSync, writeFileSync as writeFileSync3 } from "fs";
@@ -29326,7 +29520,7 @@ function hookLog(level, msg) {
 }
 
 // src/hooks/routing.ts
-var SYMBOL_KINDS = [
+var SYMBOL_KINDS2 = [
   "function",
   "class",
   "method",
@@ -29344,7 +29538,7 @@ function literalOf(pattern) {
 function symbolHints(db, pattern) {
   const lit = literalOf(pattern);
   if (!lit) return void 0;
-  const nodes = db.graphFindNodes({ query: lit, kinds: SYMBOL_KINDS, limit: 5 });
+  const nodes = db.graphFindNodes({ query: lit, kinds: SYMBOL_KINDS2, limit: 5 });
   if (!nodes.length) return void 0;
   const list = nodes.map((n) => `${n.kind} ${n.name} (${n.path}:${n.start_line ?? "?"})`).join("; ");
   return `eminiar graph: symbols matching "${lit}": ${list}. em_symbols {name_path, include_body: true} reads one; {mode:"references"} lists its callers.`;
@@ -29354,6 +29548,47 @@ function coverageHint(db, rel) {
   if (!row || row.status === "indexed") return void 0;
   return `eminiar graph: ${rel} is ${row.status}${row.reason ? ` (${row.reason})` : ""}; graph answers about it may be incomplete.`;
 }
+var GIT_HISTORY = /(?:^|[;&|]\s*)git\s+(?:(?:-C|--git-dir|--work-tree)[= ]\S+\s+|--no-pager\s+)*(log|blame|shortlog|show|whatchanged|reflog)\b([^;&|]*)/;
+var ONE_COMMIT = /(^|\s)(-1|-n\s*1|-n1|--max-count[= ]1)(?=\s|$)/;
+function historyCall(cmd) {
+  const m = GIT_HISTORY.exec(cmd);
+  if (!m) return void 0;
+  const sub = m[1];
+  const rest = (m[2] ?? "").trim();
+  const args = rest.split(/\s+/).filter(Boolean);
+  const q = (s) => JSON.stringify(s.replace(/^['"]|['"]$/g, ""));
+  const positional = (a) => !a.startsWith("-");
+  if (sub === "show") {
+    if (/\S+:\S+/.test(rest)) return void 0;
+    const sha = args.find(positional);
+    return `{action:"commit", sha:${q(sha ?? "HEAD")}}`;
+  }
+  if (sub === "blame") {
+    const path3 = args.filter(positional).pop();
+    return path3 ? `{action:"file", path:${q(path3)}}` : void 0;
+  }
+  if (sub === "log" && ONE_COMMIT.test(rest) && !/(^|\s)(-p|--patch|--stat)\b/.test(rest))
+    return void 0;
+  const lineRange = /-L\s*:?([^:\s]+):(\S+)/.exec(rest);
+  if (lineRange) {
+    const [, fn, file3] = lineRange;
+    return /^[A-Za-z_$]/.test(fn) ? `{action:"symbol", name_path:${q(`${file3}#${fn}`)}}` : `{action:"file", path:${q(file3)}}`;
+  }
+  const grep = /--grep[= ]("[^"]*"|'[^']*'|\S+)/.exec(rest);
+  if (grep) return `{action:"search", query:${q(grep[1])}}`;
+  const author = /--author[= ]("[^"]*"|'[^']*'|\S+)/.exec(rest);
+  const range = args.find((a) => positional(a) && /\.\.\.?/.test(a));
+  if (range) {
+    const [a, b] = range.split(/\.\.\.?/);
+    return `{action:"branch", name:${q(b || a || "HEAD")}}`;
+  }
+  const dash = args.indexOf("--");
+  const path2 = dash !== -1 ? args[dash + 1] : args.find((a) => positional(a) && /[/.]/.test(a) && !/^[0-9a-f]{7,40}$/i.test(a));
+  if (path2) return `{action:"file", path:${q(path2)}}`;
+  if (author) return `{action:"timeline", author:${q(author[1])}}`;
+  if (sub === "shortlog") return `{action:"timeline"}`;
+  return `{action:"overview"}`;
+}
 function docsSources(root) {
   try {
     return readManifestAt(join11(root, ".eminiar", "docs.json")).sources;
@@ -29397,20 +29632,201 @@ var BIG_TEXT_EXT = /* @__PURE__ */ new Set([
 function withoutHeredocs(cmd) {
   return cmd.replace(/<<-?\s*(['"]?)(\w+)\1[^\n]*\n[\s\S]*?\n\s*\2\s*(?=\n|$)/g, "<<$2");
 }
-function suggest(toolName, input2, root) {
-  switch (toolName) {
-    case "Bash": {
-      const cmd = withoutHeredocs(String(input2.command ?? ""));
-      if (!cmd || TINY_BASH.test(cmd)) return void 0;
-      if (/^\s*cat\b[^|\n]*>/.test(cmd) && !cmd.includes("|")) return void 0;
-      if (HEAVY_BASH.test(cmd) || /\|\s*(head|tail|grep|wc|sort|uniq|jq|less)\b/.test(cmd)) {
-        return {
-          tool: "em_execute",
-          reason: `this command is likely to print a lot; em_execute {language:"shell", code, intent} keeps the output out of context and returns only matching sections`
-        };
-      }
-      return void 0;
+function splitUnquoted(s, sep2) {
+  const out = [];
+  let cur = "";
+  let quote2;
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (quote2) {
+      cur += ch;
+      if (ch === quote2 && s[i - 1] !== "\\") quote2 = void 0;
+      continue;
+    }
+    if (ch === "'" || ch === '"') {
+      quote2 = ch;
+      cur += ch;
+      continue;
+    }
+    const n = sep2(s, i);
+    if (n) {
+      out.push(cur);
+      cur = "";
+      i += n - 1;
+      continue;
+    }
+    cur += ch;
+  }
+  out.push(cur);
+  return out.map((p) => p.trim()).filter(Boolean);
+}
+function commandSegments(cmd) {
+  return splitUnquoted(cmd, (s, i) => {
+    const ch = s[i];
+    if (ch === ";" || ch === "\n") return 1;
+    if ((ch === "&" || ch === "|") && s[i + 1] === ch) return 2;
+    return 0;
+  });
+}
+function pipeStages(segment) {
+  return splitUnquoted(segment, (s, i) => s[i] === "|" && s[i + 1] !== "|" ? 1 : 0);
+}
+function headLines(stage) {
+  const m = /(?:^|\s)(?:-n\s*=?\s*|-)(\d+)(?=\s|$)|--lines[= ](\d+)/.exec(stage);
+  return m ? Number(m[1] ?? m[2]) : 10;
+}
+var BOUNDED_LINES = 400;
+function bounds(stage) {
+  if (/^\s*wc\b/.test(stage)) return true;
+  if (!/^\s*(head|tail)\b/.test(stage) || /(^|\s)-c\b|--bytes\b/.test(stage)) return false;
+  return headLines(stage) <= BOUNDED_LINES;
+}
+var MUTATING = /^\s*(?:(?:sudo|env|[A-Z_][A-Z0-9_]*=\S*)\s+)*(git\s+(add|commit|checkout|switch|push|pull|fetch|merge|rebase|stash|reset|restore|cherry-pick|revert|tag|init|clone|worktree|mv|rm|am|apply|submodule)|npm\s+(install|i|ci|uninstall|un|link|publish|version|update|up|dedupe)|pnpm\s+(install|i|add|remove|rm|update|up|link)|yarn\s+(add|remove|install|upgrade)|pip3?\s+(install|uninstall)|cargo\s+(add|install)|brew\s+(install|uninstall|upgrade)|gh\s+(pr|issue|release|repo)\s+(create|edit|merge|close|comment|delete|ready)|rm|mv|cp|mkdir|rmdir|touch|chmod|chown|ln|sed\s+(?:-\S+\s+)*-i|tee)\b/;
+var WRITES_FILE = /(?:^|\s|\d)>{1,2}\s*(?!&)(?!\/dev\/null)\S/;
+function mutates(segment) {
+  return MUTATING.test(segment) || WRITES_FILE.test(segment);
+}
+var READ_LIMIT = 200 * 1024;
+var BIG_TEXT_LIMIT = 20 * 1024;
+var GREP_VALUE_FLAGS = /* @__PURE__ */ new Set([
+  "-e",
+  "-f",
+  "-m",
+  "-A",
+  "-B",
+  "-C",
+  "-d",
+  "-g",
+  "-t",
+  "-T",
+  "--regexp",
+  "--file",
+  "--max-count",
+  "--after-context",
+  "--before-context",
+  "--context",
+  "--include",
+  "--exclude",
+  "--glob",
+  "--type"
+]);
+function fileOperands(stage, cwd) {
+  const tokens = stage.trim().split(/\s+/);
+  const cmd = tokens[0];
+  const isGrep = /^(grep|egrep|fgrep|rg)$/.test(cmd);
+  const files = [];
+  let patternGiven = !isGrep;
+  for (let i = 1; i < tokens.length; i++) {
+    const t = tokens[i];
+    if (t === "--") {
+      files.push(...tokens.slice(i + 1));
+      break;
+    }
+    if (t.startsWith("-") && t.length > 1) {
+      if (/^-[ef]$|^--(regexp|file)$/.test(t)) patternGiven = true;
+      if (GREP_VALUE_FLAGS.has(t)) i++;
+      continue;
+    }
+    if (!patternGiven) {
+      patternGiven = true;
+      continue;
+    }
+    files.push(t);
+  }
+  if (!files.length) return void 0;
+  const out = [];
+  for (let f of files) {
+    if (/[*?[\]{}$`\\]/.test(f)) return void 0;
+    f = f.replace(/^['"]|['"]$/g, "");
+    if (f.startsWith("~/")) f = join11(homedir4(), f.slice(2));
+    out.push(resolve3(cwd, f));
+  }
+  return out;
+}
+function stageBytes(stage, cwd) {
+  const files = fileOperands(stage, cwd);
+  if (!files) return void 0;
+  let total = 0;
+  for (const f of files) {
+    try {
+      const st = statSync4(f);
+      if (st.isDirectory()) return void 0;
+      if (BIG_TEXT_EXT.has(extname2(f).toLowerCase()) && st.size > BIG_TEXT_LIMIT)
+        return READ_LIMIT + st.size;
+      total += st.size;
+    } catch {
     }
+  }
+  return total;
+}
+function sedRangeLines(stage) {
+  const m = /^\s*sed\s+(?:-\S+\s+)*-n\s+['"]?(\d+),(\d+)p['"]?/.exec(stage);
+  return m ? Number(m[2]) - Number(m[1]) + 1 : void 0;
+}
+function firstStageBound(first, cwd) {
+  if (/^\s*(head|tail)\s/.test(first)) return bounds(first) || void 0;
+  const sed = sedRangeLines(first);
+  if (sed !== void 0) return sed <= BOUNDED_LINES || void 0;
+  if (/^\s*du\s+-[a-zA-Z]*s/.test(first)) return true;
+  if (/^\s*git\s+log\b/.test(first) && ONE_COMMIT.test(first)) return true;
+  if (/^\s*(grep|egrep|fgrep|rg)\s/.test(first) && /(^|\s)-[a-zA-Z]*[lLcq][a-zA-Z]*(?=\s|$)|--(files-with-matches|files-without-match|count|quiet)\b/.test(
+    first
+  ))
+    return true;
+  if (/^\s*(cat|grep|egrep|fgrep|rg)\s/.test(first)) {
+    const bytes = stageBytes(first, cwd);
+    if (bytes === void 0) return void 0;
+    if (bytes <= READ_LIMIT) return true;
+    return { rule: "big-read", text: `reads about ${Math.round(bytes / 1024)} KB` };
+  }
+  return void 0;
+}
+function heavySegment(segment, cwd) {
+  if (TINY_BASH.test(segment)) return void 0;
+  const stages = pipeStages(segment);
+  const first = stages[0];
+  if (!first) return void 0;
+  if (stages.length > 1 && bounds(stages[stages.length - 1])) return void 0;
+  const bound = firstStageBound(first, cwd);
+  if (bound === true) return void 0;
+  if (bound) return bound;
+  if (HEAVY_BASH.test(first)) return { rule: "heavy", text: "usually prints a lot" };
+  if (stages.slice(1).some((s) => /^\s*(grep|rg|sort|uniq|jq|less)\b/.test(s)))
+    return { rule: "pipe", text: "streams an unbounded output through a filter" };
+  return void 0;
+}
+function headOf(segment, n = 60) {
+  const one = segment.replace(/\s+/g, " ").trim();
+  return one.length > n ? `${one.slice(0, n - 1)}\u2026` : one;
+}
+function bashSuggestion(raw, cwd) {
+  const cmd = withoutHeredocs(raw);
+  if (!cmd.trim()) return void 0;
+  const segments = commandSegments(cmd);
+  if (segments.some(mutates)) return void 0;
+  const history = historyCall(cmd);
+  if (history) {
+    return {
+      tool: "em_history",
+      rule: "history",
+      reason: `the git history is already classified (commit kinds, fixes traced to the change that caused them, risk per file); em_history ${history} answers this without the raw log`
+    };
+  }
+  for (const segment of segments) {
+    const heavy = heavySegment(segment, cwd);
+    if (!heavy) continue;
+    return {
+      tool: "em_execute",
+      rule: heavy.rule,
+      reason: `\`${headOf(segment)}\` ${heavy.text}; em_execute {language:"shell", code, intent} keeps the output out of context and returns only matching sections`
+    };
+  }
+  return void 0;
+}
+function suggest(toolName, input2, root, extra = {}) {
+  switch (toolName) {
+    case "Bash":
+      return bashSuggestion(String(input2.command ?? ""), extra.cwd ?? root);
     case "Read": {
       const fp = String(input2.file_path ?? "");
       if (!fp) return void 0;
@@ -29422,6 +29838,7 @@ function suggest(toolName, input2, root) {
           if (!checkReadPath(loadPermissionRules(root), abs).allowed) return void 0;
           return {
             tool: "em_execute_file",
+            rule: "big-read",
             reason: `${fp} is ${Math.round(st.size / 1024)} KB; em_execute_file {path, code} processes it in the sandbox so only what you print enters context`
           };
         }
@@ -29430,10 +29847,20 @@ function suggest(toolName, input2, root) {
       return void 0;
     }
     case "Grep": {
-      if (input2.output_mode === "content" && !input2.head_limit) {
+      const content = input2.output_mode === "content" && !input2.head_limit;
+      if (extra.symbol) {
+        return {
+          tool: "em_symbols",
+          rule: "symbol",
+          annotateOnly: !content,
+          reason: `the graph indexes "${extra.symbol}": em_symbols {name_path:"${extra.symbol}", mode:"references"} lists its uses, {include_body:true} its definition; em_search {queries:["${extra.symbol}"], source:"code"} finds the code by symbol`
+        };
+      }
+      if (content) {
         return {
           tool: "em_execute",
-          reason: `content-mode grep can be large; em_execute with rg and an intent returns only matching sections`
+          rule: "content-grep",
+          reason: `content-mode grep can be large; em_execute with rg and an intent returns only matching sections (em_search {queries, mode:"regex"} scans the indexed files with context)`
         };
       }
       return void 0;
@@ -29461,7 +29888,7 @@ function suggest(toolName, input2, root) {
       return {
         tool: "em_*",
         reason: "subagents should prefer em_execute / em_batch_execute / em_search over Bash, Read and Grep",
-        prefixPrompt: 'Use the eminiar tools (em_execute, em_batch_execute, em_execute_file, em_fetch_and_index, em_search) instead of Bash/Read/Grep/WebFetch whenever output may be large; return only derived answers. Check em_recall {query} for project decisions and constraints before proposing changes, and em_docs {action:"lookup", query} before WebFetch/WebSearch for anything the project depends on.\n\n'
+        prefixPrompt: 'Use the eminiar tools (em_execute, em_batch_execute, em_execute_file, em_fetch_and_index, em_search, em_symbols, em_history) instead of Bash/Read/Grep/WebFetch whenever output may be large; return only derived answers. Check em_recall {query} for project decisions and constraints before proposing changes, em_history {action:"file", path} before editing a file, em_symbols / em_search {source:"code"} before grepping for an identifier, and em_docs {action:"lookup", query} before WebFetch/WebSearch for anything the project depends on.\n\n'
       };
     default:
       return void 0;
@@ -29502,15 +29929,20 @@ function fileKnowledge(ctx, input2) {
     if (!rel) return void 0;
     const db = getStorage(ctx, { vectors: false });
     const sessionId = input2.session_id || void 0;
-    const results = [memoriesForFile(db, rel, { sessionId })];
-    if (EDIT_TOOLS2.has(input2.tool_name ?? "")) results.push(fileContext(db, rel, { sessionId }));
+    const repeatAfter = ctx.config.recall.repeatAfter;
+    const edit = EDIT_TOOLS2.has(input2.tool_name ?? "");
+    const results = [
+      memoriesForFile(db, rel, { sessionId, symbols: fileSymbols(db, rel), repeatAfter }),
+      fileContext(db, rel, { sessionId, edit, repeatAfter })
+    ];
     const shown = results.filter((r) => r.text);
     if (!shown.length) return void 0;
     if (sessionId)
       recordShown(
         db,
         sessionId,
-        shown.flatMap((r) => r.keys)
+        shown.flatMap((r) => r.keys),
+        { path: "file" }
       );
     return shown.map((r) => r.text).join("\n");
   } catch {
@@ -29550,7 +29982,7 @@ async function webKnowledge(ctx, input2) {
   if (!text.trim()) return void 0;
   try {
     const db = getStorage(ctx, { vectors: false });
-    const r = await recallForText(db, text, { maxMemories: 0, maxDocs: 3 });
+    const r = await recallForText(db, text, { maxMemories: 0, maxDocs: 3, path: "web" });
     if (!r.text) return void 0;
     const pages = r.text.split("\n").filter((l) => l.startsWith("- docs:"));
     return [
@@ -29593,10 +30025,19 @@ var preToolUse = async (input2) => {
   const coexisting = contextModeInstalled() && ctx.config.routing.deferToContextMode;
   if (coexisting && ["Bash", "Read", "Grep", "WebFetch"].includes(input2.tool_name))
     return withContext(void 0, memo2);
-  const hint = joinHints(graphContext(ctx, input2), memo2);
-  const s = suggest(input2.tool_name, input2.tool_input, ctx.root);
-  if (!s) return withContext(void 0, hint);
-  if (s.annotateOnly) return withContext(annotate(s), hint);
+  const graph = graphContext(ctx, input2);
+  const hint = joinHints(graph, memo2);
+  const symbol2 = input2.tool_name === "Grep" && graph ? literalOf(String(input2.tool_input.pattern ?? "")) : void 0;
+  const s = suggest(input2.tool_name, input2.tool_input, ctx.root, { symbol: symbol2, cwd: input2.cwd });
+  const record2 = routingRecorder(ctx, input2, s);
+  if (!s) {
+    record2("allow");
+    return withContext(void 0, hint);
+  }
+  if (s.annotateOnly) {
+    record2("annotate", "annotate-only");
+    return withContext(annotate(s), hint);
+  }
   if (mode === "enforce") {
     if (s.prefixPrompt) {
       const prompt = String(input2.tool_input.prompt ?? "");
@@ -29617,6 +30058,7 @@ var preToolUse = async (input2) => {
         "info",
         `enforce \u2192 annotate for ${input2.tool_name}: no eminiar MCP server running for ${ctx.root}`
       );
+      record2("annotate", "no-server");
       return withContext(
         annotate(
           s,
@@ -29625,6 +30067,8 @@ var preToolUse = async (input2) => {
         hint
       );
     }
+    record2("deny");
+    hookLog("info", `deny ${input2.tool_name} \u2192 ${s.tool} [${s.rule ?? "?"}]: ${callHead(input2)}`);
     return {
       hookSpecificOutput: {
         hookEventName: "PreToolUse",
@@ -29633,9 +30077,35 @@ var preToolUse = async (input2) => {
       }
     };
   }
+  record2("annotate", "mode");
   const extra = s.prefixPrompt ? joinHints((await briefFor(ctx, String(input2.tool_input.prompt ?? ""))).trim(), hint) : hint;
   return withContext(annotate(s), extra);
 };
+var ROUTED_TOOLS = /* @__PURE__ */ new Set(["Bash", "Read", "Grep", "WebFetch", "WebSearch"]);
+function callHead(input2) {
+  const t = input2.tool_input ?? {};
+  const v = t.command ?? t.file_path ?? t.pattern ?? t.url ?? t.query ?? "";
+  return headOf(String(v), 120);
+}
+function routingRecorder(ctx, input2, s) {
+  const tool = input2.tool_name ?? "";
+  const sessionId = input2.session_id;
+  if (!sessionId || !ROUTED_TOOLS.has(tool)) return () => {
+  };
+  return (decision, why) => {
+    try {
+      recordRouting(getStorage(ctx, { vectors: false }), sessionId, {
+        tool,
+        decision,
+        target: s?.tool,
+        rule: s?.rule,
+        why,
+        head: callHead(input2)
+      });
+    } catch {
+    }
+  };
+}
 async function briefFor(ctx, task) {
   const parts = [];
   try {
@@ -29651,7 +30121,8 @@ Verify structure with em_symbols / em_graph_impact before reading files; check e
     if (recall.onAgent && task) {
       const r = await recallForText(db, task, {
         maxMemories: recall.maxMemories,
-        maxDocs: recall.maxDocs
+        maxDocs: recall.maxDocs,
+        path: "agent"
       });
       if (r.text) parts.push(r.text);
     }
@@ -29708,7 +30179,8 @@ function routingGuidance(mode) {
     '- em_search {queries, sort:"timeline"}: everything indexed plus session memory.',
     "- em_remember {content, kind, name?, status?}: memories are markdown under .eminiar/memories (survive compaction, shareable via git); em_memory {action: list|read|edit|rename|delete|status} manages them.",
     '- em_architecture {aspects?}: the project map (folders, entry points, routes, hotspots, decisions) in one call; em_symbols {name_path | mode:"overview", file} for a symbol or a file outline; em_graph_impact {node} before a refactor; em_graph_changes for what the current diff reaches; em_graph_query {pattern | preset} to walk the graph; em_index_status for coverage. em_stats shows savings.',
-    "- em_history {action: overview | file {path} | risk | commit {sha} | branch {name} | symbol {name_path} | search {query}}: the git history classified (feat/fix/refactor\u2026), branches vs base, and each fix traced back to the commit that caused it \u2014 ask it before editing a file or committing instead of running git log/blame; commit messages are searchable via em_search (source git).",
+    "- em_history {action: overview | file {path} | risk | commit {sha} | branch {name} | symbol {name_path} | search {query}}: the git history classified (feat/fix/refactor\u2026), branches vs base, and each fix traced back to the commit that caused it \u2014 ask it before editing a file or committing instead of running git log/blame/show (those are routed to it); commit messages are searchable via em_search (source git).",
+    '- A Grep for an identifier the graph knows is routed to em_symbols {name_path, mode:"references"} / em_search {queries, source:"code"}: symbol-level answers instead of raw matches.',
     "Plain Bash/Read/Grep remain right for short fixed output and files you are about to edit."
   ].join("\n");
 }
@@ -29775,11 +30247,22 @@ ${guide}`);
       );
   } catch {
   }
+  try {
+    if (existsSync9(join13(ctx.root, ".git")) && !db.metaGet("history_files"))
+      parts.push(
+        'Git history is not classified yet: em_history {action:"overview"} builds it (the server also does this in the background shortly after start); bug-prone files are flagged before you read or edit them once it exists.'
+      );
+  } catch {
+  }
   const docs = db.countDocuments();
   const latest = db.sessionLatest();
   parts.push(
     `eminiar index: ${docs} documents${latest && latest.id !== sessionId && latest.started_at ? `; previous session ${new Date(latest.started_at).toISOString().slice(0, 16)}` : ""}. Use em_search {sort:"timeline"} or em_recall to pick up where you left off.`
   );
+  hookLog(
+    "info",
+    `session_start source=${input2.source ?? "?"} session=${sessionId.slice(0, 8)} root=${ctx.root} db=${ctx.dbPath} documents=${docs} memories=${db.memoryCount()} history=${db.metaGet("history_files") ? "yes" : "no"}`
+  );
   return {
     hookSpecificOutput: {
       hookEventName: "SessionStart",