@stigmer/runner 3.9.0 → 3.11.0

package/src/activities/execute-cursor/__tests__/error-classifier-extraction.test.ts

@@ -0,0 +1,208 @@
+/**
+ * Tests for the shape-aware run.wait() error extraction (oss#299).
+ *
+ * A bare String() on a structured error value yields "[object Object]",
+ * which end users saw verbatim AND which shadowed every lower-priority
+ * classifier source (stream, rejection, conversation introspection) because
+ * classification stops at the first non-empty source. These tests pin:
+ *
+ * - the extractRunErrorSources shape matrix (strings, Errors, field objects,
+ *   hopeless values)
+ * - first-USABLE-candidate chain order (a hopeless object no longer hides a
+ *   usable string one field later; an empty string no longer short-circuits)
+ * - end-to-end: structured errors classify and re-enable fresh-agent retry;
+ *   hopeless extraction yields to the introspection sources
+ * - the "[object Object]" defense-in-depth guard in classifyFromSources
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import {
+  extractRunErrorSources,
+  synthesizeError,
+  shouldRetryWithFreshAgent,
+} from "../error-classifier.js";
+
+const FALLBACK = { model: "default", mode: "cloud", agentId: "agent-1" };
+
+function base() {
+  return {
+    sdkResultFields: undefined,
+    streamErrorMessage: undefined,
+    capturedRejection: undefined,
+    isResumedHandle: false,
+    fallbackContext: FALLBACK,
+  } as const;
+}
+
+/** A run.wait()-shaped error result carrying the given error-detail fields. */
+function errorResult(fields: Record<string, unknown>): unknown {
+  return { id: "run-1", status: "error", ...fields };
+}
+
+const NOTHING = { sdkError: undefined, sdkResultFields: undefined };
+
+describe("extractRunErrorSources shape matrix", () => {
+  it("routes a plain string to sdkResultFields", () => {
+    expect(extractRunErrorSources(errorResult({ result: "rate limit exceeded" })))
+      .toEqual({ sdkError: undefined, sdkResultFields: "rate limit exceeded" });
+  });
+
+  it("lifts an Error instance into the structured channel", () => {
+    expect(extractRunErrorSources(errorResult({ result: new Error("connection lost") })))
+      .toEqual({ sdkError: { message: "connection lost" }, sdkResultFields: undefined });
+  });
+
+  it("lifts an Error carrying a code (Node/SDK error shape)", () => {
+    const err = Object.assign(new Error("stream torn down"), { code: "unavailable" });
+    expect(extractRunErrorSources(errorResult({ result: err })))
+      .toEqual({ sdkError: { code: "unavailable", message: "stream torn down" }, sdkResultFields: undefined });
+  });
+
+  it("lifts { code, status, message } from a plain object", () => {
+    expect(extractRunErrorSources(errorResult({ error: { code: "unauthenticated", status: 401, message: "bad token" } })))
+      .toEqual({
+        sdkError: { code: "unauthenticated", status: 401, message: "bad token" },
+        sdkResultFields: undefined,
+      });
+  });
+
+  it("lifts a message-only object", () => {
+    expect(extractRunErrorSources(errorResult({ error: { message: "boom" } })))
+      .toEqual({ sdkError: { message: "boom" }, sdkResultFields: undefined });
+  });
+
+  it("lifts a code-only object", () => {
+    expect(extractRunErrorSources(errorResult({ error: { code: "resource_exhausted" } })))
+      .toEqual({ sdkError: { code: "resource_exhausted" }, sdkResultFields: undefined });
+  });
+
+  it("yields nothing for an object with no recognizable fields (no JSON.stringify junk)", () => {
+    expect(extractRunErrorSources(errorResult({ result: { weird: "shape" } }))).toEqual(NOTHING);
+  });
+
+  it("yields nothing for a circular object", () => {
+    const circular: Record<string, unknown> = {};
+    circular.self = circular;
+    expect(extractRunErrorSources(errorResult({ result: circular }))).toEqual(NOTHING);
+  });
+
+  it("refuses the '[object Object]' junk string itself", () => {
+    expect(extractRunErrorSources(errorResult({ result: "[object Object]" }))).toEqual(NOTHING);
+  });
+
+  it("stringifies non-string primitives losslessly", () => {
+    expect(extractRunErrorSources(errorResult({ result: 503 })))
+      .toEqual({ sdkError: undefined, sdkResultFields: "503" });
+  });
+
+  it("yields nothing when no candidate field is present", () => {
+    expect(extractRunErrorSources(errorResult({}))).toEqual(NOTHING);
+  });
+
+  it("yields nothing for non-object results", () => {
+    expect(extractRunErrorSources(undefined)).toEqual(NOTHING);
+    expect(extractRunErrorSources(null)).toEqual(NOTHING);
+    expect(extractRunErrorSources("not-a-result-object")).toEqual(NOTHING);
+  });
+});
+
+describe("extractRunErrorSources chain order (first USABLE candidate wins)", () => {
+  it("a hopeless object in result no longer hides a usable string in message", () => {
+    const extracted = extractRunErrorSources(
+      errorResult({ result: { weird: "shape" }, message: "the real reason" }),
+    );
+    expect(extracted).toEqual({ sdkError: undefined, sdkResultFields: "the real reason" });
+  });
+
+  it("an empty string in result no longer short-circuits the chain", () => {
+    const extracted = extractRunErrorSources(
+      errorResult({ result: "", reason: "torn down mid-stream" }),
+    );
+    expect(extracted).toEqual({ sdkError: undefined, sdkResultFields: "torn down mid-stream" });
+  });
+
+  it("respects the documented field order: result before error before message before reason", () => {
+    const extracted = extractRunErrorSources(
+      errorResult({ result: "from-result", error: "from-error", message: "from-message" }),
+    );
+    expect(extracted.sdkResultFields).toBe("from-result");
+  });
+
+  it("yields nothing when every candidate is hopeless", () => {
+    const extracted = extractRunErrorSources(
+      errorResult({ result: {}, error: "", message: "[object Object]" }),
+    );
+    expect(extracted).toEqual(NOTHING);
+  });
+});
+
+describe("end-to-end through synthesizeError", () => {
+  beforeEach(() => {
+    vi.spyOn(console, "log").mockImplementation(() => {});
+  });
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("a structured retryable error classifies and re-enables fresh-agent recovery", () => {
+    // The regression at the heart of oss#299: String() turned this into
+    // "[object Object]" -> category=unknown, retryable=false -> the
+    // poisoned-handle retry could never fire for a plain network flake.
+    const extracted = extractRunErrorSources(
+      errorResult({ error: { code: "unavailable", message: "upstream connect error" } }),
+    );
+    const classified = synthesizeError({ ...base(), ...extracted });
+
+    expect(classified.source).toBe("sdk");
+    expect(classified.category).toBe("network");
+    expect(classified.message).toBe("upstream connect error");
+    expect(classified.retryable).toBe(true);
+    expect(shouldRetryWithFreshAgent(classified)).toBe(true);
+  });
+
+  it("hopeless extraction yields to the conversation introspection source", () => {
+    const extracted = extractRunErrorSources(errorResult({ result: { weird: "shape" } }));
+    const classified = synthesizeError({
+      ...base(),
+      ...extracted,
+      conversationErrorText: "grpc-status 12: routing failure",
+    });
+
+    expect(classified.source).toBe("conversation");
+    expect(classified.message).toBe("grpc-status 12: routing failure");
+  });
+
+  it("hopeless extraction yields to the captured rejection source", () => {
+    const extracted = extractRunErrorSources(errorResult({ result: { weird: "shape" } }));
+    const classified = synthesizeError({
+      ...base(),
+      ...extracted,
+      capturedRejection: { code: "unavailable", message: "socket hang up", timestamp: Date.now() },
+    });
+
+    expect(classified.source).toBe("rejection");
+    expect(classified.message).toContain("socket hang up");
+  });
+});
+
+describe("classifyFromSources '[object Object]' defense-in-depth guard", () => {
+  beforeEach(() => {
+    vi.spyOn(console, "log").mockImplementation(() => {});
+  });
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("treats a leaked '[object Object]' sdkResultFields as absent", () => {
+    // Extraction never emits it, but any other producer of the junk string
+    // must not shadow the sources below it.
+    const classified = synthesizeError({
+      ...base(),
+      sdkResultFields: "[object Object]",
+      streamErrorMessage: "fetch failed",
+    });
+
+    expect(classified.source).toBe("stream");
+    expect(classified.category).toBe("network");
+  });
+});

