@cruxy/cli 0.20.0 → 0.22.0

package/dist/constants.js

@@ -61,6 +61,14 @@ export const MEMORY_FILE_NAME = "entries.json";
  * (`~/.cruxy/memory-trust.json`) — its own file, independent of hook trust, so
  * cloning a repo carries zero memory trust (C.29 supply-chain safety). */
 export const MEMORY_TRUST_FILE_NAME = "memory-trust.json";
+/**
+ * MCP server integration (C.27). Per-repo trust for configured MCP servers, in
+ * the GLOBAL dir only (`~/.cruxy/mcp-trust.json`) — its own file, independent of
+ * hook and memory trust, so cloning a repo carries zero MCP trust. Trusting a
+ * server runs its code UNSANDBOXED with your privileges, so this decision is
+ * fingerprinted and re-checked on every run (C.27 supply-chain safety).
+ */
+export const MCP_TRUST_FILE_NAME = "mcp-trust.json";
 /**
  * Usage telemetry + cost tracking (C.22). Per-run/per-session usage records live
  * in the GLOBAL dir only (`~/.cruxy/usage/runs.json`), `0600` — LOCAL accounting

package/dist/errors/constructors.d.ts

@@ -180,6 +180,52 @@ export declare function lspTimeout(language: string, phase: "startup" | "request
  * that answered with zero results (that is an ordinary, non-error outcome).
  */
 export declare function lspCrashed(language: string, detail?: string): CruxyError;
