multicorn-shield 0.11.0 → 0.13.0

package/dist/proxy.d.ts

@@ -68,6 +68,23 @@ declare const PERMISSION_LEVELS: {
     readonly Create: "create";
 };
 type PermissionLevel = (typeof PERMISSION_LEVELS)[keyof typeof PERMISSION_LEVELS];
+/**
+ * Lifecycle states for an action processed by the policy engine.
+ *
+ * - `approved`: action passed policy checks and was executed
+ * - `blocked`: action was denied by policy
+ * - `pending`: action is awaiting human approval
+ * - `flagged`: action was executed but flagged for review
+ * - `requires_approval`: action requires content review before execution
+ */
+declare const ACTION_STATUSES: {
+    readonly Approved: "approved";
+    readonly Blocked: "blocked";
+    readonly Pending: "pending";
+    readonly Flagged: "flagged";
+    readonly RequiresApproval: "requires_approval";
+};
+type ActionStatus = (typeof ACTION_STATUSES)[keyof typeof ACTION_STATUSES];
 /**
  * A single permission scope binding a service to an access level.
  *
@@ -232,4 +249,214 @@ interface McpToolScopeMapping {
  */
 declare function mapMcpToolToScope(toolName: string): McpToolScopeMapping;
 
-export { type AgentRecord, type JsonRpcError, type JsonRpcRequest, type JsonRpcResponse, type LogLevel, type ProxyLogger, ShieldAuthError, type ToolCallParams, buildAuthErrorResponse, buildBlockedResponse, buildInternalErrorResponse, buildServiceUnreachableResponse, buildSpendingBlockedResponse, createLogger, deriveDashboardUrl, extractActionFromToolName, extractServiceFromToolName, extractToolCallParams, fetchGrantedScopes, findAgentByName, isValidLogLevel, mapMcpToolToScope, parseJsonRpcLine, registerAgent, validateScopeAccess };
+/**
+ * Action logging client for Multicorn Shield.
+ *
+ * Sends structured action events to the Multicorn hosted API, providing the
+ * observability backbone for Shield. Every agent action is logged with
+ * metadata, cost information, and status tracking.
+ *
+ * **Design principles:**
+ * - **Fire-and-forget**: Logging failures MUST NOT block the agent's action.
+ * - **Security (Jordan persona)**: API keys never logged, HTTPS enforced.
+ * - **Clear errors (Yuki persona)**: Descriptive messages for all failure modes.
+ * - **Clean async (The Team persona)**: Proper promise handling, no hanging requests.
+ *
+ * @module logger/action-logger
+ */
+
+/**
+ * Configuration options for the action logger client.
+ *
+ * @example
+ * ```ts
+ * const config: ActionLoggerConfig = {
+ *   apiKey: process.env.MULTICORN_API_KEY,
+ *   baseUrl: "https://api.multicorn.ai",
+ *   timeout: 5000,
+ *   batchMode: {
+ *     enabled: true,
+ *     maxSize: 10,
+ *     flushIntervalMs: 5000,
+ *   },
+ * };
+ * ```
+ */
+interface ActionLoggerConfig {
+    /**
+     * Multicorn API key for authentication.
+     * Passed as `X-Multicorn-Key` header. Never logged.
+     */
+    readonly apiKey: string;
+    /**
+     * Base URL for the Multicorn API.
+     * @default "https://api.multicorn.ai"
+     */
+    readonly baseUrl?: string;
+    /**
+     * Request timeout in milliseconds.
+     * @default 5000
+     */
+    readonly timeout?: number;
+    /**
+     * Optional batch mode configuration.
+     * When enabled, actions are queued and flushed periodically.
+     */
+    readonly batchMode?: BatchModeConfig;
+    /**
+     * Optional error handler for logging failures.
+     * Called asynchronously. Does not block the main action flow.
+     */
+    readonly onError?: (error: Error) => void;
+}
+/**
+ * Batch mode configuration.
+ *
+ * Actions are flushed when **either** condition is met:
+ * - The queue reaches `maxSize` actions, OR
+ * - `flushIntervalMs` milliseconds have elapsed since the last flush.
+ */
+interface BatchModeConfig {
+    /** Whether batch mode is enabled. */
+    readonly enabled: boolean;
+    /**
+     * Maximum number of actions to queue before forcing a flush.
+     * @default 10
+     */
+    readonly maxSize?: number;
+    /**
+     * Maximum time (ms) between flushes.
+     * @default 5000
+     */
+    readonly flushIntervalMs?: number;
+}
+/**
+ * A single action event to be logged.
+ *
+ * @example
+ * ```ts
+ * const action: ActionPayload = {
+ *   agent: "inbox-assistant",
+ *   service: "gmail",
+ *   actionType: "send_email",
+ *   status: "approved",
+ *   cost: 0.002,
+ *   metadata: {
+ *     recipient: "user@example.com",
+ *     subject: "Weekly report",
+ *   },
+ * };
+ * ```
+ */
+interface ActionPayload {
+    /** Agent identifier (e.g. "inbox-assistant"). */
+    readonly agent: string;
+    /** Service being accessed (e.g. "gmail", "slack"). */
+    readonly service: string;
+    /** Type of action performed (e.g. "send_email", "read_message"). */
+    readonly actionType: string;
+    /** Lifecycle status of the action. */
+    readonly status: ActionStatus;
+    /**
+     * Optional cost in USD incurred by this action.
+     * Present only for actions with usage-based pricing.
+     */
+    readonly cost?: number;
+    /**
+     * Optional structured metadata for additional context.
+     * Keys and values must be serializable to JSON.
+     */
+    readonly metadata?: Readonly<Record<string, string | number | boolean>>;
+}
+/**
+ * HTTP client for logging agent actions to the Multicorn Shield API.
+ *
+ * Supports both immediate and batched delivery modes. All network failures
+ * are handled gracefully to ensure logging never blocks the agent's execution.
+ *
+ * @example Basic usage (immediate mode)
+ * ```ts
+ * const logger = createActionLogger({
+ *   apiKey: process.env.MULTICORN_API_KEY!,
+ * });
+ *
+ * await logger.logAction({
+ *   agent: "email-assistant",
+ *   service: "gmail",
+ *   actionType: "send_email",
+ *   status: "approved",
+ *   cost: 0.002,
+ * });
+ * ```
+ *
+ * @example Batch mode with error handling
+ * ```ts
+ * const logger = createActionLogger({
+ *   apiKey: process.env.MULTICORN_API_KEY!,
+ *   batchMode: { enabled: true, maxSize: 10, flushIntervalMs: 5000 },
+ *   onError: (err) => console.error("[ActionLogger]", err.message),
+ * });
+ *
+ * // Actions are queued and flushed automatically
+ * logger.logAction({
+ *   agent: "inbox-assistant",
+ *   service: "gmail",
+ *   actionType: "read_message",
+ *   status: "approved",
+ * });
+ *
+ * // Force immediate flush
+ * await logger.flush();
+ *
+ * // Clean up resources
+ * logger.shutdown();
+ * ```
+ */
+interface ActionLogger {
+    /**
+     * Log a single action event.
+     *
+     * In immediate mode, sends the action to the API right away (non-blocking).
+     * In batch mode, queues the action and flushes when thresholds are met.
+     *
+     * @param action - The action event to log.
+     * @returns A promise that resolves when the action is sent (immediate mode)
+     *          or queued (batch mode). Rejects only on validation errors, not
+     *          network failures (those are passed to `onError`).
+     */
+    logAction(action: ActionPayload): Promise<void>;
+    /**
+     * Flush all queued actions immediately (batch mode only).
+     *
+     * In immediate mode, this is a no-op.
+     *
+     * @returns A promise that resolves when all queued actions have been sent.
+     */
+    flush(): Promise<void>;
+    /**
+     * Shut down the logger and clean up resources.
+     *
+     * Stops the flush timer (if in batch mode) and flushes any remaining actions.
+     * After calling `shutdown()`, the logger should not be used.
+     */
+    shutdown(): Promise<void>;
+}
+/**
+ * Create a new action logger client.
+ *
+ * @param config - Configuration options.
+ * @returns An {@link ActionLogger} instance.
+ * @throws {Error} If the API key is missing or the base URL is not HTTPS.
+ *
+ * @example
+ * ```ts
+ * const logger = createActionLogger({
+ *   apiKey: process.env.MULTICORN_API_KEY!,
+ *   baseUrl: "https://api.multicorn.ai",
+ *   timeout: 3000,
+ * });
+ * ```
+ */
+declare function createActionLogger(config: ActionLoggerConfig): ActionLogger;
+
+export { type ActionLogger, type ActionLoggerConfig, type ActionPayload, type AgentRecord, type JsonRpcError, type JsonRpcRequest, type JsonRpcResponse, type LogLevel, type PermissionLevel, type ProxyLogger, type Scope, ShieldAuthError, type ToolCallParams, buildAuthErrorResponse, buildBlockedResponse, buildInternalErrorResponse, buildServiceUnreachableResponse, buildSpendingBlockedResponse, createActionLogger, createLogger, deriveDashboardUrl, extractActionFromToolName, extractServiceFromToolName, extractToolCallParams, fetchGrantedScopes, findAgentByName, isValidLogLevel, mapMcpToolToScope, parseJsonRpcLine, registerAgent, validateScopeAccess };

