kibi-mcp 2.4.0 → 3.0.0

package/bin/kibi-mcp

@@ -99,7 +99,8 @@ if (args.includes("-h") || args.includes("--help")) {
 
   if (args.includes("--diagnostic-mode")) {
     globalThis.__KIBI_MCP_DIAGNOSTIC_MODE = true;
-    process.env.KIBI_WORKSPACE ??= process.cwd();
+    process.env.KIBI_WORKSPACE ??=
+      process.env.KIBI_MCP_ATTACH_ROOT?.trim() || process.cwd();
     process.env.KIBI_MCP_DIAGNOSTIC_MODE = "1";
   }
 
@@ -108,6 +109,26 @@ if (args.includes("-h") || args.includes("--help")) {
     process.stderr.write(json);
   }
 
+  // implements REQ-mcp-workspace-routing
+  // Host launchers name the workspace with KIBI_MCP_ATTACH_ROOT rather than
+  // KIBI_WORKSPACE: a pin disables per-call workspace routing. Attach after
+  // runtime resolution (which reads the launch directory) and only when no
+  // operator pin is set.
+  const attachRoot = process.env.KIBI_MCP_ATTACH_ROOT?.trim();
+  const pinned = ["KIBI_WORKSPACE", "KIBI_PROJECT_ROOT", "KIBI_ROOT"].some(
+    (key) => (process.env[key] ?? "").trim().length > 0,
+  );
+  if (attachRoot && !pinned) {
+    try {
+      process.chdir(attachRoot);
+    } catch (error) {
+      process.stderr.write(
+        `[KIBI-MCP] Cannot attach to ${attachRoot}: ${error?.message ?? String(error)}\n`,
+      );
+      process.exit(1);
+    }
+  }
+
   if (result.stale) {
     if (result.projectLocal && process.env.KIBI_MCP_PROJECT_LOCAL_REENTRY !== "1") {
       process.env.KIBI_MCP_PROJECT_LOCAL_REENTRY = "1";

package/dist/diagnostics.js

@@ -179,8 +179,11 @@ function canonicalDiagnosticValue(value) {
         .map(([key, child]) => [key, canonicalDiagnosticValue(child)]));
 }
 function mutationFingerprint(args) {
+    // A kb_upsert dry run must fingerprint like the write it previews, so
+    // validation-before-upsert pairs the two.
+    const { dryRun: _dryRun, ...payload } = args;
     return createHash("sha256")
-        .update(JSON.stringify(canonicalDiagnosticValue(args)))
+        .update(JSON.stringify(canonicalDiagnosticValue(payload)))
         .digest("hex");
 }
 function appendMutationFields(fields, args) {
@@ -311,7 +314,45 @@ function appendContradictionCheckFields(fields, contradictionCheck) {
         fields.semantic_property_key = propertyKey;
     }
 }
-export function deriveDiagnosticFields(toolName, args, telemetry, result) {
+const MODEL_MODE_OPERATIONS = {
+    analyze: "kb_semantic_advisor",
+    requirement: "kb_model_requirement",
+    predicates: "kb_suggest_predicates",
+};
+const SKILL_ACTION_OPERATIONS = {
+    list: "kb_skills_list",
+    load: "kb_skills_load",
+    read: "kb_skills_read",
+};
+/** Composite tools report diagnostics under the operation they routed to. */
+// implements REQ-kibi-mcp-tool-consolidation
+export function routedOperationName(toolName, args) {
+    if (toolName === "kb_model" && typeof args.mode === "string")
+        return MODEL_MODE_OPERATIONS[args.mode] ?? toolName;
+    if (toolName === "kb_skills" && typeof args.action === "string")
+        return SKILL_ACTION_OPERATIONS[args.action] ?? toolName;
+    if (toolName === "kb_upsert" && args.dryRun === true)
+        return "kb_validate_upsert";
+    return toolName;
+}
+/**
+ * The business arguments the routed operation received: the composite's
+ * selector is dropped, so a usage entry matches the narrow CLI route's entry.
+ */
+// implements REQ-kibi-mcp-tool-consolidation
+export function routedBusinessArgs(toolName, args) {
+    if (routedOperationName(toolName, args) === toolName)
+        return args;
+    const selector = toolName === "kb_model"
+        ? "mode"
+        : toolName === "kb_skills"
+            ? "action"
+            : "dryRun";
+    const { [selector]: _selector, ...rest } = args;
+    return rest;
+}
+export function deriveDiagnosticFields(invokedToolName, args, telemetry, result) {
+    const toolName = routedOperationName(invokedToolName, args);
     const fields = {
         telemetry_status: telemetry ? "provided" : "missing",
     };

package/dist/runtime/mcp-runtime.js

@@ -1,4 +1,31 @@
-import { CapabilityRegistryCache, ensureCapabilityRegistry, resolveBranchAttachment, } from "kibi-runtime";
+import { CapabilityRegistryCache, declaresWriteEffect, detachedHeadWriteRefusal, ensureCapabilityRegistry, resolveBranchAttachment, resolveOperationAttachment, } from "kibi-runtime";
+/**
+ * Branch attachment for one MCP operation. A detached HEAD keeps the exact
+ * contract for writes (refused with the way out) while KB reads attach the
+ * read-only snapshot compiled from the checkout, which the shared session
+ * engine then serves.
+ */
+// implements REQ-branch-store-recovery-v4
+function resolveMcpAttachment(workspaceRoot, spec) {
+    // Synchronous unless HEAD is detached: an attached checkout opens its
+    // operation context without extra event-loop turns.
+    const attachment = resolveBranchAttachment(workspaceRoot);
+    if (!("error" in attachment) || attachment.code !== "DETACHED_HEAD") {
+        return attachment;
+    }
+    if (declaresWriteEffect(spec.effects)) {
+        throw new Error(detachedHeadWriteRefusal(spec.name, workspaceRoot));
+    }
+    if (!spec.effects.includes("kb-read"))
+        return attachment;
+    return resolveOperationAttachment(workspaceRoot, spec).catch((error) => {
+        // Status diagnoses a snapshot that failed to compile instead of failing.
+        if (spec.requiresProlog)
+            throw error;
+        console.warn(`[KIBI-MCP] ${error instanceof Error ? error.message : String(error)}`);
+        return attachment;
+    });
+}
 export function attachedContextWithProlog(withAttachment, prolog) {
     return { ...withAttachment, prolog };
 }
@@ -38,7 +65,8 @@ export function createMcpRuntime(session) {
                 ...(git ? { git } : {}),
                 ...(net ? { net } : {}),
             };
-            const attachment = resolveBranchAttachment(context.workspaceRoot);
+            const resolved = resolveMcpAttachment(context.workspaceRoot, spec);
+            const attachment = resolved instanceof Promise ? await resolved : resolved;
             if (!("error" in attachment) && attachment.migrationRequired) {
                 console.warn(`[KIBI-MCP] Legacy branch attachment: Git '${attachment.gitBranch}' is reading KB '${attachment.kbBranch}'. Run 'kibi branch migrate --from ${attachment.kbBranch} --to ${attachment.gitBranch} --apply'; writes are blocked until then.`);
             }

package/dist/server/docs.js

@@ -36,7 +36,7 @@ function renderToolsDoc() {
     lines.push("");
     lines.push("Modeling note: Kibi has eight core entity types grouped into common authoring (req, scenario, test, fact) and supporting/system (adr, flag, event, symbol).");
     lines.push("Only strict domain facts (`fact_kind: subject` + `property_value`) participate in contradiction inference; use `flag` for runtime/config gates and `fact_kind: observation` or `meta` for bug/workaround notes.");
-    lines.push("Predicate flow: before writing ontology prose, call `kb_suggest_predicates`; apply a suggested `fact_kind: predicate` via `requires_predicate`, or record the returned `review:ontology-gap` observation when no predicate fits.");
+    lines.push("Predicate flow: before writing ontology prose, call `kb_model` (mode `predicates`); apply a suggested `fact_kind: predicate` via `requires_predicate`, or record the returned `review:ontology-gap` observation when no predicate fits.");
     return lines.join("\n");
 }
 export const PROMPTS = [
@@ -79,7 +79,7 @@ export const PROMPTS = [
             "Treat this server as a branch-aware knowledge graph interface for software traceability.",
             "",
             "The server exposes a curated public tool surface for KB operations:",
-            "- `kb_search`: Discovery across metadata and markdown body text",
+            "- `kb_search`: Ask a question or search; returns ranked matches plus an answer layer (governing requirements, linked facts, ADRs, scenarios and tests)",
             "- `kb_query`: Exact lookup of entities by type, ID, tags, or source file",
             "- `kb_status`: Branch, snapshot, and freshness inspection",
             "- `kb_find_gaps`: Bulk missing/present relationship analysis",
@@ -92,7 +92,7 @@ export const PROMPTS = [
             "Core modeling principles:",
             "- Kibi has eight entity types: common authoring (req, scenario, test, fact) and supporting/system (adr, flag, event, symbol).",
             "- Encode requirements as linked facts: `req --constrains--> fact` plus `req --requires_property--> fact`.",
-            "- High-confidence `kb_model_requirement` output is deterministic; `/kibi-bootstrap` bootstrap writes still require preview and explicit approval.",
+            "- High-confidence `kb_model` (mode `requirement`) output is deterministic; `/kibi-bootstrap` bootstrap writes still require preview and explicit approval.",
             "- Low-confidence claims (< 0.7) are downgraded to `observation` facts to prevent false-positive contradictions.",
             "- Only strict domain facts participate in contradiction inference; observation and meta facts are non-blocking notes.",
             "- v1 contradictions are limited to exact-value, boolean/enum, numeric range, and polarity conflicts.",
@@ -116,8 +116,8 @@ export const PROMPTS = [
             "2. **Check schema status**: Call `kb_status` to see if a schema migration is required for the branch KB.",
             "3. **Create-before-link**: Create endpoint entities with `kb_upsert` before linking them.",
             "4. **Validate intent**: If creating links, call `kb_query` for both endpoint IDs first to ensure they exist.",
-            "5. **Model requirements as facts**: For new/updated reqs, create/reuse fact entities first, then express req semantics with `constrains` + `requires_property` (automated via `kb_model_requirement`).",
-            "6. **Suggest predicates before prose**: For ontology-lane requirements, spell out the prose claim and call `kb_suggest_predicates` before writing `fact_kind: observation`. Apply the selected `fact_kind: predicate` applyPlan, then attach the returned `relationshipPlan` as `requires_predicate` while preserving existing req metadata; use the returned `review:ontology-gap` observation when no predicate fits.",
+            "5. **Model requirements as facts**: For new/updated reqs, create/reuse fact entities first, then express req semantics with `constrains` + `requires_property` (automated via `kb_model` (mode `requirement`)).",
+            "6. **Suggest predicates before prose**: For ontology-lane requirements, spell out the prose claim and call `kb_model` (mode `predicates`) before writing `fact_kind: observation`. Apply the selected `fact_kind: predicate` applyPlan, then attach the returned `relationshipPlan` as `requires_predicate` while preserving existing req metadata; use the returned `review:ontology-gap` observation when no predicate fits.",
             "7. **Plan repairs**: Requirement `kb_coverage` returns `repairPlan`; require `repairPlan.scope.complete`, apply only a batch whose state is `ready`, and treat every batch as non-auto-applicable guidance.",
             "8. **Mutate sequentially**: Query current endpoints, validate each payload, then call `kb_upsert` one at a time or `kb_delete` for explicit removals. Re-run `kb_coverage` after each batch rather than continuing from a stale plan.",
             "9. **Targeted checks**: Run `kb_check` after meaningful mutations; specify only the rules you need so scoped validation stays fast and skips the full-KB advisory scan.",
@@ -191,7 +191,7 @@ function registerDocResources() {
         '5. `kb_check` with `{ "rules": ["required-fields","no-dangling-refs"] }` for targeted validation; supplying `rules` skips the full-KB advisory scan',
         "",
         "## Model requirements as ontology predicates",
-        '1. Spell out the requirement prose and call `kb_suggest_predicates` with `{ "text": "...", "requirementId": "REQ-..." }`',
+        '1. Spell out the requirement prose and call `kb_model` with `{ "mode": "predicates", "text": "...", "requirementId": "REQ-..." }`',
         "2. If candidates are returned, apply the top or user-selected `structuredContent.applyPlan` to create `fact_kind: predicate`, then attach `structuredContent.relationshipPlan` with `requires_predicate` while preserving existing req metadata",
         "3. If no candidate fits, apply or review the returned `review:ontology-gap` observation instead of silently writing prose",
         "",

package/dist/server/session.js

@@ -20,7 +20,7 @@ import { createRequire } from "node:module";
 import process from "node:process";
 import { EngineClient } from "kibi-runtime";
 import { PrologProcess } from "kibi-runtime";
-import { copyCleanSnapshot, ensureBranchStoreManifest, getBranchDiagnostic, isValidBranchName, resolveActiveBranch, resolveBranchAttachment, } from "kibi-runtime";
+import { copyCleanSnapshot, ensureBranchStoreManifest, getBranchDiagnostic, isValidBranchName, resolveActiveBranch, resolveReadBranchAttachment, } from "kibi-runtime";
 import { getBranchOverride, isMcpDebugEnabled } from "../env.js";
 import { resolveKbPath, resolveWorkspaceRoot } from "../workspace.js";
 import { KbRefreshError, describeBranchKbStamp, readBranchKbStamp, sameBranchKbStamp, } from "./kb-freshness.js";
@@ -32,7 +32,9 @@ const defaultSessionDeps = {
     getBranchDiagnostic,
     isValidBranchName,
     resolveActiveBranch,
-    resolveBranchAttachment,
+    // The session engine serves reads; on a detached HEAD it attaches the
+    // checkout's read-only snapshot, and writes are refused before reaching it.
+    resolveBranchAttachment: resolveReadBranchAttachment,
     resolveKbPath,
     resolveWorkspaceRoot,
 };
@@ -48,7 +50,7 @@ const state = {
     isShuttingDown: false,
     shutdownTimeout: null,
 };
-// implements REQ-008
+// implements REQ-core-prolog-process-management
 export function getPrologProcess() {
     return state.prologProcess;
 }
@@ -56,11 +58,11 @@ export function getPrologProcess() {
 export function getActiveBranchName() {
     return state.activeBranchName;
 }
-// implements REQ-008
+// implements REQ-mcp-kb-freshness
 export function getAttachedBranchKbPath() {
     return state.attachedBranchKbPath;
 }
-// implements REQ-008
+// implements REQ-core-prolog-process-management
 export function getIsShuttingDown() {
     return state.isShuttingDown;
 }
@@ -70,7 +72,7 @@ export const inFlightRequests = new Map();
 export function updateAttachedBranchStamp(stamp) {
     state.attachedBranchStamp = stamp;
 }
-// implements REQ-008
+// implements REQ-core-prolog-process-management
 export function resetSessionStateForTests() {
     state.prologProcess = null;
     state.isInitialized = false;
@@ -87,15 +89,15 @@ export function resetSessionStateForTests() {
     }
 }
 export function _setSessionDepsForTests(
-// implements REQ-008
+// implements REQ-core-prolog-process-management
 overrides) {
     sessionDeps = { ...sessionDeps, ...overrides };
 }
 export function _resetSessionDepsForTests() {
-    // implements REQ-008
+    // implements REQ-core-prolog-process-management
     sessionDeps = { ...defaultSessionDeps };
 }
-// implements REQ-008
+// implements REQ-core-prolog-process-management
 export function _setPrologProcessForTests(process) {
     state.prologProcess = process;
 }
@@ -105,7 +107,7 @@ function debugLog(...args) {
     }
 }
 export function ensureBranchKbExists(workspaceRoot, branch) {
-    // implements REQ-008
+    // implements REQ-branch-store-recovery-v4
     if (!sessionDeps.isValidBranchName(branch)) {
         throw new Error(`Invalid branch name: ${branch}`);
     }
@@ -175,7 +177,7 @@ export async function initiateGracefulShutdown(exitCode = 0) {
     // Exit
     process.exit(exitCode);
 }
-// implements REQ-008
+// implements REQ-core-prolog-process-management
 export async function resetProlog(reason) {
     debugLog(`[KIBI-MCP] Resetting Prolog worker: ${reason}`);
     state.prologResetGeneration += 1;
@@ -222,7 +224,7 @@ async function refreshAttachedBranchKbWithRetry(prolog, kbPath, currentStamp, as
 function usesBranchKbPath(kbPath) {
     return (kbPath.includes("/.kb/branches/") || kbPath.includes("\\.kb\\branches\\"));
 }
-// implements REQ-008
+// implements REQ-core-prolog-process-management
 async function ensurePrologUnsafe() {
     const generationAtStart = state.prologResetGeneration;
     const workspaceRoot = sessionDeps.resolveWorkspaceRoot();

package/dist/server/tool-registration.js

@@ -1,5 +1,6 @@
 import { getSpec, statusSpec } from "kibi-runtime";
-import { executeApplyPlan, executeCompileIntent, executeDelete, executeIngestProof, executeUpsert, validateUpsertSpec, } from "kibi-runtime";
+import { MODEL_ROUTES, SKILL_ROUTES, dispatchComposite, executeApplyPlan, executeCompileIntent, executeDelete, executeIngestProof, executeUpsert, } from "kibi-runtime";
+import { OPTIONAL_TOOL_NAMES, enabledOptionalTools } from "../tools-config.js";
 import { startJob } from "./jobs.js";
 // implements REQ-002, REQ-013
 export function registerConfiguredTools(server, runtime, registerTool) {
@@ -21,6 +22,12 @@ export function registerConfiguredTools(server, runtime, registerTool) {
         prolog: prologFor(context),
     });
     const register = ({ name, execute }) => {
+        // Optional tools (kb_sparql_remote) are registered only when enabled;
+        // every other configured tool must have a definition.
+        if (OPTIONAL_TOOL_NAMES.includes(name) &&
+            !runtime.tools.some((tool) => tool.name === name)) {
+            return;
+        }
         const definition = toolDef(name);
         const publicSpec = getSpec(name);
         const spec = {
@@ -55,16 +62,21 @@ export function registerConfiguredTools(server, runtime, registerTool) {
         statusSpec.execute(args, context),
     });
     register({
-        name: "kb_skills_list",
-        execute: async (_context, args) => runtime.handleKbSkillsList(args),
-    });
-    register({
-        name: "kb_skills_load",
-        execute: async (_context, args) => runtime.handleKbSkillsLoad(args),
-    });
-    register({
-        name: "kb_skills_read",
-        execute: async (_context, args) => runtime.handleKbSkillsRead(args),
+        name: "kb_skills",
+        execute: async (context, args) => dispatchComposite("action", {
+            list: {
+                ...SKILL_ROUTES.list,
+                execute: async (input) => runtime.handleKbSkillsList(input),
+            },
+            load: {
+                ...SKILL_ROUTES.load,
+                execute: async (input) => runtime.handleKbSkillsLoad(input),
+            },
+            read: {
+                ...SKILL_ROUTES.read,
+                execute: async (input) => runtime.handleKbSkillsRead(input),
+            },
+        }, args, context),
     });
     register({
         name: "kb_find_gaps",
@@ -83,17 +95,26 @@ export function registerConfiguredTools(server, runtime, registerTool) {
         execute: async (context, args) => runtime.handleSparql(args, context),
     });
     register({
-        name: "kb_semantic_advisor",
-        execute: async (context, args) => runtime.handleKbSemanticAdvisor(args, context),
+        name: "kb_model",
+        execute: async (context, args) => dispatchComposite("mode", {
+            analyze: {
+                ...MODEL_ROUTES.analyze,
+                execute: async (input) => runtime.handleKbSemanticAdvisor(input, context),
+            },
+            requirement: {
+                ...MODEL_ROUTES.requirement,
+                execute: async (input) => runtime.handleKbModelRequirement(prologFor(context), input, withSessionProlog(context)),
+            },
+            predicates: {
+                ...MODEL_ROUTES.predicates,
+                execute: async (input) => runtime.handleKbSuggestPredicates(prologFor(context), input, withSessionProlog(context)),
+            },
+        }, args, context),
     });
     register({
         name: "kb_upsert",
         execute: async (context, args) => executeUpsert(args, withSessionProlog(context)),
     });
-    register({
-        name: "kb_validate_upsert",
-        execute: async (context, args) => validateUpsertSpec.execute(args, withSessionProlog(context)),
-    });
     register({
         name: "kb_delete",
         execute: async (context, args) => executeDelete(args, withSessionProlog(context)),
@@ -102,7 +123,9 @@ export function registerConfiguredTools(server, runtime, registerTool) {
         name: "kb_check",
         execute: async (context, args) => {
             const { async: asyncMode, ...checkArgs } = args;
-            if (asyncMode !== true) {
+            // Without a registered kb_job_status nothing could poll the receipt,
+            // so async falls back to a synchronous check.
+            if (asyncMode !== true || !enabledOptionalTools().has("kb_job_status")) {
                 return runtime.handleKbCheck(prologFor(context), args);
             }
             // Long-KB full checks can exceed the tool timeout. Detach into a job
@@ -115,14 +138,6 @@ export function registerConfiguredTools(server, runtime, registerTool) {
         name: "kb_prepare_impact_review",
         execute: async (context, args) => getSpec("kb_prepare_impact_review").execute(args, context),
     });
-    register({
-        name: "kb_model_requirement",
-        execute: async (context, args) => runtime.handleKbModelRequirement(prologFor(context), args, withSessionProlog(context)),
-    });
-    register({
-        name: "kb_suggest_predicates",
-        execute: async (context, args) => runtime.handleKbSuggestPredicates(prologFor(context), args, withSessionProlog(context)),
-    });
     register({
         name: "kb_plan_bootstrap",
         execute: async (context, args) => runtime.handleKbPlanBootstrap(args, context),

package/dist/server/tools-runtime.js

@@ -25,7 +25,7 @@ const defaultToolsServerDeps = {
 };
 let sessionModulePromise = null;
 const prologPorts = new WeakMap();
-// implements REQ-008
+// implements REQ-002
 export function _setToolsServerDepsForTests(deps, resetPromise = false) {
     defaultToolsServerDeps.getSessionModule =
         deps.getSessionModule ?? defaultToolsServerDeps.getSessionModule;

package/dist/server/tools.js

@@ -16,9 +16,11 @@
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 import process from "node:process";
-import { executeOperation } from "kibi-runtime";
+import { QUERY_LIMIT_EXCEEDED_CODE, detachedReadOnlyDiagnostic, executeOperation, queryLimitExceededOf, } from "kibi-runtime";
 import { operationData, toKibiResult } from "kibi-runtime";
+import { routedBusinessArgs, routedOperationName } from "../diagnostics.js";
 import { isMcpDebugEnabled } from "../env.js";
+import { enabledOptionalTools } from "../tools-config.js";
 import { appendDiagnosticErrorUsage, appendDiagnosticSuccessUsage, } from "./diagnostic-usage.js";
 import { getJob, jobSnapshot } from "./jobs.js";
 import { jsonSchemaToZod } from "./json-schema-to-zod.js";
@@ -55,7 +57,7 @@ function withAgentVisibleText(content, data) {
     const text = summary.length > 0 ? `${payload}\n${summary}` : payload;
     return [{ type: "text", text }, ...nonTextParts];
 }
-// implements REQ-008
+// implements REQ-002
 function debugLog(...args) {
     if (isMcpDebugEnabled()) {
         console.error(...args);
@@ -142,12 +144,33 @@ function localDecision(name, args) {
     const { [WORKSPACE_ROOT_ARGUMENT]: _ignored, ...rest } = args;
     return { kind: "local", args: rest };
 }
-/** A result's diagnostics name the workspace mismatch when routing fell back. */
+/** A result's diagnostics carry a routing or detached-HEAD notice when one applies. */
 function withWorkspaceNotice(envelope, notice) {
     if (!notice)
         return envelope;
     return { ...envelope, diagnostics: [...envelope.diagnostics, notice] };
 }
+/**
+ * Observe the context an operation opens so its envelope can say when a
+ * detached HEAD answered from the read-only snapshot, and which store.
+ */
+// implements REQ-branch-store-recovery-v4
+function observeDetachedReads(base) {
+    let notice;
+    return {
+        runtime: {
+            // Read the attachment at close (success or error) so opening the
+            // context costs no extra event-loop turn.
+            open: (spec, options) => base.open(spec, options),
+            afterSuccess: (spec, context) => base.afterSuccess(spec, context),
+            close: (context, outcome) => {
+                notice = detachedReadOnlyDiagnostic(context.branchAttachment);
+                return base.close(context, outcome);
+            },
+        },
+        notice: () => notice,
+    };
+}
 // implements REQ-002
 export function addTool(server, name, description, inputSchema, handler, 
 // INTENTIONAL: DEFAULT_TOOLS_RUNTIME is typed as ToolsRuntime<PrologProcess>; the
@@ -204,7 +227,8 @@ runtime = DEFAULT_TOOLS_RUNTIME, spec, annotations, outputSchema) {
                 requiresProlog: false,
                 execute: async (input, _context) => handler(input),
             };
-            const handlerPromise = executeOperation(runtime.operationRuntime, operationSpec, businessArgs, { signal: controller.signal });
+            const observed = observeDetachedReads(runtime.operationRuntime);
+            const handlerPromise = executeOperation(observed.runtime, operationSpec, businessArgs, { signal: controller.signal });
             trackedRequests.set(requestId, handlerPromise);
             let resetAttempted = false;
             let resetSucceeded = false;
@@ -239,15 +263,18 @@ runtime = DEFAULT_TOOLS_RUNTIME, spec, annotations, outputSchema) {
                     }
                 });
                 const data = operationData(result);
-                const envelope = withWorkspaceNotice(toKibiResult(operationSpec, data), workspaceNotice);
+                const envelope = withWorkspaceNotice(withWorkspaceNotice(toKibiResult(operationSpec, data), workspaceNotice), observed.notice());
                 // Log usage in diagnostic mode
                 if (diagnosticModeEnabled) {
                     await appendDiagnosticSuccessUsage({
                         runtime,
-                        toolName: name,
+                        // Usage evidence records the routed operation (kb_model mode
+                        // predicates logs as kb_suggest_predicates) so telemetry
+                        // acceptance keeps reading one operation per entry.
+                        toolName: routedOperationName(name, businessArgs),
                         requestId,
                         args,
-                        businessArgs,
+                        businessArgs: routedBusinessArgs(name, businessArgs),
                         telemetry,
                         startedAt,
                         result: envelope,
@@ -277,10 +304,13 @@ runtime = DEFAULT_TOOLS_RUNTIME, spec, annotations, outputSchema) {
                 if (diagnosticModeEnabled) {
                     await appendDiagnosticErrorUsage({
                         runtime,
-                        toolName: name,
+                        // Usage evidence records the routed operation (kb_model mode
+                        // predicates logs as kb_suggest_predicates) so telemetry
+                        // acceptance keeps reading one operation per entry.
+                        toolName: routedOperationName(name, businessArgs),
                         requestId,
                         args,
-                        businessArgs,
+                        businessArgs: routedBusinessArgs(name, businessArgs),
                         telemetry,
                         startedAt,
                         error,
@@ -288,7 +318,9 @@ runtime = DEFAULT_TOOLS_RUNTIME, spec, annotations, outputSchema) {
                     });
                 }
                 if (isToolTimeoutError(error) &&
-                    isMutationEffect(operationSpec.effects)) {
+                    isMutationEffect(operationSpec.effects) &&
+                    // A kb_upsert dry run writes nothing, so its outcome is known.
+                    !(name === "kb_upsert" && businessArgs.dryRun === true)) {
                     const recoveryActions = [
                         {
                             operation: "kb_status",
@@ -329,6 +361,25 @@ runtime = DEFAULT_TOOLS_RUNTIME, spec, annotations, outputSchema) {
                         structuredContent: envelope,
                     };
                 }
+                const limitExceeded = queryLimitExceededOf(error);
+                if (error instanceof Error && limitExceeded !== null) {
+                    // A read stopped at its engine limit has no answer: say which
+                    // limit stopped it rather than failing like a broken tool.
+                    const envelope = withWorkspaceNotice(withWorkspaceNotice(toKibiResult(operationSpec, null, {
+                        status: "error",
+                        error: {
+                            code: QUERY_LIMIT_EXCEEDED_CODE,
+                            message: error.message,
+                            retryable: false,
+                            details: { limitExceeded },
+                        },
+                    }), workspaceNotice), observed.notice());
+                    return {
+                        content: [{ type: "text", text: JSON.stringify(envelope) }],
+                        structuredContent: envelope,
+                        isError: true,
+                    };
+                }
                 throw error;
             }
             finally {
@@ -357,7 +408,9 @@ export function registerAllTools(server,
 // INTENTIONAL: same generic bridge cast as addTool — see comment there.
 runtime = DEFAULT_TOOLS_RUNTIME) {
     registerConfiguredTools(server, runtime, addTool);
-    registerJobStatusTool(server);
+    if (enabledOptionalTools().has("kb_job_status")) {
+        registerJobStatusTool(server);
+    }
 }
 /**
  * kb_job_status polls background jobs started by long-running operations

package/dist/server.js

@@ -31,8 +31,8 @@ const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.me
 const VERSION = packageJson.version ?? "0.1.0";
 const SERVER_INSTRUCTIONS = [
     "Kibi is a branch-local requirements knowledge base for software traceability.",
-    "Start with kb_search for discovery, then kb_query for exact lookups before any mutation.",
-    "Model requirements as linked facts via kb_model_requirement or kb_upsert (create endpoints before linking them).",
+    "Start with kb_search (ask it a question; its answer layer names the governing requirements, facts, ADRs and tests), then kb_query for exact lookups before any mutation.",
+    "Model requirements as linked facts via kb_model (mode requirement) or kb_upsert (create endpoints before linking them); preflight writes with kb_upsert dryRun:true.",
     "Mutate sequentially with kb_upsert and kb_delete; validate with kb_check during iteration and run an unfiltered kb_check before completion.",
     "Confirm branch freshness with kb_status. For first-time repository setup, use the kibi-bootstrap prompt.",
 ].join(" ");

package/dist/tools-config.js

@@ -18,30 +18,50 @@
 import { getSpec } from "kibi-runtime";
 import { DIAGNOSTIC_MODE_ENABLED, DIAGNOSTIC_TELEMETRY_SCHEMA, } from "./diagnostics.js";
 import { withWorkspaceRootSchema } from "./server/workspace-router.js";
+// implements REQ-kibi-mcp-tool-consolidation
+/**
+ * The agent-facing tool list. Narrower operations (kb_skills_list,
+ * kb_semantic_advisor, kb_model_requirement, kb_suggest_predicates,
+ * kb_validate_upsert) stay in the operation catalog and on the CLI; MCP
+ * reaches them through kb_skills, kb_model and kb_upsert dryRun so hosts
+ * load fewer tool definitions.
+ */
 const MCP_TOOL_ORDER = [
     "kb_query",
     "kb_search",
     "kb_status",
-    "kb_skills_list",
-    "kb_skills_load",
-    "kb_skills_read",
+    "kb_skills",
     "kb_find_gaps",
     "kb_coverage",
     "kb_graph",
-    "kb_sparql_remote",
-    "kb_semantic_advisor",
+    "kb_model",
     "kb_upsert",
-    "kb_validate_upsert",
     "kb_delete",
     "kb_check",
     "kb_prepare_impact_review",
-    "kb_model_requirement",
-    "kb_suggest_predicates",
     "kb_plan_bootstrap",
     "kb_compile_intent",
     "kb_apply_plan",
     "kb_ingest_proof",
 ];
+/** Tools registered only when named in KIBI_MCP_OPTIONAL_TOOLS. */
+// implements REQ-kibi-mcp-tool-consolidation
+export const OPTIONAL_TOOL_NAMES = [
+    "kb_sparql_remote",
+    "kb_job_status",
+];
+/**
+ * Parse KIBI_MCP_OPTIONAL_TOOLS: a comma-separated list of optional tool
+ * names, or "all".
+ */
+// implements REQ-kibi-mcp-tool-consolidation
+export function enabledOptionalTools(value = process.env.KIBI_MCP_OPTIONAL_TOOLS) {
+    const requested = new Set((value ?? "")
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter(Boolean));
+    return new Set(OPTIONAL_TOOL_NAMES.filter((name) => requested.has("all") || requested.has(name)));
+}
 // implements REQ-002
 const TOOL_ANNOTATIONS = {
     kb_query: {
@@ -57,6 +77,20 @@ const TOOL_ANNOTATIONS = {
         idempotentHint: true,
         openWorldHint: false,
     },
+    kb_skills: {
+        title: "Read bundled Kibi skills",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+    kb_model: {
+        title: "Model Kibi requirement prose",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     kb_skills_list: {
         title: "List bundled Kibi skills",
         readOnlyHint: true,
@@ -151,7 +185,15 @@ const TOOL_ANNOTATIONS = {
         openWorldHint: false,
     },
 };
-const BASE_TOOLS = MCP_TOOL_ORDER.map((name) => {
+function exposedToolNames(optional) {
+    return [
+        ...MCP_TOOL_ORDER,
+        ...(optional.has("kb_sparql_remote")
+            ? ["kb_sparql_remote"]
+            : []),
+    ];
+}
+function toolConfig(name) {
     const spec = getSpec(name);
     const effects = spec.declaredEffects;
     const derived = {
@@ -173,7 +215,13 @@ const BASE_TOOLS = MCP_TOOL_ORDER.map((name) => {
             ...derived,
         },
     };
-});
+}
+/** Catalog tool configs for the base list plus the given optional tools. */
+// implements REQ-kibi-mcp-tool-consolidation
+export function buildBaseTools(optional = enabledOptionalTools()) {
+    return exposedToolNames(optional).map(toolConfig);
+}
+const BASE_TOOLS = buildBaseTools();
 /**
  * Inject _diagnostic_telemetry schema into tool inputs when diagnostic mode is enabled.
  * Exported for unit coverage; TOOLS still applies it only when the server starts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-mcp",
-  "version": "2.4.0",
+  "version": "3.0.0",
   "mcpName": "io.github.Looted/kibi-mcp",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
@@ -10,8 +10,8 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-runtime": "^2.2.0",
-    "kibi-core": "^0.14.1",
+    "kibi-runtime": "^2.3.0",
+    "kibi-core": "^0.15.0",
     "mcpcat": "^0.1.12",
     "zod": "^4.3.6"
   },
@@ -29,7 +29,10 @@
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "prepack": "npm run build && node ../../scripts/verify-package-contract.mjs kibi-mcp"
   },
-  "files": ["dist", "bin"],
+  "files": [
+    "dist",
+    "bin"
+  ],
   "engines": {
     "node": ">=22"
   },