multicorn-shield 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- Gemini CLI native plugin: BeforeTool/AfterTool hook scripts for full governance
+- Gemini CLI hosted proxy support with httpUrl config field
+- CLI wizard: Gemini CLI platform with native plugin and hosted proxy integration modes
+- CLI wizard: platform prerequisite detection (warns if target platform is not installed)
+
 ## [X.Y.Z] - YYYY-MM-DD
 
 ### Added

package/dist/index.cjs

@@ -14,6 +14,18 @@ var __decorateClass = (decorators, target, key, kind) => {
 };
 
 // src/types/index.ts
+var AGENT_PLATFORM_SLUGS = [
+  "openclaw",
+  "claude-code",
+  "claude-desktop",
+  "cursor",
+  "windsurf",
+  "cline",
+  "gemini-cli",
+  "other-mcp",
+  "github-actions",
+  "unknown"
+];
 var AGENT_STATUSES = {
   Active: "active",
   Paused: "paused",
@@ -2893,6 +2905,7 @@ function validateApiKey(apiKey) {
 }
 
 exports.ACTION_STATUSES = ACTION_STATUSES;
+exports.AGENT_PLATFORM_SLUGS = AGENT_PLATFORM_SLUGS;
 exports.AGENT_STATUSES = AGENT_STATUSES;
 exports.BUILT_IN_SERVICES = BUILT_IN_SERVICES;
 exports.CONSENT_ELEMENT_TAG = CONSENT_ELEMENT_TAG;

package/dist/index.d.cts

@@ -9,6 +9,11 @@ import { LitElement, PropertyValues, HTMLTemplateResult } from 'lit';
  *
  * @module types
  */
+/**
+ * Agent client platforms supported by hosted proxy and native hooks (aligned with API validation).
+ */
+declare const AGENT_PLATFORM_SLUGS: readonly ["openclaw", "claude-code", "claude-desktop", "cursor", "windsurf", "cline", "gemini-cli", "other-mcp", "github-actions", "unknown"];
+type AgentPlatformSlug = (typeof AGENT_PLATFORM_SLUGS)[number];
 /**
  * Possible operational states for an agent.
  *
@@ -2310,4 +2315,4 @@ interface ContentReviewRequestPayload {
  */
 declare function requestContentReview(payload: ContentReviewRequestPayload, apiKey: string, baseUrl: string, logger?: PluginLogger): Promise<ContentReviewResult>;
 
-export { ACTION_STATUSES, AGENT_STATUSES, type Action, type ActionInput, type ActionLogger, type ActionLoggerConfig, type ActionPayload, type ActionStatus, type Agent, type AgentStatus, type ApiError, BUILT_IN_SERVICES, type BatchModeConfig, type BuiltInServiceName, CONSENT_ELEMENT_TAG, type ConsentDecision, type ConsentDeniedEventDetail, type ConsentEventDetail, type ConsentEventMap, type ConsentEventName, type ConsentGrantedEventDetail, type ConsentOptions, type ConsentPartialEventDetail, type ContentReviewRequestPayload, type ContentReviewResult, type ContentReviewStatusResponse, type FocusTrap, type McpAdapter, type McpAdapterConfig, type McpAdapterResult, type McpBlockedResult, type McpToolCall, type McpToolHandler, type McpToolResult, MulticornBadge, MulticornConsent, MulticornShield, type MulticornShieldConfig, PERMISSION_LEVELS, type Permission, type PermissionLevel, type RemainingBudget, SERVICE_NAME_PATTERN, type Scope, ScopeParseError, type ScopeParseResult, type ScopeRegistry, type ScopeRequest, type ServiceDefinition, type SpendCheckResult, type SpendingCheckResult, type SpendingChecker, type SpendingLimit, type SpendingLimits, type SpendingTrackerConfig, type ValidationResult, centsToDollars, createActionLogger, createFocusTrap, createMcpAdapter, createScopeRegistry, createSpendingChecker, dollarsToCents, formatScope, getPermissionLabel, getScopeLabel, getScopeShortLabel, getServiceDisplayName, getServiceIcon, hasScope, isBlockedResult, isPublicContentAction, isValidScopeString, parseScope, parseScopes, requestContentReview, requiresContentReview, tryParseScope, validateAllScopesAccess, validateScopeAccess };
+export { ACTION_STATUSES, AGENT_PLATFORM_SLUGS, AGENT_STATUSES, type Action, type ActionInput, type ActionLogger, type ActionLoggerConfig, type ActionPayload, type ActionStatus, type Agent, type AgentPlatformSlug, type AgentStatus, type ApiError, BUILT_IN_SERVICES, type BatchModeConfig, type BuiltInServiceName, CONSENT_ELEMENT_TAG, type ConsentDecision, type ConsentDeniedEventDetail, type ConsentEventDetail, type ConsentEventMap, type ConsentEventName, type ConsentGrantedEventDetail, type ConsentOptions, type ConsentPartialEventDetail, type ContentReviewRequestPayload, type ContentReviewResult, type ContentReviewStatusResponse, type FocusTrap, type McpAdapter, type McpAdapterConfig, type McpAdapterResult, type McpBlockedResult, type McpToolCall, type McpToolHandler, type McpToolResult, MulticornBadge, MulticornConsent, MulticornShield, type MulticornShieldConfig, PERMISSION_LEVELS, type Permission, type PermissionLevel, type RemainingBudget, SERVICE_NAME_PATTERN, type Scope, ScopeParseError, type ScopeParseResult, type ScopeRegistry, type ScopeRequest, type ServiceDefinition, type SpendCheckResult, type SpendingCheckResult, type SpendingChecker, type SpendingLimit, type SpendingLimits, type SpendingTrackerConfig, type ValidationResult, centsToDollars, createActionLogger, createFocusTrap, createMcpAdapter, createScopeRegistry, createSpendingChecker, dollarsToCents, formatScope, getPermissionLabel, getScopeLabel, getScopeShortLabel, getServiceDisplayName, getServiceIcon, hasScope, isBlockedResult, isPublicContentAction, isValidScopeString, parseScope, parseScopes, requestContentReview, requiresContentReview, tryParseScope, validateAllScopesAccess, validateScopeAccess };

package/dist/index.d.ts

@@ -9,6 +9,11 @@ import { LitElement, PropertyValues, HTMLTemplateResult } from 'lit';
  *
  * @module types
  */
+/**
+ * Agent client platforms supported by hosted proxy and native hooks (aligned with API validation).
+ */
+declare const AGENT_PLATFORM_SLUGS: readonly ["openclaw", "claude-code", "claude-desktop", "cursor", "windsurf", "cline", "gemini-cli", "other-mcp", "github-actions", "unknown"];
+type AgentPlatformSlug = (typeof AGENT_PLATFORM_SLUGS)[number];
 /**
  * Possible operational states for an agent.
  *
@@ -2310,4 +2315,4 @@ interface ContentReviewRequestPayload {
  */
 declare function requestContentReview(payload: ContentReviewRequestPayload, apiKey: string, baseUrl: string, logger?: PluginLogger): Promise<ContentReviewResult>;
 
-export { ACTION_STATUSES, AGENT_STATUSES, type Action, type ActionInput, type ActionLogger, type ActionLoggerConfig, type ActionPayload, type ActionStatus, type Agent, type AgentStatus, type ApiError, BUILT_IN_SERVICES, type BatchModeConfig, type BuiltInServiceName, CONSENT_ELEMENT_TAG, type ConsentDecision, type ConsentDeniedEventDetail, type ConsentEventDetail, type ConsentEventMap, type ConsentEventName, type ConsentGrantedEventDetail, type ConsentOptions, type ConsentPartialEventDetail, type ContentReviewRequestPayload, type ContentReviewResult, type ContentReviewStatusResponse, type FocusTrap, type McpAdapter, type McpAdapterConfig, type McpAdapterResult, type McpBlockedResult, type McpToolCall, type McpToolHandler, type McpToolResult, MulticornBadge, MulticornConsent, MulticornShield, type MulticornShieldConfig, PERMISSION_LEVELS, type Permission, type PermissionLevel, type RemainingBudget, SERVICE_NAME_PATTERN, type Scope, ScopeParseError, type ScopeParseResult, type ScopeRegistry, type ScopeRequest, type ServiceDefinition, type SpendCheckResult, type SpendingCheckResult, type SpendingChecker, type SpendingLimit, type SpendingLimits, type SpendingTrackerConfig, type ValidationResult, centsToDollars, createActionLogger, createFocusTrap, createMcpAdapter, createScopeRegistry, createSpendingChecker, dollarsToCents, formatScope, getPermissionLabel, getScopeLabel, getScopeShortLabel, getServiceDisplayName, getServiceIcon, hasScope, isBlockedResult, isPublicContentAction, isValidScopeString, parseScope, parseScopes, requestContentReview, requiresContentReview, tryParseScope, validateAllScopesAccess, validateScopeAccess };
+export { ACTION_STATUSES, AGENT_PLATFORM_SLUGS, AGENT_STATUSES, type Action, type ActionInput, type ActionLogger, type ActionLoggerConfig, type ActionPayload, type ActionStatus, type Agent, type AgentPlatformSlug, type AgentStatus, type ApiError, BUILT_IN_SERVICES, type BatchModeConfig, type BuiltInServiceName, CONSENT_ELEMENT_TAG, type ConsentDecision, type ConsentDeniedEventDetail, type ConsentEventDetail, type ConsentEventMap, type ConsentEventName, type ConsentGrantedEventDetail, type ConsentOptions, type ConsentPartialEventDetail, type ContentReviewRequestPayload, type ContentReviewResult, type ContentReviewStatusResponse, type FocusTrap, type McpAdapter, type McpAdapterConfig, type McpAdapterResult, type McpBlockedResult, type McpToolCall, type McpToolHandler, type McpToolResult, MulticornBadge, MulticornConsent, MulticornShield, type MulticornShieldConfig, PERMISSION_LEVELS, type Permission, type PermissionLevel, type RemainingBudget, SERVICE_NAME_PATTERN, type Scope, ScopeParseError, type ScopeParseResult, type ScopeRegistry, type ScopeRequest, type ServiceDefinition, type SpendCheckResult, type SpendingCheckResult, type SpendingChecker, type SpendingLimit, type SpendingLimits, type SpendingTrackerConfig, type ValidationResult, centsToDollars, createActionLogger, createFocusTrap, createMcpAdapter, createScopeRegistry, createSpendingChecker, dollarsToCents, formatScope, getPermissionLabel, getScopeLabel, getScopeShortLabel, getServiceDisplayName, getServiceIcon, hasScope, isBlockedResult, isPublicContentAction, isValidScopeString, parseScope, parseScopes, requestContentReview, requiresContentReview, tryParseScope, validateAllScopesAccess, validateScopeAccess };

package/dist/index.js

@@ -12,6 +12,18 @@ var __decorateClass = (decorators, target, key, kind) => {
 };
 
 // src/types/index.ts
+var AGENT_PLATFORM_SLUGS = [
+  "openclaw",
+  "claude-code",
+  "claude-desktop",
+  "cursor",
+  "windsurf",
+  "cline",
+  "gemini-cli",
+  "other-mcp",
+  "github-actions",
+  "unknown"
+];
 var AGENT_STATUSES = {
   Active: "active",
   Paused: "paused",
@@ -2890,4 +2902,4 @@ function validateApiKey(apiKey) {
   }
 }
 
-export { ACTION_STATUSES, AGENT_STATUSES, BUILT_IN_SERVICES, CONSENT_ELEMENT_TAG, MulticornBadge, MulticornConsent, MulticornShield, PERMISSION_LEVELS, SERVICE_NAME_PATTERN, ScopeParseError, centsToDollars, createActionLogger, createFocusTrap, createMcpAdapter, createScopeRegistry, createSpendingChecker, dollarsToCents, formatScope, getPermissionLabel, getScopeLabel, getScopeShortLabel, getServiceDisplayName, getServiceIcon, hasScope, isBlockedResult, isPublicContentAction, isValidScopeString, parseScope, parseScopes, requestContentReview, requiresContentReview, tryParseScope, validateAllScopesAccess, validateScopeAccess };
+export { ACTION_STATUSES, AGENT_PLATFORM_SLUGS, AGENT_STATUSES, BUILT_IN_SERVICES, CONSENT_ELEMENT_TAG, MulticornBadge, MulticornConsent, MulticornShield, PERMISSION_LEVELS, SERVICE_NAME_PATTERN, ScopeParseError, centsToDollars, createActionLogger, createFocusTrap, createMcpAdapter, createScopeRegistry, createSpendingChecker, dollarsToCents, formatScope, getPermissionLabel, getScopeLabel, getScopeShortLabel, getServiceDisplayName, getServiceIcon, hasScope, isBlockedResult, isPublicContentAction, isValidScopeString, parseScope, parseScopes, requestContentReview, requiresContentReview, tryParseScope, validateAllScopesAccess, validateScopeAccess };

package/dist/multicorn-proxy.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { existsSync } from 'fs';
+import { existsSync, statSync } from 'fs';
 import { mkdir, writeFile, readFile, copyFile, chmod, unlink } from 'fs/promises';
 import { join, dirname } from 'path';
 import { homedir } from 'os';
@@ -43,6 +43,23 @@ function withSpinner(message) {
     }
   };
 }
