multicorn-shield 0.7.0 → 0.9.0

package/dist/multicorn-proxy.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 import { existsSync } from 'fs';
-import { mkdir, writeFile, readFile, unlink } from 'fs/promises';
-import { join } from 'path';
+import { mkdir, writeFile, readFile, copyFile, unlink } from 'fs/promises';
+import { join, dirname } from 'path';
 import { homedir } from 'os';
+import { fileURLToPath } from 'url';
 import { createInterface } from 'readline';
 import { spawn } from 'child_process';
 import { createHash } from 'crypto';
@@ -366,17 +367,125 @@ async function isCursorConnected() {
     return false;
   }
 }
-var PLATFORM_LABELS = ["OpenClaw", "Claude Code", "Cursor", "Local MCP / Other"];
+function getWindsurfConfigPath() {
+  return join(homedir(), ".codeium", "windsurf", "mcp_config.json");
+}
+async function isWindsurfConnected() {
+  try {
+    const raw = await readFile(getWindsurfConfigPath(), "utf8");
+    const obj = JSON.parse(raw);
+    const mcpServers = obj["mcpServers"];
+    if (mcpServers === void 0 || typeof mcpServers !== "object") return false;
+    for (const entry of Object.values(mcpServers)) {
+      if (typeof entry !== "object" || entry === null) continue;
+      const rec = entry;
+      const url = rec["serverUrl"];
+      if (typeof url === "string" && url.includes("multicorn")) return true;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+function multicornShieldPackageRoot() {
+  return join(dirname(fileURLToPath(import.meta.url)), "..");
+}
+function getWindsurfHooksInstallDir() {
+  return join(homedir(), ".multicorn", "windsurf-hooks");
+}
+function getWindsurfCascadeHooksJsonPath() {
+  return join(homedir(), ".codeium", "windsurf", "hooks.json");
+}
+function isShieldWindsurfHookCommand(cmd) {
+  return cmd.includes("windsurf-hooks/pre-action.cjs") || cmd.includes("windsurf-hooks\\pre-action.cjs") || cmd.includes("windsurf-hooks/post-action.cjs") || cmd.includes("windsurf-hooks\\post-action.cjs");
+}
+function filterOutShieldWindsurfHooks(entries) {
+  if (!Array.isArray(entries)) return [];
+  const out = [];
+  for (const e of entries) {
+    if (typeof e !== "object" || e === null) continue;
+    const rec = e;
+    const cmd = rec["command"];
+    if (typeof cmd !== "string" || isShieldWindsurfHookCommand(cmd)) continue;
+    const powershell = rec["powershell"];
+    const show_output = rec["show_output"];
+    out.push({
+      command: cmd,
+      ...typeof powershell === "string" ? { powershell } : {},
+      ...show_output === true ? { show_output: true } : {}
+    });
+  }
+  return out;
+}
+async function installWindsurfNativeHooks() {
+  const root = multicornShieldPackageRoot();
+  const srcPre = join(root, "plugins", "windsurf", "hooks", "scripts", "pre-action.cjs");
+  const srcPost = join(root, "plugins", "windsurf", "hooks", "scripts", "post-action.cjs");
+  if (!existsSync(srcPre) || !existsSync(srcPost)) {
+    throw new Error(
+      `Could not find Shield Windsurf hook scripts at ${srcPre}. If you use npm, install the latest multicorn-shield package.`
+    );
+  }
+  const installDir = getWindsurfHooksInstallDir();
+  await mkdir(installDir, { recursive: true });
+  const destPre = join(installDir, "pre-action.cjs");
+  const destPost = join(installDir, "post-action.cjs");
+  await copyFile(srcPre, destPre);
+  await copyFile(srcPost, destPost);
+  const preCmd = `node ${JSON.stringify(destPre)}`;
+  const postCmd = `node ${JSON.stringify(destPost)}`;
+  const preEntry = { command: preCmd, powershell: preCmd, show_output: true };
+  const postEntry = { command: postCmd, powershell: postCmd };
+  const hooksPath = getWindsurfCascadeHooksJsonPath();
+  let base = { hooks: {} };
+  try {
+    const raw = await readFile(hooksPath, "utf8");
+    base = JSON.parse(raw);
+  } catch (err) {
+    if (!isErrnoException(err) || err.code !== "ENOENT") {
+      throw err;
+    }
+  }
+  const hooks = base["hooks"] ?? {};
+  const preKeys = [
+    "pre_read_code",
+    "pre_write_code",
+    "pre_run_command",
+    "pre_mcp_tool_use"
+  ];
+  const postKeys = [
+    "post_read_code",
+    "post_write_code",
+    "post_run_command",
+    "post_mcp_tool_use"
+  ];
+  const nextHooks = { ...hooks };
+  for (const k of preKeys) {
+    const merged = filterOutShieldWindsurfHooks(nextHooks[k]);
+    nextHooks[k] = [...merged, preEntry];
+  }
+  for (const k of postKeys) {
+    const merged = filterOutShieldWindsurfHooks(nextHooks[k]);
+    nextHooks[k] = [...merged, postEntry];
+  }
+  base["hooks"] = nextHooks;
+  const hooksDir = dirname(hooksPath);
+  await mkdir(hooksDir, { recursive: true });
+  await writeFile(hooksPath, JSON.stringify(base, null, 2) + "\n", { encoding: "utf8" });
+}
+var PLATFORM_LABELS = ["OpenClaw", "Claude Code", "Cursor", "Windsurf", "Local MCP / Other"];
 var PLATFORM_BY_SELECTION = {
   1: "openclaw",
   2: "claude-code",
   3: "cursor",
-  4: "other-mcp"
+  4: "windsurf",
+  5: "other-mcp"
 };
 var DEFAULT_AGENT_NAMES = {
   openclaw: "my-openclaw-agent",
   "claude-code": "my-claude-code-agent",
-  cursor: "my-cursor-agent"
+  cursor: "my-cursor-agent",
+  windsurf: "my-windsurf-agent"
 };
 async function promptPlatformSelection(ask) {
   process.stderr.write(
@@ -385,7 +494,8 @@ async function promptPlatformSelection(ask) {
   const connectedFlags = [
     await isOpenClawConnected(),
     isClaudeCodeConnected(),
-    await isCursorConnected()
+    await isCursorConnected(),
+    await isWindsurfConnected()
   ];
   for (let i = 0; i < PLATFORM_LABELS.length; i++) {
     const marker = i < connectedFlags.length && connectedFlags[i] ? " " + style.dim("\u25CF detected locally") : "";
@@ -395,18 +505,35 @@ async function promptPlatformSelection(ask) {
     );
   }
   process.stderr.write(
-    style.dim("     Pick 4 if you want to wrap a local MCP server with multicorn-proxy --wrap.") + "\n"
+    style.dim("     Pick 5 if you want to wrap a local MCP server with multicorn-proxy --wrap.") + "\n"
   );
   let selection = 0;
   while (selection === 0) {
-    const input = await ask("Select (1-4): ");
+    const input = await ask("Select (1-5): ");
     const num = parseInt(input.trim(), 10);
-    if (num >= 1 && num <= 4) {
+    if (num >= 1 && num <= 5) {
       selection = num;
     }
   }
   return selection;
 }
+async function promptWindsurfIntegrationMode(ask) {
+  process.stderr.write("\n" + style.bold("Windsurf integration") + "\n");
+  process.stderr.write(
+    "  " + style.violet("1") + ". Native plugin (recommended) \u2014 Cascade Hooks see every file, terminal, and MCP action\n"
+  );
+  process.stderr.write(
+    "  " + style.violet("2") + ". Hosted proxy \u2014 govern MCP traffic only (paste proxy URL into mcp_config)\n"
+  );
+  let choice = 0;
+  while (choice === 0) {
+    const input = await ask("Choose integration (1-2): ");
+    const num = parseInt(input.trim(), 10);
+    if (num === 1) choice = 1;
+    if (num === 2) choice = 2;
+  }
+  return choice === 1 ? "native" : "hosted";
+}
 async function promptAgentName(ask, platform) {
   const defaultAgentName = DEFAULT_AGENT_NAMES[platform] ?? "my-agent";
   let agentName = "";
@@ -505,12 +632,14 @@ async function createProxyConfig(baseUrl, apiKey, agentName, targetUrl, serverNa
   return typeof data?.["proxy_url"] === "string" ? data["proxy_url"] : "";
 }
 function printPlatformSnippet(platform, routingToken, shortName, apiKey) {
-  const authHeader = platform === "cursor" ? `Bearer ${apiKey}` : "Bearer YOUR_SHIELD_API_KEY";
+  const usesInlineKey = platform === "cursor" || platform === "windsurf";
+  const authHeader = usesInlineKey ? `Bearer ${apiKey}` : "Bearer YOUR_SHIELD_API_KEY";
+  const urlKey = platform === "windsurf" ? "serverUrl" : "url";
   const mcpSnippet = JSON.stringify(
     {
       mcpServers: {
         [shortName]: {
-          url: routingToken,
+          [urlKey]: routingToken,
           headers: {
             Authorization: authHeader
           }
@@ -524,11 +653,15 @@ function printPlatformSnippet(platform, routingToken, shortName, apiKey) {
     process.stderr.write("\n" + style.dim("Add this to your OpenClaw agent config:") + "\n\n");
   } else if (platform === "claude-code") {
     process.stderr.write("\n" + style.dim("Add this to your Claude Code MCP config:") + "\n\n");
+  } else if (platform === "windsurf") {
+    process.stderr.write(
+      "\n" + style.dim("Add this to ~/.codeium/windsurf/mcp_config.json:") + "\n\n"
+    );
   } else {
     process.stderr.write("\n" + style.dim("Add this to ~/.cursor/mcp.json:") + "\n\n");
   }
   process.stderr.write(style.cyan(mcpSnippet) + "\n\n");
-  if (platform !== "cursor") {
+  if (!usesInlineKey) {
     process.stderr.write(
       style.dim(
         "Replace YOUR_SHIELD_API_KEY with your API key. Find it in Settings > API keys at https://app.multicorn.ai/settings#api-keys"
@@ -547,6 +680,14 @@ function printPlatformSnippet(platform, routingToken, shortName, apiKey) {
       ) + "\n"
     );
   }
+  if (platform === "windsurf") {
+    process.stderr.write(style.dim("Then restart Windsurf (Cmd/Ctrl+Q, then reopen).") + "\n");
+    process.stderr.write(
+      style.dim(
+        "Open the Cascade panel and verify the server appears with a green status indicator."
+      ) + "\n"
+    );
+  }
 }
 var DEFAULT_SHIELD_API_BASE_URL = "https://api.multicorn.ai";
 async function runInit(explicitBaseUrl) {
@@ -636,7 +777,7 @@ async function runInit(explicitBaseUrl) {
     const selection = await promptPlatformSelection(ask);
     const selectedPlatform = PLATFORM_BY_SELECTION[selection] ?? "cursor";
     const selectedLabel = PLATFORM_LABELS[selection - 1] ?? "Cursor";
-    if (selection === 4) {
+    if (selection === 5) {
       const raw = existing !== null ? { ...existing } : {};
       raw["apiKey"] = apiKey;
       raw["baseUrl"] = resolvedBaseUrl;
@@ -786,6 +927,80 @@ An agent for ${selectedLabel} already exists: ${style.cyan(existingForPlatform.n
         agentName
       });
       setupSucceeded = true;
+    } else if (selection === 4) {
+      const windsurfMode = await promptWindsurfIntegrationMode(ask);
+      if (windsurfMode === "native") {
+        try {
+          await installWindsurfNativeHooks();
+          process.stderr.write("\n" + style.bold("Shield Windsurf hooks installed") + "\n");
+          process.stderr.write(
+            style.dim("Scripts: ") + style.cyan(getWindsurfHooksInstallDir()) + "\n"
+          );
+          process.stderr.write(
+            style.dim("Hooks config: ") + style.cyan(getWindsurfCascadeHooksJsonPath()) + "\n"
+          );
+          process.stderr.write(
+            "\n" + style.dim(
+              "The Shield hook runs with your user permissions. It intercepts Cascade actions to check permissions and log activity. Review the scripts under "
+            ) + style.cyan("~/.multicorn/windsurf-hooks") + style.dim(" if that is a concern.") + "\n\n"
+          );
+          process.stderr.write(
+            style.dim("Restart Windsurf (quit fully, then reopen) so hooks load.") + "\n"
+          );
+          configuredAgents.push({
+            selection,
+            platform: selectedPlatform,
+            platformLabel: selectedLabel,
+            agentName,
+            windsurfIntegration: "native"
+          });
+          setupSucceeded = true;
+        } catch (error) {
+          const detail = error instanceof Error ? error.message : String(error);
+          process.stderr.write(style.red("\u2717 ") + detail + "\n");
+        }
+      } else {
+        const { targetUrl, shortName } = await promptProxyConfig(ask, agentName);
+        let proxyUrl = "";
+        let created = false;
+        while (!created) {
+          const spinner = withSpinner("Creating proxy config...");
+          try {
+            proxyUrl = await createProxyConfig(
+              resolvedBaseUrl,
+              apiKey,
+              agentName,
+              targetUrl,
+              shortName,
+              selectedPlatform
+            );
+            spinner.stop(true, "Proxy config created!");
+            created = true;
+          } catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            spinner.stop(false, detail);
+            const retry = await ask("Try again? (Y/n) ");
+            if (retry.trim().toLowerCase() === "n") {
+              break;
+            }
+          }
+        }
+        if (created && proxyUrl.length > 0) {
+          process.stderr.write("\n" + style.bold("Your Shield proxy URL:") + "\n");
+          process.stderr.write("  " + style.cyan(proxyUrl) + "\n");
+          printPlatformSnippet(selectedPlatform, proxyUrl, shortName, apiKey);
+          configuredAgents.push({
+            selection,
+            platform: selectedPlatform,
+            platformLabel: selectedLabel,
+            agentName,
+            shortName,
+            proxyUrl,
+            windsurfIntegration: "hosted"
+          });
+          setupSucceeded = true;
+        }
+      }
     } else {
       const { targetUrl, shortName } = await promptProxyConfig(ask, agentName);
       let proxyUrl = "";
@@ -885,7 +1100,23 @@ An agent for ${selectedLabel} already exists: ${style.cyan(existingForPlatform.n
     }
     if (configuredPlatforms.has("cursor")) {
       blocks.push(
-        "\n" + style.bold("To complete your Cursor setup:") + "\n  \u2192 Restart Cursor to pick up MCP config changes\n"
+        "\n" + style.bold("To complete your Cursor setup:") + "\n  1. If you don't have Cursor yet, download it from " + style.cyan("https://cursor.com/downloads") + "\n  2. Open " + style.cyan("~/.cursor/mcp.json") + " and paste the config snippet shown above\n  3. Restart Cursor (or launch it for the first time) to load the new MCP server\n"
+      );
+    }
+    const windsurfNativeConfigured = configuredAgents.some(
+      (a) => a.platform === "windsurf" && a.windsurfIntegration === "native"
+    );
+    const windsurfHostedConfigured = configuredAgents.some(
+      (a) => a.platform === "windsurf" && a.windsurfIntegration === "hosted"
+    );
+    if (windsurfNativeConfigured) {
+      blocks.push(
+        "\n" + style.bold("To complete native Windsurf (Shield) setup:") + "\n  1. Hook scripts: " + style.cyan(getWindsurfHooksInstallDir()) + "\n  2. Hooks config: " + style.cyan(getWindsurfCascadeHooksJsonPath()) + "\n  3. Restart Windsurf (quit fully, then reopen)\n"
+      );
+    }
+    if (windsurfHostedConfigured) {
+      blocks.push(
+        "\n" + style.bold("To complete your Windsurf hosted-proxy setup:") + "\n  1. If you don't have Windsurf yet, download it from " + style.cyan("https://windsurf.com/download") + "\n  2. Open " + style.cyan("~/.codeium/windsurf/mcp_config.json") + " and paste the config snippet shown above\n  3. Restart Windsurf (or launch it for the first time) to load the new MCP server\n"
       );
     }
     if (blocks.length > 0) {

package/dist/multicorn-shield.js

@@ -3,6 +3,7 @@ import { readFile, mkdir, writeFile } from 'fs/promises';
 import { join, dirname } from 'path';
 import 'fs';
 import { homedir } from 'os';
+import 'url';
 import 'readline';
 
 var CONFIG_DIR = join(homedir(), ".multicorn");

package/dist/shield-extension.js

@@ -7,6 +7,7 @@ import process3 from 'process';
 import 'stream';
 import { spawn } from 'child_process';
 import { createHash } from 'crypto';
+import 'url';
 import 'readline';
 
 // Multicorn Shield Claude Desktop Extension - https://multicorn.ai
@@ -22358,7 +22359,7 @@ async function writeExtensionBackup(claudeDesktopConfigPath, mcpServers) {
 
 // package.json
 var package_default = {
-  version: "0.7.0"};
+  version: "0.9.0"};
 
 // src/package-meta.ts
 var PACKAGE_VERSION = package_default.version;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "multicorn-shield",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "The control layer for AI agents: permissions, consent, spending limits, and audit logging.",
   "license": "MIT",
   "type": "module",
@@ -35,6 +35,7 @@
   },
   "files": [
     "dist",
+    "plugins/windsurf",
     "LICENSE",
     "README.md"
   ],

package/plugins/windsurf/README.md

@@ -0,0 +1,54 @@
+# Multicorn Shield for Windsurf (Cascade Hooks)
+
+Native Shield integration for [Windsurf](https://windsurf.com) using [Cascade Hooks](https://docs.windsurf.com/windsurf/cascade/hooks). Every governed pre-hook asks the Shield API whether the action may run; post-hooks log completed actions to your audit trail.
+
+## Install
+
+1. Install the CLI package (or use `npx`).
+
+```bash
+  npm install -g multicorn-shield
+```
+
+2. Run the wizard and pick **Windsurf**, then **Native plugin (recommended)**.
+
+   ```bash
+   npx multicorn-proxy init
+   ```
+
+3. Restart Windsurf (quit fully, then reopen) so hooks load.
+
+The wizard copies `pre-action.cjs` and `post-action.cjs` to `~/.multicorn/windsurf-hooks/` and merges entries into `~/.codeium/windsurf/hooks.json`.
+
+## How it works
+
+- **Config** is read from `~/.multicorn/config.json` (same file as other Shield integrations). The agent row must use `platform: "windsurf"`.
+- **Permission check**: `POST /api/v1/actions` with `status: "pending"` and `X-Multicorn-Key`. Exit code `0` allows the action; `2` blocks and prints guidance on stderr (see Windsurf hook docs). (Exit code `2` tells Windsurf to cancel the action and show the message to the user.)
+- **Audit log**: post-hooks send `POST /api/v1/actions` with `status: "approved"` after the action completes.
+
+### Event to Shield mapping
+
+| Windsurf `agent_action_name`  | Shield `service`      | Shield `actionType` |
+| ----------------------------- | --------------------- | ------------------- |
+| `pre_read_code` / `post_*`    | `filesystem`          | `read`              |
+| `pre_write_code` / `post_*`   | `filesystem`          | `write`             |
+| `pre_run_command` / `post_*`  | `terminal`            | `execute`           |
+| `pre_mcp_tool_use` / `post_*` | `mcp:<server>.<tool>` | `execute`           |
+
+Stdin includes `trajectory_id`, `execution_id`, and `tool_info`; those are forwarded in `metadata` for auditing.
+
+## Trust model
+
+Hooks run shell commands with **your user permissions**. They can read the JSON on stdin and call the network. Review the scripts under `~/.multicorn/windsurf-hooks/` before you rely on them in sensitive environments.
+
+## Hosted proxy alternative
+
+If you only need MCP traffic governed, use **Hosted proxy** in `npx multicorn-proxy init` and paste the proxy URL into `~/.codeium/windsurf/mcp_config.json` instead.
+
+## Windows
+
+Hooks include a `powershell` field for Windsurf on Windows. Full Windows support may be incomplete compared to macOS and Linux; if something breaks, open an issue with your Windsurf and Node versions.
+
+## References
+
+- [Cascade Hooks](https://docs.windsurf.com/windsurf/cascade/hooks)

package/plugins/windsurf/hooks/scripts/post-action.cjs

@@ -0,0 +1,245 @@
+/**
+ * Windsurf Cascade post-hook: logs completed actions to the Shield audit trail.
+ * Routes by agent_action_name. Never blocks; always exit 0.
+ */
+
+"use strict";
+
+const fs = require("node:fs");
+const http = require("node:http");
+const https = require("node:https");
+const os = require("node:os");
+const path = require("node:path");
+
+const AUTH_HEADER = "X-Multicorn-Key";
+const LOG_PREFIX = "[multicorn-shield] Windsurf post-hook:";
+const HTTP_REQUEST_TIMEOUT_MS =
+  process.env.MULTICORN_SHIELD_WINDSURF_PRE_HOOK_TEST_FAST_POLL === "1" ? 100 : 10000;
+
+/** @type {Readonly<Record<string, { service: string; actionType: string }>>} */
+const POST_EVENT_MAP = {
+  post_read_code: { service: "filesystem", actionType: "read" },
+  post_write_code: { service: "filesystem", actionType: "write" },
+  post_run_command: { service: "terminal", actionType: "execute" },
+};
+
+/**
+ * @returns {Promise<string>}
+ */
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (c) => chunks.push(c));
+    process.stdin.on("end", () => resolve(chunks.join("")));
+    process.stdin.on("error", reject);
+  });
+}
+
+// Duplicated in pre-action.cjs. CJS hooks cannot import shared TypeScript modules.
+/**
+ * @param {Record<string, unknown>} obj
+ * @returns {string}
+ */
+function resolveWindsurfAgentName(obj) {
+  const agents = obj.agents;
+  if (Array.isArray(agents)) {
+    for (const entry of agents) {
+      if (
+        entry &&
+        typeof entry === "object" &&
+        /** @type {{ platform?: string; name?: string }} */ (entry).platform === "windsurf" &&
+        typeof (/** @type {{ platform?: string; name?: string }} */ (entry).name) === "string"
+      ) {
+        return /** @type {{ name: string }} */ (entry).name;
+      }
+    }
+  }
+  return typeof obj.agentName === "string" ? obj.agentName : "";
+}
+
+/**
+ * @returns {{ apiKey: string; baseUrl: string; agentName: string } | null}
+ */
+function loadConfig() {
+  try {
+    const configPath = path.join(os.homedir(), ".multicorn", "config.json");
+    const raw = fs.readFileSync(configPath, "utf8");
+    const obj = JSON.parse(raw);
+    const apiKey = typeof obj.apiKey === "string" ? obj.apiKey : "";
+    const baseUrl =
+      typeof obj.baseUrl === "string" && obj.baseUrl.length > 0
+        ? obj.baseUrl.replace(/\/+$/, "")
+        : "https://api.multicorn.ai";
+    const agentName = resolveWindsurfAgentName(obj);
+    return { apiKey, baseUrl, agentName };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {unknown} toolInfo
+ * @returns {{ service: string; actionType: string }}
+ */
+function mapMcpPost(toolInfo) {
+  if (toolInfo === null || typeof toolInfo !== "object") {
+    return { service: "mcp", actionType: "execute" };
+  }
+  const t = /** @type {Record<string, unknown>} */ (toolInfo);
+  const server = String(t.mcp_server_name ?? "unknown").trim() || "unknown";
+  const tool = String(t.mcp_tool_name ?? "unknown").trim() || "unknown";
+  const safeServer = server.replace(/[^a-zA-Z0-9._-]+/g, "_");
+  const safeTool = tool.replace(/[^a-zA-Z0-9._-]+/g, "_");
+  return { service: `mcp:${safeServer}.${safeTool}`, actionType: "execute" };
+}
+
+/**
+ * @param {string} agentActionName
+ * @param {unknown} toolInfo
+ * @returns {{ service: string; actionType: string } | null}
+ */
+function mapPostEvent(agentActionName, toolInfo) {
+  const name = String(agentActionName || "").trim();
+  if (name === "post_mcp_tool_use") {
+    return mapMcpPost(toolInfo);
+  }
+  const mapped = POST_EVENT_MAP[name];
+  if (mapped !== undefined) {
+    return mapped;
+  }
+  return null;
+}
+
+/**
+ * @param {string} baseUrl
+ * @param {string} apiKey
+ * @param {Record<string, unknown>} bodyObj
+ * @returns {Promise<void>}
+ */
+function postJson(baseUrl, apiKey, bodyObj) {
+  return new Promise((resolve, reject) => {
+    let u;
+    try {
+      const root = String(baseUrl).replace(/\/+$/, "");
+      u = new URL(`${root}/api/v1/actions`);
+    } catch (e) {
+      reject(e);
+      return;
+    }
+    const payload = JSON.stringify(bodyObj);
+    const isHttps = u.protocol === "https:";
+    const lib = isHttps ? https : http;
+    const port = u.port || (isHttps ? 443 : 80);
+    const options = {
+      hostname: u.hostname,
+      port,
+      path: u.pathname + u.search,
+      method: "POST",
+      headers: {
+        Connection: "close",
+        "Content-Type": "application/json",
+        "Content-Length": Buffer.byteLength(payload, "utf8"),
+        [AUTH_HEADER]: apiKey,
+      },
+    };
+    const req = lib.request(options, (res) => {
+      res.resume();
+      res.on("end", () => {
+        const code = res.statusCode ?? 0;
+        if (code >= 200 && code < 300) {
+          resolve();
+        } else {
+          reject(new Error(`HTTP ${String(code)}`));
+        }
+      });
+    });
+    req.setTimeout(HTTP_REQUEST_TIMEOUT_MS, () => {
+      req.destroy(new Error("request timeout"));
+    });
+    req.on("error", reject);
+    req.write(payload);
+    req.end();
+  });
+}
+
+async function main() {
+  let raw;
+  try {
+    raw = await readStdin();
+  } catch {
+    process.exit(0);
+  }
+
+  const config = loadConfig();
+  if (config === null || config.apiKey.length === 0 || config.agentName.length === 0) {
+    process.exit(0);
+  }
+
+  /** @type {Record<string, unknown>} */
+  let hookPayload;
+  try {
+    hookPayload = JSON.parse(raw.length > 0 ? raw : "{}");
+  } catch {
+    process.exit(0);
+  }
+
+  const agentActionName =
+    typeof hookPayload.agent_action_name === "string" ? hookPayload.agent_action_name : "";
+  const toolInfo = hookPayload.tool_info;
+
+  const mapped = mapPostEvent(agentActionName, toolInfo);
+  if (mapped === null) {
+    process.exit(0);
+  }
+  const { service, actionType } = mapped;
+
+  let toolInfoSerialized;
+  try {
+    toolInfoSerialized =
+      typeof toolInfo === "string"
+        ? toolInfo
+        : JSON.stringify(toolInfo === undefined ? null : toolInfo);
+  } catch {
+    process.exit(0);
+  }
+
+  /** @type {Record<string, unknown>} */
+  const metadata = {
+    agent_action_name: agentActionName,
+    trajectory_id: typeof hookPayload.trajectory_id === "string" ? hookPayload.trajectory_id : "",
+    execution_id: typeof hookPayload.execution_id === "string" ? hookPayload.execution_id : "",
+    model_name: typeof hookPayload.model_name === "string" ? hookPayload.model_name : "",
+    tool_info: toolInfoSerialized,
+    source: "windsurf",
+  };
+
+  /** @type {Record<string, unknown>} */
+  const payload = {
+    agent: config.agentName,
+    service,
+    actionType,
+    status: "approved",
+    metadata,
+    platform: "windsurf",
+  };
+
+  try {
+    await postJson(config.baseUrl, config.apiKey, payload);
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    process.stderr.write(
+      `${LOG_PREFIX} Warning: failed to log action to Shield audit trail. Check your network connection and that your API key in ~/.multicorn/config.json is valid.\n  Detail: ${msg}\n`,
+    );
+  }
+
+  process.exit(0);
+}
+
+main().catch((e) => {
+  const msg = e instanceof Error ? e.message : String(e);
+  process.stderr.write(
+    `${LOG_PREFIX} Warning: failed to log action to Shield audit trail. Check your network connection and that your API key in ~/.multicorn/config.json is valid.\n  Detail: ${msg}\n`,
+  );
+  process.exit(0);
+});

package/plugins/windsurf/hooks/scripts/pre-action.cjs

@@ -0,0 +1,646 @@
+/**
+ * Windsurf Cascade pre-hook: permission check before read, write, terminal, or MCP tool use.
+ * Routes by stdin JSON field agent_action_name (see Windsurf Cascade Hooks docs).
+ * Fail-closed on API errors once config is loaded. Fail-open if Shield is not configured.
+ */
+
+"use strict";
+
+const { execFileSync, execSync } = require("node:child_process");
+const fs = require("node:fs");
+const http = require("node:http");
+const https = require("node:https");
+const os = require("node:os");
+const path = require("node:path");
+
+const AUTH_HEADER = "X-Multicorn-Key";
+const LOG_PREFIX = "[multicorn-shield] Windsurf pre-hook:";
+const HOOK_TEST_FAST_POLL = process.env.MULTICORN_SHIELD_WINDSURF_PRE_HOOK_TEST_FAST_POLL === "1";
+const POLL_INTERVAL_MS = HOOK_TEST_FAST_POLL ? 1 : 3000;
+const MAX_APPROVAL_POLLS = HOOK_TEST_FAST_POLL ? 3 : 100;
+const HTTP_REQUEST_TIMEOUT_MS = HOOK_TEST_FAST_POLL ? 100 : 10000;
+
+/** @type {Readonly<Record<string, { service: string; actionType: string }>>} */
+const PRE_EVENT_MAP = {
+  pre_read_code: { service: "filesystem", actionType: "read" },
+  pre_write_code: { service: "filesystem", actionType: "write" },
+  pre_run_command: { service: "terminal", actionType: "execute" },
+};
+
+/**
+ * @returns {Promise<string>}
+ */
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (c) => chunks.push(c));
+    process.stdin.on("end", () => resolve(chunks.join("")));
+    process.stdin.on("error", reject);
+  });
+}
+
+// Duplicated in post-action.cjs. CJS hooks cannot import shared TypeScript modules.
+/**
+ * @param {Record<string, unknown>} obj
+ * @returns {string}
+ */
+function resolveWindsurfAgentName(obj) {
+  const agents = obj.agents;
+  if (Array.isArray(agents)) {
+    for (const entry of agents) {
+      if (
+        entry &&
+        typeof entry === "object" &&
+        /** @type {{ platform?: string; name?: string }} */ (entry).platform === "windsurf" &&
+        typeof (/** @type {{ platform?: string; name?: string }} */ (entry).name) === "string"
+      ) {
+        return /** @type {{ name: string }} */ (entry).name;
+      }
+    }
+  }
+  return typeof obj.agentName === "string" ? obj.agentName : "";
+}
+
+/**
+ * @returns {{ apiKey: string; baseUrl: string; agentName: string } | null}
+ */
+function loadConfig() {
+  try {
+    const configPath = path.join(os.homedir(), ".multicorn", "config.json");
+    const raw = fs.readFileSync(configPath, "utf8");
+    const obj = JSON.parse(raw);
+    const apiKey = typeof obj.apiKey === "string" ? obj.apiKey : "";
+    const baseUrl =
+      typeof obj.baseUrl === "string" && obj.baseUrl.length > 0
+        ? obj.baseUrl.replace(/\/+$/, "")
+        : "https://api.multicorn.ai";
+    const agentName = resolveWindsurfAgentName(obj);
+    return { apiKey, baseUrl, agentName };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string} apiBaseUrl
+ * @returns {string}
+ */
+function dashboardOrigin(apiBaseUrl) {
+  try {
+    const raw = String(apiBaseUrl).replace(/\/+$/, "");
+    const lower = raw.toLowerCase();
+    if (lower.includes("localhost:8080") || lower.includes("127.0.0.1:8080")) {
+      return "http://localhost:5173";
+    }
+    const u = new URL(raw);
+    if (u.hostname.startsWith("api.")) {
+      u.hostname = "app." + u.hostname.slice(4);
+    }
+    return u.origin;
+  } catch {
+    return "https://app.multicorn.ai";
+  }
+}
+
+/**
+ * @param {string} apiBaseUrl
+ * @returns {string}
+ */
+function dashboardHintUrl(apiBaseUrl) {
+  return `${dashboardOrigin(apiBaseUrl)}/approvals`;
+}
+
+/**
+ * @param {string} apiBaseUrl
+ * @param {string} agentName
+ * @param {string} service
+ * @param {string} actionType
+ * @returns {string}
+ */
+function consentUrl(apiBaseUrl, agentName, service, actionType) {
+  const origin = dashboardOrigin(apiBaseUrl);
+  const params = new URLSearchParams();
+  params.set("agent", agentName);
+  params.set("scopes", `${service}:${actionType}`);
+  params.set("platform", "windsurf");
+  return `${origin}/consent?${params.toString()}`;
+}
+
+/**
+ * @param {unknown} toolInfo
+ * @returns {{ service: string; actionType: string }}
+ */
+function mapMcpPre(toolInfo) {
+  if (toolInfo === null || typeof toolInfo !== "object") {
+    return { service: "mcp", actionType: "execute" };
+  }
+  const t = /** @type {Record<string, unknown>} */ (toolInfo);
+  const server = String(t.mcp_server_name ?? "unknown").trim() || "unknown";
+  const tool = String(t.mcp_tool_name ?? "unknown").trim() || "unknown";
+  const safeServer = server.replace(/[^a-zA-Z0-9._-]+/g, "_");
+  const safeTool = tool.replace(/[^a-zA-Z0-9._-]+/g, "_");
+  return { service: `mcp:${safeServer}.${safeTool}`, actionType: "execute" };
+}
+
+/**
+ * @param {string} agentActionName
+ * @param {unknown} toolInfo
+ * @returns {{ service: string; actionType: string } | null}
+ */
+function mapPreEvent(agentActionName, toolInfo) {
+  const name = String(agentActionName || "").trim();
+  if (name === "pre_mcp_tool_use") {
+    return mapMcpPre(toolInfo);
+  }
+  const mapped = PRE_EVENT_MAP[name];
+  if (mapped !== undefined) {
+    return mapped;
+  }
+  return null;
+}
+
+/**
+ * @param {string} baseUrl
+ * @param {string} apiKey
+ * @param {string} reqPath
+ * @returns {Promise<{ statusCode: number; bodyText: string }>}
+ */
+function getJson(baseUrl, apiKey, reqPath) {
+  return new Promise((resolve, reject) => {
+    let u;
+    try {
+      const root = String(baseUrl).replace(/\/+$/, "");
+      const p = reqPath.startsWith("/") ? reqPath : `/${reqPath}`;
+      u = new URL(`${root}${p}`);
+    } catch (e) {
+      reject(e);
+      return;
+    }
+    const isHttps = u.protocol === "https:";
+    const lib = isHttps ? https : http;
+    const port = u.port || (isHttps ? 443 : 80);
+    const options = {
+      hostname: u.hostname,
+      port,
+      path: u.pathname + u.search,
+      method: "GET",
+      headers: {
+        Connection: "close",
+        [AUTH_HEADER]: apiKey,
+      },
+    };
+    const req = lib.request(options, (res) => {
+      const chunks = [];
+      res.on("data", (c) => chunks.push(c));
+      res.on("end", () => {
+        resolve({
+          statusCode: res.statusCode ?? 0,
+          bodyText: Buffer.concat(chunks).toString("utf8"),
+        });
+      });
+    });
+    req.setTimeout(HTTP_REQUEST_TIMEOUT_MS, () => {
+      req.destroy(new Error("request timeout"));
+    });
+    req.on("error", reject);
+    req.end();
+  });
+}
+
+/**
+ * @param {string} baseUrl
+ * @param {string} apiKey
+ * @param {Record<string, unknown>} bodyObj
+ * @returns {Promise<{ statusCode: number; bodyText: string }>}
+ */
+function postJson(baseUrl, apiKey, bodyObj) {
+  return new Promise((resolve, reject) => {
+    let u;
+    try {
+      const root = String(baseUrl).replace(/\/+$/, "");
+      u = new URL(`${root}/api/v1/actions`);
+    } catch (e) {
+      reject(e);
+      return;
+    }
+    const payload = JSON.stringify(bodyObj);
+    const isHttps = u.protocol === "https:";
+    const lib = isHttps ? https : http;
+    const port = u.port || (isHttps ? 443 : 80);
+    const options = {
+      hostname: u.hostname,
+      port,
+      path: u.pathname + u.search,
+      method: "POST",
+      headers: {
+        Connection: "close",
+        "Content-Type": "application/json",
+        "Content-Length": Buffer.byteLength(payload, "utf8"),
+        [AUTH_HEADER]: apiKey,
+      },
+    };
+    const req = lib.request(options, (res) => {
+      const chunks = [];
+      res.on("data", (c) => chunks.push(c));
+      res.on("end", () => {
+        resolve({
+          statusCode: res.statusCode ?? 0,
+          bodyText: Buffer.concat(chunks).toString("utf8"),
+        });
+      });
+    });
+    req.setTimeout(HTTP_REQUEST_TIMEOUT_MS, () => {
+      req.destroy(new Error("request timeout"));
+    });
+    req.on("error", reject);
+    req.write(payload);
+    req.end();
+  });
+}
+
+/**
+ * @param {string} text
+ * @returns {unknown}
+ */
+function safeJsonParse(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {unknown} body
+ * @returns {unknown}
+ */
+function unwrapData(body) {
+  if (typeof body !== "object" || body === null) return null;
+  const o = /** @type {Record<string, unknown>} */ (body);
+  return o.success === true ? o.data : null;
+}
+
+/**
+ * @param {unknown} data
+ * @param {string} service
+ * @param {string} actionType
+ * @param {string} approvalsUrl
+ * @returns {string}
+ */
+function blockedMessage(data, service, actionType, approvalsUrl) {
+  if (data !== null && typeof data === "object") {
+    const d = /** @type {Record<string, unknown>} */ (data);
+    const meta = d.metadata;
+    if (typeof meta === "string" && meta.length > 0) {
+      try {
+        const parsed = JSON.parse(meta);
+        if (parsed !== null && typeof parsed === "object" && "block_reason" in parsed) {
+          const br = /** @type {Record<string, unknown>} */ (parsed).block_reason;
+          if (typeof br === "string" && br.length > 0) {
+            return (
+              `${LOG_PREFIX} Action blocked: ${br}\n` +
+              `  Grant access in the Shield dashboard and retry.\n` +
+              `  Detail: ${approvalsUrl}\n`
+            );
+          }
+        }
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+  return (
+    `${LOG_PREFIX} Action blocked: Multicorn Shield blocked this action. Required permission: ${service} (${actionType}).\n` +
+    `  Grant access in the Shield dashboard and retry.\n` +
+    `  Detail: ${approvalsUrl}\n`
+  );
+}
+
+/**
+ * @param {string} agentName
+ * @returns {string}
+ */
+function consentMarkerPath(agentName) {
+  const safe = agentName.replace(/[^a-zA-Z0-9_-]/g, "_");
+  return path.join(os.homedir(), ".multicorn", `.consent-windsurf-${safe}`);
+}
+
+/**
+ * @param {string} agentName
+ * @returns {boolean}
+ */
+function hasConsentMarker(agentName) {
+  try {
+    fs.accessSync(consentMarkerPath(agentName));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {string} agentName
+ */
+function writeConsentMarker(agentName) {
+  try {
+    const marker = consentMarkerPath(agentName);
+    fs.mkdirSync(path.dirname(marker), { recursive: true });
+    fs.writeFileSync(marker, String(Date.now()), "utf8");
+  } catch {
+    /* ignore */
+  }
+}
+
+/**
+ * @param {string} url
+ */
+function openBrowser(url) {
+  try {
+    if (process.platform === "win32") {
+      execSync(`start "" ${JSON.stringify(url)}`, {
+        shell: true,
+        stdio: "ignore",
+        windowsHide: true,
+      });
+    } else if (process.platform === "darwin") {
+      execFileSync("open", [url], { stdio: "ignore" });
+    } else {
+      execFileSync("xdg-open", [url], { stdio: "ignore" });
+    }
+  } catch {
+    /* ignore */
+  }
+}
+
+/**
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * @param {{ apiKey: string; baseUrl: string; agentName: string }} config
+ * @param {string} approvalId
+ * @param {string} service
+ * @param {string} actionType
+ * @param {string} approvalsUrl
+ * @returns {Promise<void>}
+ */
+async function handlePendingWithConsentAndPoll(
+  config,
+  approvalId,
+  service,
+  actionType,
+  approvalsUrl,
+) {
+  if (hasConsentMarker(config.agentName)) {
+    process.stderr.write(
+      `${LOG_PREFIX} Action blocked: this action requires approval before it can run.\n` +
+        `  Grant access in the Shield dashboard and retry.\n` +
+        `  Detail: ${approvalsUrl}\n`,
+    );
+    process.exit(2);
+  }
+
+  const url = consentUrl(config.baseUrl, config.agentName, service, actionType);
+  writeConsentMarker(config.agentName);
+  openBrowser(url);
+  process.stderr.write("Opening Shield consent screen... Waiting for approval (up to 5 min).\n");
+
+  for (let i = 0; i < MAX_APPROVAL_POLLS; i++) {
+    if (i > 0) {
+      await sleep(POLL_INTERVAL_MS);
+    }
+    let statusCode;
+    let bodyText;
+    try {
+      const res = await getJson(config.baseUrl, config.apiKey, `/api/v1/approvals/${approvalId}`);
+      statusCode = res.statusCode;
+      bodyText = res.bodyText;
+    } catch {
+      continue;
+    }
+    if (statusCode < 200 || statusCode >= 300) {
+      continue;
+    }
+    const parsed = safeJsonParse(bodyText);
+    const data = unwrapData(parsed);
+    if (data === null || typeof data !== "object") {
+      continue;
+    }
+    const d = /** @type {Record<string, unknown>} */ (data);
+    const st = String(d.status ?? "").toLowerCase();
+    if (st === "approved") {
+      process.exit(0);
+    }
+    if (st === "blocked" || st === "denied" || st === "rejected") {
+      const reason =
+        typeof d.reason === "string" && d.reason.length > 0 ? d.reason : "Approval denied.";
+      process.stderr.write(
+        `${LOG_PREFIX} Action blocked: Shield denied this approval request.\n` +
+          `  Request access again from the Shield dashboard and retry.\n` +
+          `  Detail: ${reason}\n`,
+      );
+      process.exit(2);
+    }
+    if (st === "expired") {
+      process.stderr.write(
+        `${LOG_PREFIX} Action blocked: this approval request expired.\n` +
+          `  Start the action again and complete approval when prompted.\n` +
+          `  Detail: status=expired\n`,
+      );
+      process.exit(2);
+    }
+    if (st === "pending") {
+      continue;
+    }
+  }
+
+  process.stderr.write(
+    `${LOG_PREFIX} Action blocked: approval timed out after 5 minutes.\n` +
+      `  Approve in the Shield dashboard, then retry.\n` +
+      `  Detail: approvalsUrl=${approvalsUrl}\n`,
+  );
+  process.exit(2);
+}
+
+async function main() {
+  let raw;
+  try {
+    raw = await readStdin();
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    process.stderr.write(`${LOG_PREFIX} could not read stdin (${msg}). Allowing action.\n`);
+    process.exit(0);
+  }
+
+  const config = loadConfig();
+  if (config === null) {
+    process.exit(0);
+  }
+  if (config.apiKey.length === 0 || config.agentName.length === 0) {
+    process.exit(0);
+  }
+
+  /** @type {Record<string, unknown>} */
+  let hookPayload;
+  try {
+    hookPayload = JSON.parse(raw.length > 0 ? raw : "{}");
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    process.stderr.write(`${LOG_PREFIX} invalid JSON (${msg}). Allowing action.\n`);
+    process.exit(0);
+  }
+
+  const agentActionName =
+    typeof hookPayload.agent_action_name === "string" ? hookPayload.agent_action_name : "";
+
+  if (process.env.MULTICORN_SHIELD_WINDSURF_PRE_HOOK_TEST_SERIALIZE_FAIL === "1") {
+    hookPayload.tool_info = {
+      toJSON() {
+        throw new TypeError("MULTICORN_SHIELD_WINDSURF_PRE_HOOK_TEST_SERIALIZE_FAIL");
+      },
+    };
+  }
+
+  const toolInfo = hookPayload.tool_info;
+
+  const mapped = mapPreEvent(agentActionName, toolInfo);
+  if (mapped === null) {
+    process.exit(0);
+  }
+  const { service, actionType } = mapped;
+
+  let toolInfoSerialized;
+  try {
+    toolInfoSerialized =
+      typeof toolInfo === "string"
+        ? toolInfo
+        : JSON.stringify(toolInfo === undefined ? null : toolInfo);
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    process.stderr.write(
+      `${LOG_PREFIX} could not serialize tool_info (${msg}). Allowing action.\n`,
+    );
+    process.exit(0);
+  }
+
+  if (typeof toolInfoSerialized === "string" && toolInfoSerialized.length > 4096) {
+    toolInfoSerialized = toolInfoSerialized.slice(0, 4096);
+  }
+
+  const approvalsUrl = dashboardHintUrl(config.baseUrl);
+
+  /** @type {Record<string, unknown>} */
+  const metadata = {
+    agent_action_name: agentActionName,
+    trajectory_id: typeof hookPayload.trajectory_id === "string" ? hookPayload.trajectory_id : "",
+    execution_id: typeof hookPayload.execution_id === "string" ? hookPayload.execution_id : "",
+    model_name: typeof hookPayload.model_name === "string" ? hookPayload.model_name : "",
+    tool_info: toolInfoSerialized,
+    source: "windsurf",
+  };
+
+  /** @type {Record<string, unknown>} */
+  const payload = {
+    agent: config.agentName,
+    service,
+    actionType,
+    status: "pending",
+    metadata,
+    platform: "windsurf",
+  };
+
+  if (process.env.MULTICORN_SHIELD_WINDSURF_PRE_HOOK_TEST_THROW === "1") {
+    throw new Error("MULTICORN_SHIELD_WINDSURF_PRE_HOOK_TEST_THROW");
+  }
+
+  let statusCode;
+  let bodyText;
+  try {
+    const res = await postJson(config.baseUrl, config.apiKey, payload);
+    statusCode = res.statusCode;
+    bodyText = res.bodyText;
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    process.stderr.write(
+      `${LOG_PREFIX} Action blocked: Shield API unreachable, cannot verify permissions.\n` +
+        `  Check that the Shield service is running and retry.\n` +
+        `  Detail: ${msg}\n`,
+    );
+    process.exit(2);
+  }
+
+  const parsed = safeJsonParse(bodyText);
+  const data = unwrapData(parsed);
+
+  if (statusCode === 202) {
+    if (data === null || typeof data !== "object") {
+      process.stderr.write(
+        `${LOG_PREFIX} Action blocked: this action needs approval in the Shield dashboard before it can run.\n` +
+          `  Open the approvals page and complete approval, then retry.\n` +
+          `  Detail: missing approval data in Shield response\n`,
+      );
+      process.exit(2);
+    }
+    const approvalIdRaw = /** @type {Record<string, unknown>} */ (data).approval_id;
+    const approvalId = typeof approvalIdRaw === "string" ? approvalIdRaw : "";
+    if (approvalId.length === 0) {
+      process.stderr.write(
+        `${LOG_PREFIX} Action blocked: this action needs approval in the Shield dashboard before it can run.\n` +
+          `  Open the approvals page and complete approval, then retry.\n` +
+          `  Detail: approval_id missing in Shield response\n`,
+      );
+      process.exit(2);
+    }
+    await handlePendingWithConsentAndPoll(config, approvalId, service, actionType, approvalsUrl);
+    return;
+  }
+
+  if (statusCode === 201) {
+    if (data === null || typeof data !== "object") {
+      const detail = bodyText.length > 500 ? `${bodyText.slice(0, 500)}...` : bodyText;
+      process.stderr.write(
+        `${LOG_PREFIX} Action blocked: unexpected Shield response, cannot verify permissions.\n` +
+          `  Check that the Shield service is healthy and retry.\n` +
+          `  Detail: ${detail}\n`,
+      );
+      process.exit(2);
+    }
+    const st = String(/** @type {Record<string, unknown>} */ (data).status || "").toLowerCase();
+    if (st === "approved") {
+      process.exit(0);
+    }
+    if (st === "blocked") {
+      process.stderr.write(blockedMessage(data, service, actionType, approvalsUrl));
+      process.exit(2);
+    }
+    process.stderr.write(
+      `${LOG_PREFIX} Action blocked: ambiguous Shield status, cannot verify permissions.\n` +
+        `  Check that your Shield API and plugin versions match, then retry.\n` +
+        `  Detail: status=${JSON.stringify(/** @type {Record<string, unknown>} */ (data).status)}\n`,
+    );
+    process.exit(2);
+  }
+
+  const httpDetail = bodyText.length > 300 ? `${bodyText.slice(0, 300)}...` : bodyText;
+  process.stderr.write(
+    `${LOG_PREFIX} Action blocked: Shield returned HTTP ${String(statusCode)}, cannot verify permissions.\n` +
+      `  Check your API key, Shield service status, and rate limits, then retry.\n` +
+      `  Detail: HTTP ${String(statusCode)} body=${httpDetail}\n`,
+  );
+  process.exit(2);
+}
+
+main().catch((e) => {
+  const msg = e instanceof Error ? e.message : String(e);
+  process.stderr.write(
+    `${LOG_PREFIX} Action blocked: unexpected error, cannot verify permissions.\n` +
+      `  Retry the action. If it keeps failing, check Shield logs.\n` +
+      `  Detail: ${msg}\n`,
+  );
+  process.exit(2);
+});