@getmarrow/install 0.1.67 → 0.1.69

package/src/installer.js

@@ -8,6 +8,7 @@ const {
   controllerStatus,
   controllerSupportedPlatform,
   ensureCurrentGovernanceController,
+  stopProjectControllers,
 } = require('./controller-manager');
 const { firstCapturePath, harnessReloadPlan } = require('./first-hour');
 const { evidence: localControlEvidence } = require('./control-state');
@@ -19,15 +20,26 @@ const {
   planHermesMcpConfig,
 } = require('./hermes-config');
 const { ensureOwnerApiKey, readOwnerApiKey } = require('./owner-env');
+const {
+  delocalizeHookCommand,
+  ensureMcpRuntime,
+  localizeHookSettingsText,
+  mapHookCommands,
+  removeMcpRuntime,
+  verifyMcpRuntime,
+} = require('./mcp-runtime');
+const {
+  MCP_ADAPTER_VERSION,
+  MCP_ADAPTER_SOURCE_SHA,
+  MCP_ADAPTER_INTEGRITY,
+  MCP_HOST_APPROVAL_HOOKS_SINCE,
+  SDK_ADAPTER_VERSION,
+  SDK_ADAPTER_INTEGRITY,
+} = require('./pins');
 
 const DEFAULT_BASE_URL = 'https://api.getmarrow.ai';
 const MARROW_BLOCK_START = '<!-- marrow:passive-start -->';
 const MARROW_BLOCK_END = '<!-- marrow:passive-end -->';