+var NativePluginPrerequisiteMissingError = class extends Error {
+  constructor() {
+    super("Native plugin prerequisites not met");
+    this.name = "NativePluginPrerequisiteMissingError";
+  }
+};
+function isExistingDirectory(path) {
+  try {
+    if (!existsSync(path)) return false;
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function nativePluginSkippedSaveNote(wizardCommand, productName) {
+  return "\n" + style.dim("Your agent config has been saved. Run ") + style.cyan(wizardCommand) + style.dim(` again after installing ${productName} to complete hook setup.`) + "\n";
+}
 var CONFIG_DIR = join(homedir(), ".multicorn");
 var CONFIG_PATH = join(CONFIG_DIR, "config.json");
 var OPENCLAW_CONFIG_PATH = join(homedir(), ".openclaw", "openclaw.json");
@@ -426,6 +443,18 @@ async function installWindsurfNativeHooks() {
       `Could not find Shield Windsurf hook scripts at ${srcPre}. If you use npm, install the latest multicorn-shield package.`
     );
   }
+  const windsurfConfigDir = join(homedir(), ".codeium", "windsurf");
+  if (!isExistingDirectory(windsurfConfigDir)) {
+    process.stderr.write(
+      style.yellow("\u26A0") + "  Windsurf does not appear to be installed (~/.codeium/windsurf/ not found).\n\n"
+    );
+    process.stderr.write(
+      "Open Windsurf at least once so this folder exists, or install from:\n  " + style.cyan("https://windsurf.com/download") + "\n\n"
+    );
+    process.stderr.write("Then run this wizard again:\n");
+    process.stderr.write("  " + style.cyan("npx multicorn-proxy init") + "\n");
+    throw new NativePluginPrerequisiteMissingError();
+  }
   const installDir = getWindsurfHooksInstallDir();
   await mkdir(installDir, { recursive: true });
   const destPre = join(installDir, "pre-action.cjs");
@@ -489,6 +518,19 @@ async function installClineNativeHooks() {
       `Could not find Shield Cline hook scripts at ${srcPre}. If you use npm, install the latest multicorn-shield package.`
     );
   }
