@stigmer/runner 3.9.0 → 3.11.0

package/src/activities/execute-cursor/attachment-resolver.ts

@@ -22,6 +22,13 @@
  * directives are built from the RESOLVED paths, so prompt and filesystem can
  * never disagree.
  *
+ * Duplicate filenames are renamed, never overwritten (issue #364): because
+ * placement keys purely on the filename, two attachments with the same name
+ * contend for one path — the later one takes the platform's `stem-2.ext`
+ * rename (shared/attachment-naming.ts, same semantics as the deep-agent
+ * injector and the React composer) and the rename is disclosed in the
+ * prompt's `<input_files>` section via {@link ResolvedAttachment.renamedFrom}.
+ *
  * Error model: fail-hard, matching the native harness's attachment injector.
  * Attachments are explicit user inputs — an execution that silently runs
  * without one produces silently incorrect results (the "plan file wasn't
@@ -33,6 +40,7 @@ import { mkdir, copyFile, readFile, stat, writeFile } from "node:fs/promises";
 import { join, basename } from "node:path";
 import type { Attachment } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
 import type { ArtifactStorage } from "../../shared/artifact-storage.js";
+import { allocateUniqueName } from "../../shared/attachment-naming.js";
 import {
   isVisionCandidate,
   type VisionBudget,
@@ -46,9 +54,16 @@ import { ensureStigmerSymlink, STIGMER_LOCAL_STATE_DIR } from "../../shared/work
 const INPUTS_SUBDIR = "inputs";
 
 export interface ResolvedAttachment {
+  /** The final on-disk basename — after any duplicate rename. */
   filename: string;
   /** Workspace-relative path the agent reads (`.stigmer/inputs/{filename}`). */
   relativePath: string;
+  /**
+   * The attachment's original filename, present only when a duplicate name
+   * was renamed (shared/attachment-naming.ts) — rendered as disclosure in
+   * the prompt's `<input_files>` section.
+   */
+  renamedFrom?: string;
   /** Present when the attachment was accepted into the turn's vision payload. */
   vision?: VisionImage;
   /**
@@ -111,9 +126,13 @@ export async function resolveAttachments(
   // it, but only when the agent has skills).
   await ensureStigmerSymlink(options.primaryWorkspaceDir, platformDir);
 
+  // Placement keys purely on the filename, so this set is the whole
+  // collision domain — sequential resolution means each attachment sees
+  // every name claimed before it (see module doc on duplicate handling).
+  const takenNames = new Set<string>();
   const results: ResolvedAttachment[] = [];
   for (const attachment of attachments) {
-    results.push(await resolveAttachment(attachment, inputsDir, options));
+    results.push(await resolveAttachment(attachment, inputsDir, takenNames, options));
   }
 
   console.log(
@@ -127,11 +146,15 @@ export async function resolveAttachments(
 async function resolveAttachment(
   attachment: Attachment,
   inputsDir: string,
+  takenNames: Set<string>,
   options: AttachmentResolverOptions,
 ): Promise<ResolvedAttachment> {
   // Local-mode fast path: the file is already on this machine's disk.
   if (options.mode === "local" && attachment.localPath) {
-    const filename = safeInputName(attachment.filename || attachment.localPath);
+    const { name: filename, renamedFrom } = allocateUniqueName(
+      safeInputName(attachment.filename || attachment.localPath),
+      takenNames,
+    );
     let vision: VisionOutcome | undefined;
     try {
       vision = await materializeLocalFile(attachment, filename, inputsDir, options.visionBudget);
@@ -145,6 +168,7 @@ async function resolveAttachment(
     return {
       filename,
       relativePath: join(STIGMER_LOCAL_STATE_DIR, INPUTS_SUBDIR, filename),
+      ...(renamedFrom !== undefined ? { renamedFrom } : {}),
       ...visionOutcomeFields(vision),
     };
   }
@@ -164,7 +188,10 @@ async function resolveAttachment(
     );
   }
 
-  const filename = safeInputName(attachment.filename || attachment.storageKey);
+  const { name: filename, renamedFrom } = allocateUniqueName(
+    safeInputName(attachment.filename || attachment.storageKey),
+    takenNames,
+  );
   let content: Buffer;
   try {
     content = await options.storage.download(attachment.storageKey);
@@ -185,6 +212,7 @@ async function resolveAttachment(
   return {
     filename,
     relativePath: join(STIGMER_LOCAL_STATE_DIR, INPUTS_SUBDIR, filename),
+    ...(renamedFrom !== undefined ? { renamedFrom } : {}),
     ...visionOutcomeFields(vision),
   };
 }
@@ -207,6 +235,13 @@ async function materializeLocalFile(
     await copyFile(attachment.localPath, dest);
     return undefined;
   }
+  // Blind-model check BEFORE the size check: a blind model's oversized image
+  // must report the honest model_no_vision reason, never too_large's "resend
+  // smaller" advice — and an in-cap image needn't be read at all.
+  if (visionBudget.modelCannotSee()) {
+    await copyFile(attachment.localPath, dest);
+    return visionBudget.offerBlind();
+  }
   const info = await stat(attachment.localPath);
   if (visionBudget.exceedsImageCap(info.size)) {
     await copyFile(attachment.localPath, dest);

package/src/activities/execute-cursor/blueprint-resolver.ts

@@ -20,6 +20,13 @@ import type { SessionSpec } from "@stigmer/protos/ai/stigmer/agentic/session/v1/
 import type { WorkspaceEntry } from "@stigmer/protos/ai/stigmer/agentic/session/v1/workspace_pb";
 import type { ApiResourceReference } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
 import type { CloudRepo } from "./session-lifecycle.js";
+import { mergeMcpServerUsages } from "../../shared/mcp-resolver.js";
+
+// Both harnesses must merge agent + session usages identically (session wins
+// per slug — the usage whose enabled_tools the enforcement honors), so the
+// merge lives in shared/mcp-resolver.ts. Re-exported here for its historical
+// home alongside mergeSkillRefs.
+export { mergeMcpServerUsages } from "../../shared/mcp-resolver.js";
 
 /**
  * Path segments that identify runner-internal directories. Any workspace dir
@@ -130,33 +137,6 @@ export function resolveCloudRepos(workspaceEntries: WorkspaceEntry[]): CloudRepo
 // MCP and skill merging
 // ---------------------------------------------------------------------------
 
-/**
- * Merge MCP server usages from agent (base) and session (overlay).
- *
- * Replicates session_context_merge.py::merge_mcp_server_usages():
- * - Agent-level usages are the base set
- * - Session-level usages extend or override by mcp_server_ref.slug
- * - If both reference the same slug, session-level takes precedence
- */
-export function mergeMcpServerUsages(
-  agentUsages: McpServerUsage[],
-  sessionUsages: McpServerUsage[],
-): McpServerUsage[] {
-  const bySlug = new Map<string, McpServerUsage>();
-
-  for (const usage of agentUsages) {
-    const slug = usage.mcpServerRef?.slug;
-    if (slug) bySlug.set(slug, usage);
-  }
-
-  for (const usage of sessionUsages) {
-    const slug = usage.mcpServerRef?.slug;
-    if (slug) bySlug.set(slug, usage);
-  }
-
-  return [...bySlug.values()];
-}
-
 /**
  * Merge skill refs from agent and session.
  *

package/src/activities/execute-cursor/env-resolver.ts

@@ -25,7 +25,9 @@ export async function resolveExecutionEnv(
 ): Promise<EnvResult> {
   // A desktop runner exchanges its bootstrap credential for a token scoped to
   // this execution's session, so cloud's decrypt gate binds the read (#156).
-  // No-op for cloud sandbox and OSS runners.
+  // No-op for cloud sandbox and OSS runners. A failed exchange throws and
+  // fails the activity: the bootstrap credential no longer decrypts
+  // (stigmer-cloud#218), so proceeding would resolve redacted placeholders.
   const scopedToken = await client.acquireScopedRunnerToken({
     agentExecutionId: executionId,
   });

package/src/activities/execute-cursor/error-classifier.ts

@@ -7,8 +7,9 @@
  * 3. Surface isRetryable for future workflow-level retry decisions
  *
  * Error detail can come from several sources (in priority order):
- * - A thrown CursorSdkError's structured fields (highest fidelity)
- * - run.wait().result (SDK-provided string, often bare/generic)
+ * - Structured fields, either from a thrown CursorSdkError or lifted from a
+ *   structured run.wait() error value (highest fidelity)
+ * - run.wait() error text (SDK-provided string, often bare/generic)
  * - SDKStatusMessage with status "ERROR" from the stream
  * - ConnectError captured from process unhandledRejection
  * - Text extracted from the failing run.conversation() turn
@@ -39,7 +40,8 @@ export interface ClassifiedError {
 
 /**
  * Structured fields lifted from a thrown CursorSdkError (errors.d.ts:
- * { code, status, isRetryable, cause, endpoint, requestId, operation }).
+ * { code, status, isRetryable, cause, endpoint, requestId, operation }) or
+ * from a structured run.wait() error value (see extractRunErrorSources).
  * Only the fields used for classification are retained.
  */
 export interface SdkErrorFields {
@@ -48,6 +50,87 @@ export interface SdkErrorFields {
   message?: string;
 }
 
+/**
+ * What String() produces for any plain object. Carries zero signal, so it is
+ * refused everywhere: extraction never emits it, and classifyFromSources
+ * treats it as absent should any other producer leak it through.
+ */
+const OBJECT_JUNK_STRING = "[object Object]";
+
+/**
+ * Error detail lifted from a run.wait() result, split by fidelity: structured
+ * values land in sdkError, plain text in sdkResultFields. At most one of the
+ * two is set; both undefined means the result carried nothing usable and the
+ * classifier's lower-priority sources should decide.
+ */
+export interface RunErrorSources {
+  sdkError: SdkErrorFields | undefined;
+  sdkResultFields: string | undefined;
+}
+
+const NO_RUN_ERROR_SOURCES: RunErrorSources = {
+  sdkError: undefined,
+  sdkResultFields: undefined,
+};
+
+/**
+ * Lift error detail from a run.wait() result whose status is "error".
+ *
+ * The SDK types RunResult.result as `string`, but structured values (Error
+ * instances, { code, message } objects) have been observed at runtime, both
+ * in `result` and in the undeclared error/message/reason fields (oss#299).
+ * A bare String() on those yields "[object Object]", which both destroys the
+ * message users see and — worse — shadows the lower-priority classifier
+ * sources (stream, rejection, conversation introspection) that often hold
+ * the real reason.
+ *
+ * Walks the candidate fields in order and answers from the FIRST one that
+ * yields usable content: strings keep flowing to the string channel
+ * (sdkResultFields), structured values are lifted into the same structured
+ * channel a thrown CursorSdkError uses (sdkError), and hopeless values are
+ * skipped so a later candidate — or the classifier's fallback sources — can
+ * win. (The previous `??` chain stopped at the first non-nullish value, so a
+ * hopeless object or empty string hid usable text one field later.)
+ *
+ * Deliberately NO JSON.stringify fallback for unrecognized object shapes:
+ * the error arm already logs the raw result in full server-side, and a JSON
+ * blob shown to the user would shadow the introspection sources that exist
+ * precisely to recover the real reason.
+ */
+export function extractRunErrorSources(result: unknown): RunErrorSources {
+  if (result === null || typeof result !== "object") return NO_RUN_ERROR_SOURCES;
+  const r = result as Record<string, unknown>;
+  for (const candidate of [r.result, r.error, r.message, r.reason]) {
+    const extracted = extractFromCandidate(candidate);
+    if (extracted) return extracted;
+  }
+  return NO_RUN_ERROR_SOURCES;
+}
+
+function extractFromCandidate(v: unknown): RunErrorSources | undefined {
+  if (v == null) return undefined;
+  if (typeof v === "string") {
+    if (v.length === 0 || v === OBJECT_JUNK_STRING) return undefined;
+    return { sdkError: undefined, sdkResultFields: v };
+  }
+  if (typeof v === "object") {
+    // Covers Error instances too: their message (and, on SDK/Node error
+    // shapes, code/status) are readable as plain properties.
+    const o = v as Record<string, unknown>;
+    const fields: SdkErrorFields = {};
+    if (typeof o.code === "string" && o.code.length > 0) fields.code = o.code;
+    if (typeof o.status === "number") fields.status = o.status;
+    if (typeof o.message === "string" && o.message.length > 0) fields.message = o.message;
+    if (fields.code !== undefined || fields.status !== undefined || fields.message !== undefined) {
+      return { sdkError: fields, sdkResultFields: undefined };
+    }
+    return undefined;
+  }
+  // Remaining primitives (number, boolean, ...) stringify losslessly.
+  const text = String(v);
+  return text.length > 0 ? { sdkError: undefined, sdkResultFields: text } : undefined;
+}
+
 const AUTH_PATTERNS = [
   "unauthenticated", "unauthorized", "401", "forbidden",
   "permission_denied", "invalid api key", "not logged in",
@@ -168,7 +251,11 @@ function classifyFromSources(opts: SynthesizeErrorOpts): ClassifiedError {
   }
 
   if (opts.sdkResultFields) {
-    const isBareGeneric = opts.sdkResultFields === "Cursor run failed";
+    // "Cursor run failed" is the SDK's bare generic; "[object Object]" is
+    // String()-coerced junk from any producer that bypassed the shape-aware
+    // extraction. Neither carries signal — fall through to better sources.
+    const isBareGeneric = opts.sdkResultFields === "Cursor run failed"
+      || opts.sdkResultFields === OBJECT_JUNK_STRING;
     if (!isBareGeneric) {
       const { category, retryable } = classifyText(opts.sdkResultFields);
       return {

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

@@ -0,0 +1,72 @@
+/**
+ * Tier-2 structured-output extraction for the Cursor harness.
+ *
+ * When tier-1 text extraction (shared/extract-json.ts) cannot find JSON in
+ * the agent's free-text response, this tier asks an economy-tier LLM to
+ * extract it via withStructuredOutput (function-calling), which guarantees
+ * schema-conformant output through the API's tool-use mechanism.
+ *
+ * Lives in its own module (rather than inside execute-cursor/index.ts) so
+ * the LangChain construction path stays out of the Cursor activity's module
+ * graph until a run actually needs tier 2 — index.ts imports this module
+ * lazily at the call site, mirroring its tier-1 import, which is what
+ * bundle-slim's deferred evaluation preserves.
+ */
+
+import type { Config } from "../../config.js";
+import { getEconomyModel } from "../../shared/model-registry.js";
+import { buildChatModel } from "../../shared/model-client.js";
+import { checkDirectCredentials } from "../../shared/llm-backend.js";
+import { tryInferProvider } from "../../shared/llm-proxy.js";
+import { jsonSchemaToZod } from "../../shared/json-schema-to-zod.js";
+
+/**
+ * Extract structured data from an agent's free-text response using an
+ * economy-tier LLM with withStructuredOutput (function-calling).
+ *
+ * Construction (registry-id resolution, provider inference, proxy wiring) is
+ * delegated to the shared buildChatModel so the economy model's registry id
+ * is always resolved to a provider API id before the call.
+ *
+ * Throws when no LLM is reachable (no proxy and no credential path for the
+ * extraction model's provider) — the caller treats any throw here as "tier 2
+ * unavailable", logs it, and returns the agent's text without structured
+ * output, so the failure mode is a diagnosable log line, never a lost run.
+ */
+export async function extractStructuredOutput(
+  agentResponse: string,
+  schema: Record<string, unknown>,
+  config: Config,
+  primaryModel: string,
+): Promise<unknown | null> {
+  const extractionModel = await getEconomyModel(primaryModel);
+  const proxyEndpoint = config.proxyEndpoint ?? undefined;
+
+  if (!proxyEndpoint) {
+    const provider = tryInferProvider(extractionModel);
+    const missing = provider === null ? null : checkDirectCredentials(provider);
+    if (missing !== null) {
+      throw new Error(
+        `Structured-output extraction needs the ${provider} model ` +
+        `'${extractionModel}' but has no credential path. ${missing}`,
+      );
+    }
+  }
+
+  const { model: llm } = await buildChatModel({
+    modelName: extractionModel,
+    proxyEndpoint,
+    stigmerToken: config.stigmerToken ?? undefined,
+    maxTokens: 4096,
+  });
+
+  const zodSchema = jsonSchemaToZod(schema);
+  const structured = llm.withStructuredOutput(zodSchema);
+
+  const result = await structured.invoke([
+    { role: "system", content: "Extract the structured data from the agent's response. Return only the data that matches the schema." },
+    { role: "user", content: agentResponse },
+  ]);
+
+  return result ?? null;
+}

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

@@ -32,6 +32,8 @@
  *   - "secret"        — DD-26 secret hard-block: the agent continues, no pause.
  *   - "capture-error" — CAS staging failed, write kept on the deny-gate.
  *   - "fail-closed"   — approval state file missing, everything gated denies.
+ *   - "disabled"      — enabled_tools manifest exclusion (issue #350): the
+ *                       agent continues, no pause, permanent for the run.
  * Only approval-kind records carry the captured tool_input: a secret write's
  * content must never be persisted (DD-26), a capture-error's content is
  * UNCLASSIFIED (the staging error means secret classification may never have
@@ -84,8 +86,16 @@
  * set, allow the rest" — matching the native harness and avoiding denial of
  * auto-approved MCP tools (which are absent from mcpToolPolicies):
  * 0. Scope guard: not the runner's own agent → allow (never touch the ledger)
- * 1. Missing state file → deny (fail-closed); autoApproveAll (the pre-armed
- *    spec.auto_approve_all global bypass) → allow
+ * 1. Missing state file → deny (fail-closed)
+ * 1a. beforeMCPExecution event → tool excluded by the server's
+ *     mcpServerEnabledTools allow-list → record kind "disabled", deny.
+ *     Deliberately BEFORE autoApproveAll and the grant checks: enabled_tools
+ *     is a capability manifest, not an approval gate (issue #350) — no bypass
+ *     may resurrect a disabled tool, and no human may be offered "approve" on
+ *     one. Server-scoped via the payload's mcp_server_name; an absent slug in
+ *     the map means unrestricted.
+ * 1b. autoApproveAll (the pre-armed spec.auto_approve_all global bypass) →
+ *     allow
  * 2. beforeMCPExecution event → MCP tool present in mcpToolPolicies
  *    (require-approval):
  *    a. name token in approvedGrantTokens → allow (reinvocation grant)
@@ -155,6 +165,23 @@ const SECRET_BLOCKED_AGENT_MESSAGE =
   "hooks. Do not retry this write or attempt a workaround; the write will not be " +
   "applied. Continue with the rest of the task.";
 
+// Shown to the model when an MCP tool call is denied because the agent's
+// enabled_tools manifest excludes the tool (issue #350). Like
+// SECRET_BLOCKED_AGENT_MESSAGE this must NOT promise a resume — the exclusion
+// is permanent for the run and mode-independent (it is a capability manifest,
+// not an approval, so nothing can be granted). Same embedding constraint
+// (single-quoted bash echo of a JSON object): no double quotes, apostrophes,
+// or backslashes.
+const DISABLED_TOOL_AGENT_MESSAGE =
+  "This tool is not enabled for this agent: the MCP server exposes it, but the " +
+  "agent manifest (enabled_tools) excludes it. This is the platform capability " +
+  "manifest working as intended — it is not an error and not a Cursor " +
+  "misconfiguration, so never tell the user to change Cursor settings or enable " +
+  "hooks. Do not retry this tool or attempt a workaround; it will stay " +
+  "unavailable for this entire run. Use a different tool or adapt your plan, " +
+  "and if the task cannot proceed without it, tell the user plainly what was " +
+  "unavailable.";
+
 /**
  * Build the bash `case` arms that map an incoming hook `tool_name` to its
  * canonical approval category. Generated from approval-policy.ts so the hook and
@@ -209,14 +236,17 @@ function buildContentDigestScript(): string {
  * Build the inline Node.js identity extractor embedded in the hook script.
  *
  * Parses the hook's stdin JSON properly (the bash fallback's grep truncates
- * string values at the first escaped quote) and emits SEVEN lines: tool_name,
+ * string values at the first escaped quote) and emits NINE lines: tool_name,
  * canonical category, coarse identity token, MCP name-token, hook_event_name
  * (the event discriminator: `preToolUse` for built-ins, `beforeMCPExecution`
  * for MCP), base64(JSON(tool_input)) — the authoritative pre-execution args the
- * runner overlays onto the gated tool call for the approval preview — and the
+ * runner overlays onto the gated tool call for the approval preview — the
  * CONTENT token (base64(category \n salient \n contentDigest), empty when the
- * tool has no edit content). The token encodings must stay byte-identical to
- * grantToken()/contentToken() in approval-state.ts.
+ * tool has no edit content), base64(salient), and mcp_server_name (the MCP
+ * server slug the beforeMCPExecution payload carries; empty for built-ins) —
+ * the server scope for the enabled_tools manifest arm. The token encodings
+ * must stay byte-identical to grantToken()/contentToken() in
+ * approval-state.ts.
  *
  * Authored as a single-quoted bash string, so the JS must not contain single
  * quotes. The category map, salient field list, and edit/content field lists are
@@ -247,6 +277,7 @@ function buildNodeIdentityScript(): string {
     // is "" for a non-edit tool, in which case the content token (line 7) is "".
     buildContentDigestScript(),
     `const ev=typeof t.hook_event_name==="string"?t.hook_event_name:"";`,
+    `const srv=typeof t.mcp_server_name==="string"?t.mcp_server_name:"";`,
     // Line 6 is base64(JSON(tool_input)): the AUTHORITATIVE pre-execution args
     // the runner overlays onto the gated tool call so the approval card can show
     // the proposed change before the user approves. Base64 keeps the bash side
@@ -255,8 +286,10 @@ function buildNodeIdentityScript(): string {
     // grant the runner authorizes for a file edit. Line 8 is base64(salient) —
     // the raw resource value (file path / command) capture mode needs to run
     // `git check-ignore` on a file path; base64 keeps newlines/quotes out of the
-    // line-oriented bash parse.
-    `process.stdout.write(name+"\\n"+cat+"\\n"+b(cat+"\\n"+s)+"\\n"+b(name+"\\n")+"\\n"+ev+"\\n"+b(JSON.stringify(a))+"\\n"+(dig?b(cat+"\\n"+s+"\\n"+dig):"")+"\\n"+b(s));`,
+    // line-oriented bash parse. Line 9 is mcp_server_name — the server scope
+    // the enabled_tools manifest arm matches against mcpServerEnabledTools
+    // (a bare slug, never quoted/escaped, so it rides as a plain line).
+    `process.stdout.write(name+"\\n"+cat+"\\n"+b(cat+"\\n"+s)+"\\n"+b(name+"\\n")+"\\n"+ev+"\\n"+b(JSON.stringify(a))+"\\n"+(dig?b(cat+"\\n"+s+"\\n"+dig):"")+"\\n"+b(s)+"\\n"+srv);`,
   ].join("");
 }
 
@@ -279,7 +312,8 @@ function buildNodeIdentityScript(): string {
  *
  * From the pointer the script reads the current turn's approval-state file (the
  * single source of truth for the dynamic inputs: autoApproveAll, leasedCategories,
- * mcpToolPolicies, approvedGrantTokens), denial ledger, and runner PID. The
+ * mcpToolPolicies, mcpServerEnabledTools, approvedGrantTokens), denial ledger,
+ * and runner PID. The
  * static policy (which built-ins are gated, their categories, the salient arg
  * fields) is baked at generation time from approval-policy.ts.
  *
@@ -440,6 +474,9 @@ if [ -n "$IDENTITY" ]; then
   # Raw salient (base64) — the file path / command. Capture mode decodes it to
   # run git check-ignore on a file path.
   SALIENT=$(printf '%s\\n' "$IDENTITY" | sed -n 8p | base64 -d 2>/dev/null || true)
+  # MCP server slug (beforeMCPExecution payloads only; empty for built-ins) —
+  # the server scope for the enabled_tools manifest arm.
+  MCP_SERVER=$(printf '%s\\n' "$IDENTITY" | sed -n 9p)
 else
   # Fallback when the Node binary cannot run: grep/cut extraction. Best-effort
   # only — '"field":"[^"]*"' truncates at the first JSON-escaped quote, so the
@@ -449,6 +486,10 @@ else
   # would otherwise abort the script and emit no decision.
   TOOL_NAME=$(echo "$INPUT" | grep -o '"tool_name":"[^"]*"' | head -1 | cut -d'"' -f4 || true)
   HOOK_EVENT=$(echo "$INPUT" | grep -o '"hook_event_name":"[^"]*"' | head -1 | cut -d'"' -f4 || true)
+  # Server slugs are plain identifiers (no JSON-escaped quotes), so the grep
+  # fallback extracts mcp_server_name reliably — the manifest arm keeps its
+  # full precision even without the Node binary.
+  MCP_SERVER=$(echo "$INPUT" | grep -o '"mcp_server_name":"[^"]*"' | head -1 | cut -d'"' -f4 || true)
   SALIENT=""
   for field in ${salientFields}; do
     v=$(echo "$INPUT" | grep -o "\\"$field\\":\\"[^\\"]*\\"" | head -1 | cut -d'"' -f4 || true)
@@ -588,7 +629,30 @@ if [ "$CAPTURE_IGNORED" = "true" ] && [ "$CATEGORY" = "write" ] && [ -n "$SALIEN
   fi
 fi
 
-# --- 1. Auto-approve all ---
+# --- 1a. MCP capability manifest: enabled_tools (issue #350) ---
+# Runs BEFORE the auto-approve-all shortcut and every grant check because
+# enabled_tools is a capability manifest, not an approval gate: no bypass may
+# resurrect a disabled tool and no human may be offered approval on one.
+# mcpServerEnabledTools holds ONLY restricted servers (an absent slug means
+# unrestricted, so this arm is inert for the common case). Matching is
+# server-scoped via the payload's mcp_server_name — equal tool names on
+# different servers cannot cross-grant — and the quoted-name membership check
+# is exact, never a substring match. Kind "disabled": attributable,
+# non-pausing (the model adapts, same consumer semantics as "secret"), and
+# permanent for the run.
+if [ "$HOOK_EVENT" = "beforeMCPExecution" ] && [ -n "$MCP_SERVER" ] && [ -n "$TOOL_NAME" ]; then
+  ENABLED_MAP=$(echo "$STATE" | grep -o '"mcpServerEnabledTools":{[^}]*}' | head -1 || true)
+  if [ -n "$ENABLED_MAP" ]; then
+    SERVER_ENABLED=$(echo "$ENABLED_MAP" | grep -o "\\"$MCP_SERVER\\":\\[[^]]*\\]" | head -1 || true)
+    if [ -n "$SERVER_ENABLED" ] && ! echo "$SERVER_ENABLED" | grep -qF "\\"$TOOL_NAME\\""; then
+      record_denial "$MCP_TOKEN" "disabled"
+      echo '{"permission":"deny","agent_message":"${DISABLED_TOOL_AGENT_MESSAGE}","user_message":"Tool not enabled for this agent: '"$TOOL_NAME"'"}'
+      exit 0
+    fi
+  fi
+fi
+
+# --- 1b. Auto-approve all ---
 if echo "$STATE" | grep -q '"autoApproveAll":true'; then
   echo '{"permission":"allow"}'
   exit 0