@plumpslabs/kuma 2.4.20 → 2.4.22

package/dist/index.js

@@ -11438,30 +11438,33 @@ function opencodePluginTemplate() {
     "  }",
     "}",
     "",
+    "function enforceGotchas(tool, args) {",
+    '  const name = String(tool || "").toLowerCase();',
+    "  const argv = args || {};",
+    '  const targetPath = argv.filePath || argv.targetFile || argv.path || argv.file || "";',
+    "  if (!targetPath) return;",
+    '  if (!(name.includes("edit") || name.includes("write") || name.includes("patch"))) return;',
+    "  const blocking = getBlockingGotchasForFile(String(targetPath));",
+    "  if (blocking.length > 0) {",
+    "    throw new Error(",
+    "      `\u{1F43B} [Kuma] ${blocking.length} critical/high gotcha(s) for ${targetPath}:\\n` +",
+    '      blocking.map((g) => `  \u{1F534} ${g}`).join("\\n") +',
+    '      `\\nRead .kuma/KNOWN_GOTCHAS.md for workarounds, or run kuma_memory({ action: "gotcha" }) to list.`',
+    "    );",
+    "  }",
+    "}",
+    "",
+    "// \u2500\u2500\u2500 v1 host: factory (named export, legacy mode requires functions) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500",
     "export const KumaPlugin = async () => {",
     "  return {",
     '    "tool.execute.before": async (input, output) => {',
-    '      const tool = String(input.tool || "").toLowerCase();',
-    "      const args = output.args || {};",
-    '      const targetPath = args.filePath || args.targetFile || args.path || args.file || "";',
-    "      if (!targetPath) return;",
-    '      if (!(tool.includes("edit") || tool.includes("write") || tool.includes("patch"))) return;',
-    "      const blocking = getBlockingGotchasForFile(String(targetPath));",
-    "      if (blocking.length > 0) {",
-    "        throw new Error(",
-    "          `\u{1F43B} [Kuma] ${blocking.length} critical/high gotcha(s) for ${targetPath}:\\n` +",
-    '          blocking.map((g) => `  \u{1F534} ${g}`).join("\\n") +',
-    '          `\\nRead .kuma/KNOWN_GOTCHAS.md for workarounds, or run kuma_memory({ action: "gotcha" }) to list.`',
-    "        );",
-    "      }",
+    "      enforceGotchas(input?.tool, output?.args);",
     "    },",
     '    "file.edited": async (input) => {',
-    "      // Post-edit verify nudge (log channel only \u2014 never blocks).",
-    '      const fp = input.filePath || input.path || (input.file && input.file.path) || "";',
+    '      const fp = input?.filePath || input?.path || (input?.file && input?.file.path) || "";',
     '      if (fp) console.warn(`\u{1F43B} [Kuma] ${fp} edited \u2014 consider kuma_safety({ action: "verify", scope: "${fp}" })`);',
     "    },",
     '    "experimental.session.compacting": async (input, output) => {',
-    "      // Compaction survival set via the native channel (docs: plugins#compaction).",
     "      try {",
     '        const { execSync } = await import("node:child_process");',
     '        const ctx = execSync("kuma hook pre-compact", { encoding: "utf-8", timeout: 8000 });',
@@ -11473,28 +11476,46 @@ function opencodePluginTemplate() {
     "  };",
     "};",
     "",
-    "// Server-runtime definition (required by newer OpenCode server).",
-    "// Reuses the same hooks via the named export above.",
-    "const kumaHooks = {",
-    '  "tool.execute.before": async (input, output) => {',
-    "    const hooks = await KumaPlugin();",
-    '    return hooks["tool.execute.before"](input, output);',
-    "  },",
-    '  "file.edited": async (input) => {',
-    "    const hooks = await KumaPlugin();",
-    '    return hooks["file.edited"](input);',
-    "  },",
-    '  "experimental.session.compacting": async (input, output) => {',
-    "    const hooks = await KumaPlugin();",
-    '    return hooks["experimental.session.compacting"](input, output);',
-    "  },",
-    "};",
+    "// \u2500\u2500\u2500 v1 host: module object form (v1 >= 1.18 calls server(), ignores setup) \u2500",
+    "async function server() {",
+    "  return {",
+    '    "tool.execute.before": async (input, output) => {',
+    "      enforceGotchas(input?.tool, output?.args);",
+    "    },",
+    '    "file.edited": async (input) => {',
+    '      const fp = input?.filePath || input?.path || (input?.file && input?.file.path) || "";',
+    '      if (fp) console.warn(`\u{1F43B} [Kuma] ${fp} edited \u2014 consider kuma_safety({ action: "verify", scope: "${fp}" })`);',
+    "    },",
+    '    "experimental.session.compacting": async (input, output) => {',
+    "      try {",
+    '        const { execSync } = await import("node:child_process");',
+    '        const ctx = execSync("kuma hook pre-compact", { encoding: "utf-8", timeout: 8000 });',
+    '        const parsed = JSON.parse(ctx || "{}");',
+    '        const add = parsed?.hookSpecificOutput?.hookSpecificOutput?.additionalContext || "";',
+    "        if (add && output && Array.isArray(output.context)) output.context.push(add);",
+    "      } catch { /* compacting must never fail */ }",
+    "    },",
+    "  };",
+    "}",
+    "",
+    "// \u2500\u2500\u2500 v2 host: setup registers hooks on ctx (mutable event draft) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500",
+    "async function setup(ctx) {",
+    '  const hook = ctx && ctx.tool && typeof ctx.tool.hook === "function"',
+    "    ? ctx.tool.hook.bind(ctx.tool)",
+    "    : null;",
+    "  if (!hook) return;",
+    '  await hook("execute.before", async (event) => {',
+    "    const e = event || {};",
+    '    const tool = e.tool ?? e.toolName ?? e.name ?? e.input?.tool ?? "";',
+    "    const args = e.input ?? e.args ?? e.output?.args ?? {};",
+    "    enforceGotchas(tool, args);",
+    "  });",
+    "}",
     "",
     "export default {",
     '  id: "kuma",',
-    "  // NOTE: setup must return hooks synchronously \u2014 never an async",
-    "  // effect/event-loop. An async effect never resolves and hangs load.",
-    "  setup: () => kumaHooks,",
+    "  server,",
+    "  setup,",
     "};",
     ""
   ].join("\n");
@@ -13836,6 +13857,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/manifest.ts
+import { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 
 // src/tools/kumaContextTool.ts
@@ -15618,6 +15640,25 @@ function registerAllTools(server) {
   server.tool("kuma_kuma_safety", safetyDesc, safetySchema, safetyHandler);
   console.error("[Manifest] Registered 3 core tools with universal dual-prefix aliases (kuma_* and kuma_kuma_*).");
   console.error("[Manifest] Auto-init hooks installed on all tools.");
+  const baseServer = server.server;
+  const existingListHandler = baseServer._requestHandlers?.get("tools/list");
+  if (existingListHandler) {
+    const stripSchemaMeta = (schema) => {
+      if (!schema || typeof schema !== "object") return;
+      for (const key of ["$schema", "$id", "id", "title", "definitions", "$defs"]) {
+        delete schema[key];
+      }
+    };
+    baseServer.removeRequestHandler("tools/list");
+    baseServer.setRequestHandler(ListToolsRequestSchema, async (request, extra) => {
+      const result = await existingListHandler(request, extra);
+      for (const tool of result?.tools ?? []) {
+        stripSchemaMeta(tool.inputSchema);
+        stripSchemaMeta(tool.outputSchema);
+      }
+      return result;
+    });
+  }
 }
 
 // src/index.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plumpslabs/kuma",
-  "version": "2.4.20",
+  "version": "2.4.22",
   "description": "Safety-first context & orchestration engine for AI coding agents. MCP server with mandatory research pipeline, knowledge graph, impact analysis, decision memory, and safety guard — works with any MCP client.",
   "type": "module",
   "main": "dist/index.js",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://antigravity.google/schemas/v1/plugin.json",
   "name": "kuma",
-  "version": "2.4.20",
+  "version": "2.4.22",
   "description": "Safety-first context & orchestration engine for AI coding agents. Shadow memory, gotcha lifecycle, blast radius impact analysis, and test verification.",
   "author": {
     "name": "plumpslabs",

package/skills/kuma/SKILL.md

@@ -100,5 +100,77 @@ Record what matters, skip what doesn't.
 
 📖 Full rules: `.kuma/init.md`
 
+📖 Read `.kuma/init.md` for detailed rules.
+📂 Readable state: `.kuma/KNOWN_GOTCHAS.md` (gotchas) · `.kuma/memories/decisions.md` (decisions)
+
+---
+_Generated by Kuma MCP - https://github.com/plumpslabs/kuma_
+
+---
+name: kuma-mcp
+description: Kuma MCP — .kuma/ is the single source of truth
+---
+
+Kuma MCP tools: kuma_context, kuma_memory, kuma_safety.
+Record what matters, skip what doesn't.
+
+<kuma_obedience>
+## 🔒 Obedience — honest model (issue #39)
+- HARNESS-ENFORCED (no choice): MCP schema rejects unknown actions; hooks inject gotchas pre-edit (`kuma hook pre-edit`); SessionStart serves the brief; dirty-flags patch the map post-edit.
+- AGENT-EXPECTED (best-effort ~70%): call `kuma_context({ action: "init" })` first; record gotchas IMMEDIATELY; `kuma_safety({ action: "verify" })` after edits.
+- FALLBACKS: init skipped → lazy brief on first unfamiliar edit; gotcha skipped → auto-gotcha on repeated failures; verify skipped → CI is the backstop (never treat as verified).
+</kuma_obedience>
+
+<kuma_workflow>
+🧠 **Before coding:** `kuma_context({ action: "init" })`
+🗺️ **Monorepo map:** `kuma_context({ action: "map" })`
+🔬 **Unfamiliar code / blast radius:** `kuma_context({ action: "research", scope: "<area>" })` or `kuma_context({ action: "impact", target: "<file>" })`
+🐛 **Found a bug/quirk:** `kuma_memory({ action: "gotcha" })` (IMMEDIATELY)
+🧭 **Chose between options:** `kuma_memory({ action: "decision" })`
+🔀 **Traced a flow:** `kuma_memory({ action: "arch_flow" })` (max 5 files)
+🛡️ **Before risky work / after edits:** `kuma_safety({ action: "guard" | "verify" })`
+</kuma_workflow>
+
+🪄 **Auto-inject (Claude Code):** gotcha/decision/history injected automatically before edits
+   via the PreToolUse hook — an empty hook output means the file has no gotchas.
+
+📖 Full rules: `.kuma/init.md`
+
+📖 Read `.kuma/init.md` for detailed rules.
+📂 Readable state: `.kuma/KNOWN_GOTCHAS.md` (gotchas) · `.kuma/memories/decisions.md` (decisions)
+
+---
+_Generated by Kuma MCP - https://github.com/plumpslabs/kuma_
+
+---
+name: kuma-mcp
+description: Kuma MCP — .kuma/ is the single source of truth
+---
+
+Kuma MCP tools: kuma_context, kuma_memory, kuma_safety.
+Record what matters, skip what doesn't.
+
+<kuma_obedience>
+## 🔒 Obedience — honest model (issue #39)
+- HARNESS-ENFORCED (no choice): MCP schema rejects unknown actions; hooks inject gotchas pre-edit (`kuma hook pre-edit`); SessionStart serves the brief; dirty-flags patch the map post-edit.
+- AGENT-EXPECTED (best-effort ~70%): call `kuma_context({ action: "init" })` first; record gotchas IMMEDIATELY; `kuma_safety({ action: "verify" })` after edits.
+- FALLBACKS: init skipped → lazy brief on first unfamiliar edit; gotcha skipped → auto-gotcha on repeated failures; verify skipped → CI is the backstop (never treat as verified).
+</kuma_obedience>
+
+<kuma_workflow>
+🧠 **Before coding:** `kuma_context({ action: "init" })`
+🗺️ **Monorepo map:** `kuma_context({ action: "map" })`
+🔬 **Unfamiliar code / blast radius:** `kuma_context({ action: "research", scope: "<area>" })` or `kuma_context({ action: "impact", target: "<file>" })`
+🐛 **Found a bug/quirk:** `kuma_memory({ action: "gotcha" })` (IMMEDIATELY)
+🧭 **Chose between options:** `kuma_memory({ action: "decision" })`
+🔀 **Traced a flow:** `kuma_memory({ action: "arch_flow" })` (max 5 files)
+🛡️ **Before risky work / after edits:** `kuma_safety({ action: "guard" | "verify" })`
+</kuma_workflow>
+
+🪄 **Auto-inject (Claude Code):** gotcha/decision/history injected automatically before edits
+   via the PreToolUse hook — an empty hook output means the file has no gotchas.
+
+📖 Full rules: `.kuma/init.md`
+
 📖 Read `.kuma/init.md` for detailed rules.
 📂 Readable state: `.kuma/KNOWN_GOTCHAS.md` (gotchas) · `.kuma/memories/decisions.md` (decisions)