@kage-core/kage-graph-mcp 2.5.4 → 2.5.5

package/dist/cli.js

@@ -708,6 +708,22 @@ async function main() {
         }
         return;
     }
+    if (command === "gen-plugin-hooks") {
+        // Maintainer tool: regenerate plugin/hooks/* from the setupAgent("claude-code") templates
+        // so the plugin and the npm install path ship identical hooks (one source of truth).
+        const pluginDir = takeArg(args, "--plugin-dir") ?? (0, node_path_1.join)(process.cwd(), "plugin");
+        const result = (0, kernel_js_1.generatePluginHooks)(pluginDir);
+        if (args.includes("--json")) {
+            console.log(JSON.stringify({ plugin_dir: pluginDir, ...result }, null, 2));
+            return;
+        }
+        console.log(`Generated plugin hooks in ${(0, node_path_1.join)(pluginDir, "hooks")}`);
+        console.log(`  scripts: ${result.scripts.join(", ")}`);
+        console.log(`  events:  ${result.events.join(", ")}`);
+        if (result.removed.length)
+            console.log(`  removed: ${result.removed.join(", ")}`);
+        return;
+    }
     if (command === "daemon") {
         const action = args[1];
         const projectDir = projectArg(args);

package/dist/kernel.js

@@ -102,6 +102,7 @@ exports.compactProject = compactProject;
 exports.installAgentPolicy = installAgentPolicy;
 exports.createDenseEmbeddingProvider = createDenseEmbeddingProvider;
 exports.buildEmbeddingIndex = buildEmbeddingIndex;
+exports.isUngroundedConversationalCapture = isUngroundedConversationalCapture;
 exports.recall = recall;
 exports.recallWithEmbeddings = recallWithEmbeddings;
 exports.queryCodeGraph = queryCodeGraph;
@@ -150,6 +151,7 @@ exports.capture = capture;
 exports.createPublicCandidate = createPublicCandidate;
 exports.registryRecommendations = registryRecommendations;
 exports.setupAgent = setupAgent;
+exports.generatePluginHooks = generatePluginHooks;
 exports.setupDoctor = setupDoctor;
 exports.verifyAgentActivation = verifyAgentActivation;
 exports.observe = observe;
@@ -2133,9 +2135,18 @@ function evaluateMemoryAdmission(projectDir, packet) {
         score -= 10;
         risks.push("too little context");
     }
+    // Ungrounded conversational chatter (a path-less, repo-reference-free user outburst) is not
+    // durable memory regardless of its other signals — keywords like "issue"/"before" can
+    // otherwise score it as a candidate. Hard-block admission so it can never auto-promote.
+    if (isUngroundedConversationalCapture(packet)) {
+        score -= 45;
+        risks.push("ungrounded conversational utterance, not durable knowledge");
+    }
     const bounded = Math.max(0, Math.min(100, score));
     return {
-        admit: bounded >= 45 && risks.indexOf("session bookkeeping, not durable knowledge") === -1,
+        admit: bounded >= 45
+            && risks.indexOf("session bookkeeping, not durable knowledge") === -1
+            && risks.indexOf("ungrounded conversational utterance, not durable knowledge") === -1,
         class: bounded >= 72 ? "high_signal" : bounded >= 45 ? "candidate" : "episodic_only",
         score: bounded,
         reasons,
@@ -7970,6 +7981,62 @@ function isSerializedDumpBody(body) {
     return isSerializedDumpTitle(t)
         || /<task-notification\b|<tool-use-id\b|"hookSpecificOutput"|"isImage"\s*:|"noOutputExpected"\s*:|"interrupted"\s*:\s*(true|false)/i.test(t.slice(0, 4000));
 }
+// Repo grounding signals — does the text point at something concrete in the codebase? These
+// three predicates are the shared vocabulary for "grounded": observationSignalScore weights
+// them into its durable-knowledge score, and the ungrounded-utterance guard uses their union
+// to decide whether a path-less capture references the repo at all. Kept as one source of
+// truth so the scorer and the guard can never drift on what "grounded" means.
+function textCitesPath(text) {
+    return /\b[\w.-]+\/[\w./-]+\b/.test(text)
+        || /\b[\w-]+\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|rb|json|ya?ml|toml|md|sh|css|html|sql)\b/i.test(text);
+}
+function textHasCodeIdentifier(text) {
+    return /\b[a-z][a-z0-9]*[A-Z]\w*\b/.test(text) // camelCase
+        || /\b[a-z0-9]+_[a-z0-9_]+\b/.test(text) // snake_case
+        || /`[^`]+`/.test(text)
+        || /\b\w+\(\)/.test(text);
+}
+function textHasCommand(text) {
+    return /(^|\s)(npm|pnpm|yarn|npx|node|git|cargo|make|pytest|go|tsc|kage)\s+[\w.-]/.test(text);
+}
+function hasRepoGroundingSignal(text) {
+    const t = text ?? "";
+    if (!t.trim())
+        return false;
+    return textCitesPath(t) || textHasCodeIdentifier(t) || textHasCommand(t);
+}
+// A raw conversational user utterance: a frustrated/rhetorical/imperative chat message aimed
+// at the agent — e.g. "why are you asking me???!!! it's your job, don't stop before you...".
+// It is plain prose, so the serialized-dump guard waves it through, yet it is chatter, not
+// durable repo knowledge. Detection is deliberately narrow — a run of emphatic terminal
+// punctuation, or one of a curated set of rhetorical / second-person-at-the-assistant
+// phrases — so it stays clear of normal declarative learnings (which read as statements, not
+// outbursts addressed to "you").
+function looksLikeRawUserUtterance(text) {
+    const t = (text ?? "").trim();
+    if (!t)
+        return false;
+    // Emphatic or mixed terminal punctuation ("???", "!!", "?!") — common in venting chat,
+    // essentially absent from curated memory prose.
+    if (/[!?]{2,}/.test(t))
+        return true;
+    // Rhetorical questions / second-person-imperative frustration directed at the assistant.
+    return /\b(why are you|why did you|why would you|why aren'?t you|are you (kidding|serious|even|really)|it'?s your job|that'?s your job|do your job|don'?t stop|stop asking|stop before you|keep going|hurry up|just do it|figure it out yourself|i (already )?told you)\b/i.test(t);
+}
+// Capture-noise guard for ungrounded chat. A packet trips it only when ALL hold: it cites zero
+// repo paths, its text carries no repo grounding signal (no path/file/identifier/command), and
+// it reads as a raw conversational user utterance. The conjunction is what keeps it safe — a
+// real ungrounded decision or convention names a symbol, file, command, or rule and so is never
+// caught. Such packets are routed to pending (not auto-approved) at capture time and withheld
+// from recall, mirroring how serialized dumps are gated.
+function isUngroundedConversationalCapture(packet) {
+    if (packet.paths && packet.paths.length > 0)
+        return false;
+    const text = `${packet.title ?? ""}\n${packet.body ?? ""}`;
+    if (hasRepoGroundingSignal(text))
+        return false;
+    return looksLikeRawUserUtterance(text);
+}
 // Collapse whitespace and hard-cap a value rendered inline in a context block, so one
 // oversized field (e.g. a graph fact whose body is a raw transcript) can never blow up
 // the assembled output — the 270k-char overflow that motivated this guard.
@@ -8055,7 +8122,7 @@ function recallWithVectorScores(projectDir, query, limit = 5, explain = false, i
         ];
         return { packet, score: score_breakdown.final, relevance, why_matched: unique(why).slice(0, 12), score_breakdown };
     })
-        .filter((entry) => entry.relevance > 0 && !isSerializedDumpTitle(entry.packet.title))
+        .filter((entry) => entry.relevance > 0 && !isSerializedDumpTitle(entry.packet.title) && !isUngroundedConversationalCapture(entry.packet))
         .sort((a, b) => b.score - a.score || a.packet.title.localeCompare(b.packet.title));
     const scored = diversifyRecallEntries(rankedScored, limit)
         .map(({ relevance, ...entry }) => entry);
@@ -8067,7 +8134,7 @@ function recallWithVectorScores(projectDir, query, limit = 5, explain = false, i
         const { score, why } = pendingLexicalScores.get(packet.id) ?? { score: 0, why: [] };
         return { packet, score, why_matched: why };
     })
-        .filter((entry) => entry.score > 0)
+        .filter((entry) => entry.score > 0 && !isUngroundedConversationalCapture(entry.packet))
         .sort((a, b) => b.score - a.score || a.packet.title.localeCompare(b.packet.title))
         .filter((entry) => {
         const key = `${entry.packet.type}:${entry.packet.title.toLowerCase()}:${entry.packet.paths.join(",")}`;
@@ -13711,6 +13778,20 @@ function capture(input) {
     if (missingPaths.length) {
         warnings.push(`Some referenced paths do not exist in this repo: ${missingPaths.join(", ")}`);
     }
+    // Ungrounded conversational chatter — a frustrated/rhetorical user message with no cited repo
+    // paths — is not durable memory. Don't hard-reject (a reviewer may still salvage it); instead
+    // deny it the auto-approve fast path so it lands in the pending inbox, tagged with why. Recall
+    // withholds it regardless of status. Explicit pendingReview captures already route to review.
+    const ungroundedUtterance = isUngroundedConversationalCapture({
+        title: input.title,
+        body: input.body,
+        paths: groundedPaths,
+    });
+    const routeToPending = Boolean(input.pendingReview) || ungroundedUtterance;
+    if (ungroundedUtterance && !input.pendingReview) {
+        warnings.push("Routed to pending review: this reads as an ungrounded conversational message with no cited repo paths, " +
+            "not a durable learning. Cite a repo path or restate it as a reusable insight to approve it.");
+    }
     const createdAt = nowIso();
     // Agent-asserted links to code-graph nodes (PRD `graph_nodes`): the agent recording the
     // memory knows which symbol/route/file the rule is about, so let it declare them instead
@@ -13729,9 +13810,9 @@ function capture(input) {
         scope: "repo",
         visibility: "team",
         sensitivity: "internal",
-        status: input.pendingReview ? "pending" : "approved",
+        status: routeToPending ? "pending" : "approved",
         confidence: DEFAULT_CONFIDENCE,
-        tags: input.tags ?? [],
+        tags: ungroundedUtterance ? unique([...(input.tags ?? []), "needs-grounding"]) : (input.tags ?? []),
         paths: groundedPaths,
         stack: input.stack ?? [],
         source_refs: [
@@ -13793,7 +13874,7 @@ function capture(input) {
         ...evaluateMemoryQuality(input.projectDir, packet),
         ...(contradictions.length ? { contradicts: contradictions.map((c) => c.packet_id) } : {}),
     };
-    const path = writePacket(input.projectDir, packet, input.pendingReview ? "pending" : "packets");
+    const path = writePacket(input.projectDir, packet, routeToPending ? "pending" : "packets");
     recordMemoryAudit(input.projectDir, "capture", [packet], {
         type: packet.type,
         status: packet.status,
@@ -14354,6 +14435,58 @@ exit 0
     setSnippet(paths[agent] || null, universal, [`Merge this MCP stdio config into ${agent}'s MCP settings.`, "Restart the agent after updating config."]);
     return result;
 }