package/dist/proxy.js

@@ -435,4 +435,177 @@ function mapMcpToolToScope(toolName) {
   return { service: head, permissionLevel, actionType };
 }
 
-export { ShieldAuthError, buildAuthErrorResponse, buildBlockedResponse, buildInternalErrorResponse, buildServiceUnreachableResponse, buildSpendingBlockedResponse, createLogger, deriveDashboardUrl, extractActionFromToolName, extractServiceFromToolName, extractToolCallParams, fetchGrantedScopes, findAgentByName, isValidLogLevel, mapMcpToolToScope, parseJsonRpcLine, registerAgent, validateScopeAccess };
+// src/logger/action-logger.ts
+function createActionLogger(config) {
+  if (!config.apiKey || config.apiKey.trim().length === 0) {
+    throw new Error(
+      "[ActionLogger] API key is required. Provide it via the 'apiKey' config option."
+    );
+  }
+  const baseUrl = config.baseUrl ?? "https://api.multicorn.ai";
+  const timeout = config.timeout ?? 5e3;
+  if (!baseUrl.startsWith("https://") && !baseUrl.startsWith("http://localhost")) {
+    throw new Error(
+      `[ActionLogger] Base URL must use HTTPS for security. Received: "${baseUrl}". Use https:// or http://localhost for local development.`
+    );
+  }
+  const endpoint = `${baseUrl}/api/v1/actions`;
+  const batchEnabled = config.batchMode?.enabled ?? false;
+  const maxBatchSize = config.batchMode?.maxSize ?? 10;
+  const flushInterval = config.batchMode?.flushIntervalMs ?? 5e3;
+  const queue = [];
+  let flushTimer;
+  let isShutdown = false;
+  async function sendActions(actions) {
+    if (actions.length === 0) return;
+    const convertAction = (action) => ({
+      agent: action.agent,
+      service: action.service,
+      actionType: action.actionType,
+      status: action.status,
+      ...action.cost !== void 0 ? { cost: action.cost } : {},
+      ...action.metadata !== void 0 ? { metadata: action.metadata } : {}
+    });
+    const convertedActions = actions.map(convertAction);
+    const payload = batchEnabled ? { actions: convertedActions } : convertedActions[0];
+    let lastError;
+    for (let attempt = 0; attempt < 2; attempt++) {
+      try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => {
+          controller.abort();
+        }, timeout);
+        const response = await fetch(endpoint, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "X-Multicorn-Key": config.apiKey
+          },
+          body: JSON.stringify(payload),
+          signal: controller.signal
+        });
+        clearTimeout(timeoutId);
+        if (response.ok) {
+          return;
+        }
+        if (response.status >= 400 && response.status < 500) {
+          const body = await response.text().catch(() => "");
+          throw new Error(
+            `[ActionLogger] Client error (${String(response.status)}): ${response.statusText}. Response: ${body}. Check your API key and payload format.`
+          );
+        }
+        if (response.status >= 500 && attempt === 0) {
+          lastError = new Error(
+            `[ActionLogger] Server error (${String(response.status)}): ${response.statusText}. Retrying once...`
+          );
+          await sleep(100 * Math.pow(2, attempt));
+          continue;
+        }
+        throw new Error(
+          `[ActionLogger] Server error (${String(response.status)}) after retry: ${response.statusText}. Multicorn API may be experiencing issues.`
+        );
+      } catch (error) {
+        if (error instanceof Error) {
+          if (error.name === "AbortError") {
+            lastError = new Error(
+              `[ActionLogger] Request timeout after ${String(timeout)}ms. Increase the 'timeout' config option or check your network connection.`
+            );
+          } else if (error.message.includes("Client error") || error.message.includes("Server error")) {
+            lastError = error;
+          } else {
+            lastError = new Error(
+              `[ActionLogger] Network error: ${error.message}. Check your network connection and API endpoint.`
+            );
+          }
+        } else {
+          lastError = new Error(`[ActionLogger] Unknown error: ${String(error)}`);
+        }
+        if (attempt === 0 && !lastError.message.includes("Client error")) {
+          await sleep(100 * Math.pow(2, attempt));
+          continue;
+        }
+        break;
+      }
+    }
+    if (lastError) {
+      if (config.onError) {
+        config.onError(lastError);
+      }
+    }
+  }
+  async function flushQueue() {
+    if (queue.length === 0) return;
+    const actions = queue.map((item) => item.payload);
+    queue.length = 0;
+    await sendActions(actions);
+  }
+  function startFlushTimer() {
+    if (flushTimer !== void 0) return;
+    flushTimer = setInterval(() => {
+      flushQueue().catch(() => {
+      });
+    }, flushInterval);
+    const timer = flushTimer;
+    if (typeof timer.unref === "function") {
+      timer.unref();
+    }
+  }
+  function stopFlushTimer() {
+    if (flushTimer) {
+      clearInterval(flushTimer);
+      flushTimer = void 0;
+    }
+  }
+  if (batchEnabled) {
+    startFlushTimer();
+  }
+  return {
+    logAction(action) {
+      if (isShutdown) {
+        throw new Error(
+          "[ActionLogger] Cannot log action after shutdown. Create a new logger instance."
+        );
+      }
+      if (action.agent.trim().length === 0) {
+        throw new Error("[ActionLogger] Action must have a non-empty 'agent' field.");
+      }
+      if (action.service.trim().length === 0) {
+        throw new Error("[ActionLogger] Action must have a non-empty 'service' field.");
+      }
+      if (action.actionType.trim().length === 0) {
+        throw new Error("[ActionLogger] Action must have a non-empty 'actionType' field.");
+      }
+      if (action.status.trim().length === 0) {
+        throw new Error("[ActionLogger] Action must have a non-empty 'status' field.");
+      }
+      if (batchEnabled) {
+        queue.push({ payload: action, timestamp: Date.now() });
+        if (queue.length >= maxBatchSize) {
+          flushQueue().catch(() => {
+          });
+        }
+      } else {
+        sendActions([action]).catch(() => {
+        });
+      }
+      return Promise.resolve();
+    },
+    async flush() {
+      if (!batchEnabled) return;
+      await flushQueue();
+    },
+    async shutdown() {
+      if (isShutdown) return;
+      isShutdown = true;
+      stopFlushTimer();
+      if (batchEnabled) {
+        await flushQueue();
+      }
+    }
+  };
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export { ShieldAuthError, buildAuthErrorResponse, buildBlockedResponse, buildInternalErrorResponse, buildServiceUnreachableResponse, buildSpendingBlockedResponse, createActionLogger, createLogger, deriveDashboardUrl, extractActionFromToolName, extractServiceFromToolName, extractToolCallParams, fetchGrantedScopes, findAgentByName, isValidLogLevel, mapMcpToolToScope, parseJsonRpcLine, registerAgent, validateScopeAccess };

