@cjhyy/code-shell-core 0.7.1 → 0.8.1

package/dist/tool-system/executor.js

@@ -3,6 +3,7 @@
  */
 import { setMaxListeners } from "node:events";
 import { resolve as resolvePath, isAbsolute as isAbsolutePath } from "node:path";
+import { isMcpToolNameAllowed, isRegisteredMcpToolAllowed } from "./mcp-tool-policy.js";
 import { classifyBashCommand } from "./permission.js";
 import { ToolNotFoundError } from "../exceptions.js";
 import { logger as rootLogger, getCurrentSid } from "../logging/logger.js";
@@ -10,8 +11,6 @@ import { recordToolCall, recordToolResult } from "../logging/session-recorder.js
 import { validateToolArgs } from "./validation.js";
 import { PLAN_MODE_ALLOWED_TOOLS } from "./plan-mode-allowlist.js";
 import { attachFinalWritePathSnapshot, enforcePathPolicyWithApproval, } from "./path-policy.js";
-import { parsePatch } from "./builtin/apply-patch/parser.js";
-import { BUILTIN_TOOL_GUARDS } from "./builtin/index.js";
 import { COMPLETE_GOAL_TOOL_NAME } from "./builtin/complete-goal.js";
 import { CANCEL_GOAL_TOOL_NAME } from "./builtin/cancel-goal.js";
 import { toolResultDisplayText } from "./tool-result-redaction.js";
@@ -119,6 +118,14 @@ export class ToolExecutor {
                 isError: true,
             };
         }
+        if (this.toolCtx?.allowedToolNames && !this.toolCtx.allowedToolNames.has(call.toolName)) {
+            return {
+                id: call.id,
+                toolName: call.toolName,
+                error: `Tool ${call.toolName} is not allowed by this run profile. Do NOT retry this tool call.`,
+                isError: true,
+            };
+        }
         // 0. Capability override: a builtin the project marked `off` is HIDDEN from
         // the model's tool list (engine.ts applyBuiltinOverrideVisibility), but the
         // model can still NAME it (hallucination, or a remembered earlier turn). The
@@ -142,7 +149,7 @@ export class ToolExecutor {
                 isError: true,
             };
         }
-        const visibilityGuard = BUILTIN_TOOL_GUARDS.get(call.toolName);
+        const visibilityGuard = this.registry.getAvailabilityGuard(call.toolName);
         if (visibilityGuard &&
             this.toolCtx?.toolVisibility &&
             !visibilityGuard(this.toolCtx.toolVisibility)) {
@@ -167,6 +174,19 @@ export class ToolExecutor {
                     isError: true,
                 };
             }
+            if (reg?.source === "mcp" &&
+                !isRegisteredMcpToolAllowed({
+                    source: "mcp",
+                    serverName: reg.serverName,
+                    mcpToolName: reg.mcpToolName,
+                }, this.toolCtx.mcpToolPolicies)) {
+                return {
+                    id: call.id,
+                    toolName: call.toolName,
+                    error: `MCP tool "${reg.mcpToolName ?? call.toolName}" is disabled by this project's tool policy. Do NOT retry this tool call.`,
+                    isError: true,
+                };
+            }
             // The generic MCP builtins (MCPTool / ReadMcpResource) take the target
             // server as an ARGUMENT and call MCPManager directly, so the source==="mcp"
             // check above can't see them — without this a session could invoke a tool
@@ -184,6 +204,17 @@ export class ToolExecutor {
                         isError: true,
                     };
                 }