+  const clineDocsDir = join(homedir(), "Documents", "Cline");
+  if (!isExistingDirectory(clineDocsDir)) {
+    process.stderr.write(
+      style.yellow("\u26A0") + "  Cline does not appear to be installed (~/Documents/Cline/ not found).\n\n"
+    );
+    process.stderr.write("Install the Cline VS Code extension first. See:\n");
+    process.stderr.write(
+      "  " + style.cyan("https://docs.cline.bot/getting-started/installing-cline") + "\n\n"
+    );
+    process.stderr.write("Then run this wizard again:\n");
+    process.stderr.write("  " + style.cyan("npx multicorn-shield init") + "\n");
+    throw new NativePluginPrerequisiteMissingError();
+  }
   const installDir = getClineHooksInstallDir();
   await mkdir(installDir, { recursive: true });
   const destPre = join(installDir, "pre-tool-use.cjs");
@@ -531,12 +573,211 @@ async function promptClineIntegrationMode(ask) {
   }
   return choice === 1 ? "native" : "hosted";
 }
+function getGeminiCliHooksInstallDir() {
+  return join(homedir(), ".multicorn", "gemini-cli-hooks");
+}
+function getGeminiCliSettingsPath() {
+  return join(homedir(), ".gemini", "settings.json");
+}
+function geminiInnerHooksReferenceShield(inner, multicornName) {
+  if (!Array.isArray(inner)) return false;
+  for (const h of inner) {
+    if (typeof h !== "object" || h === null) continue;
+    const rec = h;
+    if (rec["name"] === multicornName) return true;
+    const cmd = rec["command"];
+    if (typeof cmd === "string" && cmd.includes("gemini-cli-hooks")) return true;
+  }
+  return false;
+}
+function geminiHookEventsReferenceShield(arr) {
+  if (!Array.isArray(arr)) return false;
+  for (const entry of arr) {
+    if (typeof entry !== "object" || entry === null) continue;
+    const hooks = entry["hooks"];
+    if (geminiInnerHooksReferenceShield(hooks, "multicorn-shield") || geminiInnerHooksReferenceShield(hooks, "multicorn-shield-log")) {
+      return true;
+    }
+  }
+  return false;
+}
+function geminiSettingsHasMulticornHooks(hooks) {
+  if (hooks === null || typeof hooks !== "object" || Array.isArray(hooks)) return false;
+  const h = hooks;
+  return geminiHookEventsReferenceShield(h["BeforeTool"]) || geminiHookEventsReferenceShield(h["AfterTool"]);
+}
+function geminiFilterInnerHooks(inner) {
+  if (!Array.isArray(inner)) return [];
+  return inner.filter((h) => {
+    if (typeof h !== "object" || h === null) return true;
+    const rec = h;
+    if (rec["name"] === "multicorn-shield" || rec["name"] === "multicorn-shield-log") return false;
+    const cmd = rec["command"];
+    if (typeof cmd === "string" && cmd.includes("gemini-cli-hooks")) return false;
+    return true;
+  });
+}
+function geminiStripMatcherGroups(arr) {
+  if (!Array.isArray(arr)) return [];
+  const out = [];
+  for (const entry of arr) {
+    if (typeof entry !== "object" || entry === null) continue;
+    const e = entry;
+    const filtered = geminiFilterInnerHooks(e["hooks"]);
+    if (filtered.length > 0) {
+      out.push({ ...e, hooks: filtered });
+    }
+  }
+  return out;
+}
+function geminiStripMulticornHookEntries(hooks) {
+  const out = { ...hooks };
+  out["BeforeTool"] = geminiStripMatcherGroups(out["BeforeTool"]);
+  out["AfterTool"] = geminiStripMatcherGroups(out["AfterTool"]);
+  return out;
+}
+async function installGeminiCliNativeHooks(ask) {
+  const root = multicornShieldPackageRoot();
+  const srcBefore = join(root, "plugins", "gemini-cli", "hooks", "scripts", "before-tool.cjs");
+  const srcAfter = join(root, "plugins", "gemini-cli", "hooks", "scripts", "after-tool.cjs");
+  const srcShared = join(root, "plugins", "gemini-cli", "hooks", "scripts", "shared.cjs");
+  if (!existsSync(srcBefore) || !existsSync(srcAfter) || !existsSync(srcShared)) {
+    throw new Error(
+      `Could not find Shield Gemini CLI hook scripts at ${srcBefore}. If you use npm, install the latest multicorn-shield package.`
+    );
+  }
+  const geminiConfigDir = join(homedir(), ".gemini");
+  if (!isExistingDirectory(geminiConfigDir)) {
+    process.stderr.write(
+      style.yellow("\u26A0") + "  Gemini CLI does not appear to be installed (~/.gemini/ not found).\n\n"
+    );
+    process.stderr.write("Install Gemini CLI first:\n");
+    process.stderr.write("  " + style.cyan("npm install -g @google/gemini-cli") + "\n\n");
+    process.stderr.write("Then run this wizard again:\n");
+    process.stderr.write("  " + style.cyan("npx multicorn-shield init") + "\n");
+    throw new NativePluginPrerequisiteMissingError();
+  }
+  const installDir = getGeminiCliHooksInstallDir();
+  await mkdir(installDir, { recursive: true });
+  const destBefore = join(installDir, "before-tool.cjs");
+  const destAfter = join(installDir, "after-tool.cjs");
+  const destShared = join(installDir, "shared.cjs");
+  await copyFile(srcBefore, destBefore);
+  await copyFile(srcAfter, destAfter);
+  await copyFile(srcShared, destShared);
+  const mode = 493;
+  await chmod(destBefore, mode);
+  await chmod(destAfter, mode);
+  await chmod(destShared, mode);
+  const settingsPath = getGeminiCliSettingsPath();
+  let existing = {};
+  try {
+    const rawText = await readFile(settingsPath, "utf8");
+    const parsed = JSON.parse(rawText);
+    if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+      existing = parsed;
+    }
+  } catch (err) {
+    if (isErrnoException(err) && err.code === "ENOENT") {
+      existing = {};
+    } else {
+      process.stderr.write(
+        style.yellow("\u26A0") + ` Could not parse ${settingsPath}. Create valid JSON or remove the file, then run init again.
+`
+      );
+      throw new Error(`Invalid Gemini CLI settings at ${settingsPath}`);
+    }
+  }
+  const hooksRaw = existing["hooks"];
+  const hooksObj = typeof hooksRaw === "object" && hooksRaw !== null && !Array.isArray(hooksRaw) ? hooksRaw : {};
+  if (geminiSettingsHasMulticornHooks(hooksObj)) {
+    const answer = await ask(
+      "Existing Multicorn Shield hooks were found in ~/.gemini/settings.json. Overwrite? (Y/n) "
+    );
+    if (answer.trim().toLowerCase() === "n") {
+      throw new Error("Installation cancelled: existing Shield hooks left unchanged.");
+    }
+  }
+  const cleaned = geminiStripMulticornHookEntries({ ...hooksObj });
+  const beforeArr = Array.isArray(cleaned["BeforeTool"]) ? [...cleaned["BeforeTool"]] : [];
+  const afterArr = Array.isArray(cleaned["AfterTool"]) ? [...cleaned["AfterTool"]] : [];
+  const beforeCmd = `node ${destBefore}`;
+  const afterCmd = `node ${destAfter}`;
+  beforeArr.push({
+    matcher: ".*",
+    hooks: [
+      {
+        type: "command",
+        name: "multicorn-shield",
+        command: beforeCmd,
+        timeout: 6e4
+      }
+    ]
+  });
+  afterArr.push({
+    matcher: ".*",
+    hooks: [
+      {
+        type: "command",
+        name: "multicorn-shield-log",
+        command: afterCmd,
+        timeout: 1e4
+      }
+    ]
+  });
+  existing["hooks"] = {
+    ...cleaned,
+    BeforeTool: beforeArr,
+    AfterTool: afterArr
+  };
+  await mkdir(dirname(settingsPath), { recursive: true });
+  await writeFile(settingsPath, JSON.stringify(existing, null, 2) + "\n", "utf8");
+}
+async function promptGeminiCliIntegrationMode(ask) {
+  process.stderr.write("\n" + style.bold("Gemini CLI integration") + "\n");
+  process.stderr.write(
+    "  " + style.violet("1") + ". Native plugin (recommended) - Gemini CLI Hooks see every file, terminal, web, and MCP action\n"
+  );
+  process.stderr.write(
+    "  " + style.violet("2") + ". Hosted proxy - govern MCP traffic only (paste proxy URL into Gemini CLI settings)\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";
+}
+function getClaudeDesktopConfigPath() {
+  switch (process.platform) {
+    case "win32":
+      return join(
+        process.env["APPDATA"] ?? join(homedir(), "AppData", "Roaming"),
+        "Claude",
+        "claude_desktop_config.json"
+      );
+    case "linux":
+      return join(homedir(), ".config", "Claude", "claude_desktop_config.json");
+    default:
+      return join(
+        homedir(),
+        "Library",
+        "Application Support",
+        "Claude",
+        "claude_desktop_config.json"
+      );
+  }
+}
 var PLATFORM_LABELS = [
   "OpenClaw",
   "Claude Code",
   "Cursor",
   "Windsurf",
   "Cline",
+  "Claude Desktop",
+  "Gemini CLI",
   "Local MCP / Other"
 ];
 var PLATFORM_BY_SELECTION = {
@@ -545,14 +786,18 @@ var PLATFORM_BY_SELECTION = {
   3: "cursor",
   4: "windsurf",
   5: "cline",
-  6: "other-mcp"
+  6: "claude-desktop",
+  7: "gemini-cli",
+  8: "other-mcp"
 };
 var DEFAULT_AGENT_NAMES = {
   openclaw: "my-openclaw-agent",
   "claude-code": "my-claude-code-agent",
   cursor: "my-cursor-agent",
   windsurf: "my-windsurf-agent",
-  cline: "my-cline-agent"
+  cline: "my-cline-agent",
+  "claude-desktop": "my-claude-desktop-agent",
+  "gemini-cli": "my-gemini-cli-agent"
 };
 async function promptPlatformSelection(ask) {
   process.stderr.write(
@@ -572,13 +817,13 @@ async function promptPlatformSelection(ask) {
     );
   }
   process.stderr.write(
-    style.dim("     Pick 6 if you want to wrap a local MCP server with multicorn-proxy --wrap.") + "\n"
+    style.dim("     Pick 8 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-6): ");
+    const input = await ask("Select (1-8): ");
     const num = parseInt(input.trim(), 10);
-    if (num >= 1 && num <= 6) {
+    if (num >= 1 && num <= 8) {
       selection = num;
     }
   }
@@ -587,10 +832,10 @@ async function promptPlatformSelection(ask) {
 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"
+    "  " + style.violet("1") + ". Native plugin (recommended) - 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"
+    "  " + style.violet("2") + ". Hosted proxy - govern MCP traffic only (paste proxy URL into mcp_config)\n"
   );
   let choice = 0;
   while (choice === 0) {
@@ -699,9 +944,9 @@ async function createProxyConfig(baseUrl, apiKey, agentName, targetUrl, serverNa
   return typeof data?.["proxy_url"] === "string" ? data["proxy_url"] : "";
 }
 function printPlatformSnippet(platform, routingToken, shortName, apiKey) {
-  const usesInlineKey = platform === "cursor" || platform === "windsurf" || platform === "cline";
+  const usesInlineKey = platform === "cursor" || platform === "claude-desktop" || platform === "windsurf" || platform === "cline" || platform === "gemini-cli";
   const authHeader = usesInlineKey ? `Bearer ${apiKey}` : "Bearer YOUR_SHIELD_API_KEY";
-  const urlKey = platform === "windsurf" ? "serverUrl" : "url";
+  const urlKey = platform === "windsurf" ? "serverUrl" : platform === "gemini-cli" ? "httpUrl" : "url";
   const mcpSnippet = JSON.stringify(
     {
       mcpServers: {
@@ -720,6 +965,8 @@ 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 === "claude-desktop") {
+    process.stderr.write("\n" + style.dim(`Add this to ${getClaudeDesktopConfigPath()}:`) + "\n\n");
   } else if (platform === "windsurf") {
     process.stderr.write(
       "\n" + style.dim("Add this to ~/.codeium/windsurf/mcp_config.json:") + "\n\n"
@@ -741,6 +988,12 @@ function printPlatformSnippet(platform, routingToken, shortName, apiKey) {
         "  Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json"
       ) + "\n\n"
     );
+  } else if (platform === "gemini-cli") {
+    process.stderr.write(
+      "\n" + style.dim(
+        "Add this to ~/.gemini/settings.json (create the file if it does not exist). For project-specific config, use .gemini/settings.json in your project root. Restart Gemini CLI after saving. Run /mcp to verify the server is connected."
+      ) + "\n\n"
+    );
   } else {
     process.stderr.write("\n" + style.dim("Add this to ~/.cursor/mcp.json:") + "\n\n");
   }
@@ -764,6 +1017,9 @@ function printPlatformSnippet(platform, routingToken, shortName, apiKey) {
       ) + "\n"
     );
   }
+  if (platform === "claude-desktop") {
+    process.stderr.write(style.dim("Then restart Claude Desktop to load the MCP server.") + "\n");
+  }
   if (platform === "cline") {
     process.stderr.write(
       style.dim(
@@ -865,10 +1121,11 @@ async function runInit(explicitBaseUrl) {
   };
   let configuring = true;
   while (configuring) {
+    let postSaveNativeSkipNote = null;
     const selection = await promptPlatformSelection(ask);
     const selectedPlatform = PLATFORM_BY_SELECTION[selection] ?? "cursor";
     const selectedLabel = PLATFORM_LABELS[selection - 1] ?? "Cursor";
-    if (selection === 6) {
+    if (selection === 8) {
       const raw = existing !== null ? { ...existing } : {};
       raw["apiKey"] = apiKey;
       raw["baseUrl"] = resolvedBaseUrl;
@@ -1047,8 +1304,22 @@ An agent for ${selectedLabel} already exists: ${style.cyan(existingForPlatform.n
           });
           setupSucceeded = true;
         } catch (error) {
-          const detail = error instanceof Error ? error.message : String(error);
-          process.stderr.write(style.red("\u2717 ") + detail + "\n");
+          if (error instanceof NativePluginPrerequisiteMissingError) {
+            postSaveNativeSkipNote = nativePluginSkippedSaveNote(
+              "npx multicorn-proxy init",
+              "Windsurf"
+            );
+            configuredAgents.push({
+              selection,
+              platform: selectedPlatform,
+              platformLabel: selectedLabel,
+              agentName
+            });
+            setupSucceeded = true;
+          } else {
+            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);
@@ -1092,6 +1363,91 @@ An agent for ${selectedLabel} already exists: ${style.cyan(existingForPlatform.n
           setupSucceeded = true;
         }
       }
+    } else if (selection === 7) {
+      const geminiMode = await promptGeminiCliIntegrationMode(ask);
+      if (geminiMode === "native") {
+        try {
+          await installGeminiCliNativeHooks(ask);
+          process.stderr.write("\n" + style.bold("Shield Gemini CLI hooks installed") + "\n\n");
+          process.stderr.write(
+            style.dim("Hook scripts: ") + style.cyan(getGeminiCliHooksInstallDir()) + "\n"
+          );
+          process.stderr.write(
+            style.dim("Settings updated at ") + style.cyan("~/.gemini/settings.json") + "\n"
+          );
+          process.stderr.write(
+            style.dim(
+              "The Shield hook runs with your user permissions. It intercepts Gemini CLI tool calls to check permissions and log activity. Review the scripts if that is a concern."
+            ) + "\n"
+          );
+          configuredAgents.push({
+            selection,
+            platform: selectedPlatform,
+            platformLabel: selectedLabel,
+            agentName,
+            geminiCliIntegration: "native"
+          });
+          setupSucceeded = true;
+        } catch (error) {
+          if (error instanceof NativePluginPrerequisiteMissingError) {
+            postSaveNativeSkipNote = nativePluginSkippedSaveNote(
+              "npx multicorn-shield init",
+              "Gemini CLI"
+            );
+            configuredAgents.push({
+              selection,
+              platform: selectedPlatform,
+              platformLabel: selectedLabel,
+              agentName
+            });
+            setupSucceeded = true;
+          } else {
+            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,
+            geminiCliIntegration: "hosted"
+          });
+          setupSucceeded = true;
+        }
+      }
     } else if (selection === 5) {
       const clineMode = await promptClineIntegrationMode(ask);
       if (clineMode === "native") {
@@ -1112,8 +1468,22 @@ An agent for ${selectedLabel} already exists: ${style.cyan(existingForPlatform.n
           });
           setupSucceeded = true;
         } catch (error) {
-          const detail = error instanceof Error ? error.message : String(error);
-          process.stderr.write(style.red("\u2717 ") + detail + "\n");
+          if (error instanceof NativePluginPrerequisiteMissingError) {
+            postSaveNativeSkipNote = nativePluginSkippedSaveNote(
+              "npx multicorn-shield init",
+              "Cline"
+            );
+            configuredAgents.push({
+              selection,
+              platform: selectedPlatform,
+              platformLabel: selectedLabel,
+              agentName
+            });
+            setupSucceeded = true;
+          } else {
+            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);
@@ -1215,9 +1585,14 @@ An agent for ${selectedLabel} already exists: ${style.cyan(existingForPlatform.n
           style.green("\u2713") + ` Config saved to ${style.cyan(CONFIG_PATH)}
 `
         );
+        if (postSaveNativeSkipNote != null) {
+          process.stderr.write(postSaveNativeSkipNote);
+          postSaveNativeSkipNote = null;
+        }
       } catch (error) {
         const detail = error instanceof Error ? error.message : String(error);
         process.stderr.write(style.red(`Failed to save config: ${detail}`) + "\n");
+        postSaveNativeSkipNote = null;
       }
     }
     const another = await ask("\nConnect another agent? (Y/n) ");
@@ -1291,6 +1666,22 @@ An agent for ${selectedLabel} already exists: ${style.cyan(existingForPlatform.n
         "\n" + style.bold("To complete your Cline hosted-proxy setup:") + "\n  1. If you don't have Cline yet, install it from the VS Code marketplace\n  2. Open your Cline MCP settings file and paste the config snippet shown above\n  3. Restart Cline or reload the VS Code window\n"
       );
     }
+    const geminiCliNativeConfigured = configuredAgents.some(
+      (a) => a.platform === "gemini-cli" && a.geminiCliIntegration === "native"
+    );
+    const geminiCliHostedConfigured = configuredAgents.some(
+      (a) => a.platform === "gemini-cli" && a.geminiCliIntegration === "hosted"
+    );
+    if (geminiCliNativeConfigured) {
+      blocks.push(
+        "\n" + style.bold("Gemini CLI native hooks:") + "\n  Your Gemini CLI hooks are installed. Restart Gemini CLI to activate Shield governance.\n"
+      );
+    }
+    if (geminiCliHostedConfigured) {
+      blocks.push(
+        "\n" + style.bold("To complete your Gemini CLI setup:") + "\n  1. Open " + style.cyan("~/.gemini/settings.json") + "\n  2. Paste the config snippet shown above\n  3. Restart Gemini CLI, then run /mcp to verify\n"
+      );
+    }
     if (blocks.length > 0) {
       process.stderr.write("\n" + style.bold(style.violet("Next steps")) + "\n");
       process.stderr.write(blocks.join("") + "\n");

package/dist/shield-extension.js

@@ -22359,7 +22359,7 @@ async function writeExtensionBackup(claudeDesktopConfigPath, mcpServers) {
 
 // package.json
 var package_default = {
-  version: "0.12.0"};
+  version: "0.13.0"};
 
 // src/package-meta.ts
 var PACKAGE_VERSION = package_default.version;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "multicorn-shield",
-  "version": "0.12.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",
@@ -38,6 +38,7 @@
     "dist",
     "plugins/windsurf",
     "plugins/cline",
+    "plugins/gemini-cli",
     "LICENSE",
     "README.md",
     "CHANGELOG.md"

package/plugins/gemini-cli/hooks/scripts/after-tool.cjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+// Copyright (c) Multicorn AI Pty Ltd. MIT License. See LICENSE file.
+/**
+ * Gemini CLI AfterTool hook: audit logging to Shield.
+ * Always returns { "decision": "allow" } on stdout.
+ */
+
+"use strict";
+
+const {
+  loadConfig,
+  logPrefix,
+  mapToolName,
+  postJson,
+  readStdin,
+  scrubParameters,
+  scrubResultForMetadata,
+} = require("./shared.cjs");
+
+const HOOK_PREFIX = logPrefix("after-tool");
+
+function respond() {
+  process.stdout.write(JSON.stringify({ decision: "allow" }) + "\n");
+  process.exit(0);
+}
+
+async function main() {
+  let raw;
+  try {
+    raw = await readStdin();
+  } catch {
+    respond();
+    return;
+  }
+
+  /** @type {Record<string, unknown>} */
+  let hookPayload;
+  try {
+    hookPayload = JSON.parse(raw.length > 0 ? raw : "{}");
+  } catch {
+    respond();
+    return;
+  }
+
+  const toolName = typeof hookPayload.tool_name === "string" ? hookPayload.tool_name : "";
+  const mapped = mapToolName(toolName);
+
+  if (mapped === null) {
+    respond();
+    return;
+  }
+  const { service, actionType } = mapped;
+
+  const config = loadConfig();
+  if (config === null || config.apiKey.length === 0 || config.agentName.length === 0) {
+    respond();
+    return;
+  }
+
+  const toolInput =
+    typeof hookPayload.tool_input === "object" && hookPayload.tool_input !== null
+      ? /** @type {Record<string, unknown>} */ (hookPayload.tool_input)
+      : {};
+
+  const paramsSerialized = scrubParameters(toolInput);
+  const toolResponse = hookPayload.tool_response;
+
+  /** @type {Record<string, unknown>} */
+  const metadata = {
+    tool_name: toolName,
+    session_id: typeof hookPayload.session_id === "string" ? hookPayload.session_id : "",
+    cwd: typeof hookPayload.cwd === "string" ? hookPayload.cwd : "",
+    parameters: paramsSerialized,
+    result: scrubResultForMetadata(toolResponse),
+    source: "gemini-cli",
+  };
+
+  /** @type {Record<string, unknown>} */
+  const payload = {
+    agent: config.agentName,
+    service,
+    actionType,
+    status: "approved",
+    metadata,
+    platform: "gemini-cli",
+  };
+
+  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();
+});

package/plugins/gemini-cli/hooks/scripts/before-tool.cjs

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+// Copyright (c) Multicorn AI Pty Ltd. MIT License. See LICENSE file.
+/**
+ * Gemini CLI BeforeTool hook: asks Shield whether a tool call is allowed.
+ * Reads JSON from stdin. Writes JSON to stdout only (decision allow/deny). Logs to stderr.
+ * Fail-open on missing config or unreachable API.
+ */
+
+"use strict";
+
+const {
+  loadConfig,
+  logPrefix,
+  mapToolName,
+  postJson,
+  readStdin,
+  safeJsonParse,
+  scrubParameters,
+  unwrapData,
+  consentUrl,
+  openBrowser,
+} = require("./shared.cjs");
+
+const HOOK_PREFIX = logPrefix("before-tool");
+
+/**
+ * @param {string} decision
+ * @param {string} [reason]
+ */
+function respond(decision, reason) {
+  /** @type {Record<string, unknown>} */
+  const out = { decision };
+  if (reason !== undefined && reason.length > 0) {
+    out.reason = reason;
+  }
+  process.stdout.write(JSON.stringify(out) + "\n");
+  process.exit(0);
+}
+
+function dashboardHintUrl(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/approvals";
+    }
+    const u = new URL(raw);
+    if (u.hostname.startsWith("api.")) {
+      u.hostname = "app." + u.hostname.slice(4);
+    }
+    return `${u.origin}/approvals`;
+  } catch {
+    return "https://app.multicorn.ai/approvals";
+  }
+}
+
+/**
+ * @param {unknown} data
+ * @param {string} approvalsUrl
+ */
+function blockedReason(data, 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 `Blocked by Multicorn Shield: ${br}. Grant access at ${approvalsUrl}`;
+          }
+        }
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+  return `Blocked by Multicorn Shield. Grant access at ${approvalsUrl}`;
+}
+
+async function main() {
+  let raw;
+  try {
+    raw = await readStdin();
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    process.stderr.write(`${HOOK_PREFIX} could not read stdin (${msg}). Allowing.\n`);
+    respond("allow");
+    return;
+  }
+
+  /** @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(`${HOOK_PREFIX} invalid JSON (${msg}). Allowing.\n`);
+    respond("allow");
+    return;
+  }
+
+  const toolName = typeof hookPayload.tool_name === "string" ? hookPayload.tool_name : "";
+
+  const mapped = mapToolName(toolName);
+  if (mapped === null) {
+    respond("allow");
+    return;
+  }
+  const { service, actionType } = mapped;
+
+  const toolInput =
+    typeof hookPayload.tool_input === "object" && hookPayload.tool_input !== null
+      ? /** @type {Record<string, unknown>} */ (hookPayload.tool_input)
+      : {};
+
+  const config = loadConfig();
+  if (config === null || config.apiKey.length === 0 || config.agentName.length === 0) {
+    respond("allow");
+    return;
+  }
+
+  const paramsSerialized = scrubParameters(toolInput);
+  const approvalsUrl = dashboardHintUrl(config.baseUrl);
+
+  /** @type {Record<string, unknown>} */
+  const metadata = {
+    tool_name: toolName,
+    session_id: typeof hookPayload.session_id === "string" ? hookPayload.session_id : "",
+    cwd: typeof hookPayload.cwd === "string" ? hookPayload.cwd : "",
+    parameters: paramsSerialized,
+    source: "gemini-cli",
+  };
+
+  /** @type {Record<string, unknown>} */
+  const payload = {
+    agent: config.agentName,
+    service,
+    actionType,
+    status: "pending",
+    metadata,
+    platform: "gemini-cli",
+  };
+
+  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(`${HOOK_PREFIX} Shield API unreachable (${msg}). Allowing.\n`);
+    respond("allow");
+    return;
+  }
+
+  const parsed = safeJsonParse(bodyText);
+  const data = unwrapData(parsed);
+
+  if (statusCode === 202) {
+    const url = consentUrl(config.baseUrl, config.agentName, service, actionType);
+    openBrowser(url);
+    respond("deny", `Action blocked by Multicorn Shield. Authorise at: ${url}`);
+    return;
+  }
+
+  if (statusCode === 201) {
+    if (data === null || typeof data !== "object") {
+      const url = consentUrl(config.baseUrl, config.agentName, service, actionType);
+      respond("deny", `Action blocked by Multicorn Shield. Authorise at: ${url}`);
+      return;
+    }
+    const st = String(/** @type {Record<string, unknown>} */ (data).status || "").toLowerCase();
+    if (st === "approved") {
+      respond("allow");
+      return;
+    }
+    if (st === "blocked") {
+      respond("deny", blockedReason(data, approvalsUrl));
+      return;
+    }
+    const url = consentUrl(config.baseUrl, config.agentName, service, actionType);
+    respond("deny", `Action blocked by Multicorn Shield. Authorise at: ${url}`);
+    return;
+  }
+
+  const url = consentUrl(config.baseUrl, config.agentName, service, actionType);
+  respond("deny", `Action blocked by Multicorn Shield. Authorise at: ${url}`);
+}
+
+main().catch((e) => {
+  const msg = e instanceof Error ? e.message : String(e);
+  process.stderr.write(`${HOOK_PREFIX} unexpected error (${msg}). Allowing.\n`);
+  respond("allow");
+});

package/plugins/gemini-cli/hooks/scripts/shared.cjs

@@ -0,0 +1,319 @@
+// Copyright (c) Multicorn AI Pty Ltd. MIT License. See LICENSE file.
+
+/**
+ * @file Shared helpers for Gemini CLI BeforeTool / AfterTool Shield hooks.
+ */
+
+"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 HTTP_REQUEST_TIMEOUT_MS = 10000;
+
+/** Tools that should pass through without calling Shield (internal / UX-only). */
+const SKIP_TOOLS = new Set([
+  "save_memory",
+  "activate_skill",
+  "get_internal_docs",
+  "ask_user",
+  "write_todos",
+  "enter_plan_mode",
+  "exit_plan_mode",
+  "update_topic",
+  "complete_task",
+]);
+
+/** @type {Readonly<Record<string, { service: string; actionType: string }>>} */
+const TOOL_MAP = {
+  read_file: { service: "filesystem", actionType: "read" },
+  read_many_files: { service: "filesystem", actionType: "read" },
+  list_directory: { service: "filesystem", actionType: "read" },
+  glob: { service: "filesystem", actionType: "read" },
+  grep_search: { service: "filesystem", actionType: "read" },
+  write_file: { service: "filesystem", actionType: "write" },
+  replace: { service: "filesystem", actionType: "write" },
+  run_shell_command: { service: "terminal", actionType: "execute" },
+  google_web_search: { service: "browser", actionType: "execute" },
+  web_fetch: { service: "browser", actionType: "execute" },
+};
+
+function logPrefix(label) {
+  return `[multicorn-shield] Gemini CLI ${label}:`;
+}
+
+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);
+  });
+}
+
+function resolveGeminiCliAgentName(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 === "gemini-cli" &&
+        typeof (/** @type {{ platform?: string; name?: string }} */ (entry).name) === "string"
+      ) {
+        return /** @type {{ name: string }} */ (entry).name;
+      }
+    }
+  }
+  return typeof obj.agentName === "string" ? obj.agentName : "";
+}
+
+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 baseLower = baseUrl.toLowerCase();
+    const isHttps = baseLower.startsWith("https://");
+    const isLocal = baseLower.includes("localhost") || baseLower.includes("127.0.0.1");
+    if (!isHttps && !isLocal) {
+      process.stderr.write(
+        `${logPrefix("config")} baseUrl must use HTTPS for non-local servers. Fail-open: Shield disabled.\n`,
+      );
+      return null;
+    }
+    const agentName = resolveGeminiCliAgentName(obj);
+    return { apiKey, baseUrl, agentName };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string} toolName
+ * @returns {{ service: string; actionType: string } | null} null = skip hook API calls
+ */
+function mapToolName(toolName) {
+  const name = String(toolName || "").trim();
+  if (name.length === 0) return null;
+  if (SKIP_TOOLS.has(name)) return null;
+
+  if (name.startsWith("mcp_")) {
+    const rest = name.slice(4);
+    const idx = rest.indexOf("_");
+    if (idx <= 0) {
+      const safe = rest.replace(/[^a-zA-Z0-9._-]+/g, "_");
+      return { service: `mcp:${safe}`, actionType: "execute" };
+    }
+    const server = rest.slice(0, idx).replace(/[^a-zA-Z0-9._-]+/g, "_");
+    const tool = rest.slice(idx + 1).replace(/[^a-zA-Z0-9._-]+/g, "_");
+    return { service: `mcp:${server}.${tool}`, actionType: "execute" };
+  }
+
+  const mapped = TOOL_MAP[name];
+  if (mapped !== undefined) {
+    return mapped;
+  }
+
+  return { service: "unknown", actionType: "execute" };
+}
+
+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 hostname = u.hostname;
+    /** @type {string} */
+    const pathnamePlusSearch = u.pathname + u.search;
+    const options = {
+      hostname,
+      port,
+      path: pathnamePlusSearch,
+      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();
+  });
+}
+
+function safeJsonParse(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+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;
+}
+
+function applyParameterScrub(parameters) {
+  const scrubbedParams = { ...parameters };
+  if (typeof scrubbedParams.content === "string") {
+    scrubbedParams.content = `[${scrubbedParams.content.length} chars redacted]`;
+  }
+  if (typeof scrubbedParams.command === "string" && scrubbedParams.command.length > 200) {
+    scrubbedParams.command = scrubbedParams.command.slice(0, 200) + "... [truncated]";
+  }
+  return scrubbedParams;
+}
+
+function scrubParameters(parameters, maxLen = 4096) {
+  /** @type {Record<string, unknown>} */
+  let base = {};
+  if (typeof parameters === "object" && parameters !== null) {
+    base = { .../** @type {Record<string, unknown>} */ (parameters) };
+  } else if (typeof parameters === "string") {
+    try {
+      const p = JSON.parse(parameters);
+      if (p !== null && typeof p === "object") {
+        base = { .../** @type {Record<string, unknown>} */ (p) };
+      } else {
+        base = { raw: parameters };
+      }
+    } catch {
+      base = { raw: parameters };
+    }
+  }
+
+  const scrubbed = applyParameterScrub(base);
+  let paramsSerialized;
+  try {
+    paramsSerialized = JSON.stringify(scrubbed);
+  } catch {
+    paramsSerialized = "{}";
+  }
+  if (paramsSerialized.length > maxLen) {
+    paramsSerialized = paramsSerialized.slice(0, maxLen);
+  }
+  return paramsSerialized;
+}
+
+function scrubResultForMetadata(result) {
+  if (result === null || result === undefined) return "";
+  let s;
+  try {
+    s = typeof result === "string" ? result : JSON.stringify(result);
+  } catch {
+    s = String(result);
+  }
+  s = s.replace(/\bsk-[A-Za-z0-9_-]{8,}\b/g, "[REDACTED]");
+  s = s.replace(/\bmcs_[A-Za-z0-9_-]+\b/g, "[REDACTED]");
+  s = s.replace(/\bghp_[A-Za-z0-9]{20,}\b/g, "[REDACTED]");
+  s = s.replace(/Bearer\s+[^\s]+/gi, "[REDACTED]");
+  s = s.replace(/\b(password|token)\s*[:=]\s*[^\s]+\b/gi, "[REDACTED]");
+  if (s.length > 500) {
+    s = s.slice(0, 500) + "[truncated]";
+  }
+  return s;
+}
+
+/**
+ * @param {string} apiBaseUrl
+ * @param {string} agentName
+ * @param {string} service
+ * @param {string} actionType
+ */
+function consentUrl(apiBaseUrl, agentName, service, actionType) {
+  let origin = "https://app.multicorn.ai";
+  try {
+    const raw = String(apiBaseUrl).replace(/\/+$/, "");
+    const lower = raw.toLowerCase();
+    if (lower.includes("localhost:8080") || lower.includes("127.0.0.1:8080")) {
+      origin = "http://localhost:5173";
+    } else {
+      const u = new URL(raw);
+      if (u.hostname.startsWith("api.")) {
+        u.hostname = "app." + u.hostname.slice(4);
+      }
+      origin = u.origin;
+    }
+  } catch {
+    /* keep default */
+  }
+  const params = new URLSearchParams();
+  params.set("agent", agentName);
+  params.set("scopes", `${service}:${actionType}`);
+  params.set("platform", "gemini-cli");
+  return `${origin}/consent?${params.toString()}`;
+}
+
+/** @param {string} url */
+function openBrowser(url) {
+  try {
+    const { execFileSync } = require("node:child_process");
+    if (process.platform === "darwin") {
+      execFileSync("open", [url], { stdio: "ignore" });
+    } else if (process.platform === "win32") {
+      execFileSync("cmd.exe", ["/c", "start", "", url], {
+        stdio: "ignore",
+        windowsHide: true,
+      });
+    } else {
+      execFileSync("xdg-open", [url], { stdio: "ignore" });
+    }
+  } catch {
+    /* ignore */
+  }
+}
+
+module.exports = {
+  AUTH_HEADER,
+  logPrefix,
+  HTTP_REQUEST_TIMEOUT_MS,
+  TOOL_MAP,
+  readStdin,
+  loadConfig,
+  resolveGeminiCliAgentName,
+  mapToolName,
+  postJson,
+  safeJsonParse,
+  unwrapData,
+  scrubParameters,
+  scrubResultForMetadata,
+  consentUrl,
+  openBrowser,
+};