package/src/activities/execute-cursor/__tests__/extract-structured-output.test.ts

@@ -0,0 +1,120 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import type { Config } from "../../../config.js";
+
+vi.mock("../../../shared/model-registry.js", () => ({
+  getEconomyModel: vi.fn().mockResolvedValue("gpt-4o-mini"),
+}));
+
+const mockInvoke = vi.fn();
+const mockWithStructuredOutput = vi.fn().mockReturnValue({ invoke: mockInvoke });
+
+vi.mock("../../../shared/model-client.js", () => ({
+  buildChatModel: vi.fn().mockResolvedValue({
+    model: { withStructuredOutput: (...args: unknown[]) => mockWithStructuredOutput(...args) },
+    provider: "openai",
+    apiModelId: "gpt-4o-mini",
+  }),
+}));
+
+// llm-backend.js and llm-proxy.js stay real: the pre-check behavior under
+// test IS their composition, and both are pure modules.
+
+const SCHEMA = { type: "object", properties: { answer: { type: "string" } } };
+
+function makeConfig(overrides: Partial<Config> = {}): Config {
+  return {
+    proxyEndpoint: null,
+    stigmerToken: null,
+    ...overrides,
+  } as Config;
+}
+
+describe("extractStructuredOutput", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // Deterministic regardless of the developer's shell: blank reads as
+    // missing, and backend vars must not leak in from outside.
+    vi.stubEnv("OPENAI_API_KEY", "");
+    vi.stubEnv("ANTHROPIC_API_KEY", "");
+    vi.stubEnv("STIGMER_ANTHROPIC_BACKEND", "");
+    vi.stubEnv("STIGMER_OPENAI_BACKEND", "");
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("direct mode with a key builds a direct-mode model (no endpoint threaded)", async () => {
+    vi.stubEnv("OPENAI_API_KEY", "sk-direct");
+    const { buildChatModel } = await import("../../../shared/model-client.js");
+    const { extractStructuredOutput } = await import("../extract-structured-output.js");
+    mockInvoke.mockResolvedValueOnce({ answer: "42" });
+
+    const result = await extractStructuredOutput("the answer is 42", SCHEMA, makeConfig(), "gpt-4.1");
+
+    expect(result).toEqual({ answer: "42" });
+    // The regression pin: the gRPC control-plane endpoint must never
+    // reappear here as a stand-in LLM proxy.
+    expect(buildChatModel).toHaveBeenCalledWith(
+      expect.objectContaining({ proxyEndpoint: undefined }),
+    );
+  });
+
+  it("throws the credential message before any construction when no path exists", async () => {
+    const { buildChatModel } = await import("../../../shared/model-client.js");
+    const { extractStructuredOutput } = await import("../extract-structured-output.js");
+
+    await expect(
+      extractStructuredOutput("text", SCHEMA, makeConfig(), "gpt-4.1"),
+    ).rejects.toThrow(/'gpt-4o-mini'.*OPENAI_API_KEY/s);
+    expect(buildChatModel).not.toHaveBeenCalled();
+    expect(mockInvoke).not.toHaveBeenCalled();
+  });
+
+  it("proxy mode threads the proxy endpoint and token, consulting no keys", async () => {
+    const { buildChatModel } = await import("../../../shared/model-client.js");
+    const { extractStructuredOutput } = await import("../extract-structured-output.js");
+    mockInvoke.mockResolvedValueOnce({ answer: "ok" });
+
+    const result = await extractStructuredOutput(
+      "text", SCHEMA,
+      makeConfig({ proxyEndpoint: "https://api.stigmer.ai", stigmerToken: "tok" }),
+      "gpt-4.1",
+    );
+
+    expect(result).toEqual({ answer: "ok" });
+    expect(buildChatModel).toHaveBeenCalledWith(
+      expect.objectContaining({
+        proxyEndpoint: "https://api.stigmer.ai",
+        stigmerToken: "tok",
+      }),
+    );
+  });
+
+  it("defers an un-inferable extraction model to buildChatModel's own error", async () => {
+    // The registry-empty fallback returns the primary model verbatim; when
+    // its provider can't be inferred the pre-check must not guess — the
+    // construction path owns the precise message.
+    const { getEconomyModel } = await import("../../../shared/model-registry.js");
+    vi.mocked(getEconomyModel).mockResolvedValueOnce("mystery-model");
+    const { buildChatModel } = await import("../../../shared/model-client.js");
+    const { extractStructuredOutput } = await import("../extract-structured-output.js");
+    mockInvoke.mockResolvedValueOnce({ answer: "ok" });
+
+    await extractStructuredOutput("text", SCHEMA, makeConfig(), "mystery-model");
+
+    expect(buildChatModel).toHaveBeenCalledWith(
+      expect.objectContaining({ modelName: "mystery-model" }),
+    );
+  });
+
+  it("normalizes an empty extraction result to null", async () => {
+    vi.stubEnv("OPENAI_API_KEY", "sk-direct");
+    const { extractStructuredOutput } = await import("../extract-structured-output.js");
+    mockInvoke.mockResolvedValueOnce(undefined);
+
+    const result = await extractStructuredOutput("text", SCHEMA, makeConfig(), "gpt-4.1");
+
+    expect(result).toBeNull();
+  });
+});