+                if (call.toolName === "MCPTool") {
+                    const tool = String(call.args.tool ?? "");
+                    if (!isMcpToolNameAllowed(this.toolCtx.mcpToolPolicies, server, tool)) {
+                        return {
+                            id: call.id,
+                            toolName: call.toolName,
+                            error: `MCP tool "${tool}" is disabled by this project's tool policy. Do NOT retry this tool call.`,
+                            isError: true,
+                        };
+                    }
+                }
             }
             else if (call.toolName === "ListMcpResources") {
                 const server = String(call.args.server ?? "");
@@ -520,6 +551,20 @@ export class ToolExecutor {
         return op.default;
     }
     async enforceDeclaredPathPolicy(tool, args) {
+        if (tool?.pathResolver) {
+            let targets;
+            try {
+                targets = tool.pathResolver.resolve(args, this.toolCtx?.cwd ?? process.cwd());
+            }
+            catch (err) {
+                return `Error: ${err instanceof Error ? err.message : String(err)}`;
+            }
+            for (const target of targets) {
+                const blocked = await enforcePathPolicyWithApproval(target, tool.pathResolver.operation, this.toolCtx);
+                if (blocked)
+                    return blocked;
+            }
+        }
         const policies = tool?.pathPolicy;
         if (!policies?.length)
             return null;
@@ -537,55 +582,35 @@ export class ToolExecutor {
         return null;
     }
     resolvePathPolicyTargets(policy, args) {
-        if (policy.kind === "arg") {
-            const raw = args[policy.arg];
-            if (typeof raw === "string" && raw.length > 0) {
-                // Resolve a RELATIVE single-string path arg against ctx.cwd before
-                // classification, mirroring the array branch below and the apply_patch
-                // branch — otherwise classifyPath's process.cwd()-based resolution
-                // mis-places an in-workspace relative path (e.g. Read "src/x.ts") as
-                // "outside workspace" and over-prompts. Absolute paths pass through.
-                const cwd = this.toolCtx?.cwd ?? process.cwd();
-                return [isAbsolutePath(raw) ? raw : resolvePath(cwd, raw)];
-            }
-            // Array path args (e.g. GenerateImage `referenceImages`, GenerateVideo
-            // `images`): enforce EVERY element. Without this an array yielded zero
-            // targets, so out-of-workspace reads bypassed the path-policy "ask" gate
-            // that Read/Write enforce. http(s) URLs aren't file reads → skip them.
-            // Relative paths resolve against ctx.cwd (the workspace) before
-            // classification, like the apply_patch branch — otherwise classifyPath's
-            // process.cwd()-based resolution would mis-place an in-workspace relative
-            // path as "outside" and over-prompt. Non-string / empty elements skipped.
-            if (Array.isArray(raw)) {
-                const cwd = this.toolCtx?.cwd ?? process.cwd();
-                const paths = raw
-                    .filter((v) => typeof v === "string" && v.length > 0)
-                    .filter((v) => !/^https?:\/\//i.test(v))
-                    .map((v) => (isAbsolutePath(v) ? v : resolvePath(cwd, v)));
-                if (paths.length > 0)
-                    return paths;
-            }
-            if (policy.defaultToCwd && this.toolCtx?.cwd)
-                return [this.toolCtx.cwd];
-            return [];
-        }
-        const rawPatch = args[policy.arg];
-        if (typeof rawPatch !== "string" || rawPatch.length === 0)
-            return [];
-        try {
-            const parsed = parsePatch(rawPatch, "lenient");
+        const raw = args[policy.arg];
+        if (typeof raw === "string" && raw.length > 0) {
+            // Resolve a RELATIVE single-string path arg against ctx.cwd before
+            // classification, mirroring the array branch below and the apply_patch
+            // branch — otherwise classifyPath's process.cwd()-based resolution
+            // mis-places an in-workspace relative path (e.g. Read "src/x.ts") as
+            // "outside workspace" and over-prompts. Absolute paths pass through.
             const cwd = this.toolCtx?.cwd ?? process.cwd();
-            const targets = [];
-            for (const hunk of parsed.hunks) {
-                targets.push(resolvePath(cwd, hunk.path));
-                if (hunk.kind === "update" && hunk.movePath) {
-                    targets.push(resolvePath(cwd, hunk.movePath));
-                }
-            }
-            return targets;
+            return [isAbsolutePath(raw) ? raw : resolvePath(cwd, raw)];
         }
-        catch (err) {
-            return `Error: ${err.message}`;
+        // Array path args (e.g. GenerateImage `referenceImages`, GenerateVideo
+        // `images`): enforce EVERY element. Without this an array yielded zero
+        // targets, so out-of-workspace reads bypassed the path-policy "ask" gate
+        // that Read/Write enforce. http(s) URLs aren't file reads → skip them.
+        // Relative paths resolve against ctx.cwd (the workspace) before
+        // classification, like the apply_patch branch — otherwise classifyPath's
+        // process.cwd()-based resolution would mis-place an in-workspace relative
+        // path as "outside" and over-prompt. Non-string / empty elements skipped.
+        if (Array.isArray(raw)) {
+            const cwd = this.toolCtx?.cwd ?? process.cwd();
+            const paths = raw
+                .filter((v) => typeof v === "string" && v.length > 0)
+                .filter((v) => !/^https?:\/\//i.test(v))
+                .map((v) => (isAbsolutePath(v) ? v : resolvePath(cwd, v)));
+            if (paths.length > 0)
+                return paths;
         }
+        if (policy.defaultToCwd && this.toolCtx?.cwd)
+            return [this.toolCtx.cwd];
+        return [];
     }
 }

package/dist/tool-system/external-tool-exposure.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The Host Tool allowlist for external Agent Runtimes.
+ *
+ * This is a policy artifact, not plumbing. It exists as one reviewable file —
+ * rather than scattered through the Claude/Codex adapters — because the design
+ * (§9.1) requires each entry to have been risk-reviewed individually, and a
+ * reviewer needs to see the whole surface at once.
+ *
+ * Two rules shape everything here:
+ *
+ *  1. **Allowlist only.** No "everything in the registry", no prefix matching.
+ *     A tool absent from this file does not exist for an external runtime.
+ *     Widening it is an edit to this file, which is the point: it leaves a diff.
+ *  2. **Host-loopback tools are special** (§9.3). `Panel`, `Browser`,
+ *     `SwitchSessionWorkspace` and `InjectCredential` reach back out to a
+ *     specific Desktop renderer window to do their work. Passing `ToolExecutor`
+ *     does NOT make them callable — owner routing decides that, and it lives
+ *     outside the executor. Any such tool needs its owner story argued before it
+ *     can be listed.
+ *
+ * ## Why this is much wider than the original phase-one list
+ *
+ * The first cut exposed exactly one tool (`Panel`). That was not the product of
+ * a risk judgement so much as of an ordering: tools were held back until each
+ * had an argument written, and only one did. The result was a runtime that
+ * could list panels and nothing else — no skills, no memory, no file access —
+ * which is not a usable Agent Runtime, and made the feature's real state easy
+ * to overstate.
+ *
+ * The widening below was an explicit product-owner decision. The governing
+ * principle it rests on: **every tool here still executes through
+ * `ToolExecutor`**, so path policy, project trust, the user's permission rules
+ * and the approval UI all still apply. An external runtime holding `Bash` from
+ * this list is strictly more governed than the same model calling its own
+ * built-in shell, which answers only to the runtime's sandbox. Exposure moves
+ * capability from an unobservable authorization domain into the user's.
+ *
+ * That argument does not extend to everything, and four tools remain excluded
+ * for structural reasons rather than caution — see the block below them.
+ * `InjectCredential` is the highest-risk entry and depends on an in-tool
+ * approval that must stay mandatory; if that ever changes, it goes back out.
+ */
+import type { ExternalToolExposurePolicy } from "./session-tool-host.js";
+/** Why a tool is in (or out of) the first-phase allowlist. */
+export interface ExposureRationale {
+    tool: string;
+    /** `self-contained` completes in-process; `host-loopback` calls back to a window. */
+    kind: "self-contained" | "host-loopback";
+    status: "exposed" | "deferred" | "excluded";
+    reason: string;
+}
+/**
+ * The audit trail behind {@link FIRST_PHASE_EXPOSURE}. Kept as data so the
+ * "excluded" decisions are visible too — a bare allowlist tells a reviewer what
+ * was included but not what was considered and rejected, which is the more
+ * useful half when judging whether the surface is sound.
+ */
+export declare const FIRST_PHASE_EXPOSURE_RATIONALE: readonly ExposureRationale[];
+/** The phase-one policy. Pass to `createSessionToolHost({ exposure })`. */
+export declare const FIRST_PHASE_EXPOSURE: ExternalToolExposurePolicy;

package/dist/tool-system/external-tool-exposure.js

@@ -0,0 +1,304 @@
+/**
+ * The audit trail behind {@link FIRST_PHASE_EXPOSURE}. Kept as data so the
+ * "excluded" decisions are visible too — a bare allowlist tells a reviewer what
+ * was included but not what was considered and rejected, which is the more
+ * useful half when judging whether the surface is sound.
+ */
+export const FIRST_PHASE_EXPOSURE_RATIONALE = [
+    {
+        tool: "Panel",
+        kind: "host-loopback",
+        status: "exposed",
+        reason: "Only list/open/tools. These are read-or-focus, and they have a broadcast " +
+            "fallback, so they work without an owning window. invoke stays out for now " +
+            "for a DIFFERENT reason than originally recorded: the owner claim it was " +
+            "waiting on now exists and is wired (ExternalRuntimeService claims before " +
+            "the runtime starts), so the blocker is no longer technical. What is still " +
+            "missing is a per-Panel-App risk review — invoke runs third-party Panel App " +
+            "code with whatever arguments the model supplies, and argsPatterns cannot " +
+            "constrain a nested payload. Enabling it is a policy decision, not a wiring " +
+            "one, and it belongs to whoever reviews the first Panel App to be trusted.",
+    },
+    {
+        // NOTE the names: there is no tool called "Browser". The registry exposes
+        // three separate browser tools, and an allowlist entry for a name that does
+        // not exist is silently inert — it neither grants nor denies anything,
+        // which is the worst of both (a reviewer reads it as covered).
+        tool: "browser_navigate",
+        kind: "host-loopback",
+        status: "exposed",
+        reason: "The browser capability the runtime genuinely lacks — the differentiator, " +
+            "not a duplicate — and the owner argument it was waiting on is the same one " +
+            "Panel now has: ExternalRuntimeService registers the session and claims the " +
+            "owning window before the runtime starts. Stays under ToolExecutor plus the " +
+            "user's permission rules; without an owning window it fails closed on " +
+            "routing rather than broadcasting.",
+    },
+    {
+        tool: "browser_observe",
+        kind: "host-loopback",
+        status: "exposed",
+        reason: "Reads page content. Same owner story as browser_navigate, no mutation.",
+    },
+    {
+        tool: "browser_act",
+        kind: "host-loopback",
+        status: "exposed",
+        reason: "Click / type / interact — the mutating third of the browser surface, and " +
+            "the one that combines with InjectCredential to act as the logged-in user. " +
+            "Exposed on the product owner's call, under the same ToolExecutor rules as " +
+            "every other entry here.",
+    },
+    {
+        tool: "InjectCredential",
+        kind: "host-loopback",
+        status: "exposed",
+        reason: "Injects saved cookie credentials into the built-in browser to restore a " +
+            "login. This is the single highest-risk entry in this file and the one " +
+            "reviewers should look at first: it hands a live session cookie to a page, " +
+            "and a model that can also drive the Browser can then act as the logged-in " +
+            "user. §12.4 excluded credential-bearing tools outright; that blanket rule " +
+            "is relaxed here on the product owner's explicit call because credential " +
+            "restore is what makes browser automation usable at all. The mitigation is " +
+            "NOT the allowlist — it is the tool's own in-tool approval, which stays " +
+            "mandatory (see builtin/index.ts) and is never auto-approved for an " +
+            "external runtime. If that approval is ever made skippable, this entry must " +
+            "go back to excluded.",
+    },
+    // ── Still excluded, and for a different KIND of reason ───────────
+    // The four below are not held back out of caution — widening the allowlist
+    // does not make them work. Each is excluded by a structural property that
+    // would have to be designed away first, so listing them would produce a tool
+    // that is advertised and then fails or misbehaves.
+    {
+        tool: "Agent",
+        kind: "self-contained",
+        status: "excluded",
+        reason: "Can spawn another agent, so an external runtime could recurse into itself, " +
+            "nest approvals, and escape concurrency/budget limits (§12.5). Unlike Bash " +
+            "or Browser, this is not a permission question: the recursion has no owner " +
+            "and no budget to charge, so exposing it would need a nesting model first.",
+    },
+    {
+        tool: "DriveAgent",
+        kind: "self-contained",
+        status: "excluded",
+        reason: "Same recursion hazard as Agent (§12.5).",
+    },
+    {
+        tool: "EnterPlanMode",
+        kind: "self-contained",
+        status: "excluded",
+        reason: "Engine state-machine tool. Exposing it lets the runtime and the Native " +
+            "Engine drive each other's plan state (§12.3) — and an external runtime has " +
+            "no Engine plan state of its own to enter, so the call has no coherent " +
+            "meaning on this path.",
+    },
+    {
+        tool: "ExitPlanMode",
+        kind: "self-contained",
+        status: "excluded",
+        reason: "Engine state-machine tool; same reason as EnterPlanMode.",
+    },
+    {
+        tool: "Read",
+        kind: "self-contained",
+        status: "exposed",
+        reason: "Overlaps a tool the runtime already has, which was the original reason to " +
+            "exclude it. That reasoning was wrong about which risk matters: the runtime's " +
+            "OWN Read answers to the runtime's sandbox, while this one answers to " +
+            "ToolExecutor — path policy, project trust and the user's permission rules. " +
+            "Exposing it means the model has a reachable path that IS governed by " +
+            "CodeShell, which is the point of augmented mode. Naming overlap is a " +
+            "presentation problem (the MCP server prefixes its tools); sandbox " +
+            "divergence is a security one.",
+    },
+    {
+        tool: "Bash",
+        kind: "self-contained",
+        status: "exposed",
+        reason: "Same argument as Read, and it is the tool where it matters most: the " +
+            "runtime's own shell runs under the runtime's approval policy, which the " +
+            "user did not configure and cannot see. Routing a shell call through " +
+            "ToolExecutor puts it under the user's own permission rules and the " +
+            "approval UI. Note this does NOT remove the runtime's own shell — it adds a " +
+            "governed alternative.",
+    },
+    // ── Skills, memory and planning ──────────────────────────────────
+    // These are the reason someone runs a model inside CodeShell rather than in a
+    // bare terminal. A runtime that cannot reach them is a stranger in the app: it
+    // cannot load the user's skills, cannot recall anything, and forgets the
+    // session the moment it ends. Phase one excluded them by omission rather than
+    // by argument — no rationale entry existed at all, which is how a surface ends
+    // up shipping at 1 tool out of 48 without anyone deciding that.
+    {
+        tool: "Skill",
+        kind: "self-contained",
+        status: "exposed",
+        reason: "Loads a SKILL.md body and returns it as the tool result — it reads from " +
+            "the scanner, never the disk directly, and executes nothing itself. A skill " +
+            "body may TELL the model to run commands, but those become ordinary tool " +
+            "calls that face the same authorization as any other. Withholding Skill " +
+            "does not withhold that capability; it only withholds the user's own " +
+            "curated instructions.",
+    },
+    {
+        tool: "MemoryRead",
+        kind: "self-contained",
+        status: "exposed",
+        reason: "Reads the user's memory store. No side effects.",
+    },
+    {
+        tool: "MemoryList",
+        kind: "self-contained",
+        status: "exposed",
+        reason: "Enumerates memory entries. No side effects.",
+    },
+    {
+        tool: "MemorySave",
+        kind: "self-contained",
+        status: "exposed",
+        reason: "Writes to the memory store, so it is a mutation — but a scoped one, into " +
+            "a store the user can read and edit, and it carries the same permission " +
+            "rules as on the native path.",
+    },
+    {
+        tool: "MemoryDelete",
+        kind: "self-contained",
+        status: "exposed",
+        reason: "Mutation, same store and same rules as MemorySave.",
+    },
+    {
+        tool: "TodoWrite",
+        kind: "self-contained",
+        status: "exposed",
+        reason: "Session-scoped task list. Visible to the user, trivially reversible.",
+    },
+    {
+        tool: "Glob",
+        kind: "self-contained",
+        status: "exposed",
+        reason: "Path search under the same path policy as Read.",
+    },
+    {
+        tool: "Grep",
+        kind: "self-contained",
+        status: "exposed",
+        reason: "Content search under the same path policy as Read.",
+    },
+    {
+        tool: "Write",
+        kind: "self-contained",
+        status: "exposed",
+        reason: "File mutation governed by ToolExecutor. Same argument as Bash.",
+    },
+    {
+        tool: "Edit",
+        kind: "self-contained",
+        status: "exposed",
+        reason: "File mutation governed by ToolExecutor. Same argument as Bash.",
+    },
+    {
+        tool: "WebSearch",
+        kind: "self-contained",
+        status: "exposed",
+        reason: "Read-only network lookup; already available to the model by other means.",
+    },
+    {
+        tool: "WebFetch",
+        kind: "self-contained",
+        status: "exposed",
+        reason: "Read-only fetch, subject to the same URL handling as the native path.",
+    },
+];
+/**
+ * Action-level narrowing for tools that multiplex several operations behind one
+ * name. Anchored automatically — see `matchesWholeValue`.
+ *
+ * This is a second, independent layer from the tool's own
+ * `defaultPermissionRules`: those decide allow/ask for a call that IS permitted,
+ * while this decides whether the action is reachable from an external runtime at
+ * all. Both are narrowed to read-only actions in phase one, and `Panel.invoke`
+ * additionally fails closed on owner routing — three independent barriers, by
+ * design.
+ */
+const FIRST_PHASE_ARGS_PATTERNS = new Map([
+    // Panel.invoke remains the one action-level restriction. It runs third-party
+    // Panel App code with whatever arguments the model supplies, and argsPatterns
+    // cannot constrain a nested payload — so unlike every tool widened above, the
+    // authorization layer genuinely cannot see what is being authorized. Enabling
+    // it belongs to whoever reviews the first Panel App to be trusted.
+    ["Panel", { action: "list|open|tools" }],
+]);
+/**
+ * `ReadonlySet` / `ReadonlyMap` are compile-time only — the underlying `Set` and
+ * `Map` stay mutable at runtime, and this policy is a process-wide singleton read
+ * live on every `execute()`. Without this, one `argsPatterns.delete("Panel")`
+ * anywhere in the process would re-enable `Panel.invoke` for every already-running
+ * host: exactly the capability held back pending the §9.3.2 owner claim.
+ */
+function reject() {
+    throw new TypeError("The external tool exposure policy is frozen and cannot be widened.");
+}
+/**
+ * Hand out a plain object implementing the read half of `Set`, not a real `Set`.
+ *
+ * Shadowing `add`/`delete`/`clear` on a `Set` is not enough: the prototype method
+ * is still reachable (`Set.prototype.add.call(policySet, "Bash")`), and `delete
+ * s.add` un-shadows it. Returning a non-`Set` object removes the mutators
+ * entirely — there is no `Set` internal slot to target — and `Object.freeze`
+ * stops the read methods from being swapped out.
+ */
+function frozenSet(values) {
+    const inner = new Set(values);
+    const view = Object.freeze({
+        has: (value) => inner.has(value),
+        get size() {
+            return inner.size;
+        },
+        keys: () => inner.keys(),
+        values: () => inner.values(),
+        entries: () => inner.entries(),
+        // Pass the VIEW as the third argument, never `inner`. Set.prototype.forEach
+        // hands the callback the collection itself, so forwarding `inner` would leak
+        // a live mutable handle to the very object this wrapper exists to protect —
+        // `policy.forEach((_a, _b, s) => s.add("Bash"))` would widen it in one line,
+        // through the public frozen API, with no prototype tricks at all.
+        forEach: (fn, thisArg) => inner.forEach((a, b) => fn.call(thisArg, a, b, view)),
+        [Symbol.iterator]: () => inner[Symbol.iterator](),
+        add: reject,
+        delete: reject,
+        clear: reject,
+    });
+    return view;
+}
+/** Same reasoning as {@link frozenSet}, for the args-pattern map. */
+function frozenMap(entries) {
+    const inner = new Map(entries);
+    const view = Object.freeze({
+        get: (key) => inner.get(key),
+        has: (key) => inner.has(key),
+        get size() {
+            return inner.size;
+        },
+        keys: () => inner.keys(),
+        values: () => inner.values(),
+        entries: () => inner.entries(),
+        // See frozenSet.forEach — arg 3 must be the view, not `inner`.
+        forEach: (fn, thisArg) => inner.forEach((v, k) => fn.call(thisArg, v, k, view)),
+        [Symbol.iterator]: () => inner[Symbol.iterator](),
+        set: reject,
+        delete: reject,
+        clear: reject,
+    });
+    return view;
+}
+/** The phase-one policy. Pass to `createSessionToolHost({ exposure })`. */
+export const FIRST_PHASE_EXPOSURE = Object.freeze({
+    mode: "allowlist",
+    toolNames: frozenSet(FIRST_PHASE_EXPOSURE_RATIONALE.filter((entry) => entry.status === "exposed").map((entry) => entry.tool)),
+    argsPatterns: frozenMap([...FIRST_PHASE_ARGS_PATTERNS].map(([tool, patterns]) => [
+        tool,
+        Object.freeze({ ...patterns }),
+    ])),
+});

package/dist/tool-system/mcp-manager.d.ts

@@ -79,6 +79,16 @@ export declare function spillMcpImage(serverName: string, toolName: string, base
 export declare function wrapMcpOutput(serverName: string, toolName: string, body: string): string;
 export declare function stripInternalToolArgs(args: Record<string, unknown>): Record<string, unknown>;
 export declare function buildRegisteredTool(serverName: string, tool: McpTool): RegisteredTool;
+/**
+ * Per-server outcome of a connectAll() sweep (see the optional onServerEvent
+ * parameter). The engine forwards these onto the `notification` hook so hosts
+ * and plugins can surface MCP availability without polling.
+ */
+export interface McpServerLifecycleEvent {
+    type: "mcp_server_connected" | "mcp_server_failed";
+    server: string;
+    error?: string;
+}
 export declare class MCPManager {
     private readonly toolRegistry;
     private static instance;
@@ -104,7 +114,7 @@ export declare class MCPManager {
     /**
      * Connect to all configured MCP servers and register their tools.
      */
-    connectAll(servers: Record<string, MCPServerConfig>, owner?: unknown): Promise<void>;
+    connectAll(servers: Record<string, MCPServerConfig>, owner?: unknown, onServerEvent?: (event: McpServerLifecycleEvent) => void): Promise<void>;
     reconcile(servers: Record<string, MCPServerConfig>, owner?: unknown): Promise<void>;
     /**
      * Remove one owner from the shared desired-server pool and disconnect servers

package/dist/tool-system/mcp-manager.js

@@ -174,6 +174,9 @@ export function createMcpAuthenticatedFetch(serverName, config, access = getCred
             }
             token = (await access.resolveOAuthAccess({ id: credentialId, scope: "full" })).accessToken;
         }
+        // The SDK and Bun can contribute distinct undici-compatible Request types.
+        // Normalize once at the adapter boundary instead of leaking that ambient
+        // declaration mismatch through the authentication/replay logic.
         const source = new Request(input, init);
         let replayable = true;
         try {
@@ -184,12 +187,14 @@ export function createMcpAuthenticatedFetch(serverName, config, access = getCred
         }
         const send = async (accessToken) => {
             const request = replayable ? source.clone() : source;
-            const requestHeaders = new Headers(request.headers);
+            const requestHeaders = new Headers(Array.from(request.headers.entries()));
             for (const [name, value] of Object.entries(headers))
                 requestHeaders.set(name, value);
             if (accessToken)
                 requestHeaders.set("Authorization", `Bearer ${accessToken}`);
-            return baseFetch(new Request(request, { headers: requestHeaders }));
+            return baseFetch(new Request(request, {
+                headers: Array.from(requestHeaders.entries()),
+            }));
         };
         const first = await send(token);
         if (first.status !== 401 || !isOAuth || !credentialId || !replayable || source.signal.aborted) {
@@ -345,6 +350,7 @@ export function buildRegisteredTool(serverName, tool) {
         },
         source: "mcp",
         serverName,
+        mcpToolName: tool.name,
         permissionDefault: "ask",
         isConcurrencySafe: readOnly,
         isReadOnly: readOnly,
@@ -383,7 +389,7 @@ export class MCPManager {
     /**
      * Connect to all configured MCP servers and register their tools.
      */
-    async connectAll(servers, owner) {
+    async connectAll(servers, owner, onServerEvent) {
         const enabledNames = this.enabledServerNames(servers);
         // Register this owner's desired set up front (see reconcile's shared-pool
         // note) so a later reconcile from ANOTHER session can't disconnect servers
@@ -410,12 +416,21 @@ export class MCPManager {
         const results = await Promise.allSettled(entries.map(([name, config]) => this.connect(name, config)));
         for (let i = 0; i < results.length; i++) {
             const result = results[i];
+            const server = entries[i][0];
             if (result.status === "rejected") {
                 logger.warn("mcp.connect_failed", {
-                    server: entries[i][0],
+                    server,
                     error: result.reason.message,
                 });
             }
+            try {
+                onServerEvent?.(result.status === "rejected"
+                    ? { type: "mcp_server_failed", server, error: result.reason.message }
+                    : { type: "mcp_server_connected", server });
+            }
+            catch {
+                /* observers must not affect connection handling */
+            }
         }
     }
     async reconcile(servers, owner) {

package/dist/tool-system/mcp-tool-policy.d.ts

@@ -0,0 +1,9 @@
+import type { MCPServerConfig, RegisteredTool } from "../types.js";
+export interface McpToolPolicy {
+    /** Undefined means every tool is eligible before the denylist is applied. */
+    allowedTools?: ReadonlySet<string>;
+    disabledTools: ReadonlySet<string>;
+}
+export declare function buildMcpToolPolicies(servers: Record<string, MCPServerConfig>): ReadonlyMap<string, McpToolPolicy>;
+export declare function isMcpToolNameAllowed(policies: ReadonlyMap<string, McpToolPolicy> | undefined, serverName: string, toolName: string): boolean;
+export declare function isRegisteredMcpToolAllowed(tool: Pick<RegisteredTool, "source" | "serverName" | "mcpToolName">, policies: ReadonlyMap<string, McpToolPolicy> | undefined): boolean;