agentapprove 0.1.20 → 0.1.22

package/dist/cli.js

@@ -2313,9 +2313,9 @@ var source_default = chalk;
 
 // src/cli.ts
 var import_qrcode_terminal = __toESM(require_main(), 1);
-import { existsSync as existsSync2, readFileSync, writeFileSync, mkdirSync, copyFileSync, renameSync, readdirSync as readdirSync2, statSync, lstatSync, realpathSync as realpathSync2, rmSync as rmSync2 } from "fs";
-import { homedir, hostname, platform } from "os";
-import { join, dirname as dirname2 } from "path";
+import { existsSync as existsSync2, readFileSync, writeFileSync, mkdirSync, mkdtempSync, copyFileSync, renameSync, readdirSync as readdirSync2, statSync, lstatSync, realpathSync as realpathSync2, rmSync as rmSync2 } from "fs";
+import { homedir, hostname, platform, tmpdir } from "os";
+import { join, dirname as dirname2, sep as sep2 } from "path";
 import { execSync, spawnSync } from "child_process";
 import { randomBytes, createHash } from "crypto";
 
@@ -2630,8 +2630,204 @@ function shouldCreateFreshPairing(connectionMethod) {
   return connectionMethod === "qr" || connectionMethod === "copy";
 }
 
+// src/install-validation.ts
+async function safeReadText(response) {
+  try {
+    return await response.text();
+  } catch {
+    return "";
+  }
+}
+function parseErrorBody(body) {
+  if (!body)
+    return null;
+  try {
+    const parsed = JSON.parse(body);
+    if (parsed && typeof parsed === "object") {
+      return parsed;
+    }
+  } catch {}
+  return null;
+}
+async function validateExistingToken(token, apiUrl, apiVersion, options = {}) {
+  const fetchImpl = options.fetchImpl || fetch;
+  const filename = options.preflightFilename || "common.sh";
+  const url = `${apiUrl}/${apiVersion}/hooks/${filename}?format=raw`;
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      headers: {
+        Authorization: `Bearer ${token}`
+      }
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "network error";
+    return {
+      kind: "network_error",
+      summary: "cannot reach Agent Approve from this network",
+      serverMessage: message
+    };
+  }
+  const status = response.status;
+  if (response.ok) {
+    const body2 = await safeReadText(response);
+    return {
+      kind: "valid",
+      summary: "verified - token is valid",
+      cachedContent: body2,
+      status
+    };
+  }
+  const body = await safeReadText(response);
+  const parsed = parseErrorBody(body);
+  const code = parsed?.code;
+  const serverMessage = parsed?.error;
+  if (status === 401 && code === "TOKEN_EXPIRED") {
+    return {
+      kind: "expired",
+      summary: "expired (refresh required)",
+      serverMessage,
+      status
+    };
+  }
+  if (status === 401 && code === "INVALID_TOKEN") {
+    return {
+      kind: "invalid",
+      summary: "invalid (re-pair required)",
+      serverMessage,
+      status
+    };
+  }
+  if (status === 403 && code === "AUTH_SCOPE_DENIED") {
+    return {
+      kind: "scope_denied",
+      summary: "scope denied (re-pair required)",
+      serverMessage,
+      status
+    };
+  }
+  if (status === 503) {
+    return {
+      kind: "unavailable",
+      summary: "validation temporarily unavailable",
+      serverMessage,
+      status
+    };
+  }
+  if (status === 403) {
+    return {
+      kind: "network_blocked",
+      summary: "cannot reach service from this network",
+      serverMessage,
+      status
+    };
+  }
+  if (status === 401) {
+    return {
+      kind: "invalid",
+      summary: "invalid (re-pair required)",
+      serverMessage,
+      status
+    };
+  }
+  return {
+    kind: "unavailable",
+    summary: "validation temporarily unavailable",
+    serverMessage,
+    status
+  };
+}
+function classifyHookDownloadFailure(status, body) {
+  const parsed = parseErrorBody(body);
+  const code = parsed?.code;
+  if (status === 401 && code === "TOKEN_EXPIRED")
+    return "token_expired";
+  if (status === 401 && code === "INVALID_TOKEN")
+    return "token_invalid";
+  if (status === 403 && code === "AUTH_SCOPE_DENIED")
+    return "scope_denied";
+  if (status === 503)
+    return "validation_unavailable";
+  if (status === 403)
+    return "network_blocked";
+  if (status === 401)
+    return "token_invalid";
+  return "recoverable";
+}
+
+// src/copy-hook-scripts.ts
+import { writeFileSync as fsWriteFileSync } from "fs";
+import { join as pathJoin } from "path";
+async function copyHookScripts(hooksDir, token, files, options) {
+  const fetchImpl = options.fetchImpl || fetch;
+  const writeFile = options.writeFileSync || fsWriteFileSync;
+  const join = options.joinPath || pathJoin;
+  let downloaded = 0;
+  const failed = [];
+  for (const file of files) {
+    try {
+      const response = await fetchImpl(`${options.apiUrl}/${options.apiVersion}/hooks/${file}?format=raw`, {
+        headers: {
+          Authorization: `Bearer ${token}`
+        }
+      });
+      if (response.ok) {
+        const content = await response.text();
+        const isShellScript = content.startsWith("#!/") || content.startsWith("# ");
+        const isJsBundle = file.endsWith(".js") && (content.startsWith("//") || content.startsWith("import ") || content.startsWith("var ") || content.startsWith("const ") || content.startsWith("export "));
+        if (isShellScript || isJsBundle) {
+          const filePath = join(hooksDir, file);
+          writeFile(filePath, content, { mode: isShellScript ? 493 : 420 });
+          downloaded++;
+        } else {
+          failed.push(`${file} (invalid content)`);
+        }
+      } else {
+        const body = await response.text().catch(() => "");
+        const failureKind = classifyHookDownloadFailure(response.status, body);
+        if (failureKind !== "recoverable") {
+          return {
+            downloaded,
+            failed,
+            terminalFailure: {
+              kind: failureKind,
+              file,
+              status: response.status
+            }
+          };
+        }
+        failed.push(`${file} (${response.status})`);
+      }
+    } catch (err) {
+      failed.push(`${file} (${err instanceof Error ? err.message : "network error"})`);
+    }
+  }
+  return { downloaded, failed };
+}
+
+// src/pairing-api-url.ts
+function looksLikeHostedAgentApproveApi(baseUrl) {
+  try {
+    const host = new URL(baseUrl).hostname.toLowerCase();
+    return host === "agentapprove.com" || host.endsWith(".agentapprove.com");
+  } catch {
+    return false;
+  }
+}
+function resolvePairingApiBaseUrl(options) {
+  const fromEnv = options.agentapproveApiEnv?.trim();
+  if (fromEnv) {
+    return fromEnv;
+  }
+  const fromFile = options.savedApiUrl?.trim();
+  if (fromFile) {
+    return fromFile;
+  }
+  return options.processDefaultApiUrl;
+}
+
 // src/cli.ts
-var VERSION = "0.1.20";
+var VERSION = "0.1.22";
 function getApiUrl() {
   return process.env.AGENTAPPROVE_API || "https://api.agentapprove.com";
 }
@@ -2703,13 +2899,15 @@ function getCommand() {
   }
   return filtered[0] || "install";
 }
-var OPENCODE_PLUGIN_VERSION = "0.1.16";
+var OPENCODE_PLUGIN_VERSION = "0.1.18";
 var OPENCODE_PLUGIN_SPEC = `@agentapprove/opencode@${OPENCODE_PLUGIN_VERSION}`;
-var OPENCLAW_PLUGIN_VERSION = "0.2.10";
+var OPENCLAW_PLUGIN_VERSION = "0.2.11";
 var OPENCLAW_PLUGIN_SPEC = `@agentapprove/openclaw@${OPENCLAW_PLUGIN_VERSION}`;