package/src/activities/execute-cursor/__tests__/hook-script.test.ts

@@ -245,6 +245,99 @@ d("generated approval hook (preToolUse + beforeMCPExecution)", () => {
     });
   });
 
+  // The enabled_tools capability manifest (issue #350): mcpServerEnabledTools
+  // holds ONLY restricted servers; the hook denies a listed server's
+  // non-listed tool with the non-pausing, permanent "disabled" kind — BEFORE
+  // autoApproveAll and the grant checks, because a manifest is not an
+  // approval gate (nothing may resurrect a disabled tool). hookMcp payloads
+  // carry mcp_server_name "srv".
+  describe("MCP enabled_tools manifest (beforeMCPExecution, issue #350)", () => {
+    it("denies a non-enabled tool with kind disabled (content-free, single record) and the manifest message", () => {
+      const h = setup({ mcpServerEnabledTools: { srv: ["list_apps"] } });
+
+      const res = h.decide(hookMcp("click", { app: "Slack" }));
+
+      expect(res.permission).toBe("deny");
+      // Permanent-denial framing, never the approval promise: the model must
+      // adapt, not wait for a resume that will never come.
+      expect(res.raw).toContain("not enabled for this agent");
+      expect(res.raw).not.toContain("submitted to the user for approval");
+      const ledger = h.ledger();
+      expect(ledger).toHaveLength(1);
+      expect(ledger[0].kind).toBe("disabled");
+      // Attributable under the MCP name-token (the identity the stream row
+      // computes), content-free like every non-approval kind.
+      expect(ledger[0].token).toBe(grantToken("click", ""));
+      expect(ledger[0]).not.toHaveProperty("input");
+    });
+
+    it("allows an enabled tool on a restricted server", () => {
+      const h = setup({ mcpServerEnabledTools: { srv: ["list_apps"] } });
+      expect(h.decide(hookMcp("list_apps")).permission).toBe("allow");
+      expect(h.ledger()).toEqual([]);
+    });
+
+    it("denies even under autoApproveAll (a manifest is not an approval gate)", () => {
+      const h = setup({
+        autoApproveAll: true,
+        mcpServerEnabledTools: { srv: ["list_apps"] },
+      });
+      const res = h.decide(hookMcp("click"));
+      expect(res.permission).toBe("deny");
+      expect(h.ledger()[0].kind).toBe("disabled");
+    });
+
+    it("denies even when the tool holds a reinvocation grant (no approval may resurrect it)", () => {
+      const h = setup({
+        mcpServerEnabledTools: { srv: ["list_apps"] },
+        grants: [{ toolName: "click", mcpServerSlug: "srv", key: "click", salient: "", contentDigest: "", sourceToolCallId: "consent-1" }],
+      });
+      const res = h.decide(hookMcp("click"));
+      expect(res.permission).toBe("deny");
+      expect(h.ledger()[0].kind).toBe("disabled");
+    });
+
+    it("stays kind disabled under unattended mode (mode-independent, like secret)", () => {
+      const h = setup({
+        unattendedSkip: true,
+        mcpServerEnabledTools: { srv: ["list_apps"] },
+      });
+      const res = h.decide(hookMcp("click"));
+      expect(res.permission).toBe("deny");
+      expect(h.ledger()[0].kind).toBe("disabled");
+    });
+
+    it("an enabled tool still flows into the normal approval arm (manifest and gate compose)", () => {
+      const h = setup({
+        mcpPolicies: { click: { requiresApproval: true, message: "Approve click?" } },
+        mcpServerEnabledTools: { srv: ["click"] },
+      });
+      const res = h.decide(hookMcp("click"));
+      expect(res.permission).toBe("deny");
+      expect(res.raw).toContain("Approve click?");
+      expect(h.ledger()[0].kind).toBe("approval");
+    });
+
+    it("a restriction on ANOTHER server never narrows this one (server-scoped matching)", () => {
+      const h = setup({ mcpServerEnabledTools: { other: ["something_else"] } });
+      expect(h.decide(hookMcp("click")).permission).toBe("allow");
+      expect(h.ledger()).toEqual([]);
+    });
+
+    it("quoted-name matching is exact — an enabled name never allows its prefix-sibling", () => {
+      const h = setup({ mcpServerEnabledTools: { srv: ["list_apps_extended"] } });
+      const res = h.decide(hookMcp("list_apps"));
+      expect(res.permission).toBe("deny");
+      expect(h.ledger()[0].kind).toBe("disabled");
+    });
+
+    it("never gates a preToolUse (built-in) payload — the manifest arm is MCP-event-scoped", () => {
+      const h = setup({ mcpServerEnabledTools: { srv: ["list_apps"] } });
+      expect(h.decide(hookRead("/x/a.txt")).permission).toBe("allow");
+      expect(h.ledger()).toEqual([]);
+    });
+  });
+
   // The hook captures the COMPLETE tool_input on every denial (base64(JSON)),
   // so the runner can overlay the proposed change onto the gated tool call for
   // the approval preview — the cursor analog of the native harness reading args