+// Single source of truth for Claude Code hooks. The plugin's hook scripts and hooks.json are
+// GENERATED from the exact same setupAgent("claude-code") output the npm install path writes —
+// so a hook fix lands in both channels and they can't silently drift. The hook scripts call the
+// kage CLI and never reference their own location, so the same bodies serve both the ~/.claude
+// install and the plugin; only the wiring's command path is re-targeted to ${CLAUDE_PLUGIN_ROOT}.
+// Run via `kage gen-plugin-hooks`; a unit test asserts the committed plugin/hooks match this.
+function generatePluginHooks(pluginDir) {
+    const tmpHome = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "kage-plugin-home-"));
+    const tmpProject = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "kage-plugin-proj-"));
+    try {
+        setupAgent("claude-code", tmpProject, { write: true, homeDir: tmpHome });
+        const srcHookDir = (0, node_path_1.join)(tmpHome, ".claude", "kage", "hooks");
+        const settings = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(tmpHome, ".claude", "settings.json"), "utf8"));
+        const hooksOut = (0, node_path_1.join)(pluginDir, "hooks");
+        (0, node_fs_1.mkdirSync)(hooksOut, { recursive: true });
+        // Copy the generated hook scripts verbatim (path-agnostic — they shell out to `kage`).
+        const scripts = (0, node_fs_1.readdirSync)(srcHookDir).filter((f) => f.endsWith(".sh")).sort();
+        for (const file of scripts) {
+            (0, node_fs_1.writeFileSync)((0, node_path_1.join)(hooksOut, file), (0, node_fs_1.readFileSync)((0, node_path_1.join)(srcHookDir, file), "utf8"), { mode: 0o755 });
+        }
+        // Re-target the event wiring from the install path's `~/.claude/kage/hooks/` to the plugin's
+        // `${CLAUDE_PLUGIN_ROOT}/hooks/`, preserving events, matchers, and timeouts exactly.
+        const events = Object.keys(settings.hooks ?? {});
+        const pluginHooks = { hooks: {} };
+        for (const event of events) {
+            pluginHooks.hooks[event] = (settings.hooks ?? {})[event].map((entry) => ({
+                ...(entry.matcher !== undefined ? { matcher: entry.matcher } : {}),
+                hooks: entry.hooks.map((h) => {
+                    const m = h.command.match(/^bash ~\/\.claude\/kage\/hooks\/(.+)$/);
+                    return {
+                        type: h.type,
+                        command: m ? `bash "\${CLAUDE_PLUGIN_ROOT}/hooks/${m[1]}"` : h.command,
+                        ...(h.timeout !== undefined ? { timeout: h.timeout } : {}),
+                    };
+                }),
+            }));
+        }
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(hooksOut, "hooks.json"), `${JSON.stringify(pluginHooks, null, 2)}\n`, "utf8");
+        // Drop committed scripts the install path no longer emits (e.g. kage-prompt-context.sh,
+        // now subsumed by observe.sh handling UserPromptSubmit).
+        const removed = [];
+        for (const stale of (0, node_fs_1.readdirSync)(hooksOut).filter((f) => f.endsWith(".sh") && !scripts.includes(f))) {
+            (0, node_fs_1.unlinkSync)((0, node_path_1.join)(hooksOut, stale));
+            removed.push(stale);
+        }
+        return { scripts, removed, events };
+    }
+    finally {
+        (0, node_fs_1.rmSync)(tmpHome, { recursive: true, force: true });
+        (0, node_fs_1.rmSync)(tmpProject, { recursive: true, force: true });
+    }
+}
 function upsertJsonMcpServer(path, name, server) {
     ensureDir((0, node_path_1.dirname)(path));
     let config = {};
@@ -14756,19 +14889,13 @@ function observationSignalScore(observation) {
     const causalHits = SIGNAL_CAUSAL_MARKERS.filter((marker) => lower.includes(marker)).length;
     if (causalHits > 0)
         score += Math.min(0.35, 0.25 + (causalHits - 1) * 0.05);
-    const citesPath = Boolean(observation.path)
-        || /\b[\w.-]+\/[\w./-]+\b/.test(prose)
-        || /\b[\w-]+\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|rb|json|ya?ml|toml|md|sh|css|html|sql)\b/i.test(prose);
+    const citesPath = Boolean(observation.path) || textCitesPath(prose);
     if (citesPath)
         score += 0.2;
-    const codeIdentifier = /\b[a-z][a-z0-9]*[A-Z]\w*\b/.test(prose) // camelCase
-        || /\b[a-z0-9]+_[a-z0-9_]+\b/.test(prose) // snake_case
-        || /`[^`]+`/.test(prose)
-        || /\b\w+\(\)/.test(prose);
+    const codeIdentifier = textHasCodeIdentifier(prose);
     if (codeIdentifier)
         score += 0.15;
-    const commandLine = Boolean(observation.command)
-        || /(^|\s)(npm|pnpm|yarn|npx|node|git|cargo|make|pytest|go|tsc|kage)\s+[\w.-]/.test(prose);
+    const commandLine = Boolean(observation.command) || textHasCommand(prose);
     if (commandLine)
         score += 0.15;
     const words = combined.split(/\s+/).filter(Boolean).length;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kage-core/kage-graph-mcp",
-  "version": "2.5.4",
+  "version": "2.5.5",
   "description": "Team memory for coding agents: captures the decisions, runbooks, and bug fixes that get lost, verified against your code and shared via git. MCP server, zero deps, no account.",
   "main": "dist/index.js",
   "files": [