kibi-mcp 2.2.0 → 2.4.0

package/dist/server/docs.js

@@ -54,9 +54,13 @@ export const PROMPTS = [
             "",
             "Inspect `kb_status.bootstrap` and follow its typed `nextAction`. If infrastructure is missing, run `kibi init` before planning.",
             "",
+            "## Source interview",
+            "",
+            "Before planning, list the knowledge sources you can read (your MCP connectors for issue trackers, wikis, and specs, plus in-repo docs) and ask the user which hold product intent and which are authoritative, supporting, or stale. Read the confirmed sources and pass them as `bootstrapContext.knowledgeSources` with cited `bootstrapContext.intentClaims`. Kibi never contacts those sources itself.",
+            "",
             "## Preview and Approval",
             "",
-            "Call `kb_plan_bootstrap` read-only. Ask only the bounded questions returned when its status is `needs_context`; do not invent a questionnaire.",
+            "Call `kb_plan_bootstrap` read-only. After the source interview, ask only the bounded questions returned when its status is `needs_context`.",
             "",
             "Show the exact returned `structuredContent.plan`, its actions, and canonical hash. Get explicit user approval, then pass that plan object unchanged to `kb_apply_plan`.",
             "",

package/dist/server/tool-registration.js

@@ -111,6 +111,10 @@ export function registerConfiguredTools(server, runtime, registerTool) {
             return startJob("kb_check", () => runtime.handleKbCheck(prologFor(context), checkArgs));
         },
     });
+    register({
+        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)),

package/dist/server/tools.js

@@ -24,6 +24,7 @@ import { getJob, jobSnapshot } from "./jobs.js";
 import { jsonSchemaToZod } from "./json-schema-to-zod.js";
 import { registerConfiguredTools } from "./tool-registration.js";
 import { DEFAULT_TOOLS_RUNTIME, _resetSessionModulePromise, _setToolsServerDepsForTests, } from "./tools-runtime.js";
+import { WORKSPACE_ROOT_ARGUMENT, getWorkspaceRouter, } from "./workspace-router.js";
 export { jsonSchemaToZod } from "./json-schema-to-zod.js";
 export { _resetSessionModulePromise, _setToolsServerDepsForTests };
 const DEFAULT_TOOL_TIMEOUT_MS = 90_000;
@@ -115,23 +116,72 @@ async function withToolTimeout(toolName, operation, onTimeout) {
         }
     }
 }