+/**
+ * A project configures MCP servers that this repo has not trusted, and cruxy is
+ * running non-interactively so it cannot ask. Fail closed BEFORE any server is
+ * spawned: trusting a server runs its code UNSANDBOXED with the user's full
+ * privileges (a stdio server's own side effects can't be contained by the shell
+ * sandbox), so an untrusted config must never connect silently. The wording says
+ * this plainly — it is a real escalation, not a "gated shell in a box".
+ */
+export declare function mcpUntrusted(root: string, servers: string[]): CruxyError;
+/**
+ * A trusted MCP server could not be reached — spawn failed, the `initialize`
+ * handshake errored/timed out, or `tools/list` failed. That server simply
+ * contributes no tools (the run continues); the coded reason is surfaced so a
+ * misconfigured server is visible, not a silent absence. External server text is
+ * gag-scrubbed (U.8) before it reaches the user-facing cause.
+ */
+export declare function mcpConnect(server: string, underlying?: unknown): CruxyError;
+/**
+ * `web.enabled` is on but no usable search provider is configured — the API-key
+ * environment variable is unset (or the provider is unknown). THE HONESTY RULE:
+ * this is a coded, actionable failure, never an empty result — "no provider"
+ * must not read as "the web had no results". `apiKeyEnv` names the variable to set.
+ */
+export declare function webUnavailable(provider: string, apiKeyEnv: string): CruxyError;
+/**
+ * A web search did not complete — the provider returned an HTTP error, the network
+ * failed, or the request timed out. Distinct from a search that ran and found
+ * nothing (that stays an ordinary `ok:true` empty result). External provider text
+ * is gag-scrubbed (U.8) before it reaches the user-facing cause.
+ */
+export declare function webSearchFailed(underlying?: unknown): CruxyError;
+/**
+ * A `web_fetch` failed to retrieve a page: network error, timeout, an oversize or
+ * non-text body, or too many redirects. Distinct from a page that was fetched but
+ * held no readable text (an ordinary `ok:true` empty result). External response
+ * text is gag-scrubbed (U.8) before it reaches the user-facing cause.
+ */
+export declare function webFetchFailed(url: string, underlying?: unknown): CruxyError;
+/**
+ * A `web_fetch` was REFUSED before any request went out (SSRF guard): a non-http(s)
+ * scheme, or a host that resolves into a private/loopback/link-local range
+ * (127.0.0.1, 169.254.169.254 cloud metadata, 10.x, internal DNS, …). A security
+ * stop kept distinct from an ordinary fetch failure — the request is never
+ * dispatched. `web.allowPrivateHosts` is the deliberate escape hatch.
+ */
+export declare function webBlockedHost(url: string, reason: string): CruxyError;
 export declare function internal(underlying?: unknown): CruxyError;
 /**
  * Map a known provider/transport error (from `@cruxy/sdk`) to a typed

package/dist/errors/constructors.js

@@ -733,6 +733,129 @@ export function lspCrashed(language, detail) {
         meta: { language },
     });
 }
+// ── MCP client (exit 16) — C.27 ───────────────────────────────────────────────
+/**
+ * A project configures MCP servers that this repo has not trusted, and cruxy is
+ * running non-interactively so it cannot ask. Fail closed BEFORE any server is
+ * spawned: trusting a server runs its code UNSANDBOXED with the user's full
+ * privileges (a stdio server's own side effects can't be contained by the shell
+ * sandbox), so an untrusted config must never connect silently. The wording says
+ * this plainly — it is a real escalation, not a "gated shell in a box".
+ */
+export function mcpUntrusted(root, servers) {
+    const list = servers.join(", ");
+    return new CruxyError({
+        code: ErrorCode.McpUntrusted,
+        title: "this project's MCP servers have not been trusted",
+        cause: `${servers.length} configured server${servers.length === 1 ? "" : "s"} (${list}) ` +
+            "would run UNSANDBOXED with your full privileges — cruxy will not connect to them " +
+            "non-interactively without an explicit, recorded trust decision",
+        nextSteps: [
+            "review the servers with `cruxy mcp list`",
+            "then trust them with `cruxy mcp trust .` (re-trust is required if the config changes)",
+            "or set `mcp.enabled = false` to disable MCP for this project",
+        ],
+        meta: { root, servers },
+    });
+}
+/**
+ * A trusted MCP server could not be reached — spawn failed, the `initialize`
+ * handshake errored/timed out, or `tools/list` failed. That server simply
+ * contributes no tools (the run continues); the coded reason is surfaced so a
+ * misconfigured server is visible, not a silent absence. External server text is
+ * gag-scrubbed (U.8) before it reaches the user-facing cause.
+ */
+export function mcpConnect(server, underlying) {
+    return new CruxyError({
+        code: ErrorCode.McpConnect,
+        title: `could not connect to MCP server "${server}"`,
+        cause: scrubbedMessageOf(underlying) ??
+            "the server failed to start, handshake, or list its tools",
+        nextSteps: [
+            "re-run with --verbose to see the server's error",
+            `verify the command in \`mcp.servers.${server}\` runs standalone`,
+        ],
+        meta: { server },
+        underlying,
+    });
+}
+// ── web search + fetch (exit 17) — C.20 ───────────────────────────────────────
+/**
+ * `web.enabled` is on but no usable search provider is configured — the API-key
+ * environment variable is unset (or the provider is unknown). THE HONESTY RULE:
+ * this is a coded, actionable failure, never an empty result — "no provider"
+ * must not read as "the web had no results". `apiKeyEnv` names the variable to set.
+ */
+export function webUnavailable(provider, apiKeyEnv) {
+    return new CruxyError({
+        code: ErrorCode.WebUnavailable,
+        title: `web search is enabled but the "${provider}" provider has no API key`,
+        cause: `the \`${apiKeyEnv}\` environment variable is not set`,
+        nextSteps: [
+            `export ${apiKeyEnv}=<your ${provider} api key> and re-run`,
+            "or set `web.enabled = false` to disable web tools for this project",
+        ],
+        meta: { provider, apiKeyEnv },
+    });
+}
+/**
+ * A web search did not complete — the provider returned an HTTP error, the network
+ * failed, or the request timed out. Distinct from a search that ran and found
+ * nothing (that stays an ordinary `ok:true` empty result). External provider text
+ * is gag-scrubbed (U.8) before it reaches the user-facing cause.
+ */
+export function webSearchFailed(underlying) {
+    return new CruxyError({
+        code: ErrorCode.WebSearch,
+        title: "web search failed",
+        cause: scrubbedMessageOf(underlying) ??
+            "the search provider errored, was unreachable, or timed out",
+        nextSteps: [
+            "re-run with --verbose to see the provider's error",
+            "check the provider status and your network, then retry",
+        ],
+        underlying,
+    });
+}
+/**
+ * A `web_fetch` failed to retrieve a page: network error, timeout, an oversize or
+ * non-text body, or too many redirects. Distinct from a page that was fetched but
+ * held no readable text (an ordinary `ok:true` empty result). External response
+ * text is gag-scrubbed (U.8) before it reaches the user-facing cause.
+ */
+export function webFetchFailed(url, underlying) {
+    return new CruxyError({
+        code: ErrorCode.WebFetch,
+        title: `could not fetch ${url}`,
+        cause: scrubbedMessageOf(underlying) ??
+            "the request errored, timed out, or returned a non-text/oversize body",
+        nextSteps: [
+            "verify the URL is reachable and serves text (html/plain/json)",
+            "re-run with --verbose to see the underlying error",
+        ],
+        meta: { url },
+        underlying,
+    });
+}
+/**
+ * A `web_fetch` was REFUSED before any request went out (SSRF guard): a non-http(s)
+ * scheme, or a host that resolves into a private/loopback/link-local range
+ * (127.0.0.1, 169.254.169.254 cloud metadata, 10.x, internal DNS, …). A security
+ * stop kept distinct from an ordinary fetch failure — the request is never
+ * dispatched. `web.allowPrivateHosts` is the deliberate escape hatch.
+ */
+export function webBlockedHost(url, reason) {
+    return new CruxyError({
+        code: ErrorCode.WebBlockedHost,
+        title: `refused to fetch ${url}`,
+        cause: reason,
+        nextSteps: [
+            "fetch a public http(s) URL instead",
+            "if you intentionally target an internal host, set `web.allowPrivateHosts = true`",
+        ],
+        meta: { url },
+    });
+}
 // ── internal (exit 1) ─────────────────────────────────────────────────────────
 export function internal(underlying) {
     return new CruxyError({

package/dist/errors/types.d.ts

@@ -93,6 +93,32 @@ export declare const ErrorCode: {
     /** A language server crashed (and, where applicable, a single restart also
      * failed). Distinct from "server returned no results". */
     readonly LspCrashed: "CRUXY_E_LSP_CRASHED";
+    /** A project configures MCP servers that have not been trusted for this repo.
+     * Trusting a server runs its code UNSANDBOXED with your privileges, so an
+     * untrusted config is never connected silently — and in non-interactive mode
+     * it fails closed BEFORE any server is spawned (supply-chain safety). */
+    readonly McpUntrusted: "CRUXY_E_MCP_UNTRUSTED";
+    /** A trusted MCP server failed to spawn, complete the `initialize` handshake,
+     * or list its tools. Surfaced (that server contributes no tools) rather than
+     * silently swallowed; never fatal to the run. */
+    readonly McpConnect: "CRUXY_E_MCP_CONNECT";
+    /** `web.enabled` is on but no usable search provider is configured — the API
+     * key env var is unset or the provider is unknown. Actionable, NEVER a silent
+     * empty result: "no provider" must not read as "no search results". */
+    readonly WebUnavailable: "CRUXY_E_WEB_UNAVAILABLE";
+    /** A web search failed (provider HTTP error, network failure, or timeout). The
+     * search did NOT run to completion — distinct from a search that ran and found
+     * nothing (that is an ordinary `ok:true` empty result). */
+    readonly WebSearch: "CRUXY_E_WEB_SEARCH";
+    /** A `web_fetch` failed: network error, timeout, oversize/non-text body, or too
+     * many redirects. Distinct from a page fetched successfully that had no readable
+     * text (an ordinary `ok:true` empty result). */
+    readonly WebFetch: "CRUXY_E_WEB_FETCH";
+    /** A `web_fetch` was REFUSED before any request was dispatched: a non-http(s)
+     * scheme, or a host that resolves into a private/loopback/link-local range
+     * (SSRF guard — e.g. 127.0.0.1, 169.254.169.254, 10.x, internal DNS). A
+     * security stop, kept distinct from an ordinary fetch failure for grep-ability. */
+    readonly WebBlockedHost: "CRUXY_E_WEB_BLOCKED_HOST";
 };
 export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
 /** The process exit code for an error code (defaults to 1 for safety). */

package/dist/errors/types.js

@@ -110,6 +110,34 @@ export const ErrorCode = {
     /** A language server crashed (and, where applicable, a single restart also
      * failed). Distinct from "server returned no results". */
     LspCrashed: "CRUXY_E_LSP_CRASHED",
+    // MCP client (exit 16) — C.27
+    /** A project configures MCP servers that have not been trusted for this repo.
+     * Trusting a server runs its code UNSANDBOXED with your privileges, so an
+     * untrusted config is never connected silently — and in non-interactive mode
+     * it fails closed BEFORE any server is spawned (supply-chain safety). */
+    McpUntrusted: "CRUXY_E_MCP_UNTRUSTED",
+    /** A trusted MCP server failed to spawn, complete the `initialize` handshake,
+     * or list its tools. Surfaced (that server contributes no tools) rather than
+     * silently swallowed; never fatal to the run. */
+    McpConnect: "CRUXY_E_MCP_CONNECT",
+    // web search + fetch (exit 17) — C.20
+    /** `web.enabled` is on but no usable search provider is configured — the API
+     * key env var is unset or the provider is unknown. Actionable, NEVER a silent
+     * empty result: "no provider" must not read as "no search results". */
+    WebUnavailable: "CRUXY_E_WEB_UNAVAILABLE",
+    /** A web search failed (provider HTTP error, network failure, or timeout). The
+     * search did NOT run to completion — distinct from a search that ran and found
+     * nothing (that is an ordinary `ok:true` empty result). */
+    WebSearch: "CRUXY_E_WEB_SEARCH",
+    /** A `web_fetch` failed: network error, timeout, oversize/non-text body, or too
+     * many redirects. Distinct from a page fetched successfully that had no readable
+     * text (an ordinary `ok:true` empty result). */
+    WebFetch: "CRUXY_E_WEB_FETCH",
+    /** A `web_fetch` was REFUSED before any request was dispatched: a non-http(s)
+     * scheme, or a host that resolves into a private/loopback/link-local range
+     * (SSRF guard — e.g. 127.0.0.1, 169.254.169.254, 10.x, internal DNS). A
+     * security stop, kept distinct from an ordinary fetch failure for grep-ability. */
+    WebBlockedHost: "CRUXY_E_WEB_BLOCKED_HOST",
 };
 /**
  * Category exit codes. Distinct per category so a caller (CI, a script) can
@@ -187,6 +215,19 @@ const EXIT_CODES = {
     [ErrorCode.LspServerNotFound]: 15,
     [ErrorCode.LspTimeout]: 15,
     [ErrorCode.LspCrashed]: 15,
+    // MCP client (C.27). An untrusted MCP config is an execution-safety stop that
+    // fails closed before any spawn; a connect failure surfaces per-server and is
+    // never fatal on its own. Grouped for a greppable exit code.
+    [ErrorCode.McpUntrusted]: 16,
+    [ErrorCode.McpConnect]: 16,
+    // Web search + fetch (C.20). A missing provider, a search/fetch failure, and an
+    // SSRF-blocked host all surface inside a tool result (the agent reads and
+    // adapts) and only exit the process if thrown directly. Grouped for a greppable
+    // exit code.
+    [ErrorCode.WebUnavailable]: 17,
+    [ErrorCode.WebSearch]: 17,
+    [ErrorCode.WebFetch]: 17,
+    [ErrorCode.WebBlockedHost]: 17,
 };
 /** The process exit code for an error code (defaults to 1 for safety). */
 export function exitCodeFor(code) {

package/dist/lsp/transport.d.ts

@@ -1,4 +1,10 @@
+import { killTree, killTrackedTrees, trackedTreeCount } from "../utils/child-tree.js";
 import type { LspTransport, ServerSpec } from "./types.js";
+export { killTree };
+/** @deprecated Use the shared backstop; kept for LSP tests. */
+export declare const killTrackedServers: typeof killTrackedTrees;
+/** @deprecated Use the shared backstop; kept for LSP tests. */
+export declare const trackedServerCount: typeof trackedTreeCount;
 export declare class StdioTransport implements LspTransport {
     private readonly child;
     private nextId;
@@ -31,18 +37,3 @@ export declare class TransportTimeoutError extends Error {
     readonly timeoutMs: number;
     constructor(method: string, timeoutMs: number);
 }
-/**
- * Kill the process's entire group (POSIX negative-PID `SIGKILL`), same helper
- * shape as run_command's `killTree`. Swallows errors — the process may be gone.
- */
-export declare function killTree(pid: number | undefined): void;
-/**
- * Force-kill the process group of every tracked-but-not-yet-shut-down server,
- * then forget them. This is exactly what the `exit`/`SIGINT`/`SIGTERM`/`SIGHUP`
- * handlers run — the last line against orphaned language servers on a hard exit.
- * Exported so it is directly testable (like `resetIndexServices`) without having
- * to raise real process signals. Idempotent: a second call is a no-op.
- */
-export declare function killTrackedServers(): void;
-/** Number of servers currently tracked by the exit backstop (for tests). */
-export declare function trackedServerCount(): number;

package/dist/lsp/transport.js

@@ -1,4 +1,14 @@
 import { spawn } from "node:child_process";
+import { killTree, killTrackedTrees, registerForCleanup, trackedTreeCount, } from "../utils/child-tree.js";
+// Re-exported under their historical LSP names so callers and tests keep
+// importing them from here; the machinery now lives in the shared child-tree
+// backstop (also used by the C.27 MCP transport) so exit-time reaping is
+// unified across every managed process tree.
+export { killTree };
+/** @deprecated Use the shared backstop; kept for LSP tests. */
+export const killTrackedServers = killTrackedTrees;
+/** @deprecated Use the shared backstop; kept for LSP tests. */
+export const trackedServerCount = trackedTreeCount;
 /**
  * JSON-RPC 2.0 over a language server's stdio (C.12). Owns the child process:
  * spawns it in its OWN process group (`detached`) so the whole tree is killable,
@@ -196,69 +206,3 @@ export class TransportTimeoutError extends Error {
         this.name = "TransportTimeoutError";
     }
 }
-/**
- * Kill the process's entire group (POSIX negative-PID `SIGKILL`), same helper
- * shape as run_command's `killTree`. Swallows errors — the process may be gone.
- */
-export function killTree(pid) {
-    if (pid === undefined)
-        return;
-    try {
-        process.kill(-pid, "SIGKILL");
-    }
-    catch {
-        try {
-            // Fall back to a direct kill if there was no group (or on win32).
-            process.kill(pid, "SIGKILL");
-        }
-        catch {
-            /* already exited */
-        }
-    }
-}
-// ── process-exit kill-tree backstop ───────────────────────────────────────────
-//
-// Language servers are long-lived child processes. A per-session shutdown covers
-// the normal path, but a hard exit (Ctrl-C, an uncaught throw) would otherwise
-// orphan them — so every live server's process group is tracked here and killed
-// on process teardown. Handlers are registered ONCE, lazily, on the first spawn,
-// so unit tests using the fake transport never install them.
-const livePids = new Set();
-let handlersInstalled = false;
-/**
- * Force-kill the process group of every tracked-but-not-yet-shut-down server,
- * then forget them. This is exactly what the `exit`/`SIGINT`/`SIGTERM`/`SIGHUP`
- * handlers run — the last line against orphaned language servers on a hard exit.
- * Exported so it is directly testable (like `resetIndexServices`) without having
- * to raise real process signals. Idempotent: a second call is a no-op.
- */
-export function killTrackedServers() {
-    for (const pid of livePids)
-        killTree(pid);
-    livePids.clear();
-}
-/** Number of servers currently tracked by the exit backstop (for tests). */
-export function trackedServerCount() {
-    return livePids.size;
-}
-function installExitHandlers() {
-    if (handlersInstalled)
-        return;
-    handlersInstalled = true;
-    process.once("exit", killTrackedServers);
-    for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
-        process.once(sig, () => {
-            killTrackedServers();
-            // Restore default behavior and re-raise so the exit code is correct.
-            process.exit(130);
-        });
-    }
-}
-/** Track a live child for the exit backstop; returns a deregister callback. */
-function registerForCleanup(pid) {
-    if (pid === undefined)
-        return () => { };
-    installExitHandlers();
-    livePids.add(pid);
-    return () => livePids.delete(pid);
-}

package/dist/mcp/adapter.d.ts

@@ -0,0 +1,44 @@
+import type { Tool } from "../tools/types.js";
+import { type McpBounds } from "./bounds.js";
+import type { McpCallResult, RawMcpTool } from "./types.js";
+/**
+ * THE SINGLE SEAM (C.27). `mcpToolsFrom` is the ONE and ONLY place an MCP server
+ * becomes an agent {@link Tool}. Nothing else in the codebase constructs an
+ * MCP-backed tool, so every security property is enforced here, by construction:
+ *
+ * - GATE. Every produced tool's `execute` calls `ctx.requestApproval({kind:"mcp",
+ *   …})` BEFORE it ever calls the server. A rejection returns the feedback as the
+ *   tool result and `tools/call` never fires. The action is classified
+ *   `destructive` and the classifier never reads the server's `readOnlyHint`
+ *   (which this adapter deliberately does not even forward) — a server cannot
+ *   self-declare its tool safe. A session grant is keyed on the exact server+tool
+ *   pair, so approving one tool never covers another.
+ * - DEMARCATE + GAG. Both the advertised description and every result are wrapped
+ *   as untrusted external data with upstream model names scrubbed
+ *   ({@link demarcateDescription} / {@link demarcateResult}) — the model never
+ *   sees a raw, un-boxed description or result.
+ * - BOUNDS. The server's tool list is capped in count and per-tool size
+ *   ({@link boundToolList}); overflow is truncated with a visible note, never a
+ *   silent drop or an unbounded context blow-up.
+ * - NON-PERSISTENCE. `execute` returns a plain {@link ToolResult}; it writes to
+ *   no store. Results live only in the in-memory conversation (asserted by test).
+ *
+ * Trust is enforced UPSTREAM (the service never calls this until the server is
+ * trusted), so reaching this function already means "the user accepted running
+ * this server's code unsandboxed".
+ */
+export interface McpToolSource {
+    /** The configured server id (the tool-name prefix and gate key). */
+    server: string;
+    /** Tools exactly as the server advertised them (untrusted). */
+    tools: readonly RawMcpTool[];
+    /** Invoke a tool on the server by its ORIGINAL name. Adapter-internal only. */
+    call(toolName: string, args: unknown): Promise<McpCallResult>;
+    /** Size/count caps for the advertised list. */
+    bounds: McpBounds;
+    /** Where the visible "N tools dropped" note is surfaced. */
+    logger?: {
+        warn(message: string): void;
+    };
+}
+export declare function mcpToolsFrom(source: McpToolSource): Tool[];

package/dist/mcp/adapter.js

@@ -0,0 +1,70 @@
+import { z } from "zod";
+import { boundToolList } from "./bounds.js";
+import { demarcateDescription, demarcateResult } from "./demarcate.js";
+/** Args validation is delegated to the server; accept any object here. */
+const PASSTHROUGH = z.object({}).passthrough();
+export function mcpToolsFrom(source) {
+    const { server, tools, call, bounds, logger } = source;
+    const bounded = boundToolList(tools, bounds);
+    if (bounded.droppedCount > 0) {
+        // Visible, coded note — a hostile server flooding the tool list is bounded
+        // exactly like find_references' output, never silently truncated.
+        logger?.warn(`[CRUXY_E_MCP_CONNECT] server "${server}" advertised ${tools.length} tools; ` +
+            `kept ${bounded.tools.length} (mcp.maxToolsPerServer), dropped ${bounded.droppedCount}`);
+    }
+    return bounded.tools.map((t) => {
+        // The original (unsanitized) name is what the server expects on tools/call;
+        // the wire name is sanitized so it is a valid, collision-resistant tool id.
+        const originalName = t.name;
+        const wireName = `mcp__${sanitizeId(server)}__${sanitizeId(originalName)}`;
+        const description = demarcateDescription(server, originalName, t.description) +
+            (t.notes.length > 0
+                ? `\n[cruxy applied limits: ${t.notes.join("; ")}]`
+                : "");
+        return {
+            name: wireName,
+            description,
+            parameters: PASSTHROUGH,
+            // Advertise the server's own (bounds-capped) schema verbatim; the registry
+            // uses this instead of deriving one from `parameters` (C.27 seam on Tool).
+            rawInputSchema: t.inputSchema,
+            async execute(input, ctx) {
+                // GATE — always, before any call. readOnlyHint is intentionally NOT
+                // passed: the tier is decided by the classifier (destructive), never by
+                // the server. A rejection means the call is never made.
+                const decision = await ctx.requestApproval({
+                    kind: "mcp",
+                    server,
+                    tool: originalName,
+                });
+                if (!decision.allow) {
+                    return {
+                        ok: false,
+                        error: decision.feedback ??
+                            `the call to MCP tool "${originalName}" on server "${server}" was rejected`,
+                    };
+                }
+                let result;
+                try {
+                    result = await call(originalName, input);
+                }
+                catch (err) {
+                    // A transport/protocol failure — surface it, scrubbed + demarcated.
+                    return {
+                        ok: false,
+                        error: demarcateResult(server, originalName, err.message ?? "MCP tool call failed"),
+                    };
+                }
+                const body = demarcateResult(server, originalName, result.text);
+                return result.isError
+                    ? { ok: false, error: body }
+                    : { ok: true, output: body };
+            },
+        };
+    });
+}
+/** Reduce an arbitrary MCP id to a safe, stable wire token. */
+function sanitizeId(id) {
+    const cleaned = id.replace(/[^A-Za-z0-9_-]/g, "_");
+    return cleaned === "" ? "unnamed" : cleaned;
+}

package/dist/mcp/bounds.d.ts

@@ -0,0 +1,35 @@
+import type { RawMcpTool } from "./types.js";
+/**
+ * Tool-list bounds (C.27). A malicious or buggy MCP server can advertise
+ * thousands of tools with enormous descriptions and schemas — a context-budget
+ * DoS. So the list a server returns is bounded exactly like `find_references`'
+ * output: capped in count and per-tool size, and every truncation is surfaced as
+ * a VISIBLE note (never a silent drop, never an unbounded blow-up). The caps are
+ * config-driven (`mcp.maxToolsPerServer` / `maxDescriptionChars` / `maxSchemaBytes`).
+ */
+export interface McpBounds {
+    maxTools: number;
+    maxDescriptionChars: number;
+    maxSchemaBytes: number;
+}
+/** A single tool after bounding, carrying any truncation notes for the model. */
+export interface BoundedTool {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    /** Human notes about what was truncated on THIS tool (surfaced as data). */
+    notes: string[];
+}
+export interface BoundedToolList {
+    tools: BoundedTool[];
+    /** How many tools were dropped because the server exceeded the count cap. */
+    droppedCount: number;
+}
+/**
+ * Apply the bounds to a raw `tools/list`. Over the count cap → keep the first N
+ * (by advertised order) and report `droppedCount`. Per tool: an over-long
+ * description is truncated with a marker; an over-size input schema is replaced
+ * with a permissive `object` schema and a note (we never forward an unbounded
+ * schema, but we also never claim the args are constrained when we dropped it).
+ */
+export declare function boundToolList(tools: readonly RawMcpTool[], bounds: McpBounds): BoundedToolList;

package/dist/mcp/bounds.js

@@ -0,0 +1,36 @@
+const PERMISSIVE_SCHEMA = {
+    type: "object",
+    additionalProperties: true,
+};
+/**
+ * Apply the bounds to a raw `tools/list`. Over the count cap → keep the first N
+ * (by advertised order) and report `droppedCount`. Per tool: an over-long
+ * description is truncated with a marker; an over-size input schema is replaced
+ * with a permissive `object` schema and a note (we never forward an unbounded
+ * schema, but we also never claim the args are constrained when we dropped it).
+ */
+export function boundToolList(tools, bounds) {
+    const kept = tools.slice(0, bounds.maxTools);
+    const droppedCount = tools.length - kept.length;
+    const bounded = kept.map((t) => {
+        const notes = [];
+        const rawDesc = t.description ?? "";
+        let description = rawDesc;
+        if (description.length > bounds.maxDescriptionChars) {
+            description =
+                description.slice(0, bounds.maxDescriptionChars) +
+                    " …[description truncated by cruxy]";
+            notes.push(`description truncated to ${bounds.maxDescriptionChars} chars`);
+        }
+        let inputSchema = t.inputSchema ?? {
+            ...PERMISSIVE_SCHEMA,
+        };
+        const schemaBytes = Buffer.byteLength(JSON.stringify(inputSchema), "utf8");
+        if (schemaBytes > bounds.maxSchemaBytes) {
+            inputSchema = { ...PERMISSIVE_SCHEMA };
+            notes.push(`input schema (${schemaBytes} bytes) exceeded the ${bounds.maxSchemaBytes}-byte cap and was replaced with a permissive one`);
+        }
+        return { name: t.name, description, inputSchema, notes };
+    });
+    return { tools: bounded, droppedCount };
+}

package/dist/mcp/client.d.ts

@@ -0,0 +1,19 @@
+import type { McpCallResult, McpTransport, RawMcpTool } from "./types.js";
+export interface McpClientTimeouts {
+    /** `initialize` + `tools/list` budget (connect-time). */
+    startupTimeout: number;
+    /** Per `tools/call` budget. */
+    requestTimeout: number;
+}
+export declare class McpClient {
+    private readonly transport;
+    private readonly timeouts;
+    constructor(transport: McpTransport, timeouts: McpClientTimeouts);
+    /** Perform the MCP handshake: `initialize`, then the `initialized` notice. */
+    initialize(): Promise<void>;
+    /** List the server's tools. Malformed entries are dropped, not thrown on. */
+    listTools(): Promise<RawMcpTool[]>;
+    /** Call one tool. Normalizes content to flat text + the server's error flag. */
+    callTool(name: string, args: unknown): Promise<McpCallResult>;
+    dispose(force?: boolean): Promise<void>;
+}