package/dist/shield-extension.js

@@ -22359,7 +22359,7 @@ async function writeExtensionBackup(claudeDesktopConfigPath, mcpServers) {
 
 // package.json
 var package_default = {
-  version: "0.11.0"};
+  version: "0.13.0"};
 
 // src/package-meta.ts
 var PACKAGE_VERSION = package_default.version;
@@ -23705,9 +23705,6 @@ async function autoCreateProxyConfig(baseUrl, apiKey, serverName, entry, agentNa
   return true;
 }
 async function runShieldExtension() {
-  const debugBaseUrl = process.env["MULTICORN_BASE_URL"] ?? "";
-  const debugApiKeyPrefix = process.env["MULTICORN_API_KEY"]?.slice(0, 8) ?? "";
-  console.error(`[SHIELD-DEBUG] BASE_URL=${debugBaseUrl} API_KEY=${debugApiKeyPrefix}...`);
   const logger = createLogger(readLogLevel());
   const apiKey = readApiKey();
   if (apiKey === null) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "multicorn-shield",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "The control layer for AI agents: permissions, consent, spending limits, and audit logging.",
   "license": "MIT",
   "author": "Multicorn AI Pty Ltd",
@@ -37,6 +37,8 @@
   "files": [
     "dist",
     "plugins/windsurf",
+    "plugins/cline",
+    "plugins/gemini-cli",
     "LICENSE",
     "README.md",
     "CHANGELOG.md"
@@ -74,7 +76,7 @@
     "@open-wc/testing-helpers": "^3.0.1",
     "@size-limit/file": "^11.1.6",
     "@types/node": "^22.0.0",
-    "@vitest/coverage-istanbul": "^3.0.5",
+    "@vitest/coverage-v8": "^3.0.5",
     "eslint": "^9.19.0",
     "eslint-config-prettier": "^10.0.1",
     "eslint-plugin-unicorn": "^57.0.0",

package/plugins/cline/README.md

@@ -0,0 +1,61 @@
+# Multicorn Shield Cline plugin
+
+This folder ships **Shield hooks for the [Cline](https://github.com/cline/cline) VS Code extension**. The PreToolUse script asks Shield whether a pending tool call is allowed; the PostToolUse script records completed actions in the Shield audit trail.
+
+## Prerequisites
+
+- **Node.js** 20 or newer (hooks run as standalone Node scripts).
+- **Cline** v3.36 or newer with **Hooks** enabled in settings.
+
+Keep these three scripts together whenever you install by hand:
+
+- `hooks/scripts/pre-tool-use.cjs`
+- `hooks/scripts/post-tool-use.cjs`
+- `hooks/scripts/shared.cjs`
+
+## Installing the hooks
+
+**CLI (recommended):** run `npx multicorn-shield init` and follow prompts so the scripts are copied into Cline's hooks directory.
+
+**Manual:** copy the `hooks/scripts/` `.cjs` files into:
+
+`~/Documents/Cline/Hooks/`
+
+(or the equivalent Hooks path on your machine). Cline runs each hook with stdin JSON from its Hooks API.
+
+## Config file
+
+Path: **`~/.multicorn/config.json`**
+
+| Field     | Required | Description                                                                                                                                                                               |
+| --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `apiKey`  | yes      | Multicorn API key used in the Shield request (`X-Multicorn-Key`).                                                                                                                         |
+| `baseUrl` | no       | API root. Defaults to `https://api.multicorn.ai` (no trailing slash). Non-local URLs must use `https://` or the hooks disable Shield (fail-open). `localhost` / `127.0.0.1` may use HTTP. |
+| `agents`  | no       | Array of `{ "name": "...", "platform": "cline" }` objects so the hooks know which Shield agent name to use. Legacy `agentName` string is still read if present.                           |
+
+Example:
+
+```json
+{
+  "apiKey": "mcs_your_key_here",
+  "baseUrl": "https://api.multicorn.ai",
+  "agents": [{ "name": "my-repo-agent", "platform": "cline" }]
+}
+```
+
+## How it works
+
+1. **PreToolUse:** before Cline runs a tool, stdin carries the pending request. The script maps the tool name to a Shield **service** and **actionType**, POSTs `status: pending` to `/api/v1/actions`, and reads the response. It either allows the tool (`cancel: false`) or blocks with an error message and optional consent workflow.
+2. **PostToolUse:** after the tool completes, stdin includes the outcome. The script POSTs `status: approved` with metadata (scrubbed parameters and result) so the audit log stays usable without stuffing large secrets into the payload.
+
+Both hooks reply with JSON on stdout. The post-hook always finishes with `{ "cancel": false }`.
+
+## Security model
+
+Shield wiring is **fail-open by design**. If config is missing, invalid for remote HTTP, or the API errors or times out, **actions are allowed** so work is not silently blocked because Shield is down. Deployers treat Shield as governance and auditing, not as a cryptographic boundary against a hostile process on the same machine.
+
+## Troubleshooting
+
+1. **Confirm hooks run:** temporarily add stderr output (not recommended long term), or tail Cline's hook output/logs if exposed. Successful runs should not spam the developer console unless there is an API warning.
+2. **Nothing reaches Shield:** check `config.json` path and `apiKey`, that `agents` includes `platform: "cline"` with the right `name`, and that `baseUrl` uses HTTPS on non-local installs.
+3. **Windows consent / browser:** the pre-hook opens the consent URL via `cmd.exe start`; if that fails, open the URL from the blocking message manually.

package/plugins/cline/hooks/scripts/post-tool-use.cjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// Copyright (c) Multicorn AI Pty Ltd. MIT License. See LICENSE file.
+/**
+ * Cline PostToolUse hook: logs completed actions to the Shield audit trail.
+ * Reads JSON from stdin (Cline Hooks API), posts to Shield API.
+ * Always returns {"cancel": false} - post hooks never block.
+ */
+
+"use strict";
+
+const {
+  buildScrubbedParametersJson,
+  loadConfig,
+  logPrefix,
+  mapToolName,
+  postJson,
+  readStdin,
+  scrubResultForMetadata,
+} = require("./shared.cjs");
+
+const HOOK_PREFIX = logPrefix("post-hook");
+
+/**
+ * Outputs JSON response to stdout and exits.
+ */
+function respond() {
+  process.stdout.write(JSON.stringify({ cancel: false }) + "\n");
+  process.exit(0);
+}
+
+async function main() {
+  let raw;
+  try {
+    raw = await readStdin();
+  } catch {
+    respond();
+    return;
+  }
+
+  const config = loadConfig();
+  if (config === null || config.apiKey.length === 0 || config.agentName.length === 0) {
+    respond();
+    return;
+  }
+
+  /** @type {Record<string, unknown>} */
+  let hookPayload;
+  try {
+    hookPayload = JSON.parse(raw.length > 0 ? raw : "{}");
+  } catch {
+    respond();
+    return;
+  }
+
+  const postToolUse = hookPayload.postToolUse;
+  if (postToolUse === null || typeof postToolUse !== "object") {
+    respond();
+    return;
+  }
+
+  const toolUse = /** @type {Record<string, unknown>} */ (postToolUse);
+  const toolName = typeof toolUse.tool === "string" ? toolUse.tool : "";
+
+  if (toolName.length === 0) {
+    respond();
+    return;
+  }
+
+  const { service, actionType } = mapToolName(toolName);
+
+  const paramsSerialized = buildScrubbedParametersJson(toolUse.parameters);
+
+  /** @type {Record<string, unknown>} */
+  const metadata = {
+    tool_name: toolName,
+    task_id: typeof hookPayload.taskId === "string" ? hookPayload.taskId : "",
+    cline_version: typeof hookPayload.clineVersion === "string" ? hookPayload.clineVersion : "",
+    parameters: paramsSerialized,
+    result: scrubResultForMetadata(toolUse.result),
+    timing: typeof toolUse.timing === "object" ? JSON.stringify(toolUse.timing) : "",
+    source: "cline",
+  };
+
+  /** @type {Record<string, unknown>} */
+  const payload = {
+    agent: config.agentName,
+    service,
+    actionType,
+    status: "approved",
+    metadata,
+    platform: "cline",
+  };
+
+  try {
+    const res = await postJson(config.baseUrl, config.apiKey, payload);
+    const code = res.statusCode ?? 0;
+    if (code < 200 || code >= 300) {
+      throw new Error(`HTTP ${String(code)}`);
+    }
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    process.stderr.write(
+      `${HOOK_PREFIX} Warning: failed to log action to Shield audit trail. Detail: ${msg}\n`,
+    );
+  }
+
+  respond();
+}
+
+main().catch((e) => {
+  const msg = e instanceof Error ? e.message : String(e);
+  process.stderr.write(
+    `${HOOK_PREFIX} Warning: failed to log action to Shield audit trail. Detail: ${msg}\n`,
+  );
+  respond();
+});