+/**
+ * A module that vanished after startup means the package was upgraded or
+ * reinstalled under a running server; only a restart loads the new install.
+ */
+function staleInstallHint(error) {
+    const code = error.code;
+    const missingModule = code === "ERR_MODULE_NOT_FOUND" ||
+        code === "MODULE_NOT_FOUND" ||
+        /Cannot find (module|package)/.test(error.message);
+    return missingModule
+        ? " — this Kibi MCP server is running from files that are no longer installed (Kibi was likely upgraded or reinstalled after it started). Restart the Kibi MCP server; the project-local kibi CLI works in the meantime."
+        : "";
+}
+/**
+ * The decision when no workspace router is installed (unit tests, embedded
+ * use): every call is local, and `workspaceRoot` is dropped so handlers never
+ * see a routing-only argument. kb_check keeps it: there it also names the
+ * tree to inspect for impact diagnostics.
+ */
+function localDecision(name, args) {
+    if (!(WORKSPACE_ROOT_ARGUMENT in args) || name === "kb_check") {
+        return { kind: "local", 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. */
+function withWorkspaceNotice(envelope, notice) {
+    if (!notice)
+        return envelope;
+    return { ...envelope, diagnostics: [...envelope.diagnostics, notice] };
+}
 // implements REQ-002
 export function addTool(server, name, description, inputSchema, handler, 
 // INTENTIONAL: DEFAULT_TOOLS_RUNTIME is typed as ToolsRuntime<PrologProcess>; the
 // generic TProlog parameter exists so tests can inject a mock type. The cast is safe
 // because the runtime object satisfies the full ToolsRuntime contract at runtime.
 runtime = DEFAULT_TOOLS_RUNTIME, spec, annotations, outputSchema) {
-    const wrappedHandler = async (args) => {
+    const wrappedHandler = async (rawArgs) => {
         const startedAt = new Date();
         const diagnosticModeEnabled = runtime.diagnosticModeEnabled();
-        const { businessArgs, telemetry } = diagnosticModeEnabled
-            ? runtime.extractToolCallPayload(args)
-            : { businessArgs: args, telemetry: null };
+        let args = rawArgs;
+        let workspaceNotice;
+        let businessArgs = rawArgs;
+        let telemetry = null;
         try {
             // Validate that args is a valid object
             if (typeof args !== "object" || args === null) {
                 throw new Error(`Invalid arguments for tool ${name}: expected object, got ${typeof args}`);
             }
+            // Answer from the workspace the caller is working in. A call routed to
+            // another workspace's kibi-mcp returns that server's result as is; the
+            // child logs its own usage and the parent records nothing for it.
+            // Without a router the decision is synchronous, so a plain call reaches
+            // its handler without an extra microtask.
+            const router = getWorkspaceRouter();
+            const routing = router
+                ? await router.route(name, args)
+                : localDecision(name, args);
+            if (routing.kind === "remote")
+                return routing.result;
+            args = routing.args;
+            workspaceNotice = routing.notice;
+            ({ businessArgs, telemetry } = diagnosticModeEnabled
+                ? runtime.extractToolCallPayload(args)
+                : { businessArgs: args, telemetry: null });
             // Check if shutting down before processing
             if (await runtime.isShuttingDown()) {
                 throw new Error(`Tool ${name} rejected: server is shutting down`);
@@ -189,7 +239,7 @@ runtime = DEFAULT_TOOLS_RUNTIME, spec, annotations, outputSchema) {
                     }
                 });
                 const data = operationData(result);
-                const envelope = toKibiResult(operationSpec, data);
+                const envelope = withWorkspaceNotice(toKibiResult(operationSpec, data), workspaceNotice);
                 // Log usage in diagnostic mode
                 if (diagnosticModeEnabled) {
                     await appendDiagnosticSuccessUsage({
@@ -292,7 +342,7 @@ runtime = DEFAULT_TOOLS_RUNTIME, spec, annotations, outputSchema) {
             if (err.stack) {
                 debugLog(`[KIBI-MCP] Tool ${name} stack:`, err.stack);
             }
-            throw new Error(`Tool ${name} failed: ${err.message}`, { cause: err });
+            throw new Error(`Tool ${name} failed: ${err.message}${staleInstallHint(err)}`, { cause: err });
         }
     };
     server.registerTool(name, {

package/dist/server/workspace-router.js

@@ -0,0 +1,583 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+// implements REQ-mcp-workspace-routing
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { CallToolResultSchema, RootsListChangedNotificationSchema, } from "@modelcontextprotocol/sdk/types.js";
+/**
+ * Workspace routing: answer every tool call from the workspace the caller is
+ * working in, not the one this server happened to start in.
+ *
+ * Hosts start an MCP server once per project and then let the agent work
+ * elsewhere, most often in a git worktree. A server attached at startup would
+ * answer from the original checkout's branch, and nothing in the result would
+ * say so. This router decides, per call, which workspace should answer:
+ *
+ * 1. an explicit `workspaceRoot` argument (every tool accepts it; host hooks
+ *    fill it in from the agent's current directory where hooks exist, and any
+ *    agent can pass its working directory);
+ * 2. otherwise the client's MCP roots, when the client declares them;
+ * 3. otherwise the workspace this server is attached to.
+ *
+ * Another workspace is served by a child kibi-mcp started there (the
+ * workspace's own project-local install when present, else this server's
+ * entry), connected as an MCP client, pooled, and retired when idle. Routing
+ * is limited to worktrees of the same repository, directories under the
+ * client's roots, and `KIBI_MCP_ROUTABLE_ROOTS`; anything else, and any
+ * failure to start the child, falls back to the attached workspace with a
+ * `workspace_mismatch` diagnostic in the result, so a wrong-branch answer is
+ * never silent. `KIBI_WORKSPACE` (or an alias) pins the server and disables
+ * routing; a routed child is itself pinned and never routes further.
+ */
+export const WORKSPACE_ROOT_ARGUMENT = "workspaceRoot";
+export const WORKSPACE_ROOT_SCHEMA = {
+    type: "string",
+    description: "Optional absolute path of the workspace this call is about when it differs from the one the server started in, for example the git worktree you are working in. The server answers from that workspace's knowledge base when it is a worktree of the same repository or lies under the client's MCP roots; otherwise it answers from its own workspace and adds a workspace_mismatch diagnostic. Host hooks fill this in automatically where available.",
+};
+/** Mirror of the runtime's workspace env keys; any of them pins the server. */
+const WORKSPACE_PIN_KEYS = [
+    "KIBI_WORKSPACE",
+    "KIBI_PROJECT_ROOT",
+    "KIBI_ROOT",
+];
+const ROUTED_CHILD_ENV = "KIBI_MCP_ROUTED";
+const ROUTING_SWITCH_ENV = "KIBI_MCP_ROUTING";
+const ROUTABLE_ROOTS_ENV = "KIBI_MCP_ROUTABLE_ROOTS";
+const KIBI_MCP_PACKAGE = "kibi-mcp";
+const DEFAULT_MAX_CHILDREN = 4;
+const DEFAULT_IDLE_RETIRE_MS = 10 * 60 * 1000;
+const DEFAULT_ROOTS_TIMEOUT_MS = 2000;
+const DEFAULT_CONNECT_TIMEOUT_MS = 30000;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * The Kibi workspace that owns `directory`: the nearest ancestor holding
+ * `.kb/manifest.json`, without crossing a `.git` boundary so an unrelated
+ * enclosing repository never claims the directory.
+ */
+export function kibiWorkspaceFor(directory) {
+    let current = path.resolve(directory);
+    for (;;) {
+        if (fs.existsSync(path.join(current, ".kb", "manifest.json"))) {
+            return current;
+        }
+        if (fs.existsSync(path.join(current, ".git")))
+            return null;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+/** The workspace named by MCP roots: the first file root in a Kibi workspace. */
+export function workspaceFromRoots(roots, resolveWorkspace = kibiWorkspaceFor) {
+    for (const root of roots) {
+        const workspace = resolveWorkspace(root);
+        if (workspace)
+            return workspace;
+    }
+    return null;
+}
+function realpathOrSelf(target) {
+    try {
+        return fs.realpathSync.native(target);
+    }
+    catch {
+        return path.resolve(target);
+    }
+}
+function isWithin(parent, candidate) {
+    const relative = path.relative(realpathOrSelf(parent), realpathOrSelf(candidate));
+    return (relative === "" ||
+        (!relative.startsWith("..") && !path.isAbsolute(relative)));
+}
+/** The repository's shared git directory, so worktrees compare equal. */
+export function gitCommonDirectory(directory) {
+    const result = spawnSync("git", ["rev-parse", "--git-common-dir"], {
+        cwd: directory,
+        encoding: "utf8",
+        timeout: 5000,
+    });
+    if (result.status !== 0)
+        return null;
+    const common = result.stdout.trim();
+    if (!common)
+        return null;
+    return realpathOrSelf(path.resolve(directory, common));
+}
+/**
+ * Default routing boundary: worktrees of the attached repository, anything
+ * under the client's roots, and operator-listed roots.
+ */
+export function defaultIsRoutable(attachedRoot, env) {
+    let attachedCommon;
+    const allowlist = (env[ROUTABLE_ROOTS_ENV] ?? "")
+        .split(path.delimiter)
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+    return (workspaceRoot, roots) => {
+        if (roots.some((root) => isWithin(root, workspaceRoot)))
+            return true;
+        if (allowlist.some((root) => isWithin(root, workspaceRoot)))
+            return true;
+        if (attachedCommon === undefined) {
+            attachedCommon = gitCommonDirectory(attachedRoot);
+        }
+        if (!attachedCommon)
+            return false;
+        return gitCommonDirectory(workspaceRoot) === attachedCommon;
+    };
+}
+function readDeclaredBin(packageJsonPath) {
+    try {
+        const manifest = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+        if (manifest.name !== KIBI_MCP_PACKAGE)
+            return null;
+        const bin = typeof manifest.bin === "string"
+            ? manifest.bin
+            : isRecord(manifest.bin) &&
+                typeof manifest.bin[KIBI_MCP_PACKAGE] === "string"
+                ? manifest.bin[KIBI_MCP_PACKAGE]
+                : null;
+        if (!bin)
+            return null;
+        const entry = path.resolve(path.dirname(packageJsonPath), bin);
+        return fs.existsSync(entry) ? entry : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The kibi-mcp to run for a workspace: its own project-local install when it
+ * has one (so the child matches that branch's code), else this server's
+ * entry. Resolution goes through the package's public entry, since its
+ * exports map usually blocks `kibi-mcp/package.json`.
+ */
+export function defaultResolveChildCommand(workspaceRoot) {
+    const marker = path.join(workspaceRoot, "package.json");
+    if (fs.existsSync(marker)) {
+        try {
+            const entry = createRequire(marker).resolve(KIBI_MCP_PACKAGE);
+            let current = path.dirname(entry);
+            for (;;) {
+                const bin = readDeclaredBin(path.join(current, "package.json"));
+                if (bin)
+                    return { command: process.execPath, args: [bin] };
+                const parent = path.dirname(current);
+                if (parent === current)
+                    break;
+                current = parent;
+            }
+        }
+        catch {
+            // No project-local install; fall through to this server's own entry.
+        }
+    }
+    const self = process.argv[1];
+    if (self && fs.existsSync(self)) {
+        return { command: process.execPath, args: [path.resolve(self)] };
+    }
+    try {
+        const entry = fileURLToPath(new URL("../../bin/kibi-mcp", import.meta.url));
+        if (fs.existsSync(entry))
+            return { command: process.execPath, args: [entry] };
+    }
+    catch {
+        // Not resolvable from this module location.
+    }
+    return null;
+}
+function isPinned(env) {
+    return WORKSPACE_PIN_KEYS.some((key) => (env[key] ?? "").trim().length > 0);
+}
+function withTimeout(promise, timeoutMs, what) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`${what} timed out after ${timeoutMs}ms`)), timeoutMs);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
+export class WorkspaceRouter {
+    options;
+    env;
+    attachedRoot;
+    resolveWorkspace;
+    isRoutable;
+    resolveChildCommand;
+    log;
+    now;
+    children = new Map();
+    starting = new Map();
+    /** Background jobs started in a child, so polls reach the same process. */
+    jobOwners = new Map();
+    rootsCache = null;
+    rootsHandlerInstalled = false;
+    shutDown = false;
+    constructor(options) {
+        this.options = options;
+        this.env = options.env ?? process.env;
+        this.attachedRoot = realpathOrSelf(options.workspaceRoot);
+        this.resolveWorkspace = options.resolveWorkspace ?? kibiWorkspaceFor;
+        this.isRoutable =
+            options.isRoutable ?? defaultIsRoutable(this.attachedRoot, this.env);
+        this.resolveChildCommand =
+            options.resolveChildCommand ?? defaultResolveChildCommand;
+        this.log =
+            options.log ?? ((text) => process.stderr.write(`[kibi-mcp] ${text}\n`));
+        this.now = options.now ?? Date.now;
+    }
+    /** Routing is off for pinned servers, routed children, and by switch. */
+    get enabled() {
+        if (this.shutDown)
+            return false;
+        if ((this.env[ROUTING_SWITCH_ENV] ?? "").trim() === "0")
+            return false;
+        if ((this.env[ROUTED_CHILD_ENV] ?? "").trim() === "1")
+            return false;
+        return !isPinned(this.env);
+    }
+    /** Decide where `toolName(args)` is answered; strips `workspaceRoot`. */
+    async route(toolName, args) {
+        // Callers that never mention a workspace get their argument object back
+        // untouched, so handlers see exactly what the client sent.
+        if (!(WORKSPACE_ROOT_ARGUMENT in args)) {
+            if (!this.enabled)
+                return { kind: "local", args };
+            if (toolName === "kb_job_status")
+                return this.routeJobPoll(args);
+            const roots = await this.clientRoots();
+            const desired = workspaceFromRoots(roots, this.resolveWorkspace);
+            if (!desired)
+                return { kind: "local", args };
+            return this.routeTo(desired, roots[0] ?? desired, toolName, args);
+        }
+        const { [WORKSPACE_ROOT_ARGUMENT]: requestedRaw, ...rest } = args;
+        const requested = typeof requestedRaw === "string" && requestedRaw.trim().length > 0
+            ? requestedRaw.trim()
+            : undefined;
+        if (!this.enabled) {
+            if (requested === undefined)
+                return { kind: "local", args: rest };
+            if (toolName === "kb_check")
+                return { kind: "local", args };
+            const resolved = this.resolveWorkspace(requested);
+            if (resolved && realpathOrSelf(resolved) === this.attachedRoot) {
+                return { kind: "local", args: rest };
+            }
+            return {
+                kind: "local",
+                args: rest,
+                notice: this.notice(requested, resolved, "pinned"),
+            };
+        }
+        if (toolName === "kb_job_status")
+            return this.routeJobPoll(rest);
+        if (requested !== undefined) {
+            const resolved = this.resolveWorkspace(requested);
+            if (!resolved) {
+                // kb_check keeps its older meaning for a plain directory: impact
+                // diagnostics for that tree, answered by the attached knowledge base.
+                if (toolName === "kb_check")
+                    return { kind: "local", args };
+                return {
+                    kind: "local",
+                    args: rest,
+                    notice: this.notice(requested, null, "not_a_kibi_workspace"),
+                };
+            }
+            return this.routeTo(resolved, requested, toolName, rest);
+        }
+        // An empty workspaceRoot means "no preference": fall back to roots.
+        const roots = await this.clientRoots();
+        const desired = workspaceFromRoots(roots, this.resolveWorkspace);
+        if (!desired)
+            return { kind: "local", args: rest };
+        return this.routeTo(desired, roots[0] ?? desired, toolName, rest);
+    }
+    /** Polls for a job started in a child go to that child. */
+    async routeJobPoll(args) {
+        const owner = typeof args.jobId === "string"
+            ? this.jobOwners.get(args.jobId)
+            : undefined;
+        const child = owner ? this.children.get(owner) : undefined;
+        if (child && !child.closed) {
+            return this.callChild(child, "kb_job_status", args);
+        }
+        return { kind: "local", args };
+    }
+    async shutdown() {
+        this.shutDown = true;
+        await Promise.all([...this.children.values()].map((child) => this.retire(child)));
+    }
+    notice(requested, resolved, reason, error) {
+        const why = {
+            pinned: "this server is pinned to its workspace by KIBI_WORKSPACE (or an alias) and does not route calls",
+            not_a_kibi_workspace: "no Kibi workspace (.kb/manifest.json) owns that directory",
+            not_routable: "that workspace is neither a worktree of this server's repository nor under the client's MCP roots or KIBI_MCP_ROUTABLE_ROOTS",
+            unavailable: `kibi-mcp could not be started there${error ? `: ${error}` : ""}`,
+        }[reason];
+        return {
+            code: "workspace_mismatch",
+            severity: "warning",
+            message: `Answered from ${this.attachedRoot}, not from the requested workspace ${requested}: ${why}. Run the Kibi CLI from that directory if you need its knowledge base.`,
+            detail: {
+                requested,
+                resolved,
+                answeredFrom: this.attachedRoot,
+                reason,
+                ...(error ? { error } : {}),
+            },
+        };
+    }
+    async routeTo(resolved, requested, toolName, args) {
+        const target = realpathOrSelf(resolved);
+        if (target === this.attachedRoot)
+            return { kind: "local", args };
+        const roots = this.rootsCache ?? [];
+        if (!this.isRoutable(target, roots)) {
+            return {
+                kind: "local",
+                args,
+                notice: this.notice(requested, resolved, "not_routable"),
+            };
+        }
+        let child;
+        try {
+            child = await this.childFor(target);
+        }
+        catch (error) {
+            child = null;
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                kind: "local",
+                args,
+                notice: this.notice(requested, resolved, "unavailable", message),
+            };
+        }
+        if (!child) {
+            return {
+                kind: "local",
+                args,
+                notice: this.notice(requested, resolved, "unavailable", "no kibi-mcp entry resolves for that workspace"),
+            };
+        }
+        return this.callChild(child, toolName, args);
+    }
+    async callChild(child, toolName, args) {
+        child.inFlight += 1;
+        this.touch(child);
+        try {
+            const result = (await child.client.callTool({ name: toolName, arguments: args }, CallToolResultSchema));
+            this.rememberJob(child, result);
+            return { kind: "remote", workspaceRoot: child.root, result };
+        }
+        finally {
+            child.inFlight -= 1;
+            this.touch(child);
+        }
+    }
+    rememberJob(child, result) {
+        const structured = result
+            .structuredContent;
+        const data = isRecord(structured) ? structured.data : undefined;
+        const jobId = isRecord(data) ? data.jobId : undefined;
+        if (typeof jobId === "string")
+            this.jobOwners.set(jobId, child.root);
+    }
+    /** The client's current roots, cached while the client reports changes. */
+    async clientRoots() {
+        const capabilities = this.options.server.server.getClientCapabilities();
+        if (!capabilities?.roots)
+            return [];
+        const listChanged = capabilities.roots.listChanged === true;
+        if (listChanged && !this.rootsHandlerInstalled) {
+            this.rootsHandlerInstalled = true;
+            this.options.server.server.setNotificationHandler(RootsListChangedNotificationSchema, async () => {
+                this.rootsCache = null;
+            });
+        }
+        if (listChanged && this.rootsCache)
+            return this.rootsCache;
+        try {
+            const listed = await withTimeout(this.options.server.server.listRoots(), this.options.rootsTimeoutMs ?? DEFAULT_ROOTS_TIMEOUT_MS, "roots/list");
+            const roots = listed.roots.flatMap((root) => {
+                try {
+                    return [fileURLToPath(root.uri)];
+                }
+                catch {
+                    return [];
+                }
+            });
+            this.rootsCache = roots;
+            return roots;
+        }
+        catch (error) {
+            this.log(`roots/list failed; answering from ${this.attachedRoot}: ${error instanceof Error ? error.message : String(error)}`);
+            return this.rootsCache ?? [];
+        }
+    }
+    async childFor(root) {
+        const existing = this.children.get(root);
+        if (existing && !existing.closed)
+            return existing;
+        const pending = this.starting.get(root);
+        if (pending)
+            return pending;
+        const start = this.startChild(root).finally(() => {
+            this.starting.delete(root);
+        });
+        this.starting.set(root, start);
+        return start;
+    }
+    async startChild(root) {
+        const command = this.resolveChildCommand(root);
+        if (!command)
+            return null;
+        this.evictIfFull();
+        const env = {};
+        for (const [key, value] of Object.entries(this.env)) {
+            if (typeof value === "string")
+                env[key] = value;
+        }
+        env.KIBI_WORKSPACE = root;
+        env[ROUTED_CHILD_ENV] = "1";
+        const transport = new StdioClientTransport({
+            command: command.command,
+            args: [...command.args],
+            cwd: root,
+            env,
+            stderr: "pipe",
+        });
+        const client = new Client({
+            name: "kibi-mcp-workspace-router",
+            version: "1",
+        });
+        const child = {
+            root,
+            client,
+            transport,
+            lastUsed: this.now(),
+            inFlight: 0,
+            idleTimer: null,
+            closed: false,
+        };
+        transport.onclose = () => {
+            child.closed = true;
+            if (this.children.get(root) === child)
+                this.children.delete(root);
+            if (child.idleTimer)
+                clearTimeout(child.idleTimer);
+        };
+        await withTimeout(client.connect(transport), this.options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS, `kibi-mcp for ${root} initialize`);
+        const label = `[kibi-mcp ${path.basename(root)}]`;
+        transport.stderr?.on("data", (chunk) => {
+            for (const line of chunk.toString("utf8").split("\n")) {
+                if (line.trim().length > 0)
+                    process.stderr.write(`${label} ${line}\n`);
+            }
+        });
+        this.children.set(root, child);
+        this.touch(child);
+        this.log(`Serving ${root} through its own kibi-mcp`);
+        return child;
+    }
+    touch(child) {
+        child.lastUsed = this.now();
+        if (child.idleTimer)
+            clearTimeout(child.idleTimer);
+        const idleMs = this.options.idleRetireMs ?? DEFAULT_IDLE_RETIRE_MS;
+        child.idleTimer = setTimeout(() => {
+            if (child.inFlight === 0)
+                void this.retire(child);
+        }, idleMs);
+        child.idleTimer.unref?.();
+    }
+    evictIfFull() {
+        const max = this.options.maxChildren ?? DEFAULT_MAX_CHILDREN;
+        while (this.children.size >= max) {
+            let oldest = null;
+            for (const child of this.children.values()) {
+                if (child.inFlight > 0)
+                    continue;
+                if (!oldest || child.lastUsed < oldest.lastUsed)
+                    oldest = child;
+            }
+            if (!oldest)
+                return;
+            void this.retire(oldest);
+            this.children.delete(oldest.root);
+        }
+    }
+    async retire(child) {
+        if (child.closed)
+            return;
+        child.closed = true;
+        if (child.idleTimer)
+            clearTimeout(child.idleTimer);
+        if (this.children.get(child.root) === child)
+            this.children.delete(child.root);
+        for (const [jobId, owner] of this.jobOwners) {
+            if (owner === child.root)
+                this.jobOwners.delete(jobId);
+        }
+        try {
+            await child.client.close();
+        }
+        catch {
+            // The child is gone either way.
+        }
+    }
+}
+let activeRouter;
+/** Install the router the shared tool handler consults; undefined disables it. */
+export function setWorkspaceRouter(router) {
+    activeRouter = router;
+}
+export function getWorkspaceRouter() {
+    return activeRouter;
+}
+/** Add `workspaceRoot` to a tool input schema, keeping any existing entry's type. */
+export function withWorkspaceRootSchema(tools) {
+    return tools.map((tool) => {
+        const schema = tool.inputSchema;
+        const properties = isRecord(schema.properties) ? schema.properties : {};
+        return {
+            ...tool,
+            inputSchema: {
+                ...schema,
+                properties: {
+                    ...properties,
+                    [WORKSPACE_ROOT_ARGUMENT]: WORKSPACE_ROOT_SCHEMA,
+                },
+            },
+        };
+    });
+}

package/dist/server.js

@@ -24,6 +24,8 @@ import { setupDocsAndPrompts } from "./server/docs.js";
 import { KIBI_ICONS } from "./server/icons.js";
 import { registerAllTools } from "./server/tools.js";
 import { connectTransport, setupTransportHandlers, } from "./server/transport.js";
+import { WorkspaceRouter, setWorkspaceRouter, } from "./server/workspace-router.js";
+import { resolveWorkspaceRoot } from "./workspace.js";
 // Read version from package.json to prevent drift
 const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 const VERSION = packageJson.version ?? "0.1.0";
@@ -48,6 +50,8 @@ export async function startServer() {
         version: VERSION,
         icons: KIBI_ICONS,
     }, { instructions: SERVER_INSTRUCTIONS });
+    // Answer each call from the caller's workspace (worktrees, parallel agents).
+    setWorkspaceRouter(new WorkspaceRouter({ server, workspaceRoot: resolveWorkspaceRoot() }));
     // Setup documentation resources and prompts
     setupDocsAndPrompts(server);
     // Register all KB tools

package/dist/tools/plan-bootstrap.js

@@ -7,7 +7,7 @@ function isOperationContext(value) {
         "workspaceRoot" in value &&
         "signal" in value);
 }
-// implements REQ-mcp-kibi-bootstrap-bootstrap-v1, REQ-kibi-operation-interface-parity
+// implements REQ-KIBI-BOOTSTRAP-PLAN, REQ-kibi-operation-interface-parity
 // implements REQ-KIBI-BOOTSTRAP-PLAN
 export async function handleKbPlanBootstrap(input, context) {
     if (!isOperationContext(context))

package/dist/tools/symbols.js

@@ -74,7 +74,7 @@ async function handleKbSymbolsRefreshUnlocked(args, workspaceRoot) {
         id: typeof entry.id === "string" ? entry.id : "",
         title: typeof entry.title === "string" ? entry.title : "",
     }));
-    const enriched = await enrichSymbolCoordinates(entriesForEnrichment, workspaceRoot);
+    const enriched = await enrichSymbolCoordinates(entriesForEnrichment, workspaceRoot, { allowPythonDecoratorCoordinates: true });
     const finalized = await Promise.all(enriched.map((entry, index) => fillMissingCoordinates(original[index] ?? {}, entry, workspaceRoot)));
     parsed.symbols = finalized;
     let refreshed = 0;
@@ -148,7 +148,7 @@ async function refreshCoordinatesForSymbolIdUnlocked(symbolId, workspaceRoot) {
             ? original.title
             : "",
     };
-    const [enriched] = await enrichSymbolCoordinates([singleEntry], workspaceRoot);
+    const [enriched] = await enrichSymbolCoordinates([singleEntry], workspaceRoot, { allowPythonDecoratorCoordinates: true });
     const finalized = await fillMissingCoordinates(original, enriched ?? singleEntry, workspaceRoot);
     symbols[index] = finalized;
     parsed.symbols = symbols;

package/dist/tools-config.js

@@ -17,6 +17,7 @@
  */
 import { getSpec } from "kibi-runtime";
 import { DIAGNOSTIC_MODE_ENABLED, DIAGNOSTIC_TELEMETRY_SCHEMA, } from "./diagnostics.js";
+import { withWorkspaceRootSchema } from "./server/workspace-router.js";
 const MCP_TOOL_ORDER = [
     "kb_query",
     "kb_search",
@@ -33,6 +34,7 @@ const MCP_TOOL_ORDER = [
     "kb_validate_upsert",
     "kb_delete",
     "kb_check",
+    "kb_prepare_impact_review",
     "kb_model_requirement",
     "kb_suggest_predicates",
     "kb_plan_bootstrap",
@@ -114,6 +116,13 @@ const TOOL_ANNOTATIONS = {
     kb_check: {
         title: "Validate Kibi knowledge base",
     },
+    kb_prepare_impact_review: {
+        title: "Prepare an impact review",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     kb_model_requirement: {
         title: "Model a Kibi requirement",
     },
@@ -192,6 +201,6 @@ export function withDiagnosticTelemetrySchema(tools) {
  * Active tools list.
  * In diagnostic mode, all tools include the _diagnostic_telemetry parameter.
  */
-export const TOOLS = DIAGNOSTIC_MODE_ENABLED
+export const TOOLS = withWorkspaceRootSchema(DIAGNOSTIC_MODE_ENABLED
     ? withDiagnosticTelemetrySchema(BASE_TOOLS)
-    : [...BASE_TOOLS];
+    : [...BASE_TOOLS]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-mcp",
-  "version": "2.2.0",
+  "version": "2.4.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.0.2",
-    "kibi-core": "^0.14.0",
+    "kibi-runtime": "^2.2.0",
+    "kibi-core": "^0.14.1",
     "mcpcat": "^0.1.12",
     "zod": "^4.3.6"
   },