package/src/activities/execute-cursor/__tests__/mcp-resolver.test.ts

@@ -0,0 +1,125 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { resolveMcpServers } from "../mcp-resolver.js";
+
+function makeUsage(
+  slug: string,
+  enabledTools: string[] = [],
+  toolApprovalOverrides: Array<{ toolName: string; requiresApproval: boolean }> = [],
+) {
+  return {
+    mcpServerRef: { slug, org: "test-org", kind: 0 },
+    enabledTools,
+    toolApprovalOverrides,
+  } as any;
+}
+
+function httpMcpServer(slug: string, defaultEnabledTools: string[] = []) {
+  return {
+    metadata: { id: `id-${slug}`, slug },
+    spec: {
+      serverType: { case: "http", value: { url: "https://mcp.example.com/mcp", headers: {} } },
+      env: {},
+      defaultEnabledTools,
+    },
+    status: undefined,
+  } as any;
+}
+
+function clientReturning(serversBySlug: Record<string, unknown>) {
+  return {
+    getMcpServerByReference: vi.fn(async (ref: { slug: string }) => {
+      const server = serversBySlug[ref.slug];
+      if (!server) throw new Error(`not found: ${ref.slug}`);
+      return server;
+    }),
+  } as any;
+}
+
+// The effective-list semantics live in shared/mcp-enabled-tools.ts (tested
+// there); these tests pin the CURSOR resolver's threading — the near-duplicate
+// of shared/mcp-resolver.ts that must mirror it until oss#387 consolidates.
+describe("resolveMcpServers (cursor) — enabled_tools threading (issue #350)", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  it("carries the usage's enabled_tools as the effective allow-list", async () => {
+    const client = clientReturning({ github: httpMcpServer("github") });
+
+    const result = await resolveMcpServers(
+      client, [makeUsage("github", ["create_pr"])], {}, "stdio-forbidden",
+    );
+
+    expect(result.resolvedServers[0].enabledTools).toEqual(["create_pr"]);
+  });
+
+  it("falls back to default_enabled_tools for an empty usage list", async () => {
+    const client = clientReturning({
+      github: httpMcpServer("github", ["search_code"]),
+    });
+
+    const result = await resolveMcpServers(
+      client, [makeUsage("github")], {}, "stdio-forbidden",
+    );
+
+    expect(result.resolvedServers[0].enabledTools).toEqual(["search_code"]);
+  });
+
+  it("resolves unrestricted (absent field) when both lists are empty", async () => {
+    const client = clientReturning({ github: httpMcpServer("github") });
+
+    const result = await resolveMcpServers(
+      client, [makeUsage("github")], {}, "stdio-forbidden",
+    );
+
+    expect(result.resolvedServers[0].enabledTools).toBeUndefined();
+  });
+
+  it("never narrows the Cursor SDK config — the SDK has no allow-list field; enforcement is the hook's disabled arm", async () => {
+    const client = clientReturning({ github: httpMcpServer("github") });
+
+    const result = await resolveMcpServers(
+      client, [makeUsage("github", ["create_pr"])], {}, "stdio-forbidden",
+    );
+
+    expect(result.cursorConfig.github).toEqual({
+      type: "http",
+      url: "https://mcp.example.com/mcp",
+      headers: undefined,
+    });
+  });
+});
+
+describe("resolveMcpServers (cursor) — tool_approval_overrides threading (issue #349)", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  it("carries the usage's overrides on its own resolved server only", async () => {
+    // Riding the server is the scoping mechanism: an override can no longer
+    // reach a same-named tool on another server, because it never exists
+    // anywhere but its own server's object.
+    const client = clientReturning({
+      github: httpMcpServer("github"),
+      slack: httpMcpServer("slack"),
+    });
+
+    const result = await resolveMcpServers(
+      client,
+      [
+        makeUsage("github", [], [{ toolName: "delete_item", requiresApproval: false }]),
+        makeUsage("slack"),
+      ],
+      {},
+      "stdio-forbidden",
+    );
+
+    const bySlug = new Map(result.resolvedServers.map((s) => [s.slug, s]));
+    expect(bySlug.get("github")!.toolApprovalOverrides).toEqual([
+      { toolName: "delete_item", requiresApproval: false },
+    ]);
+    expect(bySlug.get("slack")!.toolApprovalOverrides).toEqual([]);
+  });
+});