-const MCP_ADAPTER_VERSION = '3.9.98';
-const MCP_ADAPTER_SOURCE_SHA = 'e40d3cb40479456fd937bce0b9488eb0c3f10863';
-const MCP_ADAPTER_INTEGRITY = 'sha512-AmDT3afwdm7+Dc555zDs+yGIG4RyC/YbaQm+9O1mThlC6g/9EujTr7y7UvRMEtYDvVWAAaG6CFM7/u/ytjKhwQ==';
-const SDK_ADAPTER_VERSION = '3.7.64';
-const SDK_ADAPTER_INTEGRITY = 'sha512-8qJj/8ouHEz1NnZkmujtFxUm/fWldqR/rHv62/sqabaxT0H90xCCHxodLOkV0SVxDscAtnahioZakqkeGNUwyA==';
 const SDK_ADAPTER_TARBALL = `https://registry.npmjs.org/@getmarrow/sdk/-/sdk-${SDK_ADAPTER_VERSION}.tgz`;
 const MCP_PACKAGE_SPEC = `@getmarrow/mcp@${MCP_ADAPTER_VERSION}`;
 const ADAPTER_PROVENANCE = Object.freeze({
@@ -97,6 +109,12 @@ function compatibleMcpTargetVersion(value) {
     && compareMcpVersions(value, MCP_ADAPTER_VERSION) >= 0);
 }
 
+// Whether an MCP version answers the host-approval hooks (see MCP_HOST_APPROVAL_HOOKS_SINCE).
+function hostApprovalHooksSupported(version = MCP_ADAPTER_VERSION) {
+  const comparison = compareMcpVersions(version, MCP_HOST_APPROVAL_HOOKS_SINCE);
+  return comparison !== null && comparison >= 0;
+}
+
 function mcpVersionsInText(value) {
   return [...String(value || '').matchAll(/@getmarrow\/mcp@(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/g)]
     .map((match) => match[1]);
@@ -248,6 +266,11 @@ const MCP_CONTEXT_HOOK_COMMAND = `npx -y --package=${MCP_PACKAGE_SPEC} marrow-mc
 const MCP_PRE_ACTION_HOOK_COMMAND = `npx -y --package=${MCP_PACKAGE_SPEC} marrow-mcp claude-pre-action-hook`;
 const MCP_ACTION_RESULT_HOOK_COMMAND = `npx -y --package=${MCP_PACKAGE_SPEC} marrow-mcp claude-hook`;
 const MCP_SESSION_END_HOOK_COMMAND = `npx -y --package=${MCP_PACKAGE_SPEC} marrow-mcp claude-session-hook`;
+// Host approvals: a pass-through PermissionRequest hook (installed async) that only notes that
+// Claude Code is about to show its own permission dialog for a held call, and PostToolBatch
+// (async, the result entrypoint) that settles a declined dialog. Same spelling and fields as
+// `marrow-mcp setup` writes, so neither writer rewrites the other.
+const MCP_PERMISSION_REQUEST_HOOK_COMMAND = `npx -y --package=${MCP_PACKAGE_SPEC} marrow-mcp claude-permission-request-hook`;
 const CODEX_CONTEXT_HOOK_COMMAND = `npx -y --package=${MCP_PACKAGE_SPEC} marrow-mcp codex-context-hook`;
 const CODEX_PRE_ACTION_HOOK_COMMAND = `npx -y --package=${MCP_PACKAGE_SPEC} marrow-mcp codex-pre-action-hook`;
 const CODEX_ACTION_RESULT_HOOK_COMMAND = `npx -y --package=${MCP_PACKAGE_SPEC} marrow-mcp codex-hook`;
@@ -255,6 +278,29 @@ const CODEX_SESSION_END_HOOK_COMMAND = `npx -y --package=${MCP_PACKAGE_SPEC} mar
 const CURSOR_PRE_ACTION_HOOK_COMMAND = `npx -y --package=${MCP_PACKAGE_SPEC} marrow-mcp cursor-pre-action-hook`;
 const CURSOR_ACTION_RESULT_HOOK_COMMAND = `npx -y --package=${MCP_PACKAGE_SPEC} marrow-mcp cursor-hook`;
 const CURSOR_SESSION_END_HOOK_COMMAND = `npx -y --package=${MCP_PACKAGE_SPEC} marrow-mcp cursor-session-hook`;
+const CURSOR_CONTEXT_HOOK_COMMAND = `npx -y --package=${MCP_PACKAGE_SPEC} marrow-mcp cursor-context-hook`;
+// Cursor's beforeMCPExecution takes no matcher, so this guard answers allow at once for
+// Marrow's own tools (server "marrow", tools marrow_*), as the old preToolUse matcher exempted
+// them, without starting npx. Every other call goes to the MCP entrypoint with its input
+// unchanged; a crash, a non-zero exit or output that is not a JSON object blocks (exit 2).
+const CURSOR_MCP_GUARD_FAILURE = 'Marrow governance adapter was unavailable; this MCP call is blocked.';
+const CURSOR_MCP_PRE_ACTION_GUARD_SOURCE = [
+  'const {spawn}=require("node:child_process");',
+  'const chunks=[];let size=0,over=false,done=false;',
+  `const fail=()=>{if(done)return;done=true;process.exitCode=2;process.stderr.write(${JSON.stringify(`${CURSOR_MCP_GUARD_FAILURE}\n`)},()=>process.exit(2));};`,
+  'process.stdin.on("error",fail);',
+  'process.stdin.on("data",c=>{size+=c.length;if(size>16777216){over=true;return;}chunks.push(c);});',
+  'process.stdin.on("end",()=>{if(over){fail();return;}const raw=Buffer.concat(chunks);let ev=null;try{ev=JSON.parse(raw.toString("utf8"));}catch{ev=null;}',
+  'if(ev&&typeof ev==="object"&&ev.mcp_server_name==="marrow"&&typeof ev.tool_name==="string"&&/^marrow_[a-z0-9_]{1,64}$/.test(ev.tool_name)){done=true;process.stdout.write("{\\"permission\\":\\"allow\\"}\\n");return;}',
+  'let child;try{',
+  `child=spawn(process.platform==="win32"?"npx.cmd":"npx",${JSON.stringify(['-y', `--package=${MCP_PACKAGE_SPEC}`, 'marrow-mcp', 'cursor-pre-action-hook'])},{stdio:["pipe","pipe","ignore"]});`,
+  '}catch{fail();return;}',
+  'let out="",bytes=0;child.stdout.on("data",c=>{bytes+=c.length;if(bytes<=65536)out+=c.toString("utf8");});',
+  'child.on("error",fail);child.stdin.on("error",()=>{});',
+  'child.on("close",code=>{if(done)return;let p=null;try{p=JSON.parse(out);}catch{p=null;}if(code!==0||bytes>65536||!p||typeof p!=="object"||Array.isArray(p)){fail();return;}done=true;process.stdout.write(JSON.stringify(p)+"\\n");});',
+  'child.stdin.end(raw);});',
+].join('');
+const CURSOR_MCP_PRE_ACTION_GUARD_COMMAND = `node -e '${CURSOR_MCP_PRE_ACTION_GUARD_SOURCE}'`;
 const CLINE_PRE_ACTION_HOOK_COMMAND = `npx -y --package=${MCP_PACKAGE_SPEC} marrow-mcp cline-pre-action-hook`;
 const CLINE_ACTION_RESULT_HOOK_COMMAND = `npx -y --package=${MCP_PACKAGE_SPEC} marrow-mcp cline-hook`;
 const CLINE_SESSION_END_HOOK_COMMAND = `npx -y --package=${MCP_PACKAGE_SPEC} marrow-mcp cline-session-hook`;
@@ -271,6 +317,53 @@ const GEMINI_SESSION_END_ENTRYPOINT = `npx -y --package=${MCP_PACKAGE_SPEC} marr
 const GEMINI_FIXED_DENIAL = 'Marrow blocked this action because required governance approval or proof is unavailable.';
 const GEMINI_LAUNCH_FAILURE = 'Marrow governance adapter was unavailable; this action is blocked.';
 const GEMINI_PRE_ACTION_HOOK_COMMAND = `sh -c 'output="$(${GEMINI_PRE_ACTION_ENTRYPOINT} 2>/dev/null)" && { case "$output" in "{\\"decision\\":\\"allow\\"}"|"{\\"decision\\":\\"deny\\",\\"reason\\":\\"${GEMINI_FIXED_DENIAL}\\"}") printf "%s\\n" "$output"; exit 0 ;; esac; }; printf "%s\\n" "${GEMINI_LAUNCH_FAILURE}" >&2; exit 2'`;
+// Host approvals: the BeforeTool guard also passes the hold denial that carries a typed-reply
+// code for the user only (`systemMessage`), so it checks the JSON shape instead of two fixed
+// strings. Anything else (a crash, a timeout before Gemini's own, invalid or oversized output)
+// still blocks with the fixed launch-failure text. stdin goes straight to the MCP entrypoint.
+const GEMINI_HOOK_GUARD_TIMEOUT_MS = 4500;
+const GEMINI_PRE_ACTION_GUARD_SOURCE = [
+  'const {spawn}=require("node:child_process");',
+  'const valid=value=>{try{const p=JSON.parse(value);if(!p||typeof p!=="object"||Array.isArray(p)||JSON.stringify(p)!==value)return false;const keys=Object.keys(p);',
+  'if(p.decision==="allow")return keys.length===1;',
+  'if(p.decision!=="deny"||typeof p.reason!=="string"||p.reason.length<1||p.reason.length>500)return false;',
+  'if(keys.length===2)return keys.includes("reason");',
+  'return keys.length===3&&keys.includes("systemMessage")&&typeof p.systemMessage==="string"&&p.systemMessage.length>0&&p.systemMessage.length<=600;}catch{return false;}};',
+  'let child=null,timer=null,done=false,output="",bytes=0;',
+  // Exits at once: a grandchild still holding the pipe must not keep the hook alive until the
+  // host's own timeout, which Gemini treats as a non-blocking failure.
+  `const fail=()=>{if(done)return;done=true;if(timer)clearTimeout(timer);try{if(child){if(child.stdout)child.stdout.destroy();if(!child.killed)child.kill("SIGKILL");}}catch{}process.exitCode=2;process.stderr.write(${JSON.stringify(`${GEMINI_LAUNCH_FAILURE}\n`)},()=>process.exit(2));};`,
+  'try{',
+  `child=spawn(process.platform==="win32"?"npx.cmd":"npx",${JSON.stringify(['-y', `--package=${MCP_PACKAGE_SPEC}`, 'marrow-mcp', 'gemini-pre-action-hook'])},{stdio:["inherit","pipe","ignore"]});`,
+  `timer=setTimeout(fail,${GEMINI_HOOK_GUARD_TIMEOUT_MS});`,
+  'child.stdout.on("data",chunk=>{if(done)return;bytes+=chunk.length;if(bytes>4096){fail();return;}output+=chunk.toString("utf8");});',
+  'child.on("error",fail);',
+  'child.on("close",code=>{if(done)return;const out=output.replace(/\\n+$/,"");if(code!==0||!valid(out)){fail();return;}done=true;clearTimeout(timer);process.stdout.write(out+"\\n");});',
+  '}catch{fail();}',
+].join('');
+const GEMINI_PRE_ACTION_GUARD_COMMAND = `node -e '${GEMINI_PRE_ACTION_GUARD_SOURCE}'`;
+// BeforeAgent records a typed reply ("marrow approve CODE") in a local interactive session. It
+// never blocks the prompt: only a confirmation for the user (`systemMessage`) and a retry note
+// for the agent pass; any failure prints `{}` and the prompt continues. A held action stays
+// denied at BeforeTool until Marrow has the answer, so this hook cannot let one run.
+const GEMINI_CONTEXT_GUARD_SOURCE = [
+  'const {spawn}=require("node:child_process");',
+  'const text=(v)=>typeof v==="string"&&v.length<=1000;',
+  'const valid=value=>{try{const p=JSON.parse(value);if(!p||typeof p!=="object"||Array.isArray(p)||JSON.stringify(p)!==value)return false;',
+  'for(const key of Object.keys(p)){if(key==="systemMessage"){if(!text(p.systemMessage))return false;}',
+  'else if(key==="hookSpecificOutput"){const h=p.hookSpecificOutput;if(!h||typeof h!=="object"||Array.isArray(h)||Object.keys(h).sort().join()!=="additionalContext,hookEventName"||h.hookEventName!=="BeforeAgent"||!text(h.additionalContext))return false;}',
+  'else return false;}return true;}catch{return false;}};',
+  'let child=null,timer=null,done=false,output="",bytes=0;',
+  'const neutral=()=>{if(done)return;done=true;if(timer)clearTimeout(timer);try{if(child){if(child.stdout)child.stdout.destroy();if(!child.killed)child.kill("SIGKILL");}}catch{}process.exitCode=0;process.stdout.write("{}\\n",()=>process.exit(0));};',
+  'try{',
+  `child=spawn(process.platform==="win32"?"npx.cmd":"npx",${JSON.stringify(['-y', `--package=${MCP_PACKAGE_SPEC}`, 'marrow-mcp', 'gemini-context-hook'])},{stdio:["inherit","pipe","ignore"]});`,
+  `timer=setTimeout(neutral,${GEMINI_HOOK_GUARD_TIMEOUT_MS});`,
+  'child.stdout.on("data",chunk=>{if(done)return;bytes+=chunk.length;if(bytes>4096){neutral();return;}output+=chunk.toString("utf8");});',
+  'child.on("error",neutral);',
+  'child.on("close",code=>{if(done)return;const out=output.replace(/\\n+$/,"");if(code!==0||!valid(out)){neutral();return;}done=true;clearTimeout(timer);process.stdout.write(out+"\\n");});',
+  '}catch{neutral();}',
+].join('');
+const GEMINI_CONTEXT_HOOK_COMMAND = `node -e '${GEMINI_CONTEXT_GUARD_SOURCE}'`;
 const GEMINI_ACTION_RESULT_HOOK_COMMAND = `sh -c '${GEMINI_ACTION_RESULT_ENTRYPOINT} >/dev/null 2>&1 || :; printf "%s\\n" "{}"; exit 0'`;
 const GEMINI_SESSION_END_HOOK_COMMAND = `sh -c '${GEMINI_SESSION_END_ENTRYPOINT} >/dev/null 2>&1 || :; printf "%s\\n" "{}"; exit 0'`;
 const GROK_CONTEXT_HOOK_COMMAND = `npx -y --package=${MCP_PACKAGE_SPEC} marrow-mcp grok-context-hook`;
@@ -297,6 +390,17 @@ const GROK_PRE_ACTION_HOOK_COMMAND = `node -e '${GROK_PRE_ACTION_GUARD_SOURCE}'`
 const NATIVE_HOOK_MATCHER = 'Bash|Edit|Write|MultiEdit|Read|Glob|Grep|Search|WebSearch|Task|functions\\.(?!mcp__marrow__marrow_).*|mcp__(?!marrow__marrow_).*';
 const CODEX_NATIVE_HOOK_MATCHER = 'Bash|apply_patch|Edit|Write|MultiEdit|mcp__(?!marrow__marrow_).*|functions\\.(?!marrow_).*';
 const CURSOR_NATIVE_HOOK_MATCHER = 'Shell|Write|Delete|Task|Read|Glob|Grep|Search|WebSearch|List|MCP:(?!marrow(?:_.*|:marrow_.*)$).*';
+// Host approvals: Cursor enforces an "ask" only on beforeShellExecution and beforeMCPExecution,
+// never on preToolUse. Shell calls move to beforeShellExecution (it runs in cloud agents too).
+// MCP calls stay in preToolUse as well, because cloud agents never run beforeMCPExecution: the
+// MCP hook defers there to beforeMCPExecution only in a local interactive session (sessionStart
+// evidence) and holds in cloud and background agents. The result hooks keep the full matcher.
+const CURSOR_PRE_TOOL_USE_HOST_APPROVAL_MATCHER = 'Write|Delete|Task|Read|Glob|Grep|Search|WebSearch|List|MCP:(?!marrow(?:_.*|:marrow_.*)$).*';
+// Cursor's gating hooks are failClosed: a cold npx start on a slow network must not block a
+// call, so they get room beyond the MCP hook's own 4-second budget.
+const CURSOR_GATE_HOOK_TIMEOUT_SECONDS = 15;
+const CURSOR_EXECUTION_PRE_EVENTS = Object.freeze(['beforeShellExecution', 'beforeMCPExecution']);
+const CURSOR_EXECUTION_POST_EVENTS = Object.freeze(['afterShellExecution', 'afterMCPExecution']);
 const GEMINI_NATIVE_HOOK_MATCHER = '^(?:run_shell_command|write_file|replace|edit_file|delete_file|read_file|read_many_files|glob|grep_search|list_directory|get_file_info|web_search|google_web_search|mcp_(?!marrow_marrow_)[A-Za-z0-9_]{1,192})$';
 const GROK_NATIVE_HOOK_MATCHER = 'run_terminal_command|search_replace|write|spawn_subagent|use_tool|workflow|image_gen|image_edit|image_to_video|reference_to_video';
 const CODEX_HOOK_TIMEOUT_SECONDS = 5;
@@ -723,6 +827,21 @@ function sourceClient() {
   return aliases[raw] || (SOURCE_CLIENTS.has(raw) ? raw : 'custom');
 }
 
+// What an error may print of an argument it does not know: an option's name (the text before
+// `=`, never its value) when it looks like one (--lower-case-name, or one letter after one dash),
+// or a short plain word. Anything else may be a pasted key (-pPASSWORD) and is not shown.
+function argumentLabel(arg) {
+  const text = String(arg ?? '');
+  if (text.startsWith('-')) {
+    const name = text.split('=')[0];
+    return /^(?:--[a-z][a-z0-9-]{0,40}|-[A-Za-z])$/.test(name) ? name : '(an option that is not known; not shown)';
+  }
+  return /^[a-z][a-z-]{0,23}$/.test(text) ? text : '(a value that is not an option; not shown)';
+}
+
+// Operation words parseArgs accepts. A --key value equal to one of these is a missing key.
+const SUBCOMMAND_WORDS = new Set(['activate', 'update', 'repair', 'uninstall', 'doctor', 'check']);
+
 function parseArgs(argv, env = process.env) {
   const options = {
     cwd: process.cwd(),
@@ -732,7 +851,8 @@ function parseArgs(argv, env = process.env) {
     doctor: false,
     repair: false,
     mode: 'auto',
-    apiKey: env.MARROW_API_KEY || '',
+    // MARROW_KEY is accepted when MARROW_API_KEY is absent or blank, as the runner and owner files do.
+    apiKey: String(env.MARROW_API_KEY || '').trim() || String(env.MARROW_KEY || '').trim(),
     baseUrl: env.MARROW_BASE_URL || DEFAULT_BASE_URL,
     agentId: env.MARROW_FLEET_AGENT_ID || env.MARROW_AGENT_ID || '',
     toolProfile: resolveToolProfile(env.MARROW_TOOL_PROFILE),
@@ -742,10 +862,24 @@ function parseArgs(argv, env = process.env) {
     json: false,
     activate: false,
     controller: true,
+    // Hooks start a verified local copy of the pinned MCP (installed on write runs) instead of
+    // npx. MARROW_LOCAL_RUNTIME=0 or --no-local-runtime keeps them on npx.
+    mcpLocalRuntime: env.MARROW_LOCAL_RUNTIME !== '0',
   };
   let explicitOperation = false;
 
-  for (let i = 0; i < argv.length; i += 1) {
+  // Value of the option at argv[i]. Only consumes the next argument when it exists and is not an
+  // option itself, so a missing value never swallows a following flag.
+  let i = 0;
+  const optionValue = (refuseWords = false) => {
+    const next = argv[i + 1];
+    if (next === undefined || String(next).startsWith('-')) return '';
+    // `--key $UNSET activate` must not take the subcommand word as the key.
+    if (refuseWords && SUBCOMMAND_WORDS.has(String(next))) return '';
+    i += 1;
+    return next;
+  };
+  for (; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === 'activate' || arg === '--activate') {
       explicitOperation = true;
@@ -767,6 +901,10 @@ function parseArgs(argv, env = process.env) {
       explicitOperation = true;
       options.dryRun = true;
     }
+    else if (arg === 'uninstall' || arg === '--uninstall') {
+      explicitOperation = true;
+      options.uninstall = true;
+    }
     else if (arg === '--doctor' || arg === 'doctor' || arg === 'check') {
       explicitOperation = true;
       options.doctor = true;
@@ -779,18 +917,20 @@ function parseArgs(argv, env = process.env) {
       options.selfTestExplicitlyDisabled = true;
     }
     else if (arg === '--no-controller') options.controller = false;
+    else if (arg === '--no-local-runtime') options.mcpLocalRuntime = false;
     else if (arg === '--self-test') options.selfTest = true;
-    else if (arg === '--cwd') options.cwd = path.resolve(argv[++i] || options.cwd);
+    else if (arg === '--cwd') options.cwd = path.resolve(optionValue() || options.cwd);
     else if (arg === '--mode') {
       explicitOperation = true;
-      options.mode = argv[++i] || options.mode;
+      options.mode = optionValue() || options.mode;
     }
     else if (arg === '--key') {
-      options.apiKey = argv[++i] || options.apiKey;
+      // A missing value (end of argv, or another option next) is a missing key, never a key.
+      options.apiKey = optionValue(true) || options.apiKey;
       options.keyFromArg = true;
     }
-    else if (arg === '--base-url') options.baseUrl = argv[++i] || options.baseUrl;
-    else if (arg === '--agent-id') options.agentId = argv[++i] || options.agentId;
+    else if (arg === '--base-url') options.baseUrl = optionValue() || options.baseUrl;
+    else if (arg === '--agent-id') options.agentId = optionValue() || options.agentId;
     else if (arg === '--mcp') {
       explicitOperation = true;
       options.mode = 'mcp';
@@ -810,10 +950,13 @@ function parseArgs(argv, env = process.env) {
     else if (arg === '--help' || arg === '-h') {
       options.help = true;
     } else {
-      throw new Error(`Unknown argument: ${arg}`);
+      throw new Error(`Unknown argument: ${argumentLabel(arg)}`);
     }
   }
 
+  if (options.uninstall && (options.activate || options.repair || options.doctor)) {
+    throw new Error('uninstall cannot be combined with activate, update, repair, or doctor');
+  }
   if (!['auto', 'mcp', 'sdk', 'both', 'md'].includes(options.mode)) {
     throw new Error('--mode must be one of auto, mcp, sdk, both, md');
   }
@@ -843,26 +986,34 @@ function usage() {
   npx @getmarrow/install --repair
   npx @getmarrow/install update
   npx @getmarrow/install doctor
+  npx @getmarrow/install doctor --self-test
   npx @getmarrow/install --mcp --yes
   npx @getmarrow/install --sdk --yes
+  npx @getmarrow/install uninstall [--yes]
 
 Options:
   (no command)       Detect, install, self-test, and start the supported persistent controller
   activate           Detect, install, self-test, and return a server-confirmed activation receipt
   --dry-run          Print planned changes without writing
   --doctor           Check install health without writing
+  doctor --self-test Same as doctor, which already runs the server self-test: run it after restarting the harness
   --repair           Write missing hooks/config, then run self-test and status check
   update             Same as --repair: refresh exact MCP/SDK/install package pins after owner approval
-  --yes, -y          Write detected config files
+  --yes, -y          Write detected config files (needs your API key; stops before writing without one)
   --mode <mode>      auto, mcp, sdk, both, or md
-  --key <key>        Marrow API key for self-test. Prefer MARROW_API_KEY because CLI args can appear in process listings.
   --base-url <url>   Marrow API base URL
   --agent-id <id>    Agent/fleet id for self-test headers
   --no-controller    Do not start the local background controller during install/repair
+  --no-local-runtime Keep hooks on npx instead of the verified local MCP copy in ~/.marrow/runtime
   --no-self-test     Skip API smoke/self-test
   --verbose          Print the full report instead of the one-line summary and log file
+  uninstall          Preview removing only Marrow's own hooks, MCP server entries, instructions and
+                     the local MCP runtime; add --yes to remove them. Your own hooks and settings
+                     are kept.
 
-The API key comes from MARROW_API_KEY, or from the owner-only ~/.marrow/env when unset.
+Get a key at https://getmarrow.ai/signup. Put it in the owner-only ~/.marrow/env as
+MARROW_API_KEY=your_key, then run chmod 700 ~/.marrow && chmod 600 ~/.marrow/env, or export MARROW_API_KEY. Keep it off the command line: command-line
+arguments land in shell history and process listings.
 
 Environment:
   MARROW_TOOL_PROFILE  Leave unset for primary (17 tools), or explicitly set primary, core, or full.
@@ -878,13 +1029,14 @@ function stableAgentId(root, client = sourceClient()) {
 function detectedClient(detection) {
   if (sourceClient() !== 'custom') return sourceClient();
   if (detection.openclaw) return 'openclaw';
-  if (detection.claudeCode) return 'claude-code';
+  if (detection.claudeCodeProject ?? detection.claudeCode) return 'claude-code';
   if (detection.cursor) return 'cursor';
   if (detection.cline) return 'cline';
   if (detection.windsurf) return 'windsurf';
   if (detection.gemini) return 'gemini';
   if (detection.codexProject) return 'codex';
   // Home-level harnesses rank below project markers; a shared AGENTS.md is a weaker signal.
+  if (detection.claudeCode) return 'claude-code';
   if (detection.hermes) return 'hermes';
   if (detection.codex) return 'codex';
   return 'custom';
@@ -1037,6 +1189,14 @@ function detectEnvironment(cwd = process.cwd(), env = process.env) {
   };
   const homeHarnesses = detectHomeHarnesses(home, env);
   const codexProject = codexDirectoryIsOwnerConfigured(path.join(root, '.codex'));
+  // Claude Code is detected from the project (CLAUDE.md, .claude/settings.json) or, for a repo
+  // that has neither yet, from the user's installation: ~/.claude/, ~/.claude.json or `claude`
+  // on PATH. Either way the project gets .claude/settings.json.
+  const claudeCodeProject = exists(paths.claudeSettings) || exists(paths.claudeMd);
+  const claudeCodeSource = claudeCodeProject ? 'project'
+    : exists(path.join(home, '.claude')) || exists(path.join(home, '.claude.json')) ? 'home'
+    : executableOnPath('claude', env) ? 'path'
+    : null;
 
   return {
     root,
@@ -1044,7 +1204,9 @@ function detectEnvironment(cwd = process.cwd(), env = process.env) {
     paths,
     node: exists(paths.packageJson),
     python: exists(paths.pyproject) || exists(paths.requirements) || exists(paths.setupPy),
-    claudeCode: exists(paths.claudeSettings) || exists(paths.claudeMd),
+    claudeCode: Boolean(claudeCodeSource),
+    claudeCodeProject,
+    claudeCodeSource,
     cursor: exists(path.join(root, '.cursor')),
     cline: exists(path.join(root, '.clinerules')),
     windsurf: exists(path.join(root, '.windsurf')),
@@ -1123,7 +1285,12 @@ function findLikelyEnvFiles(detection, env = process.env) {
   });
 }
 
-function passiveInstructions() {
+function passiveInstructions(options = {}) {
+  const hostApprovals = options.hostApprovals === true;
+  const geminiHooks = hostApprovals ? 'BeforeTool, AfterTool, AfterAgent, and BeforeAgent' : 'BeforeTool, AfterTool, and AfterAgent';
+  const approvals = hostApprovals
+    ? '\n- When Marrow holds an action for approval, the operator approves it in the host\'s own permission prompt, or with the typed reply the hook shows them. With nobody at the prompt, the action waits quietly: do not run it, carry on with other work, and tell the person it is waiting. Marrow sends the account owner a one-tap link only for actions the owner approves personally, to reverse the owner\'s own decline when asked, or when the owner turned on unattended pings. Never ask anyone to log in to a dashboard to approve, and never report, write, or claim an approval yourself. Retry the held action only after the approval or when the operator asks.'
+    : '';
   return `${MARROW_BLOCK_START}
 ## Marrow Passive Agent Memory
 
@@ -1137,10 +1304,10 @@ Marrow should run passively after install:
 - Before risky work, use Marrow's decision brief or passive prompt hook.
 - After activate writes MCP or hooks, restart this harness, then run \`npx @getmarrow/install@latest doctor --self-test\`. Do not claim Marrow is live in a process that has not reloaded.
 - First turn: tell the owner the gate is live and empty savings are honest. The next deploy, merge, or publish must go through Marrow.
-- Cursor and Composer use configured native hooks after restart and \`/hooks\` trust review. Cline uses its configured PreToolUse, PostToolUse, and TaskCancel hooks only after Enable Hooks, restart, executable trust, and workspace trust; TaskComplete is not claimed as current coverage. Windsurf uses configured native pre-action, success-result, and response-closeout hooks only after restart, trust review, and leaving Restricted Mode. Gemini CLI uses configured BeforeTool, AfterTool, and AfterAgent hooks only after restart and project fingerprint review and approval in \`/hooks panel\`; explicit user disablement is preserved. Grok uses global native PreToolUse, PostToolUse/PostToolUseFailure, and one nonblocking Stop closeout only after restart and \`/hooks\` inspection; Grok hooks remain user-toggleable. MCP tools remain on demand. Codex uses configured native hooks after restart and \`/hooks\` trust review. The governed wrapper remains an explicit bounded fallback.
+- Cursor and Composer use configured native hooks after restart and \`/hooks\` trust review. Cline uses its configured PreToolUse, PostToolUse, and TaskCancel hooks only after Enable Hooks, restart, executable trust, and workspace trust; TaskComplete is not claimed as current coverage. Windsurf uses configured native pre-action, success-result, and response-closeout hooks only after restart, trust review, and leaving Restricted Mode. Gemini CLI uses configured ${geminiHooks} hooks only after restart and project fingerprint review and approval in \`/hooks panel\`; explicit user disablement is preserved. Grok uses global native PreToolUse, PostToolUse/PostToolUseFailure, and one nonblocking Stop closeout only after restart and \`/hooks\` inspection; Grok hooks remain user-toggleable. MCP tools remain on demand. Codex uses configured native hooks after restart and \`/hooks\` trust review. The governed wrapper remains an explicit bounded fallback.
 - Before the session ends, close open work with session-end auto-commit or \`marrow_commit\`. Record model usage only when the host response includes counts.
 - After meaningful work, record the outcome so future agents learn from it.
-- After Marrow blocks, warns, or requires review, use the decision trace receipt to tell the operator what changed and which recorded workflow or proof is required. Stay quiet for routine low-risk work.
+- After Marrow blocks, warns, or requires review, use the decision trace receipt to tell the operator what changed and which recorded workflow or proof is required. Stay quiet for routine low-risk work.${approvals}
 - Check health with \`marrow_agent_status\` or \`GET /v1/agent/status\`.
 - When status/runtime returns a \`client_update\` notice, tell the operator and use its exact update and verification commands only when local change policy permits.
 
@@ -1208,6 +1375,9 @@ MARROW_PASSIVE_TOKEN_USAGE=true
 `;
 }
 
+// Hook files are read with Marrow's hook commands in their canonical (npx) form, whether they
+// start through npx or the local runtime, so every check and merge sees one spelling; writes
+// switch them to the local runtime again when it is verified.
 function parseJsonObject(filePath) {
   const raw = safeRead(filePath).trim();
   if (!raw) return {};
@@ -1215,7 +1385,7 @@ function parseJsonObject(filePath) {
   if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
     throw new Error(`Expected JSON object in ${filePath}`);
   }
-  return parsed;
+  return mapHookCommands(parsed, delocalizeHookCommand);
 }
 
 function canonicalJsonValue(value) {
@@ -1293,7 +1463,7 @@ function exactHookDescriptors(settings, eventName, command, matcher) {
 function marrowHookSubcommand(command) {
   if (typeof command !== 'string') return null;
   const match = command.trim().match(
-    /^npx\s+(?:-y\s+)?(?:--package=@getmarrow\/mcp(?:@[^\s]+)?\s+marrow-mcp|@getmarrow\/mcp(?:@[^\s]+)?)\s+(?:(?:claude|cline|codex|cursor|gemini|grok|windsurf)-)?(context-hook|pre-action-hook|hook|session-hook)$/,
+    /^npx\s+(?:-y\s+)?(?:--package=@getmarrow\/mcp(?:@[^\s]+)?\s+marrow-mcp|@getmarrow\/mcp(?:@[^\s]+)?)\s+(?:(?:claude|cline|codex|cursor|gemini|grok|windsurf)-)?(context-hook|pre-action-hook|hook|session-hook|permission-request-hook)$/,
   );
   return match?.[1] || null;
 }
@@ -1367,11 +1537,33 @@ function safeJsonObject(filePath) {
   }
 }
 
-function claudeNativeHookFingerprint(settings) {
+// The host-approval hooks Claude Code needs besides the core five (see upsertClaudeHooks).
+function claudeHostApprovalHooksConfigured(settings, targetCommand = (command) => command) {
+  return {
+    permission_request: exactHookConfigured(settings, 'PermissionRequest', targetCommand(MCP_PERMISSION_REQUEST_HOOK_COMMAND), NATIVE_HOOK_MATCHER),
+    post_tool_batch: exactHookConfigured(settings, 'PostToolBatch', targetCommand(MCP_ACTION_RESULT_HOOK_COMMAND)),
+  };
+}
+
+function claudeNativeHookFingerprint(settings, options = {}) {
+  const hostApprovals = options.hostApprovals ?? hostApprovalHooksSupported();
   const contract = {
     schema: 'marrow-claude-native-hooks.v3',
     adapter_version: MCP_ADAPTER_VERSION,
     expected_hooks: NATIVE_EXPECTED_HOOKS,
+    ...(hostApprovals ? {
+      host_approvals: {
+        configured: claudeHostApprovalHooksConfigured(settings),
+        descriptors: {
+          permission_request: exactHookDescriptors(settings, 'PermissionRequest', MCP_PERMISSION_REQUEST_HOOK_COMMAND, NATIVE_HOOK_MATCHER),
+          post_tool_batch: exactHookDescriptors(settings, 'PostToolBatch', MCP_ACTION_RESULT_HOOK_COMMAND),
+        },
+        active_marrow_handlers: {
+          permission_request: marrowHookDescriptors(settings, 'PermissionRequest'),
+          post_tool_batch: marrowHookDescriptors(settings, 'PostToolBatch'),
+        },
+      },
+    } : {}),
     configured: {
       prompt: exactHookConfigured(settings, 'UserPromptSubmit', MCP_CONTEXT_HOOK_COMMAND),
       pre_action: exactHookConfigured(settings, 'PreToolUse', MCP_PRE_ACTION_HOOK_COMMAND, NATIVE_HOOK_MATCHER),
@@ -1397,7 +1589,7 @@ function claudeNativeHookFingerprint(settings) {
   return crypto.createHash('sha256').update(JSON.stringify(contract)).digest('hex');
 }
 
-function upsertClaudeHooks(settingsPath) {
+function upsertClaudeHooks(settingsPath, options = {}) {
   const settings = parseJsonObject(settingsPath);
   const hooks = settings.hooks && typeof settings.hooks === 'object' && !Array.isArray(settings.hooks)
     ? settings.hooks
@@ -1426,6 +1618,18 @@ function upsertClaudeHooks(settingsPath) {
     UserPromptSubmit: userPromptSubmit,
     Stop: stop,
   };
+  if (options.hostApprovals) {
+    // Both async, exactly as `marrow-mcp setup` writes them: the marker never delays or answers
+    // the dialog, and PostToolBatch settles a declined dialog in the background.
+    settings.hooks.PermissionRequest = reconcileMarrowCommandHook(
+      settings, 'PermissionRequest', 'permission-request-hook', MCP_PERMISSION_REQUEST_HOOK_COMMAND, NATIVE_HOOK_MATCHER,
+      { async: true },
+    );
+    settings.hooks.PostToolBatch = reconcileMarrowCommandHook(
+      settings, 'PostToolBatch', 'hook', MCP_ACTION_RESULT_HOOK_COMMAND, undefined,
+      { async: true },
+    );
+  }
 
   return JSON.stringify(settings, null, 2) + '\n';
 }
@@ -1484,11 +1688,20 @@ function upsertCodexHooks(hooksPath) {
   return JSON.stringify(settings, null, 2) + '\n';
 }
 
+// A Marrow Cursor entry: the npx entrypoint, or the node guard that names it as JSON items.
+function cursorMarrowHookSubcommand(command) {
+  const direct = marrowHookSubcommand(command);
+  if (direct) return direct;
+  if (typeof command !== 'string') return null;
+  const guarded = command.match(/@getmarrow\/mcp@[^\s"',]+["'],["']marrow-mcp["'],["']cursor-(pre-action-hook|context-hook|hook|session-hook)["']/);
+  return guarded?.[1] || null;
+}
+
 function reconcileCursorHook(settings, eventName, subcommand, canonical) {
   const original = Array.isArray(settings?.hooks?.[eventName]) ? settings.hooks[eventName] : [];
   const retained = original.filter((entry) => !(
     entry && typeof entry === 'object' && !Array.isArray(entry)
-    && marrowHookSubcommand(entry.command)
+    && cursorMarrowHookSubcommand(entry.command)
   ));
   return [...retained, canonical];
 }
@@ -1506,7 +1719,7 @@ function cursorHookDescriptors(settings, eventName) {
   const entries = settings?.hooks?.[eventName];
   if (!Array.isArray(entries)) return [];
   return entries.flatMap((entry) => {
-    if (!entry || typeof entry !== 'object' || Array.isArray(entry) || !marrowHookSubcommand(entry.command)) return [];
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry) || !cursorMarrowHookSubcommand(entry.command)) return [];
     return [{
       matcher: typeof entry.matcher === 'string' ? entry.matcher : null,
       command: String(entry.command).trim(),
@@ -1517,14 +1730,43 @@ function cursorHookDescriptors(settings, eventName) {
   });
 }
 
-function cursorNativeHookFingerprint(settings) {
+// The Cursor hooks that host approvals add (see upsertCursorHooks), as configured checks.
+function cursorHostApprovalHooksConfigured(settings, targetCommand = (command) => command) {
+  const pre = targetCommand(CURSOR_PRE_ACTION_HOOK_COMMAND);
+  const post = targetCommand(CURSOR_ACTION_RESULT_HOOK_COMMAND);
+  const gate = { timeout: CURSOR_GATE_HOOK_TIMEOUT_SECONDS, failClosed: true, async: false };
+  return {
+    pre_tool_use: exactCursorHookConfigured(settings, 'preToolUse', pre, CURSOR_PRE_TOOL_USE_HOST_APPROVAL_MATCHER, gate),
+    beforeShellExecution: exactCursorHookConfigured(settings, 'beforeShellExecution', pre, undefined, gate),
+    beforeMCPExecution: exactCursorHookConfigured(settings, 'beforeMCPExecution', targetCommand(CURSOR_MCP_PRE_ACTION_GUARD_COMMAND), undefined, gate),
+    ...Object.fromEntries(CURSOR_EXECUTION_POST_EVENTS.map((event) => [event, exactCursorHookConfigured(settings, event, post, undefined, {
+      timeout: CODEX_HOOK_TIMEOUT_SECONDS,
+    })])),
+    sessionStart: exactCursorHookConfigured(settings, 'sessionStart', targetCommand(CURSOR_SESSION_END_HOOK_COMMAND), undefined, {
+      timeout: CODEX_HOOK_TIMEOUT_SECONDS,
+    }),
+    beforeSubmitPrompt: exactCursorHookConfigured(settings, 'beforeSubmitPrompt', targetCommand(CURSOR_CONTEXT_HOOK_COMMAND), undefined, {
+      timeout: CODEX_HOOK_TIMEOUT_SECONDS,
+    }),
+  };
+}
+
+function cursorNativeHookFingerprint(settings, options = {}) {
+  const hostApprovals = options.hostApprovals ?? hostApprovalHooksSupported();
   const contract = {
     schema: 'marrow-cursor-native-hooks.v1',
     adapter_version: MCP_ADAPTER_VERSION,
     expected_hooks: ['pre_action', 'action_result', 'outcome_closure'],
+    ...(hostApprovals ? {
+      host_approvals: {
+        configured: cursorHostApprovalHooksConfigured(settings),
+        descriptors: Object.fromEntries([...CURSOR_EXECUTION_PRE_EVENTS, ...CURSOR_EXECUTION_POST_EVENTS, 'sessionStart', 'beforeSubmitPrompt']
+          .map((event) => [event, cursorHookDescriptors(settings, event)])),
+      },
+    } : {}),
     configured: {
-      pre_action: exactCursorHookConfigured(settings, 'preToolUse', CURSOR_PRE_ACTION_HOOK_COMMAND, CURSOR_NATIVE_HOOK_MATCHER, {
-        timeout: CODEX_HOOK_TIMEOUT_SECONDS,
+      pre_action: exactCursorHookConfigured(settings, 'preToolUse', CURSOR_PRE_ACTION_HOOK_COMMAND, hostApprovals ? CURSOR_PRE_TOOL_USE_HOST_APPROVAL_MATCHER : CURSOR_NATIVE_HOOK_MATCHER, {
+        timeout: hostApprovals ? CURSOR_GATE_HOOK_TIMEOUT_SECONDS : CODEX_HOOK_TIMEOUT_SECONDS,
         failClosed: true,
         async: false,
       }),
@@ -1548,18 +1790,19 @@ function cursorNativeHookFingerprint(settings) {
   return crypto.createHash('sha256').update(JSON.stringify(contract)).digest('hex');
 }
 
-function upsertCursorHooks(hooksPath) {
+function upsertCursorHooks(hooksPath, options = {}) {
   const settings = parseJsonObject(hooksPath);
   const hooks = settings.hooks && typeof settings.hooks === 'object' && !Array.isArray(settings.hooks)
     ? settings.hooks
     : {};
   settings.version = 1;
+  const hostApprovals = options.hostApprovals === true;
   settings.hooks = {
     ...hooks,
     preToolUse: reconcileCursorHook(settings, 'preToolUse', 'pre-action-hook', {
       command: CURSOR_PRE_ACTION_HOOK_COMMAND,
-      matcher: CURSOR_NATIVE_HOOK_MATCHER,
-      timeout: CODEX_HOOK_TIMEOUT_SECONDS,
+      matcher: hostApprovals ? CURSOR_PRE_TOOL_USE_HOST_APPROVAL_MATCHER : CURSOR_NATIVE_HOOK_MATCHER,
+      timeout: hostApprovals ? CURSOR_GATE_HOOK_TIMEOUT_SECONDS : CODEX_HOOK_TIMEOUT_SECONDS,
       failClosed: true,
       async: false,
     }),
@@ -1578,6 +1821,36 @@ function upsertCursorHooks(hooksPath) {
       timeout: CODEX_SESSION_TIMEOUT_SECONDS,
     }),
   };
+  if (hostApprovals) {
+    // Cursor enforces "ask" only here. failClosed: a crash or timeout blocks the call instead
+    // of letting it through (Cursor fails open by default).
+    for (const eventName of CURSOR_EXECUTION_PRE_EVENTS) {
+      settings.hooks[eventName] = reconcileCursorHook(settings, eventName, 'pre-action-hook', {
+        command: eventName === 'beforeMCPExecution' ? CURSOR_MCP_PRE_ACTION_GUARD_COMMAND : CURSOR_PRE_ACTION_HOOK_COMMAND,
+        timeout: CURSOR_GATE_HOOK_TIMEOUT_SECONDS,
+        failClosed: true,
+        async: false,
+      });
+    }
+    for (const eventName of CURSOR_EXECUTION_POST_EVENTS) {
+      settings.hooks[eventName] = reconcileCursorHook(settings, eventName, 'hook', {
+        command: CURSOR_ACTION_RESULT_HOOK_COMMAND,
+        timeout: CODEX_HOOK_TIMEOUT_SECONDS,
+      });
+    }
+    // sessionStart tells the hooks whether the session is local and interactive (not a
+    // background agent); without it Cursor holds are denied instead of asked.
+    settings.hooks.sessionStart = reconcileCursorHook(settings, 'sessionStart', 'session-hook', {
+      command: CURSOR_SESSION_END_HOOK_COMMAND,
+      timeout: CODEX_HOOK_TIMEOUT_SECONDS,
+    });
+    // The typed reply ("marrow approve CODE") in a local interactive session. Never failClosed:
+    // a failure must not block the operator's own prompts.
+    settings.hooks.beforeSubmitPrompt = reconcileCursorHook(settings, 'beforeSubmitPrompt', 'context-hook', {
+      command: CURSOR_CONTEXT_HOOK_COMMAND,
+      timeout: CODEX_HOOK_TIMEOUT_SECONDS,
+    });
+  }
   return JSON.stringify(settings, null, 2) + '\n';
 }
 
@@ -1647,7 +1920,9 @@ function upsertWindsurfHooks(hooksPath) {
 
 function geminiMarrowHookEntrypoint(command) {
   if (typeof command !== 'string') return null;
-  const match = command.match(/@getmarrow\/mcp(?:@[^\s]+)?\s+marrow-mcp\s+gemini-(pre-action-hook|hook|session-hook)(?:\s|['"]|$)/);
+  const match = command.match(/@getmarrow\/mcp(?:@[^\s]+)?\s+marrow-mcp\s+gemini-(pre-action-hook|context-hook|hook|session-hook)(?:\s|['"]|$)/)
+    // The node guards name the entrypoint as JSON array items.
+    || command.match(/@getmarrow\/mcp@[^\s"',]+["'],["']marrow-mcp["'],["']gemini-(pre-action-hook|context-hook|hook|session-hook)["']/);
   return match?.[1] || null;
 }
 
@@ -1689,7 +1964,14 @@ function geminiHooksExplicitlyDisabled(settings) {
   return settings?.hooksConfig?.enabled === false;
 }
 
-function geminiNativeHookFingerprint(settings) {
+// The Gemini BeforeTool command: the JSON-checking guard with host approvals, otherwise the
+// earlier fixed-string wrapper.
+function geminiPreActionCommand(hostApprovals) {
+  return hostApprovals ? GEMINI_PRE_ACTION_GUARD_COMMAND : GEMINI_PRE_ACTION_HOOK_COMMAND;
+}
+
+function geminiNativeHookFingerprint(settings, options = {}) {
+  const hostApprovals = options.hostApprovals ?? hostApprovalHooksSupported();
   return crypto.createHash('sha256').update(JSON.stringify({
     schema: 'marrow-gemini-native-hooks.v1',
     adapter_version: MCP_ADAPTER_VERSION,
@@ -1698,7 +1980,7 @@ function geminiNativeHookFingerprint(settings) {
     explicitly_disabled: geminiHooksExplicitlyDisabled(settings),
     configured: {
       pre_action: exactGeminiHookConfigured(
-        settings, 'BeforeTool', 'marrow-before-tool', GEMINI_PRE_ACTION_HOOK_COMMAND,
+        settings, 'BeforeTool', 'marrow-before-tool', geminiPreActionCommand(hostApprovals),
         GEMINI_NATIVE_HOOK_MATCHER, GEMINI_HOOK_TIMEOUT_MS,
       ),
       action_result: exactGeminiHookConfigured(
@@ -1709,6 +1991,12 @@ function geminiNativeHookFingerprint(settings) {
         settings, 'AfterAgent', 'marrow-after-agent', GEMINI_SESSION_END_HOOK_COMMAND,
         undefined, GEMINI_CLOSEOUT_TIMEOUT_MS,
       ),
+      ...(hostApprovals ? {
+        typed_reply: exactGeminiHookConfigured(
+          settings, 'BeforeAgent', 'marrow-before-agent', GEMINI_CONTEXT_HOOK_COMMAND,
+          undefined, GEMINI_HOOK_TIMEOUT_MS,
+        ),
+      } : {}),
     },
     session_end_claimed: false,
   })).digest('hex');
@@ -1825,11 +2113,12 @@ function managedGrokHooksFile(filePath) {
   }
 }
 
-function upsertGeminiHooks(settingsPath) {
+function upsertGeminiHooks(settingsPath, options = {}) {
   const settings = parseJsonObject(settingsPath);
   const hooks = settings.hooks && typeof settings.hooks === 'object' && !Array.isArray(settings.hooks)
     ? settings.hooks
     : {};
+  const hostApprovals = options.hostApprovals === true;
   settings.hooks = {
     ...hooks,
     BeforeTool: reconcileGeminiHook(settings, 'BeforeTool', {
@@ -1837,7 +2126,7 @@ function upsertGeminiHooks(settingsPath) {
       hooks: [{
         name: 'marrow-before-tool',
         type: 'command',
-        command: GEMINI_PRE_ACTION_HOOK_COMMAND,
+        command: geminiPreActionCommand(hostApprovals),
         timeout: GEMINI_HOOK_TIMEOUT_MS,
       }],
     }),
@@ -1859,6 +2148,17 @@ function upsertGeminiHooks(settingsPath) {
       }],
     }),
   };
+  if (hostApprovals) {
+    // The typed reply in a local interactive session (`gemini`, never `gemini -p`).
+    settings.hooks.BeforeAgent = reconcileGeminiHook(settings, 'BeforeAgent', {
+      hooks: [{
+        name: 'marrow-before-agent',
+        type: 'command',
+        command: GEMINI_CONTEXT_HOOK_COMMAND,
+        timeout: GEMINI_HOOK_TIMEOUT_MS,
+      }],
+    });
+  }
   return JSON.stringify(settings, null, 2) + '\n';
 }
 
@@ -1935,7 +2235,7 @@ function clineNativeHookFingerprint(detection) {
 function activationProfile(detection, plan, changes, client) {
   const registry = HARNESS_CAPABILITY_REGISTRY.find((entry) => entry.client === client)
     || HARNESS_CAPABILITY_REGISTRY.find((entry) => entry.client === 'custom');
-  const sdkDependency = inspectSdkDependency(detection);
+  const sdkDependency = inspectSdkDependency(detection, { sdkMode: plan.mode === 'sdk' || plan.mode === 'both' });
   const capabilityLevel = client === 'custom' && (plan.mode === 'sdk' || plan.mode === 'both')
     ? 'sdk_passive_runtime'
     : registry.capability_level;
@@ -1946,6 +2246,7 @@ function activationProfile(detection, plan, changes, client) {
     ? plan.mcp_target_version
     : MCP_ADAPTER_VERSION;
   const targetCommand = (command) => retargetMcpPackageSpec(command, mcpTargetVersion);
+  const hostApprovals = hostApprovalHooksSupported(mcpTargetVersion);
   const adapterVersion = capabilityLevel === 'native_hooks' || capabilityLevel === 'mcp'
     ? mcpTargetVersion
     : capabilityLevel === 'sdk_passive_runtime'
@@ -1964,14 +2265,18 @@ function activationProfile(detection, plan, changes, client) {
     if (exactHookConfigured(codexSettings, 'PostToolUse', targetCommand(CODEX_ACTION_RESULT_HOOK_COMMAND), CODEX_NATIVE_HOOK_MATCHER)) observedHooks.push('action_result');
     if (exactHookConfigured(codexSettings, 'SessionEnd', targetCommand(CODEX_SESSION_END_HOOK_COMMAND))) observedHooks.push('session_end');
   } else if (client === 'cursor' || client === 'composer') {
-    if (exactCursorHookConfigured(cursorSettings, 'preToolUse', targetCommand(CURSOR_PRE_ACTION_HOOK_COMMAND), CURSOR_NATIVE_HOOK_MATCHER, {
-      timeout: CODEX_HOOK_TIMEOUT_SECONDS, failClosed: true, async: false,
-    })) observedHooks.push('pre_action');
+    const approvalHooks = hostApprovals ? cursorHostApprovalHooksConfigured(cursorSettings, targetCommand) : null;
+    if ((hostApprovals
+      ? approvalHooks.pre_tool_use && approvalHooks.beforeShellExecution && approvalHooks.beforeMCPExecution
+        && approvalHooks.sessionStart && approvalHooks.beforeSubmitPrompt
+      : exactCursorHookConfigured(cursorSettings, 'preToolUse', targetCommand(CURSOR_PRE_ACTION_HOOK_COMMAND), CURSOR_NATIVE_HOOK_MATCHER, {
+        timeout: CODEX_HOOK_TIMEOUT_SECONDS, failClosed: true, async: false,
+      }))) observedHooks.push('pre_action');
     if (exactCursorHookConfigured(cursorSettings, 'postToolUse', targetCommand(CURSOR_ACTION_RESULT_HOOK_COMMAND), CURSOR_NATIVE_HOOK_MATCHER, {
       timeout: CODEX_HOOK_TIMEOUT_SECONDS,
     }) && exactCursorHookConfigured(cursorSettings, 'postToolUseFailure', targetCommand(CURSOR_ACTION_RESULT_HOOK_COMMAND), CURSOR_NATIVE_HOOK_MATCHER, {
       timeout: CODEX_HOOK_TIMEOUT_SECONDS,
-    })) observedHooks.push('action_result');
+    }) && (!hostApprovals || (approvalHooks.afterShellExecution && approvalHooks.afterMCPExecution))) observedHooks.push('action_result');
     if (exactCursorHookConfigured(cursorSettings, 'stop', targetCommand(CURSOR_SESSION_END_HOOK_COMMAND), undefined, {
       timeout: CODEX_SESSION_TIMEOUT_SECONDS,
     })) observedHooks.push('outcome_closure');
@@ -1991,9 +2296,12 @@ function activationProfile(detection, plan, changes, client) {
     )) observedHooks.push('response_closeout');
   } else if (client === 'gemini' && !geminiHooksExplicitlyDisabled(geminiSettings)) {
     if (exactGeminiHookConfigured(
-      geminiSettings, 'BeforeTool', 'marrow-before-tool', targetCommand(GEMINI_PRE_ACTION_HOOK_COMMAND),
+      geminiSettings, 'BeforeTool', 'marrow-before-tool', targetCommand(geminiPreActionCommand(hostApprovals)),
       GEMINI_NATIVE_HOOK_MATCHER, GEMINI_HOOK_TIMEOUT_MS,
-    )) observedHooks.push('pre_action');
+    ) && (!hostApprovals || exactGeminiHookConfigured(
+      geminiSettings, 'BeforeAgent', 'marrow-before-agent', targetCommand(GEMINI_CONTEXT_HOOK_COMMAND),
+      undefined, GEMINI_HOOK_TIMEOUT_MS,
+    ))) observedHooks.push('pre_action');
     if (exactGeminiHookConfigured(
       geminiSettings, 'AfterTool', 'marrow-after-tool', targetCommand(GEMINI_ACTION_RESULT_HOOK_COMMAND),
       GEMINI_NATIVE_HOOK_MATCHER, GEMINI_HOOK_TIMEOUT_MS,
@@ -2017,11 +2325,14 @@ function activationProfile(detection, plan, changes, client) {
   } else {
     if (capabilityLevel === 'native_hooks'
       && exactHookConfigured(claudeSettings, 'UserPromptSubmit', targetCommand(MCP_CONTEXT_HOOK_COMMAND))) observedHooks.push('prompt');
+    const claudeApprovalHooks = hostApprovals ? claudeHostApprovalHooksConfigured(claudeSettings, targetCommand) : null;
     if (capabilityLevel === 'native_hooks'
-      && exactHookConfigured(claudeSettings, 'PreToolUse', targetCommand(MCP_PRE_ACTION_HOOK_COMMAND), NATIVE_HOOK_MATCHER)) observedHooks.push('pre_action');
+      && exactHookConfigured(claudeSettings, 'PreToolUse', targetCommand(MCP_PRE_ACTION_HOOK_COMMAND), NATIVE_HOOK_MATCHER)
+      && (!hostApprovals || claudeApprovalHooks.permission_request)) observedHooks.push('pre_action');
     if (capabilityLevel === 'native_hooks'
       && exactHookConfigured(claudeSettings, 'PostToolUse', targetCommand(MCP_ACTION_RESULT_HOOK_COMMAND), NATIVE_HOOK_MATCHER)
-      && exactHookConfigured(claudeSettings, 'PostToolUseFailure', targetCommand(MCP_ACTION_RESULT_HOOK_COMMAND), NATIVE_HOOK_MATCHER)) observedHooks.push('action_result');
+      && exactHookConfigured(claudeSettings, 'PostToolUseFailure', targetCommand(MCP_ACTION_RESULT_HOOK_COMMAND), NATIVE_HOOK_MATCHER)
+      && (!hostApprovals || claudeApprovalHooks.post_tool_batch)) observedHooks.push('action_result');
     if (capabilityLevel === 'native_hooks'
       && exactHookConfigured(claudeSettings, 'Stop', targetCommand(MCP_SESSION_END_HOOK_COMMAND))) observedHooks.push('session_end');
   }
@@ -2048,12 +2359,12 @@ function activationProfile(detection, plan, changes, client) {
     .join('|');
   const configFingerprint = capabilityLevel === 'native_hooks'
     ? client === 'codex' ? codexNativeHookFingerprint(codexSettings)
-      : client === 'cursor' || client === 'composer' ? cursorNativeHookFingerprint(cursorSettings)
+      : client === 'cursor' || client === 'composer' ? cursorNativeHookFingerprint(cursorSettings, { hostApprovals })
       : client === 'cline' ? clineNativeHookFingerprint(detection)
       : client === 'windsurf' ? windsurfNativeHookFingerprint(windsurfSettings)
-      : client === 'gemini' ? geminiNativeHookFingerprint(geminiSettings)
+      : client === 'gemini' ? geminiNativeHookFingerprint(geminiSettings, { hostApprovals })
       : client === 'grok' ? grokNativeHookFingerprint(grokSettings)
-      : claudeNativeHookFingerprint(claudeSettings)
+      : claudeNativeHookFingerprint(claudeSettings, { hostApprovals })
     : crypto.createHash('sha256')
       .update(`${client}:${capabilityLevel}:${expectedHooks.join(',')}:${fingerprintMaterial}`)
       .digest('hex');
@@ -2220,8 +2531,9 @@ function upsertMcpServerConfig(filePath, options = {}) {
   return JSON.stringify(config, null, 2) + '\n';
 }
 
-function inspectSdkDependency(detection) {
-  if (!detection.node) {
+function inspectSdkDependency(detection, { sdkMode = false } = {}) {
+  // No SDK advice unless this project uses the SDK or the owner asked for the SDK runtime.
+  if (!sdkMode && !sdkUseDetected(detection)) {
     return { required: false, present: false, install_command: null };
   }
 
@@ -2346,11 +2658,14 @@ function defaultHarnessInstallMatrix(detection = detectEnvironment(process.cwd()
       && exactHookConfigured(codexSettings, 'PreToolUse', CODEX_PRE_ACTION_HOOK_COMMAND, CODEX_NATIVE_HOOK_MATCHER)
       && exactHookConfigured(codexSettings, 'PostToolUse', CODEX_ACTION_RESULT_HOOK_COMMAND, CODEX_NATIVE_HOOK_MATCHER)
       && exactHookConfigured(codexSettings, 'SessionEnd', CODEX_SESSION_END_HOOK_COMMAND));
+    const hostApprovals = hostApprovalHooksSupported();
     const cursorSettings = ['cursor', 'composer'].includes(entry.client) ? safeJsonObject(detection.paths.cursorHooks) : null;
+    const cursorApprovalHooks = cursorSettings && hostApprovals ? cursorHostApprovalHooksConfigured(cursorSettings) : null;
     const cursorConfigured = Boolean(cursorSettings
-      && exactCursorHookConfigured(cursorSettings, 'preToolUse', CURSOR_PRE_ACTION_HOOK_COMMAND, CURSOR_NATIVE_HOOK_MATCHER, {
-        timeout: CODEX_HOOK_TIMEOUT_SECONDS, failClosed: true, async: false,
+      && exactCursorHookConfigured(cursorSettings, 'preToolUse', CURSOR_PRE_ACTION_HOOK_COMMAND, hostApprovals ? CURSOR_PRE_TOOL_USE_HOST_APPROVAL_MATCHER : CURSOR_NATIVE_HOOK_MATCHER, {
+        timeout: hostApprovals ? CURSOR_GATE_HOOK_TIMEOUT_SECONDS : CODEX_HOOK_TIMEOUT_SECONDS, failClosed: true, async: false,
       })
+      && (!cursorApprovalHooks || Object.values(cursorApprovalHooks).every(Boolean))
       && exactCursorHookConfigured(cursorSettings, 'postToolUse', CURSOR_ACTION_RESULT_HOOK_COMMAND, CURSOR_NATIVE_HOOK_MATCHER, {
         timeout: CODEX_HOOK_TIMEOUT_SECONDS,
       })
@@ -2377,9 +2692,13 @@ function defaultHarnessInstallMatrix(detection = detectEnvironment(process.cwd()
     const geminiConfigured = Boolean(geminiSettings
       && !geminiHooksExplicitlyDisabled(geminiSettings)
       && exactGeminiHookConfigured(
-        geminiSettings, 'BeforeTool', 'marrow-before-tool', GEMINI_PRE_ACTION_HOOK_COMMAND,
+        geminiSettings, 'BeforeTool', 'marrow-before-tool', geminiPreActionCommand(hostApprovals),
         GEMINI_NATIVE_HOOK_MATCHER, GEMINI_HOOK_TIMEOUT_MS,
       )
+      && (!hostApprovals || exactGeminiHookConfigured(
+        geminiSettings, 'BeforeAgent', 'marrow-before-agent', GEMINI_CONTEXT_HOOK_COMMAND,
+        undefined, GEMINI_HOOK_TIMEOUT_MS,
+      ))
       && exactGeminiHookConfigured(
         geminiSettings, 'AfterTool', 'marrow-after-tool', GEMINI_ACTION_RESULT_HOOK_COMMAND,
         GEMINI_NATIVE_HOOK_MATCHER, GEMINI_HOOK_TIMEOUT_MS,
@@ -2462,6 +2781,32 @@ function derivedAgentIdsFor(root) {
   return [...SOURCE_CLIENTS].map((candidate) => stableAgentId(root, candidate));
 }
 
+// SDK use in this project: the SDK is a declared or installed dependency, or an earlier install
+// already wrote Marrow's passive runtime here. Without it, no SDK file or SDK advice is written.
+function sdkUseDetected(detection) {
+  if (exists(detection.paths.passiveRuntime)) return true;
+  if (!detection.node) return false;
+  if (findUp(detection.root, [path.join('node_modules', '@getmarrow', 'sdk', 'package.json')])) return true;
+  const raw = safeRead(detection.paths.packageJson);
+  if (!raw) return false;
+  // A package.json Marrow cannot parse is checked by hand (the SDK check says so).
+  try {
+    JSON.parse(raw);
+  } catch {
+    return /@getmarrow\/sdk/.test(raw);
+  }
+  return /"@getmarrow\/sdk"/.test(raw) || /@getmarrow\/sdk@/.test(raw);
+}
+
+// Hosts that read AGENTS.md. Claude Code reads CLAUDE.md and Cursor gets its own rule file, so
+// a project with only those gets no AGENTS.md unless it already holds Marrow's block.
+const AGENTS_MD_READERS = Object.freeze(['codex', 'windsurf', 'gemini', 'cline', 'grok', 'hermes', 'openclaw']);
+
+function agentsMdWanted(detection) {
+  if (AGENTS_MD_READERS.some((name) => detection[name])) return true;
+  return Boolean(marrowManagedBlockInText(safeRead(detection.paths.agentsMd)));
+}
+
 function buildPlan(detection, options) {
   const client = options.client || detectedClient(detection);
   // Server-facing configuration carries only a configured agent id. Without one, the MCP
@@ -2488,9 +2833,14 @@ function buildPlan(detection, options) {
     return write;
   };
   const mcpTargetVersion = executableMcpTarget(options).version;
+  // Hooks start the verified local MCP runtime for this exact version when there is one.
+  const runtimeVersion = options.mcpRuntime && options.mcpRuntime.version === mcpTargetVersion ? mcpTargetVersion : null;
+  const localize = (text) => (runtimeVersion ? localizeHookSettingsText(text, runtimeVersion) : text);
   const retarget = (value) => retargetMcpPackageSpec(value, mcpTargetVersion);
+  // The host-approval hook layout only for an MCP that answers those hooks.
+  const hostApprovals = hostApprovalHooksSupported(mcpTargetVersion);
   const mode = options.mode === 'auto'
-    ? detection.node ? 'both' : 'mcp'
+    ? sdkUseDetected(detection) ? 'both' : 'mcp'
     : options.mode;
   const writes = [];
 
@@ -2516,7 +2866,7 @@ function buildPlan(detection, options) {
         type: 'json-transform',
         path: detection.paths.claudeSettings,
         label: 'Claude Code MCP passive hooks',
-        transform: (filePath) => retarget(upsertClaudeHooks(filePath)),
+        transform: (filePath) => localize(retarget(upsertClaudeHooks(filePath, { hostApprovals }))),
       });
     }
     if (detection.codex) {
@@ -2524,7 +2874,7 @@ function buildPlan(detection, options) {
         type: 'json-transform',
         path: detection.paths.codexHooks,
         label: 'Codex native hooks',
-        transform: (filePath) => retarget(upsertCodexHooks(filePath)),
+        transform: (filePath) => localize(retarget(upsertCodexHooks(filePath))),
       });
     }
     if (detection.cline) {
@@ -2544,7 +2894,7 @@ function buildPlan(detection, options) {
         type: 'json-transform',
         path: detection.paths.windsurfHooks,
         label: 'Windsurf native hooks',
-        transform: (filePath) => retarget(upsertWindsurfHooks(filePath)),
+        transform: (filePath) => localize(retarget(upsertWindsurfHooks(filePath))),
       });
     }
     if (detection.gemini) {
@@ -2552,7 +2902,7 @@ function buildPlan(detection, options) {
         type: 'json-transform',
         path: detection.paths.geminiSettings,
         label: 'Gemini CLI native hooks',
-        transform: (filePath) => retarget(upsertGeminiHooks(filePath)),
+        transform: (filePath) => localize(retarget(upsertGeminiHooks(filePath, { hostApprovals }))),
       });
     }
     if (detection.grok) {
@@ -2563,7 +2913,7 @@ function buildPlan(detection, options) {
         label: 'Grok native hooks',
         isManaged: managedGrokHooksFile,
         conflict_fix: 'Preserve or move the unmanaged owner Grok hook file after owner review, then rerun npx @getmarrow/install update.',
-        transform: (filePath) => retarget(upsertGrokHooks(filePath)),
+        transform: (filePath) => localize(retarget(upsertGrokHooks(filePath))),
       });
     }
     writes.push(mcpConfigWrite(detection.paths.mcpJson, 'Project MCP server config'));
@@ -2587,18 +2937,20 @@ function buildPlan(detection, options) {
         type: 'json-transform',
         path: detection.paths.cursorHooks,
         label: 'Cursor native hooks',
-        transform: (filePath) => retarget(upsertCursorHooks(filePath)),
+        transform: (filePath) => localize(retarget(upsertCursorHooks(filePath, { hostApprovals }))),
       });
       writes.push(mcpConfigWrite(detection.paths.cursorMcp, 'Cursor MCP server config'));
     }
   }
 
-  if (mode === 'md' || mode === 'both' || mode === 'mcp') {
+  // AGENTS.md only for a host that reads it, an explicit --md or --both, or a file that already
+  // carries Marrow's block (so its pins stay current).
+  if (mode === 'md' || (options.mode === 'both') || ((mode === 'both' || mode === 'mcp') && agentsMdWanted(detection))) {
     writes.push({
       type: 'md-block',
       path: detection.paths.agentsMd,
       label: 'Agent instructions',
-      block: retarget(passiveInstructions()),
+      block: retarget(passiveInstructions({ hostApprovals })),
     });
   }
 
@@ -2607,11 +2959,11 @@ function buildPlan(detection, options) {
       type: 'file',
       path: detection.paths.cursorRules,
       label: 'Cursor Marrow rule',
-      content: retarget(passiveInstructions()).replace(/<!--[^>]+-->/g, '').trim() + '\n',
+      content: retarget(passiveInstructions({ hostApprovals })).replace(/<!--[^>]+-->/g, '').trim() + '\n',
     });
   }
 
-  return { mode, root: detection.root, writes, mcp_target_version: mcpTargetVersion };
+  return { mode, root: detection.root, writes, mcp_target_version: mcpTargetVersion, host_approval_hooks: hostApprovals };
 }
 
 function assertContainedManagedTarget(root, targetPath) {
@@ -2728,7 +3080,9 @@ function applyPlan(plan, options) {
         undo = planned.action === 'update' ? planned.undo || [] : null;
       }
     } else if (write.type === 'owned-executable') {
-      if (fileExists && before !== write.content) {
+      // A file Marrow wrote for another pinned MCP version is still Marrow's and moves to this
+      // pin; any other difference is the owner's edit and is never overwritten.
+      if (fileExists && before !== write.content && !sameMarrowFile(before, [write.content])) {
         after = before;
         hookConflict = true;
       } else {
@@ -2803,6 +3157,294 @@ function applyPlan(plan, options) {
   return changes;
 }
 
+// ---------------------------------------------------------------------------
+// Uninstall: removes only what Marrow wrote. Every other hook, server, setting and file is kept.
+// Files are read in-process and never printed; the report names paths and counts only.
+// ---------------------------------------------------------------------------
+
+// Hook groups of the Claude Code, Codex, Grok and Gemini shape:
+// hooks[event] = [{ matcher?, hooks: [handler, ...] }].
+function withoutMarrowGroupedHandlers(settings, isMarrowHandler) {
+  const hooks = settings?.hooks;
+  if (!hooks || typeof hooks !== 'object' || Array.isArray(hooks)) return { settings, removed: 0, kept: 0 };
+  let removed = 0;
+  let kept = 0;
+  const next = {};
+  for (const [eventName, entries] of Object.entries(hooks)) {
+    if (!Array.isArray(entries)) {
+      next[eventName] = entries;
+      continue;
+    }
+    const retained = [];
+    let touched = false;
+    for (const entry of entries) {
+      if (!entry || typeof entry !== 'object' || Array.isArray(entry) || !Array.isArray(entry.hooks)) {
+        retained.push(entry);
+        kept += 1;
+        continue;
+      }
+      const handlers = entry.hooks.filter((handler) => !isMarrowHandler(handler));
+      kept += handlers.length;
+      if (handlers.length === entry.hooks.length) {
+        retained.push(entry);
+        continue;
+      }
+      touched = true;
+      removed += entry.hooks.length - handlers.length;
+      if (handlers.length > 0) retained.push({ ...entry, hooks: handlers });
+    }
+    // An event that held only Marrow's entries goes away with them.
+    if (touched && retained.length === 0) continue;
+    next[eventName] = retained;
+  }
+  const result = { ...settings, hooks: next };
+  if (removed > 0 && Object.keys(next).length === 0) delete result.hooks;
+  return { settings: result, removed, kept };
+}
+
+// Flat hook lists of the Cursor and Windsurf shape: hooks[event] = [{ command, ... }].
+function withoutMarrowFlatEntries(settings, isMarrowEntry) {
+  const hooks = settings?.hooks;
+  if (!hooks || typeof hooks !== 'object' || Array.isArray(hooks)) return { settings, removed: 0, kept: 0 };
+  let removed = 0;
+  let kept = 0;
+  const next = {};
+  for (const [eventName, entries] of Object.entries(hooks)) {
+    if (!Array.isArray(entries)) {
+      next[eventName] = entries;
+      continue;
+    }
+    const retained = entries.filter((entry) => !(entry && typeof entry === 'object' && !Array.isArray(entry) && isMarrowEntry(entry)));
+    kept += retained.length;
+    removed += entries.length - retained.length;
+    if (retained.length === 0 && entries.length > 0) continue;
+    next[eventName] = retained;
+  }
+  const result = { ...settings, hooks: next };
+  if (removed > 0 && Object.keys(next).length === 0) delete result.hooks;
+  return { settings: result, removed, kept };
+}
+
+const isMarrowCommandHandler = (handler) => Boolean(handler && typeof handler === 'object' && !Array.isArray(handler)
+  && handler.type === 'command' && marrowHookSubcommand(handler.command));
+const isMarrowGeminiHandler = (handler) => Boolean(handler && typeof handler === 'object' && !Array.isArray(handler)
+  && (String(handler.name || '').startsWith('marrow-') || geminiMarrowHookEntrypoint(handler.command)));
+const isMarrowGrokHandler = (handler) => Boolean(handler && typeof handler === 'object' && !Array.isArray(handler)
+  && handler.type === 'command' && grokMarrowHookSubcommand(handler.command));
+
+// The MCP server entry only when Marrow wrote it: npx running the published package.
+function withoutMarrowMcpServer(config) {
+  const servers = config?.mcpServers;
+  const entry = servers && typeof servers === 'object' && !Array.isArray(servers) ? servers.marrow : null;
+  if (!entry) return { config, removed: 0, kept: 0, custom: false };
+  const args = Array.isArray(entry.args) ? entry.args.map(String) : [];
+  const ours = entry.command === 'npx' && args.includes('marrow-mcp')
+    && args.some((arg) => /^--package=@getmarrow\/mcp(?:@[^\s]+)?$/.test(arg));
+  if (!ours) return { config, removed: 0, kept: 1, custom: true };
+  const nextServers = { ...servers };
+  delete nextServers.marrow;
+  const result = { ...config, mcpServers: nextServers };
+  if (Object.keys(nextServers).length === 0) delete result.mcpServers;
+  return { config: result, removed: 1, kept: Object.keys(nextServers).length, custom: false };
+}
+
+function withoutMarrowInstructionBlock(content) {
+  const block = marrowManagedBlockInText(content);
+  if (!block) return { content, removed: 0 };
+  const start = content.indexOf(block);
+  const before = content.slice(0, start);
+  const after = content.slice(start + block.length).replace(/^\n/, '');
+  const head = before.trim() ? before.replace(/\n*$/, after.trim() ? '\n\n' : '\n') : '';
+  return { content: `${head}${after}`, removed: 1 };
+}
+
+// Marrow-written files compare equal once the pinned MCP version is normalized.
+function sameMarrowFile(actual, candidates) {
+  const normalize = (value) => String(value).replace(/@getmarrow\/mcp@\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?/g, '@getmarrow/mcp@<pinned>');
+  const normalized = normalize(actual);
+  return candidates.some((candidate) => normalize(candidate) === normalized);
+}
+
+function buildUninstallPlan(detection) {
+  const steps = [];
+  const json = (filePath, label, transform, extra = {}) => steps.push({ kind: 'json', path: filePath, label, transform, ...extra });
+  const mcpServer = (value) => {
+    const result = withoutMarrowMcpServer(value);
+    return { settings: result.config, removed: result.removed, kept: result.kept, custom: result.custom };
+  };
+  json(detection.paths.claudeSettings, 'Claude Code hooks', (value) => withoutMarrowGroupedHandlers(value, isMarrowCommandHandler));
+  json(detection.paths.codexHooks, 'Codex hooks', (value) => withoutMarrowGroupedHandlers(value, isMarrowCommandHandler));
+  json(detection.paths.cursorHooks, 'Cursor hooks', (value) => withoutMarrowFlatEntries(value, (entry) => Boolean(cursorMarrowHookSubcommand(entry.command))));
+  json(detection.paths.windsurfHooks, 'Windsurf hooks', (value) => withoutMarrowFlatEntries(value, (entry) => Boolean(windsurfMarrowHookEntrypoint(entry.command))));
+  json(detection.paths.geminiSettings, 'Gemini CLI hooks', (value) => withoutMarrowGroupedHandlers(value, isMarrowGeminiHandler));
+  json(detection.paths.grokHooks, 'Grok hooks', (value) => withoutMarrowGroupedHandlers(value, isMarrowGrokHandler), {
+    root: detection.home,
+    grok: true,
+    // Marrow's own global file: deleted when nothing but Marrow's hooks was in it.
+    removeWhenEmpty: true,
+  });
+  json(detection.paths.mcpJson, 'Project MCP server config', mcpServer);
+  json(detection.paths.cursorMcp, 'Cursor MCP server config', mcpServer);
+  steps.push({ kind: 'md-block', path: detection.paths.agentsMd, label: 'Agent instructions' });
+  const instructionVariants = [false, true].map((hostApprovals) => passiveInstructions({ hostApprovals }).replace(/<!--[^>]+-->/g, '').trim() + '\n');
+  steps.push({ kind: 'owned-file', path: detection.paths.cursorRules, label: 'Cursor Marrow rule', candidates: instructionVariants });
+  for (const hook of clineHookContract(detection)) {
+    steps.push({ kind: 'owned-file', path: hook.path, label: hook.label, candidates: [hook.content] });
+  }
+  return steps;
+}
+
+function uninstallFileState(filePath) {
+  try {
+    const stat = fs.lstatSync(filePath);
+    if (stat.isSymbolicLink() || !stat.isFile()) return 'unsafe';
+    if (stat.size > 4 * 1024 * 1024) return 'too_large';
+    return 'file';
+  } catch {
+    return 'missing';
+  }
+}
+
+async function uninstall(options = {}) {
+  const home = options.home || process.env.HOME || process.env.USERPROFILE || os.homedir();
+  const detection = detectEnvironment(options.cwd || process.cwd(), { ...process.env, HOME: home, USERPROFILE: home });
+  const apply = Boolean(options.yes && !options.dryRun);
+  const root = path.resolve(detection.root);
+  const changes = [];
+  let controller = null;
+  if (apply && options.controller !== false) {
+    // A running controller restores missing managed hooks every five minutes; stop it first.
+    try {
+      const stopped = await stopProjectControllers({ root, client: detectedClient(detection), mode: 'auto' });
+      controller = { stopped: stopped.stopped || 0, changed: Boolean(stopped.changed) };
+    } catch {
+      controller = { stopped: 0, changed: false, error: 'controller_stop_failed' };
+    }
+  }
+  for (const step of buildUninstallPlan(detection)) {
+    const state = uninstallFileState(step.path);
+    if (state === 'missing') continue;
+    const change = { path: step.path, label: step.label, removed_entries: 0, kept_entries: 0, action: 'unchanged', applied: false };
+    if (state !== 'file') {
+      changes.push({ ...change, action: 'skipped', reason: state === 'unsafe' ? 'not a regular file' : 'larger than 4 MB' });
+      continue;
+    }
+    try {
+      const writeRoot = step.root ? path.resolve(step.root) : root;
+      if (step.grok) {
+        if (!managedGrokHooksFile(step.path)) {
+          changes.push({ ...change, action: 'skipped', reason: 'not managed by Marrow' });
+          continue;
+        }
+        assertSafeGrokHookTarget(writeRoot, step.path);
+      }
+      assertContainedManagedTarget(writeRoot, step.path);
+      const before = fs.readFileSync(step.path, 'utf8');
+      if (step.kind === 'owned-file') {
+        if (!sameMarrowFile(before, step.candidates)) {
+          if (MARROW_MANAGED_TEXT_RE.test(before)) changes.push({ ...change, action: 'kept', reason: 'edited after Marrow wrote it' });
+          continue;
+        }
+        change.removed_entries = 1;
+        change.action = 'delete_file';
+        if (apply) fs.unlinkSync(step.path);
+      } else if (step.kind === 'md-block') {
+        const result = withoutMarrowInstructionBlock(before);
+        if (!result.removed) continue;
+        change.removed_entries = 1;
+        change.action = result.content.trim() ? 'update' : 'delete_file';
+        if (change.action === 'delete_file') change.note = 'it held only the Marrow block';
+        else change.note = 'block_only';
+        if (apply) {
+          if (change.action === 'delete_file') fs.unlinkSync(step.path);
+          else atomicWriteManagedFile(writeRoot, step.path, result.content);
+        }
+      } else {
+        let parsed;
+        try {
+          // Marrow's hook commands in their canonical form, whether they start through npx or
+          // the local runtime, so both are recognized and removed.
+          parsed = before.trim() ? mapHookCommands(JSON.parse(before), delocalizeHookCommand) : {};
+        } catch {
+          changes.push({ ...change, action: 'skipped', reason: 'invalid JSON' });
+          continue;
+        }
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+          changes.push({ ...change, action: 'skipped', reason: 'root is not a JSON object' });
+          continue;
+        }
+        const result = step.transform(parsed);
+        change.kept_entries = result.kept;
+        if (result.custom) {
+          changes.push({ ...change, action: 'kept', reason: 'custom marrow server entry' });
+          continue;
+        }
+        if (!result.removed) continue;
+        change.removed_entries = result.removed;
+        const emptied = step.removeWhenEmpty && result.kept === 0
+          && Object.keys(result.settings).every((key) => key === 'hooks');
+        change.action = emptied ? 'delete_file' : 'update';
+        if (apply) {
+          if (emptied) fs.unlinkSync(step.path);
+          else atomicWriteManagedFile(writeRoot, step.path, JSON.stringify(result.settings, null, 2) + '\n');
+        }
+      }
+      change.applied = apply;
+      changes.push(change);
+    } catch (error) {
+      changes.push({ ...change, action: 'skipped', reason: error instanceof Error ? error.message.slice(0, 200) : 'unsafe target' });
+    }
+  }
+  const kept = [];
+  if (exists(detection.paths.passiveRuntime)) kept.push({ path: detection.paths.passiveRuntime, reason: 'your start command may import it; remove that import first, then delete the file' });
+  if (exists(detection.paths.passiveEnv)) kept.push({ path: detection.paths.passiveEnv, reason: 'it may hold your own edits; delete it when no longer needed' });
+  let hermesEntry = false;
+  try {
+    hermesEntry = Boolean(detection.hermesConfig)
+      && /(?:^|\n)mcp_servers:[\s\S]*\n[ \t]+marrow:/.test(fs.readFileSync(detection.paths.hermesConfig, 'utf8'));
+  } catch {
+    hermesEntry = false;
+  }
+  if (hermesEntry) kept.push({ path: detection.paths.hermesConfig, reason: 'remove mcp_servers.marrow by hand; uninstall never rewrites the Hermes config, which holds other servers\' settings' });
+  // The local MCP runtime (~/.marrow/runtime) goes too; hooks elsewhere then start through npx.
+  const runtime = removeMcpRuntime(options.home || detection.home, { dryRun: !apply });
+  const removedEntries = changes.reduce((sum, change) => sum + change.removed_entries, 0);
+  return {
+    uninstall: {
+      applied: apply,
+      dry_run: !apply,
+      root,
+      controller,
+      changes,
+      kept,
+      runtime: runtime.removed || runtime.would_remove ? runtime : null,
+      removed_entries: removedEntries,
+      next_step: apply
+        ? 'Restart the agent hosts so they stop loading the removed hooks and MCP server.'
+        : removedEntries > 0 || runtime.would_remove
+        ? 'Nothing was changed. Run npx @getmarrow/install uninstall --yes to remove these Marrow entries.'
+        : 'Nothing to remove.',
+    },
+  };
+}
+
+function printUninstallReport(report, sink = (text) => process.stdout.write(text)) {
+  const result = report.uninstall;
+  const where = (filePath) => (filePath.startsWith(`${result.root}${path.sep}`) ? path.relative(result.root, filePath) : filePath);
+  const entries = (count) => `${count} Marrow entr${count === 1 ? 'y' : 'ies'}`;
+  sink(`Marrow uninstall${result.applied ? '' : ' (preview)'}: ${entries(result.removed_entries)} ${result.applied ? 'removed' : 'to remove'}.\n`);
+  for (const change of result.changes) {
+    if (change.action === 'update' && change.note) sink(`- ${where(change.path)}: ${result.applied ? 'removed' : 'would remove'} the Marrow block; your text is kept.\n`);
+    else if (change.action === 'update') sink(`- ${where(change.path)}: ${result.applied ? 'removed' : 'would remove'} ${entries(change.removed_entries)}; kept ${change.kept_entries} of yours.\n`);
+    else if (change.action === 'delete_file') sink(`- ${where(change.path)}: ${result.applied ? 'deleted' : 'would delete'} (${change.note || 'Marrow\'s own file'}).\n`);
+    else if (change.action === 'kept' || change.action === 'skipped') sink(`- ${where(change.path)}: left unchanged (${change.reason}).\n`);
+  }
+  for (const entry of result.kept) sink(`- ${where(entry.path)}: left in place; ${entry.reason}.\n`);
+  if (result.runtime) sink(`- ${result.runtime.path}: ${result.applied ? 'removed' : 'would remove'} Marrow's local MCP runtime (other projects' hooks start through npx until the next install there).\n`);
+  if (result.controller?.stopped) sink(`Stopped ${result.controller.stopped} Marrow controller${result.controller.stopped === 1 ? '' : 's'} for this project.\n`);
+  sink(`${result.next_step}\n`);
+}
+
 const SELF_TEST_READ_TIMEOUT_MS = 15_000;
 
 async function requestJson(url, options) {
@@ -2976,7 +3618,15 @@ function runtimeGateVerified(runtime) {
   return ['allow', 'warn', 'review_required', 'block'].includes(decision);
 }
 
-const ACTIVATION_UNBOUND_KEY_FIX = 'This API key is not bound to one agent, so Marrow cannot confirm activation for a specific agent. Bind the key to one agent in the Marrow dashboard, or register the agent with POST /v1/agents and set MARROW_AGENT_ID to its id, then run npx -y @getmarrow/install@latest doctor --self-test.';
+// When Marrow refuses this machine's agent identity, the one command that fixes it. A key that
+// is simply not bound to one agent needs nothing: Marrow resolves the agent on each call.
+const IDENTITY_REFUSED_RE = /AGENT_NOT_REGISTERED|wrong_agent_id|MARROW_AGENT_SCOPE_MISMATCH|Agent-bound key cannot access another agent/i;
+function identityRefusalFix(message, configuredAgentId = '') {
+  if (!IDENTITY_REFUSED_RE.test(String(message || ''))) return null;
+  return configuredAgentId
+    ? 'unset MARROW_AGENT_ID MARROW_FLEET_AGENT_ID && npx -y @getmarrow/install@latest activate'
+    : 'npx -y @getmarrow/install@latest activate  (with a key for one agent from your Marrow account saved in ~/.marrow/env, or exported as MARROW_API_KEY)';
+}
 
 // The agent Marrow resolved for this key: its single bound agent or the Free plan seat. An
 // unbound key has no single agent, and a locally derived id is never substituted for it.
@@ -3038,7 +3688,7 @@ async function runSelfTest(options) {
     return {
       skipped: true,
       reason: 'missing MARROW_API_KEY',
-      exact_fix: 'export MARROW_API_KEY=mrw_live_... && npx @getmarrow/install --repair',
+      exact_fix: 'Create a key at https://getmarrow.ai/signup, save it as MARROW_API_KEY=your_key in the owner-only ~/.marrow/env, then run chmod 700 ~/.marrow && chmod 600 ~/.marrow/env, then run npx -y @getmarrow/install@latest activate',
       mcp_tool_profile: initialProfile,
     };
   }
@@ -3224,7 +3874,11 @@ async function runSelfTest(options) {
         method: 'POST',
         headers,
         body: JSON.stringify({
-          event_id: `activation-${activationConfigFingerprint.slice(0, 32)}`,
+          // One registration per agent: two agents with the same hook configuration (a second
+          // agent installed on the same project) are two events, so the second is not refused
+          // as a conflicting reuse of the first agent's event id. Reruns by one agent repeat
+          // the same id.
+          event_id: `activation-${crypto.createHash('sha256').update(`${activationConfigFingerprint}\0${activationAgentId}`).digest('hex').slice(0, 32)}`,
           event_type: 'activation_profile_registered',
           harness: options.activation.harness,
           agent_id: activationAgentId,
@@ -3291,7 +3945,8 @@ async function runSelfTest(options) {
     bound_agent_ids: serverIdentity.bound_agent_ids,
     activation_verified: activationVerified,
     activation_identity_unresolved: activationIdentityUnresolved,
-    activation_exact_fix: activationIdentityUnresolved ? ACTIVATION_UNBOUND_KEY_FIX : null,
+    // An unbound key is fine: Marrow resolves the agent on each call, so there is nothing to fix.
+    activation_exact_fix: null,
     activation_scope: options.activation ? 'server_self_test_only' : null,
     coverage_verified: false,
     passive_live: false,
@@ -3486,6 +4141,16 @@ function printReport(report, sink) {
     }
   }
 
+  if (report.mcp_runtime) {
+    const runtime = report.mcp_runtime;
+    out('\nMCP local runtime:\n');
+    out(`- hooks start: ${runtime.hooks_start === 'local_runtime' ? `the verified local copy of @getmarrow/mcp@${runtime.version} (${runtime.path})` : 'through npx'}\n`);
+    out(`- state: ${runtime.state}${runtime.reason ? ` (${runtime.reason})` : ''}\n`);
+    if (runtime.removed_versions?.length) out(`- removed older versions: ${runtime.removed_versions.join(', ')}\n`);
+  }
+  if (report.owner_key_storage) {
+    out(`\nAPI key for hosts opened outside this terminal: ${report.owner_key_storage.state}${report.owner_key_storage.path ? ` (${report.owner_key_storage.path})` : ''}\n`);
+  }
   out('\nLocal session loop guard:\n');
   out(`- configured: ${report.loop_guard_configured ? 'yes' : 'no'}\n`);
   out(`- isolated self-test passed: ${report.loop_guard_self_tested ? 'yes' : 'no'}\n`);
@@ -3744,6 +4409,62 @@ function hermesWiringReport(detection, changes, options, planMode) {
   };
 }
 
+// The local MCP runtime for the target version: installed (or kept) on a write run of the
+// command, otherwise only an existing verified copy is used. `mcpLocalRuntime: false` (or
+// MARROW_LOCAL_RUNTIME=0, --no-local-runtime) leaves every hook of this project on npx.
+function resolveMcpRuntime(detection, options, mcpTarget) {
+  const home = options.home || detection.home;
+  if (options.mcpLocalRuntime === false) return { state: 'disabled' };
+  const version = mcpTarget.version;
+  const integrity = mcpTarget.integrity || (version === MCP_ADAPTER_VERSION ? MCP_ADAPTER_INTEGRITY : null);
+  if (!integrity) return { state: 'skipped', reason: 'no_verified_integrity', version };
+  const install = options.mcpLocalRuntime === true && options.yes && !options.dryRun && !options.doctor && options.maintenance !== true;
+  if (install) {
+    return ensureMcpRuntime({
+      home,
+      version,
+      integrity,
+      sdk: { version: SDK_ADAPTER_VERSION, integrity: SDK_ADAPTER_INTEGRITY },
+      ...(typeof options.mcpRuntimeInstall === 'function' ? { npmInstall: options.mcpRuntimeInstall } : {}),
+      ...(options.mcpRuntimeNode ? { nodePath: options.mcpRuntimeNode } : {}),
+      // One line on stderr before npm runs, so the wait is never silent (stdout stays clean
+      // for --json).
+      onProgress: typeof options.mcpRuntimeProgress === 'function' ? options.mcpRuntimeProgress : (text) => process.stderr.write(text),
+    });
+  }
+  return verifyMcpRuntime(home, version, integrity) || { state: 'absent', version };
+}
+
+// Whether this project's managed hooks start the local runtime now, as its install chose.
+function projectHooksUseLocalRuntime(detection) {
+  const paths = detection.paths || {};
+  return [paths.claudeSettings, paths.codexHooks, paths.cursorHooks, paths.windsurfHooks, paths.geminiSettings]
+    .some((filePath) => filePath && safeRead(filePath).includes('/.marrow/runtime/mcp/'));
+}
+
+// The controller's maintenance rewrites managed hooks for the pinned MCP and keeps each project
+// in the form its install chose: on the verified local runtime for that version when the
+// project's hooks start it (verify only: maintenance never installs), on npx otherwise. A
+// project installed with --no-local-runtime stays on npx even when another project's install
+// put a runtime on this machine.
+function maintenanceMcpRuntime(detection, options = {}) {
+  if (options.mcpLocalRuntime === false || !projectHooksUseLocalRuntime(detection)) return null;
+  const runtime = resolveMcpRuntime(detection, { ...options, maintenance: true, yes: false }, executableMcpTarget(options));
+  return runtime.version && ['present', 'installed', 'verified'].includes(runtime.state) ? runtime : null;
+}
+
+function mcpRuntimeReport(runtime) {
+  if (!runtime) return null;
+  return {
+    state: runtime.state,
+    version: runtime.version || null,
+    path: runtime.directory || null,
+    ...(runtime.reason ? { reason: runtime.reason } : {}),
+    ...(runtime.removed_versions?.length ? { removed_versions: runtime.removed_versions } : {}),
+    hooks_start: runtime.directory && ['present', 'installed', 'verified'].includes(runtime.state) ? 'local_runtime' : 'npx',
+  };
+}
+
 function localControllerAgentId(root, client, configuredAgentId = '') {
   return String(configuredAgentId || '').trim() || stableAgentId(root, client);
 }
@@ -3790,6 +4511,11 @@ async function install(options) {
   });
   options.mcpTarget = mcpTarget;
   options.mcpTargetVersion = mcpTarget.version;
+  // A maintenance pass keeps the project's hooks in the form its install chose.
+  const mcpRuntime = options.maintenance === true
+    ? maintenanceMcpRuntime(detection, options) || { state: options.mcpLocalRuntime === false ? 'disabled' : 'absent', version: mcpTarget.version }
+    : resolveMcpRuntime(detection, options, mcpTarget);
+  options.mcpRuntime = mcpRuntime.version && ['present', 'installed', 'verified'].includes(mcpRuntime.state) ? mcpRuntime : null;
   const plan = buildPlan(detection, options);
   const writeMode = options.doctor ? 'doctor' : options.dryRun ? 'dry-run' : options.repair ? 'repair' : options.yes ? 'write' : 'dry-run';
   const changes = applyPlan(plan, options);
@@ -3839,7 +4565,7 @@ async function install(options) {
     intervention_verified: false,
     closure_verified: false,
   } : null;
-  const sdkDependency = inspectSdkDependency(detection);
+  const sdkDependency = inspectSdkDependency(detection, { sdkMode: plan.mode === 'sdk' || plan.mode === 'both' });
   const envHints = options.apiKey ? [] : findLikelyEnvFiles(detection);
   const mcpProcesses = inspectMcpProcesses({
     commands: options.processCommands,
@@ -4049,6 +4775,7 @@ async function install(options) {
     harnessReload,
     firstCapture: firstCapturePath(detection),
     hermes,
+    mcp_runtime: mcpRuntimeReport(mcpRuntime),
     changes,
     doctor: {
       active: Boolean(!selfTest.skipped && selfTest.active),
@@ -4099,36 +4826,48 @@ async function install(options) {
   };
 }
 
-function activationFailureFix(message) {
-  if (/Agent-bound key cannot access another agent|MARROW_AGENT_SCOPE_MISMATCH/i.test(message)) {
-    return `unset MARROW_AGENT_ID and MARROW_FLEET_AGENT_ID so Marrow uses the key's own agent, then rerun ${INSTALLER_UPDATE_COMMAND}`;
-  }
-  return INSTALLER_DOCTOR_COMMAND;
+function activationFailureFix(message, configuredAgentId = '') {
+  return identityRefusalFix(message, configuredAgentId) || INSTALLER_DOCTOR_COMMAND;
 }
 
 function installCommandFor(options) {
-  return options.update ? INSTALLER_UPDATE_COMMAND : 'npx -y @getmarrow/install@latest';
+  return options.update ? INSTALLER_UPDATE_COMMAND : 'npx -y @getmarrow/install@latest activate';
+}
+
+// Static text: it never echoes a key, a command line or a path. The stored-file form comes first
+// because a key typed on a command line lands in shell history.
+function missingKeyMessage(options) {
+  const command = installCommandFor(options);
+  return `Marrow needs your API key. Nothing was written. Create a key at https://getmarrow.ai/signup, save it as MARROW_API_KEY=your_key in the owner-only file ~/.marrow/env, then run chmod 700 ~/.marrow && chmod 600 ~/.marrow/env, then run: ${command}  (fallback: MARROW_API_KEY=your_key ${command})`;
 }
 
 // One summary for the one-command paths (first install and update). The full report goes to a
 // private log file. Nothing here prints the API key.
+// One verdict for the self-test, used by the summary and by key storage: it passed only when it
+// ran, raised no error, found the account active and Marrow committed the closure.
+function selfTestVerdict(selfTest = {}) {
+  const untrusted = !selfTest.skipped && !selfTest.error && Boolean(selfTest.active) && selfTest.decision_committed !== true;
+  const failed = !selfTest.skipped && (Boolean(selfTest.error) || !selfTest.active || untrusted);
+  return { untrusted, failed, passed: !selfTest.skipped && !failed };
+}
+
 function installSummaryLines(report, options) {
   const selfTest = report.selfTest || {};
   const activation = report.activation || {};
   const lines = [];
-  const untrusted = !selfTest.skipped && !selfTest.error && selfTest.active && selfTest.decision_committed !== true;
-  const selfTestFailed = !selfTest.skipped && (Boolean(selfTest.error) || !selfTest.active || untrusted);
+  const { untrusted, failed: selfTestFailed } = selfTestVerdict(selfTest);
   if (selfTest.skipped) {
     lines.push(`Marrow ${INSTALLER_ADAPTER_VERSION}: configuration updated; self-test skipped (${selfTest.reason}).${selfTest.exact_fix ? ` Fix: ${selfTest.exact_fix}` : ''}`);
   } else if (untrusted) {
     lines.push(`Marrow ${INSTALLER_ADAPTER_VERSION}: self-test decision ${selfTest.decision_id} was recorded without trusted closure (committed was not true). Fix: ${INSTALLER_DOCTOR_COMMAND}`);
   } else if (selfTestFailed) {
-    const fix = report.doctor?.recommendedFix || INSTALLER_DOCTOR_COMMAND;
+    const fix = identityRefusalFix(selfTest.error, activation.agent_id_source === 'configured' ? activation.agent_id : '')
+      || report.doctor?.recommendedFix || INSTALLER_DOCTOR_COMMAND;
     lines.push(`Marrow ${INSTALLER_ADAPTER_VERSION}: self-test failed: ${selfTest.error || 'Marrow reported this account as inactive'}. Fix: ${fix}`);
   } else {
     const agent = activation.agent_id
       ? `; agent ${activation.agent_id} (${activation.agent_id_source === 'configured' ? 'configured' : 'resolved by Marrow'})`
-      : '; this key is not bound to one agent';
+      : '';
     lines.push(`Marrow ${INSTALLER_ADAPTER_VERSION}: healthy. Self-test decision ${selfTest.decision_id} committed${agent}.`);
   }
   if (activation.exact_fix) lines.push(`Activation: ${activation.exact_fix}`);
@@ -4155,6 +4894,14 @@ function installSummaryLines(report, options) {
   } else if (hermes.state === 'refused' || hermes.state === 'config_not_found' || hermes.state === 'preserved_unverified_ahead') {
     lines.push(`Hermes: ${hermes.config_path || 'config.yaml'} was not changed. The exact block to add is in the full report.`);
   }
+  const ownerKey = report.owner_key_storage || {};
+  if (ownerKey.state === 'written') {
+    lines.push(`Saved your API key in ${ownerKey.path} (only you can read it), so Claude Code finds it when opened from the desktop app, an IDE or a new terminal.`);
+  } else if (ownerKey.state === 'different_key_present') {
+    lines.push(`Note: ${ownerKey.path} holds a different Marrow key, and Claude Code uses that one when opened outside this terminal. To use this key there, remove that key from the file and run npx @getmarrow/install again.`);
+  } else if (ownerKey.state && !['present', 'no_key'].includes(ownerKey.state)) {
+    lines.push(`Note: your API key was not saved for Claude Code opened outside this terminal (${ownerKey.path || '~/.marrow/env'} is not a private owner-only file).`);
+  }
   if (hermes.owner_key_storage?.state === 'written') {
     lines.push('Stored your API key in ~/.marrow/env (mode 600) so the Hermes MCP server can read it; Hermes passes no other environment to MCP servers.');
   } else if (hermes.owner_key_storage?.state === 'different_key_present') {
@@ -4190,7 +4937,16 @@ async function runCli(argv) {
     process.stdout.write(usage());
     return;
   }
+  if (options.uninstall) {
+    const report = await uninstall(options);
+    if (options.json) process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    else printUninstallReport(report);
+    return;
+  }
+  // An empty or whitespace-only key from any source (environment, --key, owner file) is missing.
+  options.apiKey = String(options.apiKey || '').trim();
   const stored = readOwnerApiKey(options.home);
+  stored.apiKey = String(stored.apiKey || '').trim();
   const keyInfo = { source: options.apiKey ? 'environment' : null, path: null, owner_files_disagree: stored.conflict };
   if (!options.apiKey && stored.apiKey) {
     options.apiKey = stored.apiKey;
@@ -4198,7 +4954,11 @@ async function runCli(argv) {
     keyInfo.path = stored.source;
   }
   const oneCommand = Boolean((options.activate || options.update) && !options.dryRun && !options.doctor);
-  if (oneCommand && !options.apiKey) {
+  // Any write run without a key stops here, before anything is written: hooks installed with no
+  // key would deny protected actions on the next harness start. Previews, doctor and uninstall
+  // are not write runs.
+  const writeRun = Boolean(options.yes && !options.dryRun && !options.doctor);
+  if ((oneCommand || writeRun) && !options.apiKey) {
     // An update aimed at an unmanaged directory is refused first; it needs no key to answer.
     if (options.update) {
       assertUpdateTargetsManagedRoot(detectEnvironment(options.cwd, {
@@ -4207,7 +4967,7 @@ async function runCli(argv) {
         USERPROFILE: options.home || options.cwd,
       }));
     }
-    process.stdout.write(`Marrow needs your API key. Run: MARROW_API_KEY=<your key> ${installCommandFor(options)}  (create a key at https://getmarrow.ai)\n`);
+    process.stdout.write(`${missingKeyMessage(options)}\n`);
     process.exitCode = 2;
     return;
   }
@@ -4217,10 +4977,23 @@ async function runCli(argv) {
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     if (!oneCommand || options.json || !/^Marrow activation failed/.test(message)) throw error;
-    process.stderr.write(`Marrow ${INSTALLER_ADAPTER_VERSION}: ${message}. Fix: ${activationFailureFix(message)}\n`);
+    process.stderr.write(`Marrow ${INSTALLER_ADAPTER_VERSION}: ${message}. Fix: ${activationFailureFix(message, String(options.agentId || '').trim())}\n`);
     process.exitCode = 1;
     return;
   }
+  // Claude Code opened from the desktop app, an IDE or a new terminal has no MARROW_API_KEY.
+  // The MCP server and hooks read ~/.marrow/env, so a first install stores a key that came
+  // from the environment there (owner-only), once the self-test passed by the same verdict the
+  // summary prints (never on an untrusted closure), with --json and --verbose too.
+  const keyWorked = report.selfTest ? selfTestVerdict(report.selfTest).passed : false;
+  if (options.activate && !options.update && keyInfo.source === 'environment' && !options.keyFromArg && keyWorked) {
+    try {
+      const stored = ensureOwnerApiKey(options.home, options.apiKey);
+      report.owner_key_storage = { state: stored.state, path: stored.path };
+    } catch {
+      report.owner_key_storage = { state: 'not_written', path: null };
+    }
+  }
   if (options.json) {
     process.stdout.write(JSON.stringify(report, null, 2) + '\n');
     return;
@@ -4246,6 +5019,8 @@ async function runCli(argv) {
 }
 
 module.exports = {
+  argumentLabel,
+  maintenanceMcpRuntime,
   parseArgs,
   detectEnvironment,
   buildPlan,
@@ -4267,6 +5042,13 @@ module.exports = {
   activationProfile,
   claudeNativeHookFingerprint,
   codexNativeHookFingerprint,
+  hostApprovalHooksSupported,
+  uninstall,
+  printUninstallReport,
+  CURSOR_PRE_TOOL_USE_HOST_APPROVAL_MATCHER,
+  GEMINI_PRE_ACTION_GUARD_COMMAND,
+  GEMINI_CONTEXT_HOOK_COMMAND,
+  MCP_PERMISSION_REQUEST_HOOK_COMMAND,
   cursorNativeHookFingerprint,
   clineNativeHookFingerprint,
   windsurfNativeHookFingerprint,