-var PI_PLUGIN_VERSION = "0.1.5";
+var PI_PLUGIN_VERSION = "0.1.7";
 var PI_PLUGIN_SPEC = `npm:@agentapprove/pi@${PI_PLUGIN_VERSION}`;
 var PI_STATUS_TIMEOUT_MS = 5000;
+var HERMES_PLUGIN_VERSION = "0.1.0";
+var HERMES_PIP_DEPS = ["cryptography>=44.0,<46", "httpx>=0.27,<0.29"];
 var AGENTS = {
   "claude-code": {
     name: "Claude Code",
@@ -2748,6 +2946,23 @@ var AGENTS = {
       { name: "afterAgentResponse", file: "cursor-response.sh", description: "Agent response" }
     ]
   },
+  windsurf: {
+    name: "Windsurf",
+    configPath: join(homedir(), ".codeium", "windsurf", "hooks.json"),
+    hooksKey: "hooks",
+    hooks: [
+      { name: "pre_user_prompt", file: "windsurf-hook.sh", description: "User prompt (logging only)" },
+      { name: "pre_read_code", file: "windsurf-hook.sh", description: "File read approval", isApprovalHook: true },
+      { name: "post_read_code", file: "windsurf-hook.sh", description: "File read completion logging" },
+      { name: "pre_write_code", file: "windsurf-hook.sh", description: "File write approval", isApprovalHook: true },
+      { name: "post_write_code", file: "windsurf-hook.sh", description: "File write completion logging" },
+      { name: "pre_run_command", file: "windsurf-hook.sh", description: "Shell command approval", isApprovalHook: true },
+      { name: "post_run_command", file: "windsurf-hook.sh", description: "Shell command completion logging" },
+      { name: "pre_mcp_tool_use", file: "windsurf-hook.sh", description: "MCP tool approval", isApprovalHook: true },
+      { name: "post_mcp_tool_use", file: "windsurf-hook.sh", description: "MCP tool completion logging" },
+      { name: "post_cascade_response", file: "windsurf-hook.sh", description: "Cascade response (logging)" }
+    ]
+  },
   "gemini-cli": {
     name: "Gemini CLI",
     configPath: join(homedir(), ".gemini", "settings.json"),
@@ -2827,6 +3042,27 @@ var AGENTS = {
     hooks: [
       { name: "agentapprove", file: "@agentapprove/pi", description: "Tool approval + event monitoring", isApprovalHook: true, isPlugin: true }
     ]
+  },
+  hermes: {
+    name: "Hermes",
+    configPath: join(homedir(), ".hermes", "config.yaml"),
+    hooksKey: "plugins",
+    hooks: [
+      { name: "agentapprove", file: "agentapprove", description: "Tool approval + event monitoring + follow-up input", isApprovalHook: true, isPlugin: true }
+    ]
+  },
+  openhands: {
+    name: "OpenHands",
+    configPath: join(homedir(), ".openhands", "hooks.json"),
+    hooksKey: "",
+    hooks: [
+      { name: "session_start", file: "openhands-hook.sh", description: "Session started" },
+      { name: "user_prompt_submit", file: "openhands-hook.sh", description: "User prompt (logging only)" },
+      { name: "pre_tool_use", file: "openhands-hook.sh", description: "Tool approval", isApprovalHook: true, timeout: 300 },
+      { name: "post_tool_use", file: "openhands-hook.sh", description: "Tool completion logging" },
+      { name: "stop", file: "openhands-hook.sh", description: "Agent stopped (iOS input)", isApprovalHook: true, timeout: 600 },
+      { name: "session_end", file: "openhands-hook.sh", description: "Session ended" }
+    ]
   }
 };
 var SHARED_HOOK_FILES = ["common.sh"];
@@ -2874,7 +3110,24 @@ var HOOK_STATUS_LABELS = {
   userPromptSubmitted: "Prompt submitted",
   errorOccurred: "Error",
   SubagentStart: "Subagent start",
-  SubagentStop: "Subagent stop"
+  SubagentStop: "Subagent stop",
+  pre_user_prompt: "User prompt",
+  pre_read_code: "File read approval",
+  post_read_code: "File read completed",
+  pre_write_code: "File write approval",
+  post_write_code: "File write completed",
+  pre_run_command: "Shell approval",
+  post_run_command: "Shell completed",
+  pre_mcp_tool_use: "MCP approval",
+  post_mcp_tool_use: "MCP completed",
+  post_cascade_response: "Cascade response",
+  pre_tool_call: "Tool approval",
+  post_tool_call: "Tool completed",
+  pre_llm_call: "Prompt submitted",
+  post_llm_call: "Stop",
+  on_session_start: "Session start",
+  on_session_end: "Session end",
+  subagent_stop: "Subagent stop"
 };
 function findGitBash() {
   if (!isWindows())
@@ -3073,6 +3326,15 @@ function detectInstalledAgents() {
           installed.push(id);
         } catch {}
       }
+    } else if (id === "hermes") {
+      if (existsSync2(join(homedir(), ".hermes"))) {
+        installed.push(id);
+      } else {
+        try {
+          execSync("hermes --version", { stdio: "ignore" });
+          installed.push(id);
+        } catch {}
+      }
     } else {
       const configDir = dirname2(agent.configPath);
       if (existsSync2(configDir)) {
@@ -3590,10 +3852,10 @@ function disableCodexFeatureFlag(configPath = join(homedir(), ".codex", "config.
   writeFileSync(configPath, updated, { mode: 384 });
   return { updated: true, backupPath };
 }
-async function createPairingSession(configuredAgents, e2eKeyId) {
+async function createPairingSession(configuredAgents, e2eKeyId, apiBaseUrl = API_URL) {
   try {
     const machineHostname = hostname();
-    const response = await fetch(`${API_URL}/${API_VERSION}/pair`, {
+    const response = await fetch(`${apiBaseUrl}/${API_VERSION}/pair`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
@@ -3612,9 +3874,9 @@ async function createPairingSession(configuredAgents, e2eKeyId) {
     return { sessionCode: "", qrUrl: "", expiresIn: 0, error: String(err) };
   }
 }
-async function pollPairingSession(sessionCode) {
+async function pollPairingSession(sessionCode, apiBaseUrl = API_URL) {
   try {
-    const response = await fetch(`${API_URL}/${API_VERSION}/pair/${sessionCode}`);
+    const response = await fetch(`${apiBaseUrl}/${API_VERSION}/pair/${sessionCode}`);
     return await response.json();
   } catch {
     return { status: "error" };
@@ -3623,7 +3885,7 @@ async function pollPairingSession(sessionCode) {
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
-async function waitForPairing(sessionCode, onProgress, onCancel) {
+async function waitForPairing(sessionCode, onProgress, onCancel, apiBaseUrl = API_URL) {
   let cancelled = false;
   const handleKeypress = (key) => {
     const char = key.toString();
@@ -3650,14 +3912,14 @@ async function waitForPairing(sessionCode, onProgress, onCancel) {
       cleanup();
       return "cancelled";
     }
-    const result = await pollPairingSession(sessionCode);
+    const result = await pollPairingSession(sessionCode, apiBaseUrl);
     if (result.status === "completed" && result.token) {
       cleanup();
       return {
         token: result.token,
         privacy: result.privacy || "full",
         email: result.email || "",
-        apiUrl: result.apiUrl || API_URL,
+        apiUrl: result.apiUrl || apiBaseUrl,
         e2eServerKey: result.e2eServerKey
       };
     }
@@ -3911,12 +4173,27 @@ async function installHooksForAgent(agentId, hooksDir, mode = "approval") {
     }
     return { success: true, backupPath: null, hooks: [installResult.label] };
   }
+  if (agentId === "hermes") {
+    if (mode === "observe") {
+      const disableResult = disableHermesPluginViaCli();
+      if (!disableResult.success) {
+        return { success: false, backupPath: null, hooks: [], error: disableResult.error };
+      }
+      return { success: true, backupPath: null, hooks: [] };
+    }
+    const installResult = await installHermesPluginViaCli();
+    if (!installResult.success) {
+      return { success: false, backupPath: null, hooks: [], error: installResult.error };
+    }
+    return { success: true, backupPath: null, hooks: [installResult.label] };
+  }
   const backupPath = backupConfig(agent.configPath);
   const config = readJsonConfig(agent.configPath);
-  if (!config[agent.hooksKey]) {
+  const useTopLevelHooks = agent.hooksKey === "";
+  if (!useTopLevelHooks && !config[agent.hooksKey]) {
     config[agent.hooksKey] = {};
   }
-  const hooksConfig = config[agent.hooksKey];
+  const hooksConfig = useTopLevelHooks ? config : config[agent.hooksKey];
   const installedHooks = [];
   if (agentId === "openclaw") {
     const installResult = installOpenClawPluginViaCli();
@@ -4096,6 +4373,19 @@ async function installHooksForAgent(agentId, hooksDir, mode = "approval") {
         }
       }
       installedHooks.push(hook.name);
+    } else if (agentId === "windsurf") {
+      const existing = hooksConfig[hook.name];
+      const existingArray = Array.isArray(existing) ? existing : existing && typeof existing === "object" ? [existing] : typeof existing === "string" ? [{ command: existing }] : [];
+      const cleanedArray = existingArray.filter((h2) => {
+        const command = h2.command || h2.powershell || "";
+        return !command.includes("agentapprove");
+      });
+      cleanedArray.push({
+        command: hookCommand,
+        show_output: false
+      });
+      hooksConfig[hook.name] = cleanedArray;
+      installedHooks.push(hook.name);
     } else if (agentId === "gemini-cli") {
       if (!hooksConfig[hook.name]) {
         hooksConfig[hook.name] = [];
@@ -4144,6 +4434,41 @@ async function installHooksForAgent(agentId, hooksDir, mode = "approval") {
       cleanedArray.push(hookEntry);
       hooksConfig[hook.name] = cleanedArray;
       installedHooks.push(hook.name);
+    } else if (agentId === "openhands") {
+      if (!hooksConfig[hook.name]) {
+        hooksConfig[hook.name] = [];
+      }
+      const hookArray = hooksConfig[hook.name];
+      const hookTimeout = hook.timeout;
+      const isApproval = hook.isApprovalHook;
+      const existingIdx = hookArray.findIndex((h2) => h2.hooks?.some((hookScript) => {
+        if (typeof hookScript === "string")
+          return hookScript.includes("agentapprove");
+        if (typeof hookScript === "object" && hookScript.command)
+          return hookScript.command.includes("agentapprove");
+        return false;
+      }));
+      const hookObject = {
+        type: "command",
+        command: hookCommand
+      };
+      if (isApproval === true || hookTimeout !== undefined) {
+        hookObject.timeout = hookTimeout ?? 300;
+        hookObject.async = false;
+      } else {
+        hookObject.timeout = 30;
+        hookObject.async = true;
+      }
+      const hookEntry = {
+        matcher: "*",
+        hooks: [hookObject]
+      };
+      if (existingIdx >= 0) {
+        hookArray[existingIdx] = hookEntry;
+      } else {
+        hookArray.push(hookEntry);
+      }
+      installedHooks.push(hook.name);
     } else if (agentId === "copilot-cli") {
       if (typeof config["version"] !== "number") {
         config["version"] = 1;
@@ -4176,7 +4501,7 @@ async function installHooksForAgent(agentId, hooksDir, mode = "approval") {
     const approvalHooks = agent.hooks.filter((h2) => h2.isApprovalHook);
     for (const hook of approvalHooks) {
       if (hooksConfig[hook.name]) {
-        if (agentId === "claude-code" || agentId === "gemini-cli" || agentId === "codex") {
+        if (agentId === "claude-code" || agentId === "gemini-cli" || agentId === "codex" || agentId === "openhands") {
           const hookArray = hooksConfig[hook.name];
           if (Array.isArray(hookArray)) {
             const cleaned = hookArray.filter((h2) => {
@@ -4237,6 +4562,31 @@ async function installHooksForAgent(agentId, hooksDir, mode = "approval") {
               hooksConfig[hook.name] = cleaned;
             }
           }
+        } else if (agentId === "windsurf") {
+          const existing = hooksConfig[hook.name];
+          if (Array.isArray(existing)) {
+            const cleaned = existing.filter((h2) => {
+              if (typeof h2 === "object" && h2 !== null) {
+                const cmd = h2.command || h2.powershell || "";
+                return !cmd.includes("agentapprove");
+              }
+              if (typeof h2 === "string")
+                return !h2.includes("agentapprove");
+              return true;
+            });
+            if (cleaned.length === 0) {
+              delete hooksConfig[hook.name];
+            } else {
+              hooksConfig[hook.name] = cleaned;
+            }
+          } else if (typeof existing === "object" && existing !== null) {
+            const cmd = existing.command || existing.powershell || "";
+            if (cmd.includes("agentapprove")) {
+              delete hooksConfig[hook.name];
+            }
+          } else if (typeof existing === "string" && existing.includes("agentapprove")) {
+            delete hooksConfig[hook.name];
+          }
         } else if (agentId === "openclaw") {
           const pluginsObj = hooksConfig;
           const entries = pluginsObj?.entries;
@@ -4314,6 +4664,14 @@ codex_hooks = true`;
       hooksObj[hook.name] = [entry];
     }
     return JSON.stringify({ version: 1, hooks: hooksObj }, null, 2);
+  } else if (agentId === "windsurf") {
+    const hooksObj = {};
+    for (const hook of agent.hooks) {
+      const hookPath = join(hooksDir, hook.file);
+      const hookCmd = buildHookCommand(hookPath, agentId);
+      hooksObj[hook.name] = [{ command: hookCmd, show_output: false }];
+    }
+    return JSON.stringify({ hooks: hooksObj }, null, 2);
   } else if (agentId === "gemini-cli") {
     const hooksObj = {};
     for (const hook of agent.hooks) {
@@ -4361,6 +4719,23 @@ codex_hooks = true`;
       hooksObj[hook.name] = [entry];
     }
     return JSON.stringify({ version: 1, hooks: hooksObj }, null, 2);
+  } else if (agentId === "openhands") {
+    const hooksObj = {};
+    for (const hook of agent.hooks) {
+      const hookPath = join(hooksDir, hook.file);
+      const hookCmd = buildHookCommand(hookPath, agentId);
+      const hookTimeout = hook.timeout;
+      const isApproval = hook.isApprovalHook;
+      const blocking = isApproval === true || hookTimeout !== undefined;
+      const hookObject = {
+        type: "command",
+        command: hookCmd,
+        timeout: blocking ? hookTimeout ?? 300 : 30,
+        async: !blocking
+      };
+      hooksObj[hook.name] = [{ matcher: "*", hooks: [hookObject] }];
+    }
+    return JSON.stringify(hooksObj, null, 2);
   } else if (agentId === "openclaw") {
     const configJson = JSON.stringify({
       plugins: {
@@ -4424,39 +4799,50 @@ codex_hooks = true`;
       "",
       "Restart Pi to activate the extension."
     ].join(`
+`);
+  } else if (agentId === "hermes") {
+    return [
+      "Install the Agent Approve plugin for Hermes:",
+      "",
+      "  npx agentapprove                # automatic: download + verify + extract + enable",
+      "",
+      `Manual: download ${HERMES_BUNDLE_FILENAME} from your Agent Approve API,`,
+      `verify SHA-256 matches ${HERMES_BUNDLE_SHA256.slice(0, 16)}…, extract into`,
+      `~/.hermes/plugins/agentapprove/, write the SHA-256 to a .bundle-hash sidecar`,
+      "in that directory, then:",
+      "",
+      "  pip install --user cryptography httpx",
+      "  hermes plugins enable agentapprove",
+      "",
+      "The plugin reads your existing Agent Approve config from ~/.agentapprove/env.",
+      "",
+      "Hermes loads the plugin on the next session — no restart needed."
+    ].join(`
 `);
   }
   return "";
 }
-async function copyHookScripts(hooksDir, token, files) {
-  let downloaded = 0;
-  const failed = [];
-  for (const file of files) {
-    try {
-      const response = await fetch(`${API_URL}/${API_VERSION}/hooks/${file}?format=raw`, {
-        headers: {
-          Authorization: `Bearer ${token}`
-        }
-      });
-      if (response.ok) {
-        const content = await response.text();
-        const isShellScript = content.startsWith("#!/") || content.startsWith("# ");
-        const isJsBundle = file.endsWith(".js") && (content.startsWith("//") || content.startsWith("import ") || content.startsWith("var ") || content.startsWith("const ") || content.startsWith("export "));
-        if (isShellScript || isJsBundle) {
-          const filePath = join(hooksDir, file);
-          writeFileSync(filePath, content, { mode: isShellScript ? 493 : 420 });
-          downloaded++;
-        } else {
-          failed.push(`${file} (invalid content)`);
-        }
-      } else {
-        failed.push(`${file} (${response.status})`);
-      }
-    } catch (err) {
-      failed.push(`${file} (${err instanceof Error ? err.message : "network error"})`);
-    }
-  }
-  return { downloaded, failed };
+function describeDownloadTerminalFailure(kind) {
+  switch (kind) {
+    case "token_expired":
+      return "Hook download stopped: your saved token has expired. Run `npx agentapprove refresh` to re-pair, or run the installer again to choose Refresh / Re-pair.";
+    case "token_invalid":
+      return "Hook download stopped: your saved token is no longer valid. Run `npx agentapprove pair` to pair this computer again.";
+    case "scope_denied":
+      return "Hook download stopped: your saved token cannot download hooks. Run `npx agentapprove pair` to pair this computer again.";
+    case "validation_unavailable":
+      return "Hook download stopped: Agent Approve could not validate your token right now. Please try again in a few minutes.";
+    case "network_blocked":
+      return "Hook download stopped: Service temporarily unavailable. Try again later.";
+    case "recoverable":
+      return "Hook download stopped: encountered an unexpected response.";
+  }
+}
+async function copyHookScripts2(hooksDir, token, files, options = {}) {
+  return copyHookScripts(hooksDir, token, files, {
+    apiUrl: options.apiUrl || API_URL,
+    apiVersion: API_VERSION
+  });
 }
 function readOpenClawInstalledVersion() {
   const packagePath = join(homedir(), ".openclaw", "extensions", "openclaw", "package.json");
@@ -4603,6 +4989,346 @@ function removePiPluginViaCli() {
     };
   }
 }
+var HERMES_BUNDLE_SHA256 = "2572cec0a2d8467e9ffc2000e5c52cf652265d20638244a8a70e2e3a6c9d2734";
+var HERMES_BUNDLE_FILENAME = `agentapprove-hermes-${HERMES_PLUGIN_VERSION}.tar.gz`;
+var HERMES_PLUGIN_DIR = join(homedir(), ".hermes", "plugins", "agentapprove");
+function findPython() {
+  for (const candidate of ["python3.12", "python3.11", "python3.10", "python3"]) {
+    try {
+      const out = execSync(`${candidate} -c "import sys; print('%d.%d' % sys.version_info[:2])"`, {
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "ignore"]
+      }).trim();
+      const [major, minor] = out.split(".").map(Number);
+      if (major === 3 && minor >= 10) {
+        return { command: candidate, version: out };
+      }
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+function isSafeApiUrl(candidate) {
+  try {
+    const parsed = new URL(candidate);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+      return false;
+    if (!parsed.hostname)
+      return false;
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isSafeApiVersion(candidate) {
+  return /^[a-z0-9-]+$/i.test(candidate);
+}
+function readInstallerConfig() {
+  const envPath = join(getAgentApproveDir(), "env");
+  let apiUrl = API_URL;
+  let apiVersion = "v001";
+  let token = "";
+  if (existsSync2(envPath)) {
+    try {
+      const content = readFileSync(envPath, "utf-8");
+      for (const line of content.split(`
+`)) {
+        if (line.startsWith("#"))
+          continue;
+        const assignment = parseEnvAssignment(line);
+        if (!assignment)
+          continue;
+        if (assignment.key === "AGENTAPPROVE_TOKEN") {
+          token = assignment.value;
+        } else if (assignment.key === "AGENTAPPROVE_API") {
+          const normalized = assignment.value.replace(/\/+$/, "");
+          if (isSafeApiUrl(normalized)) {
+            apiUrl = normalized;
+          }
+        } else if (assignment.key === "AGENTAPPROVE_API_VERSION") {
+          const normalized = assignment.value.replace(/^\/+|\/+$/g, "");
+          if (isSafeApiVersion(normalized)) {
+            apiVersion = normalized;
+          }
+        }
+      }
+    } catch {}
+  }
+  return { apiUrl: apiUrl.replace(/\/+$/, ""), apiVersion, token };
+}
+var HERMES_BUNDLE_MAX_BYTES = 10 * 1024 * 1024;
+async function downloadHermesBundle(apiUrl, apiVersion, token) {
+  if (!isSafeApiUrl(apiUrl) || !isSafeApiVersion(apiVersion)) {
+    return { ok: false, error: `Refusing to download bundle: invalid API URL or version in ~/.agentapprove/env` };
+  }
+  let url;
+  try {
+    url = new URL(`${apiVersion}/hooks/${encodeURIComponent(HERMES_BUNDLE_FILENAME)}`, apiUrl.endsWith("/") ? apiUrl : apiUrl + "/");
+  } catch (err) {
+    return { ok: false, error: `Could not build download URL: ${err instanceof Error ? err.message : String(err)}` };
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    return { ok: false, error: `Refusing to download bundle: non-http(s) URL ${url.protocol}` };
+  }
+  let response;
+  try {
+    response = await fetch(url.toString(), {
+      headers: { Authorization: `Bearer ${token}` }
+    });
+  } catch (err) {
+    return { ok: false, error: `Network error downloading ${HERMES_BUNDLE_FILENAME}: ${err instanceof Error ? err.message : String(err)}` };
+  }
+  if (!response.ok) {
+    return { ok: false, error: `Bundle download returned ${response.status} from ${url}` };
+  }
+  const declared = parseInt(response.headers.get("content-length") || "", 10);
+  if (Number.isFinite(declared) && declared > HERMES_BUNDLE_MAX_BYTES) {
+    return { ok: false, error: `Bundle exceeds ${HERMES_BUNDLE_MAX_BYTES} byte limit (server reported ${declared}). Refusing to download.` };
+  }
+  try {
+    const buffer = await response.arrayBuffer();
+    if (buffer.byteLength > HERMES_BUNDLE_MAX_BYTES) {
+      return { ok: false, error: `Bundle body exceeded ${HERMES_BUNDLE_MAX_BYTES} byte limit (got ${buffer.byteLength}).` };
+    }
+    return { ok: true, bytes: new Uint8Array(buffer) };
+  } catch (err) {
+    return { ok: false, error: `Failed to read bundle body: ${err instanceof Error ? err.message : String(err)}` };
+  }
+}
+function verifyBundleHash(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+function validateExtractedTree(root) {
+  const realRoot = realpathSync2(root);
+  const stack = [root];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = readdirSync2(dir, { withFileTypes: true });
+    } catch (err) {
+      return { ok: false, error: `Cannot read staged dir ${dir}: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    for (const entry of entries) {
+      const fullPath = join(dir, String(entry.name));
+      let resolved;
+      try {
+        resolved = realpathSync2(fullPath);
+      } catch (err) {
+        return { ok: false, error: `Cannot resolve ${fullPath}: ${err instanceof Error ? err.message : String(err)}` };
+      }
+      if (resolved !== realRoot && !resolved.startsWith(realRoot + sep2)) {
+        return { ok: false, error: `Bundle entry escapes staging dir: ${String(entry.name)} → ${resolved}` };
+      }
+      if (!entry.isFile() && !entry.isDirectory()) {
+        return { ok: false, error: `Bundle contains non-regular entry: ${String(entry.name)} (${entry.isSymbolicLink() ? "symlink" : "other"})` };
+      }
+      if (entry.isDirectory()) {
+        stack.push(fullPath);
+      }
+    }
+  }
+  return { ok: true };
+}
+function hermesDepsAlreadyInstalled(pythonCommand) {
+  try {
+    execSync(`${pythonCommand} -c "import cryptography, httpx"`, {
+      stdio: "pipe",
+      timeout: 5000
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function installHermesPluginViaCli() {
+  try {
+    execSync("hermes --version", { stdio: "pipe" });
+  } catch {
+    return {
+      success: false,
+      label: "Agent Approve plugin",
+      error: "Hermes CLI not found on PATH. Install Hermes from https://hermes-agent.nousresearch.com first, then re-run npx agentapprove."
+    };
+  }
+  const python = findPython();
+  if (!python) {
+    return {
+      success: false,
+      label: "Agent Approve plugin",
+      error: "Python 3.10+ not found on PATH. Install Python 3.10 or newer (e.g. `brew install python@3.12`) and re-run npx agentapprove."
+    };
+  }
+  const cfg = readInstallerConfig();
+  if (!cfg.token) {
+    return {
+      success: false,
+      label: "Agent Approve plugin",
+      error: "Missing API token. Pair your phone first by running `npx agentapprove` and completing the QR scan."
+    };
+  }
+  const download = await downloadHermesBundle(cfg.apiUrl, cfg.apiVersion, cfg.token);
+  if (!download.ok) {
+    return { success: false, label: "Agent Approve plugin", error: download.error };
+  }
+  const actualHash = verifyBundleHash(download.bytes);
+  if (actualHash !== HERMES_BUNDLE_SHA256) {
+    return {
+      success: false,
+      label: "Agent Approve plugin",
+      error: `Bundle integrity check failed: expected ${HERMES_BUNDLE_SHA256.slice(0, 16)}…, got ${actualHash.slice(0, 16)}…. Refusing to install.`
+    };
+  }
+  let tmpDir;
+  try {
+    tmpDir = mkdtempSync(join(tmpdir(), "aa-hermes-"));
+  } catch (err) {
+    return {
+      success: false,
+      label: "Agent Approve plugin",
+      error: `Could not create temp directory for bundle staging: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+  const tarballPath = join(tmpDir, HERMES_BUNDLE_FILENAME);
+  let backupPath = null;
+  try {
+    writeFileSync(tarballPath, download.bytes);
+    try {
+      execSync(`tar -xzf "${tarballPath}" -C "${tmpDir}" --no-same-owner --no-same-permissions`, { stdio: "pipe" });
+    } catch (err) {
+      return {
+        success: false,
+        label: "Agent Approve plugin",
+        error: `tar extract failed: ${err instanceof Error ? err.message : String(err)}`
+      };
+    }
+    const stagedDir = join(tmpDir, "agentapprove");
+    if (!existsSync2(stagedDir)) {
+      return {
+        success: false,
+        label: "Agent Approve plugin",
+        error: "Bundle did not contain expected `agentapprove/` directory."
+      };
+    }
+    const validation = validateExtractedTree(stagedDir);
+    if (!validation.ok) {
+      return {
+        success: false,
+        label: "Agent Approve plugin",
+        error: `Bundle integrity violation: ${validation.error}`
+      };
+    }
+    mkdirSync(dirname2(HERMES_PLUGIN_DIR), { recursive: true });
+    if (existsSync2(HERMES_PLUGIN_DIR)) {
+      backupPath = `${HERMES_PLUGIN_DIR}.bak-${Date.now()}`;
+      renameSync(HERMES_PLUGIN_DIR, backupPath);
+    }
+    try {
+      renameSync(stagedDir, HERMES_PLUGIN_DIR);
+    } catch (err) {
+      if (backupPath) {
+        try {
+          renameSync(backupPath, HERMES_PLUGIN_DIR);
+          backupPath = null;
+        } catch {}
+      }
+      const restoreNote = backupPath ? ` Your previous install was preserved at ${backupPath} — recover with: mv "${backupPath}" "${HERMES_PLUGIN_DIR}"` : "";
+      return {
+        success: false,
+        label: "Agent Approve plugin",
+        error: `Could not install bundle to ${HERMES_PLUGIN_DIR}: ${err instanceof Error ? err.message : String(err)}.${restoreNote}`
+      };
+    }
+    writeFileSync(join(HERMES_PLUGIN_DIR, ".bundle-hash"), HERMES_BUNDLE_SHA256, { mode: 420 });
+    if (backupPath) {
+      rmSync2(backupPath, { recursive: true, force: true });
+      backupPath = null;
+    }
+  } catch (err) {
+    if (backupPath) {
+      try {
+        rmSync2(HERMES_PLUGIN_DIR, { recursive: true, force: true });
+        renameSync(backupPath, HERMES_PLUGIN_DIR);
+        backupPath = null;
+      } catch {}
+    }
+    const restoreNote = backupPath ? ` Your previous install was preserved at ${backupPath} — recover with: mv "${backupPath}" "${HERMES_PLUGIN_DIR}"` : "";
+    return {
+      success: false,
+      label: "Agent Approve plugin",
+      error: `Bundle install failed: ${err instanceof Error ? err.message : String(err)}.${restoreNote}`
+    };
+  } finally {
+    try {
+      rmSync2(tmpDir, { recursive: true, force: true });
+    } catch {}
+    if (backupPath && existsSync2(HERMES_PLUGIN_DIR)) {
+      try {
+        rmSync2(backupPath, { recursive: true, force: true });
+      } catch {}
+    }
+  }
+  if (!hermesDepsAlreadyInstalled(python.command)) {
+    const depsArg = HERMES_PIP_DEPS.map((d2) => `"${d2}"`).join(" ");
+    try {
+      execSync(`${python.command} -m pip install --user --quiet ${depsArg}`, { stdio: "pipe" });
+    } catch (err) {
+      return {
+        success: false,
+        label: "Agent Approve plugin",
+        error: `Installed bundle but could not install Python runtime deps: ${err instanceof Error ? err.message : String(err)}. ` + `Try manually: ${python.command} -m pip install --user ${HERMES_PIP_DEPS.join(" ")}`
+      };
+    }
+  }
+  try {
+    execSync("hermes plugins enable agentapprove", { stdio: "pipe" });
+  } catch (err) {
+    return {
+      success: false,
+      label: "Agent Approve plugin",
+      error: `Installed bundle but could not enable plugin in Hermes: ${err instanceof Error ? err.message : String(err)}. ` + `Try manually: hermes plugins enable agentapprove`
+    };
+  }
+  return { success: true, label: `Agent Approve plugin ${HERMES_PLUGIN_VERSION}` };
+}
+function isHermesDisableNoOp(err) {
+  if (!err || typeof err !== "object")
+    return false;
+  const e2 = err;
+  const stderr = Buffer.isBuffer(e2.stderr) ? e2.stderr.toString() : String(e2.stderr || "");
+  const stdout = Buffer.isBuffer(e2.stdout) ? e2.stdout.toString() : String(e2.stdout || "");
+  const haystack = `${e2.message || ""}
+${stderr}
+${stdout}`.toLowerCase();
+  return haystack.includes("not enabled") || haystack.includes("not installed") || haystack.includes("is not enabled") || haystack.includes("plugin agentapprove not found") || haystack.includes("plugin 'agentapprove' not found");
+}
+function disableHermesPluginViaCli() {
+  try {
+    execSync("hermes plugins disable agentapprove", { stdio: "pipe" });
+    return { success: true };
+  } catch (err) {
+    if (isHermesDisableNoOp(err)) {
+      return { success: true, alreadyDisabled: true };
+    }
+    return {
+      success: false,
+      error: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
+function removeHermesPlugin() {
+  const disabled = disableHermesPluginViaCli();
+  try {
+    rmSync2(HERMES_PLUGIN_DIR, { recursive: true, force: true });
+    return disabled.success ? { success: true } : { success: false, error: `disable failed: ${disabled.error || "unknown"}` };
+  } catch (err) {
+    return {
+      success: false,
+      error: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
 var SYSTEM_DEPS = [
   {
     name: "curl",
@@ -4810,16 +5536,107 @@ async function checkSystemDependencies() {
   }
   return true;
 }
+async function runExistingTokenPreflight(token, apiUrlForPreflight) {
+  const preflightSpinner = _2();
+  preflightSpinner.start("Checking saved token");
+  let result = await validateExistingToken(token, apiUrlForPreflight, API_VERSION);
+  if (result.kind === "unavailable" || result.kind === "network_error") {
+    const message = result.kind === "unavailable" ? "Token validation is temporarily unavailable." : "Could not reach Agent Approve from this network.";
+    preflightSpinner.stop(message);
+    const retryChoice = await le({
+      message: "How would you like to continue?",
+      options: [
+        { value: "retry", label: "Retry" },
+        { value: "cancel", label: "Cancel" }
+      ]
+    });
+    if (lD(retryChoice) || retryChoice === "cancel") {
+      he("Installation cancelled");
+      process.exit(0);
+    }
+    preflightSpinner.start("Checking saved token");
+    result = await validateExistingToken(token, apiUrlForPreflight, API_VERSION);
+  }
+  switch (result.kind) {
+    case "valid":
+      preflightSpinner.stop("Saved token verified");
+      break;
+    case "expired":
+      preflightSpinner.stop("Saved token has expired");
+      break;
+    case "invalid":
+    case "scope_denied":
+      preflightSpinner.stop("Saved token is no longer valid");
+      break;
+    case "network_blocked":
+      preflightSpinner.stop("Service temporarily unavailable");
+      break;
+    default:
+      preflightSpinner.stop("Saved token check finished");
+  }
+  return result;
+}
+function describeExistingTokenStatus(preflight) {
+  if (!preflight) {
+    return "already linked to your Agent Approve account";
+  }
+  switch (preflight.kind) {
+    case "valid":
+      return "verified - linked to your Agent Approve account";
+    case "expired":
+      return "expired (refresh required)";
+    case "invalid":
+      return "invalid (re-pair required)";
+    case "scope_denied":
+      return "scope denied (re-pair required)";
+    case "unavailable":
+      return "validation temporarily unavailable";
+    case "network_blocked":
+      return "cannot reach service from this network";
+    case "network_error":
+      return "cannot reach Agent Approve from this network";
+  }
+}
+async function promptTokenRecoveryAction(preflight) {
+  if (preflight.kind === "expired") {
+    const choice2 = await le({
+      message: "Your saved token has expired. How would you like to continue?",
+      options: [
+        { value: "refresh", label: "Refresh token", hint: "Keeps the existing encryption key and current settings" },
+        { value: "repair", label: "Pair this computer again", hint: "You can rotate the encryption key" },
+        { value: "cancel", label: "Cancel", hint: "Exit the installer" }
+      ]
+    });
+    if (lD(choice2))
+      return "cancel";
+    return choice2;
+  }
+  const choice = await le({
+    message: "Your saved token is no longer valid. How would you like to continue?",
+    options: [
+      { value: "repair", label: "Pair this computer again" },
+      { value: "cancel", label: "Cancel", hint: "Exit the installer" }
+    ]
+  });
+  if (lD(choice))
+    return "cancel";
+  return choice;
+}
 async function installCommand() {
   console.clear();
   pe(source_default.bgCyan.black(" Agent Approve ") + source_default.gray(` Hooks Installer v${VERSION}`));
   migrateE2ERootKey();
-  const isCustomApi = !API_URL.includes("agentapprove.com");
-  if (isCustomApi) {
-    v2.warn(`Using custom API: ${API_URL}`);
-  }
   await checkSystemDependencies();
   const existingConfig = readExistingConfig();
+  const pairingApiBase = resolvePairingApiBaseUrl({
+    agentapproveApiEnv: process.env.AGENTAPPROVE_API,
+    savedApiUrl: existingConfig?.apiUrl,
+    processDefaultApiUrl: API_URL
+  });
+  const isCustomApi = !looksLikeHostedAgentApproveApi(pairingApiBase);
+  if (isCustomApi) {
+    v2.warn(`Using custom API: ${pairingApiBase}`);
+  }
   const hasExistingToken = !!(existingConfig?.token && existingConfig.token.length > 10);
   let existingTokenPreview = "Not set";
   let existingKeyId = null;
@@ -4831,8 +5648,14 @@ async function installCommand() {
       existingKeyId = createHash("sha256").update(Buffer.from(keyHex, "hex")).digest("hex").slice(0, 8);
     }
   }
+  const existingTokenPreflight = hasExistingToken ? await runExistingTokenPreflight(existingConfig.token, pairingApiBase) : null;
+  if (existingTokenPreflight?.kind === "network_blocked") {
+    v2.error("Service temporarily unavailable. Try again later.");
+    he("Installation cancelled");
+    process.exit(1);
+  }
   me(`Approve AI agent actions from your iPhone or Apple Watch.
-Installs hooks and extensions for Cursor, Claude, Gemini, Pi, OpenCode, OpenClaw, and more.`, "About");
+Installs hooks and extensions for Cursor, Windsurf, Claude, Gemini, Pi, OpenCode, OpenClaw, and more.`, "About");
   const installedAgents = detectInstalledAgents();
   const agentOptions = Object.entries(AGENTS).map(([id, agent]) => ({
     value: id,
@@ -4850,7 +5673,7 @@ Installs hooks and extensions for Cursor, Claude, Gemini, Pi, OpenCode, OpenClaw
     process.exit(0);
   }
   const setupProfileSummary = existingConfig ? formatSetupProfileBlock("Existing config", getInitialInstallConfig("existing-config", existingConfig), [
-    `Connection token: ${existingTokenPreview} - already linked to your Agent Approve account.`,
+    `Connection token: ${existingTokenPreview} - ${describeExistingTokenStatus(existingTokenPreflight)}.`,
     ...existingKeyId ? [`Encryption key ID: ${existingKeyId} - already installed for this computer.`] : []
   ]) : formatSetupProfileBlock("Recommended setup", getInitialInstallConfig("recommended", existingConfig));
   me(setupProfileSummary, "Setup profiles");
@@ -4862,13 +5685,23 @@ Installs hooks and extensions for Cursor, Claude, Gemini, Pi, OpenCode, OpenClaw
     he("Installation cancelled");
     process.exit(0);
   }
+  let pendingRecoveryAction = null;
+  if (hasExistingToken && existingTokenPreflight && (existingTokenPreflight.kind === "expired" || existingTokenPreflight.kind === "invalid" || existingTokenPreflight.kind === "scope_denied")) {
+    pendingRecoveryAction = await promptTokenRecoveryAction(existingTokenPreflight);
+    if (pendingRecoveryAction === "cancel") {
+      he("Installation cancelled");
+      process.exit(0);
+    }
+  }
+  const requiresFreshPair = pendingRecoveryAction !== null;
+  const forceKeyReuseForRecovery = pendingRecoveryAction === "refresh";
   ensureAgentApproveDir();
   const hooksDir = join(getAgentApproveDir(), "hooks");
   const selectedInstallConfig = getInitialInstallConfig(setupProfile, existingConfig);
   let token = null;
   let finalPrivacy = selectedInstallConfig.privacy;
   let email = "";
-  let apiUrl = API_URL;
+  let apiUrl = pairingApiBase;
   let debugLog = selectedInstallConfig.debugLog;
   let retentionDays = selectedInstallConfig.retentionDays;
   let failBehavior = selectedInstallConfig.failBehavior;
@@ -4956,7 +5789,8 @@ Installs hooks and extensions for Cursor, Claude, Gemini, Pi, OpenCode, OpenClaw
     if (existsSync2(existingKeyPath)) {
       const oldKeyHex = readFileSync(existingKeyPath, "utf-8").trim();
       const oldKeyId = createHash("sha256").update(Buffer.from(oldKeyHex, "hex")).digest("hex").slice(0, 8);
-      if (setupProfile === "existing-config") {
+      const autoReuseKey = forceKeyReuseForRecovery || setupProfile === "existing-config" && !requiresFreshPair;
+      if (autoReuseKey) {
         e2eUserKey = oldKeyHex;
       } else {
         v2.info(`Existing E2E key found (Key ID: ${oldKeyId})`);
@@ -5014,9 +5848,10 @@ Installs hooks and extensions for Cursor, Claude, Gemini, Pi, OpenCode, OpenClaw
     }
     debugLog = debugLogChoice;
   }
-  const silentlyReuseExistingToken = setupProfile === "existing-config" && hasExistingToken;
+  const canReuseExistingToken = hasExistingToken && !requiresFreshPair;
+  const silentlyReuseExistingToken = setupProfile === "existing-config" && canReuseExistingToken;
   const connectionOptions = [];
-  if (hasExistingToken) {
+  if (canReuseExistingToken) {
     const tokenPreview = existingConfig.token.slice(0, 15) + "...";
     connectionOptions.push({
       value: "existing",
@@ -5024,10 +5859,20 @@ Installs hooks and extensions for Cursor, Claude, Gemini, Pi, OpenCode, OpenClaw
       hint: tokenPreview
     });
   }
-  connectionOptions.push({ value: "qr", label: "Scan QR code", hint: hasExistingToken ? undefined : "Recommended" }, { value: "copy", label: "Copy and paste code", hint: "No camera" });
+  connectionOptions.push({ value: "qr", label: "Scan QR code", hint: canReuseExistingToken ? undefined : "Recommended" }, { value: "copy", label: "Copy and paste code", hint: "No camera" });
   let connectionMethod;
   if (silentlyReuseExistingToken) {
     connectionMethod = "existing";
+  } else if (requiresFreshPair) {
+    const connectionChoice = await le({
+      message: pendingRecoveryAction === "refresh" ? "How would you like to refresh the token?" : "How would you like to pair this computer?",
+      options: connectionOptions
+    });
+    if (lD(connectionChoice)) {
+      he("Installation cancelled");
+      process.exit(0);
+    }
+    connectionMethod = connectionChoice;
   } else {
     const connectionChoice = await le({
       message: "Connect to iOS app (required for setup and any hook downloads)",
@@ -5041,7 +5886,7 @@ Installs hooks and extensions for Cursor, Claude, Gemini, Pi, OpenCode, OpenClaw
   }
   if (connectionMethod === "existing") {
     token = existingConfig.token;
-    apiUrl = existingConfig.apiUrl || API_URL;
+    apiUrl = pairingApiBase;
     if (setupProfile === "existing-config" && existingConfig?.configSetAt) {
       configSetAt = existingConfig.configSetAt;
     }
@@ -5067,7 +5912,7 @@ Installs hooks and extensions for Cursor, Claude, Gemini, Pi, OpenCode, OpenClaw
       configSetAt,
       e2eEnabled: useE2E
     };
-    const session = await createPairingSession(selectedAgents, e2eKeyId);
+    const session = await createPairingSession(selectedAgents, e2eKeyId, pairingApiBase);
     if (!session || session.error) {
       v2.error(`Failed to create pairing session: ${session?.error || "Unknown error"}`);
       he("Cannot continue without token");
@@ -5093,7 +5938,7 @@ Installs hooks and extensions for Cursor, Claude, Gemini, Pi, OpenCode, OpenClaw
         const minutes = Math.floor(expiresIn / 60);
         const seconds = expiresIn % 60;
         pairingSpinner.message(`Waiting for iOS app... ${minutes}:${seconds.toString().padStart(2, "0")}`);
-      }, () => {});
+      }, () => {}, pairingApiBase);
       if (result === "cancelled") {
         pairingSpinner.stop("Cancelled");
         he("Installation cancelled");
@@ -5102,6 +5947,7 @@ Installs hooks and extensions for Cursor, Claude, Gemini, Pi, OpenCode, OpenClaw
         token = result.token;
         finalPrivacy = result.privacy;
         email = result.email;
+        apiUrl = result.apiUrl || pairingApiBase;
         if (e2eUserKey && e2eKeyId) {
           const rootKeyPath = join(agentApproveDir, "e2e-root-key");
           writeFileSync(rootKeyPath, e2eUserKey, { mode: 384 });
@@ -5152,9 +5998,15 @@ Installs hooks and extensions for Cursor, Claude, Gemini, Pi, OpenCode, OpenClaw
   if (hookDownloadPlan.files.length > 0) {
     const downloadSpinner = _2();
     downloadSpinner.start("Downloading hook scripts");
-    const downloadResult = await copyHookScripts(hooksDir, token, hookDownloadPlan.files);
+    const downloadResult = await copyHookScripts2(hooksDir, token, hookDownloadPlan.files, { apiUrl });
     const summary = formatHookDownloadSummary(hookDownloadPlan);
-    if (downloadResult.failed.length > 0) {
+    if (downloadResult.terminalFailure) {
+      downloadSpinner.stop(`Downloaded ${downloadResult.downloaded} of ${hookDownloadPlan.files.length} hook files (${summary})`);
+      const message = describeDownloadTerminalFailure(downloadResult.terminalFailure.kind);
+      v2.error(message);
+      he("Hook download stopped before completion.");
+      process.exit(1);
+    } else if (downloadResult.failed.length > 0) {
       downloadSpinner.stop(`Downloaded ${downloadResult.downloaded} of ${hookDownloadPlan.files.length} hook files (${summary})`);
       v2.warn(`Failed to download: ${downloadResult.failed.join(", ")}`);
     } else {
@@ -5217,6 +6069,9 @@ AGENTAPPROVE_E2E_MODE=${installMode}
       if (agentId === "pi") {
         filesToModify.push("Pi package registry (via `pi install`)");
       }
+      if (agentId === "hermes") {
+        filesToModify.push(`Hermes plugin directory (download + verify ${HERMES_BUNDLE_FILENAME} → extract to ~/.hermes/plugins/agentapprove/ → \`hermes plugins enable agentapprove\`)`);
+      }
       if (agentId === "vscode-agent") {
         const vsCodeVariants = findInstalledVSCodeVariants();
         for (const { path: settingsPath, variant } of vsCodeVariants) {
@@ -5238,7 +6093,7 @@ Backups will be created with timestamp`, "Files to be modified");
     for (const agentId of selectedAgents) {
       const agent = AGENTS[agentId];
       const spinner = _2();
-      const spinnerMsg = agentId === "pi" ? `Installing ${agent.name} extension` : agentId === "openclaw" ? `Installing ${agent.name} plugin` : `Configuring ${agent.name}`;
+      const spinnerMsg = agentId === "pi" ? `Installing ${agent.name} extension` : agentId === "openclaw" || agentId === "hermes" ? `Installing ${agent.name} plugin` : `Configuring ${agent.name}`;
       spinner.start(spinnerMsg);
       const result = await installHooksForAgent(agentId, hooksDir, installMode);
       if (result.success) {
@@ -5279,6 +6134,17 @@ Backups will be created with timestamp`, "Files to be modified");
           v2.warn(`Could not install ${PI_PLUGIN_SPEC} via Pi.
 ` + `  Error: ${result.error || "unknown"}
 ` + `  Install manually: pi install ${PI_PLUGIN_SPEC}
+` + `  Then re-run: npx agentapprove`);
+        } else if (agentId === "hermes") {
+          v2.warn(`Could not install Agent Approve plugin for Hermes.
+` + `  Error: ${result.error || "unknown"}
+` + `  Install manually:
+` + `    1. Download ${HERMES_BUNDLE_FILENAME} from your Agent Approve API
+` + `    2. Verify SHA-256 matches ${HERMES_BUNDLE_SHA256.slice(0, 16)}…
+` + `    3. Extract into ~/.hermes/plugins/agentapprove/
+` + `    4. Write the SHA-256 to ~/.hermes/plugins/agentapprove/.bundle-hash
+` + `    5. pip install --user cryptography httpx
+` + `    6. hermes plugins enable agentapprove
 ` + `  Then re-run: npx agentapprove`);
         }
       }
@@ -5354,6 +6220,22 @@ async function statusCommand() {
       } catch {}
       continue;
     }
+    if (agentId === "hermes") {
+      try {
+        const listOutput = execSync("hermes plugins list", {
+          encoding: "utf-8",
+          stdio: ["pipe", "pipe", "ignore"],
+          timeout: PI_STATUS_TIMEOUT_MS
+        });
+        const enabled = /^.*agentapprove.*enabled/im.test(listOutput);
+        if (enabled) {
+          console.log(`  ${source_default.green("✓")} ${agent.name}: Agent Approve plugin`);
+        } else if (listOutput.includes("agentapprove")) {
+          console.log(`  ${source_default.yellow("⚠")} ${agent.name}: Agent Approve plugin installed but disabled (run: hermes plugins enable agentapprove)`);
+        }
+      } catch {}
+      continue;
+    }
     if (existsSync2(agent.configPath)) {
       const config = readJsonConfig(agent.configPath);
       if (agentId === "opencode") {
@@ -5370,7 +6252,7 @@ async function statusCommand() {
         }
         continue;
       }
-      const hooksConfig = config[agent.hooksKey];
+      const hooksConfig = agent.hooksKey === "" ? config : config[agent.hooksKey];
       if (hooksConfig) {
         const installedHooks = agent.hooks.filter((h2) => {
           const hookEntry = hooksConfig[h2.name];
@@ -5450,10 +6332,19 @@ async function performUninstall(mode) {
       }
       continue;
     }
+    if (agentId === "hermes") {
+      const result = removeHermesPlugin();
+      if (result.success) {
+        console.log(`  ${source_default.green("✓")} Hermes plugin disabled and removed`);
+      } else {
+        console.log(`  ${source_default.yellow("⚠")} Hermes plugin removal partial (${result.error || "unknown error"})`);
+      }
+      continue;
+    }
     if (!existsSync2(agent.configPath))
       continue;
     const config = readJsonConfig(agent.configPath);
-    const hooksConfig = config[agent.hooksKey] ?? {};
+    const hooksConfig = agent.hooksKey === "" ? config : config[agent.hooksKey] ?? {};
     let modified = false;
     if (agentId === "opencode") {
       const pluginArray = config.plugin;
@@ -5697,10 +6588,15 @@ async function refreshCommand() {
     v2.error('No existing configuration found. Run "npx agentapprove install" first.');
     process.exit(1);
   }
+  const pairingApiBase = resolvePairingApiBaseUrl({
+    agentapproveApiEnv: process.env.AGENTAPPROVE_API,
+    savedApiUrl: existingConfig?.apiUrl,
+    processDefaultApiUrl: API_URL
+  });
   me(`Your API token has expired (30 days). Tokens extend automatically on use,
 but if unused for 30 days they expire. Get a new one below.`, "Token Expired");
   let token = null;
-  let apiUrl = API_URL;
+  let apiUrl = pairingApiBase;
   const installedAgents = detectInstalledAgents();
   const e2eEnabled = existingConfig.e2eEnabled !== false;
   const e2eKeyPath = join(getAgentApproveDir(), "e2e-key");
@@ -5727,7 +6623,7 @@ but if unused for 30 days they expire. Get a new one below.`, "Token Expired");
     configSetAt,
     e2eEnabled
   };
-  const session = await createPairingSession(installedAgents.length > 0 ? installedAgents : undefined, e2eKeyId);
+  const session = await createPairingSession(installedAgents.length > 0 ? installedAgents : undefined, e2eKeyId, pairingApiBase);
   if (!session || session.error) {
     v2.error(`Failed to create pairing session: ${session?.error || "Unknown error"}`);
     process.exit(1);
@@ -5753,13 +6649,14 @@ but if unused for 30 days they expire. Get a new one below.`, "Token Expired");
     const minutes = Math.floor(expiresIn / 60);
     const seconds = expiresIn % 60;
     pairingSpinner.message(`Waiting for iOS app... ${minutes}:${seconds.toString().padStart(2, "0")}`);
-  }, () => {});
+  }, () => {}, pairingApiBase);
   if (result === "cancelled") {
     pairingSpinner.stop("Cancelled");
     he("Refresh cancelled");
     process.exit(0);
   } else if (result) {
     token = result.token;
+    apiUrl = result.apiUrl || pairingApiBase;
     pairingSpinner.stop(`Connected! ${result.email ? `Account: ${result.email}` : ""}`);
   } else {
     pairingSpinner.stop("Session expired");
@@ -5797,6 +6694,11 @@ async function pairCommand() {
   console.clear();
   pe(source_default.bgCyan.black(" Agent Approve ") + source_default.gray(" Device Pairing"));
   const existingConfig = readExistingConfig();
+  const pairingApiBase = resolvePairingApiBaseUrl({
+    agentapproveApiEnv: process.env.AGENTAPPROVE_API,
+    savedApiUrl: existingConfig?.apiUrl,
+    processDefaultApiUrl: API_URL
+  });
   const keys = discoverE2EKeys();
   if (keys.length === 0 && !existingConfig) {
     v2.error("No E2E keys or configuration found.");
@@ -5887,7 +6789,7 @@ async function pairCommand() {
     configSetAt: pairingConfigSetAt,
     e2eEnabled: !!e2eUserKey
   };
-  const session = await createPairingSession(installedAgents.length > 0 ? installedAgents : undefined, e2eKeyId);
+  const session = await createPairingSession(installedAgents.length > 0 ? installedAgents : undefined, e2eKeyId, pairingApiBase);
   if (!session || session.error) {
     v2.error(`Failed to create pairing session: ${session?.error || "Unknown error"}`);
     process.exit(1);
@@ -5913,7 +6815,7 @@ async function pairCommand() {
     const minutes = Math.floor(expiresIn / 60);
     const seconds = expiresIn % 60;
     pairingSpinner.message(`Waiting for iOS app... ${minutes}:${seconds.toString().padStart(2, "0")}`);
-  }, () => {});
+  }, () => {}, pairingApiBase);
   if (result === "cancelled") {
     pairingSpinner.stop("Cancelled");
     he("Pairing cancelled");
@@ -5943,7 +6845,7 @@ async function pairCommand() {
       writeFileSync(serverKeyPath, result.e2eServerKey, { mode: 384 });
     }
   }
-  const apiUrl = API_URL;
+  const apiUrl = result.apiUrl || pairingApiBase;
   const configSetAt = Math.floor(Date.now() / 1000);
   saveEnvConfig({
     apiUrl,
@@ -5992,7 +6894,9 @@ async function updateHookScriptsWithToken(token, apiUrl) {
     "cursor-thought.sh",
     "cursor-response.sh",
     "gemini-approval.sh",
-    "gemini-complete.sh"
+    "gemini-complete.sh",
+    "windsurf-hook.sh",
+    "openhands-hook.sh"
   ];
   for (const file of hookFiles) {
     const filePath = join(hooksDir, file);