package/src/activities/execute-cursor/__tests__/prompt-builder-delegation.test.ts

@@ -70,7 +70,7 @@ describe("buildEnhancedPrompt delegation integration", () => {
     skills: [],
     subAgents: [],
     workspaceFileRefs: [],
-    attachmentPaths: [],
+    attachments: [],
   };
 
   it("includes exploration guidance when a workspace dir is present", () => {

package/src/activities/execute-cursor/__tests__/turn-stream.test.ts

@@ -222,6 +222,19 @@ describe("consumeCursorTurnStream", () => {
     expect(state.streamErrorMessage).toBe("boom");
   });
 
+  it("does not capture a non-string stream ERROR message (oss#299 hardening)", async () => {
+    // message is untyped at runtime; a structured value assigned here would
+    // crash classifyText downstream (.toLowerCase() on a non-string).
+    const { deps, state } = buildDeps();
+
+    await consumeCursorTurnStream(
+      mockRun([ev({ type: "status", status: "ERROR", message: { code: 14 } })]),
+      deps,
+    );
+
+    expect(state.streamErrorMessage).toBeUndefined();
+  });
+
   describe("first-denial early stop", () => {
     let hitlDir: string;
 

package/src/activities/execute-cursor/approval-state.ts

@@ -13,6 +13,7 @@
  *   "mcpToolPolicies": {
  *     "apply_cloud_resource": { "requiresApproval": true, "message": "..." }
  *   },
+ *   "mcpServerEnabledTools": { "planton": ["get_cloud_resource"] },
  *   "approvedGrants": [{ "toolName": "edit", "mcpServerSlug": "", "key": "write", "salient": "a.txt", "contentDigest": "<sha256>" }],
  *   "approvedGrantTokens": ["<base64(key\nsalient[\ncontentDigest])>"]
  * }
@@ -174,6 +175,21 @@ export interface ApprovalStateFile {
    */
   leasedCategories: string[];
   mcpToolPolicies: Record<string, McpToolPolicyEntry>;
+  /**
+   * Per-server effective enabled_tools allow-lists (issue #350), keyed by
+   * MCP server slug — ONLY restricted servers appear (an absent slug means
+   * unrestricted, so the common case stays an empty object). The Cursor SDK
+   * config cannot hide a server's tools, so the hook enforces the manifest
+   * instead: on beforeMCPExecution it matches the payload's mcp_server_name
+   * against this map and denies a non-listed tool with the non-pausing,
+   * permanent "disabled" kind — BEFORE autoApproveAll and grants, because
+   * enabled_tools is a capability manifest, not an approval gate (no bypass
+   * may resurrect a disabled tool, and no human may be offered "approve" on
+   * one). Unlike mcpToolPolicies (name-keyed, server-blind), this map is
+   * server-scoped: the hook payload carries the server identity, so equal
+   * tool names on different servers cannot cross-grant.
+   */
+  mcpServerEnabledTools: Record<string, string[]>;
   approvedGrants: ApprovalGrant[];
   approvedGrantTokens: string[];
   /**
@@ -381,6 +397,8 @@ function parseArgs(argsPreview: string): Record<string, unknown> | undefined {
  * - leasedCategories: built-in categories with a run-lifetime lease
  * - mcpToolPolicies: per-tool policy for MCP tools requiring approval (leased
  *   servers are already absent — dropped upstream by mergeApprovalPolicies)
+ * - mcpServerEnabledTools: per-server enabled_tools allow-lists (issue #350,
+ *   restricted servers only) for the hook's permanent "disabled" arm
  * - approvedGrants / approvedGrantTokens: tools approved in the current HITL
  *   cycle, allowed through on reinvocation
  *
@@ -396,6 +414,7 @@ export function buildApprovalState(
   captureIgnored = false,
   gitWorkspace = true,
   unattendedSkip = false,
+  mcpServerEnabledTools: Record<string, string[]> = {},
 ): ApprovalStateFile {
   const approvedGrants = grants ?? [];
 
@@ -411,6 +430,7 @@ export function buildApprovalState(
     autoApproveAll: globalBypass,
     leasedCategories: [...leasedCategories],
     mcpToolPolicies,
+    mcpServerEnabledTools,
     approvedGrants,
     // The hook matches a tool call's PRIMARY token (content when it can compute a
     // digest from tool_input, else coarse). A content-identified grant authorizes
@@ -474,12 +494,18 @@ const DENIAL_LEDGER_FILE = "denials.jsonl";
  *                     classification may never have run).
  * - `fail-closed`   — the approval state file was missing, so everything gated
  *                     denied. A turn-level "the gate itself was broken" fact.
+ * - `disabled`      — the agent's enabled_tools manifest excludes this MCP
+ *                     tool (issue #350). Permanent for the run and
+ *                     mode-independent: NOT an approval (a human must never be
+ *                     offered "approve" on a manifest-disabled tool), so it is
+ *                     non-pausing and the model adapts — the same consumer
+ *                     semantics as `secret`.
  *
  * An unknown kind string is preserved as-is: it is treated as non-pausing (an
  * unknown deny must never manufacture an approval) but still attributes the
  * blocked call to our own hook.
  */
-export type DenialKind = "approval" | "unattended" | "secret" | "capture-error" | "fail-closed";
+export type DenialKind = "approval" | "unattended" | "secret" | "capture-error" | "fail-closed" | "disabled";
 
 /** The one kind that pauses the run for user approval. */
 export const APPROVAL_DENIAL_KIND: DenialKind = "approval";
@@ -487,6 +513,9 @@ export const APPROVAL_DENIAL_KIND: DenialKind = "approval";
 /** The unattended-mode resolution kind (non-pausing; stamped SKIPPED). */
 export const UNATTENDED_DENIAL_KIND: DenialKind = "unattended";
 
+/** The enabled_tools manifest denial kind (non-pausing, permanent; issue #350). */
+export const DISABLED_DENIAL_KIND: DenialKind = "disabled";
+
 /**
  * One denial recorded by the preToolUse hook. `token` is the call's identity in
  * the same space as grantToken() (base64 of `toolName \n salientArg`), used to