@node9/proxy 1.0.2 → 1.0.4

package/dist/cli.mjs

@@ -329,6 +329,23 @@ function extractShellCommand(toolName, args, toolInspection) {
   const value = getNestedValue(args, fieldPath);
   return typeof value === "string" ? value : null;
 }
+function isSqlTool(toolName, toolInspection) {
+  const patterns = Object.keys(toolInspection);
+  const matchingPattern = patterns.find((p) => matchesPattern(toolName, p));
+  if (!matchingPattern) return false;
+  const fieldName = toolInspection[matchingPattern];
+  return fieldName === "sql" || fieldName === "query";
+}
+var SQL_DML_KEYWORDS = /* @__PURE__ */ new Set(["select", "insert", "update", "delete", "merge", "upsert"]);
+function checkDangerousSql(sql) {
+  const norm = sql.replace(/\s+/g, " ").trim().toLowerCase();
+  const hasWhere = /\bwhere\b/.test(norm);
+  if (/^delete\s+from\s+\S+/.test(norm) && !hasWhere)
+    return "DELETE without WHERE \u2014 full table wipe";
+  if (/^update\s+\S+\s+set\s+/.test(norm) && !hasWhere)
+    return "UPDATE without WHERE \u2014 updates every row";
+  return null;
+}
 async function analyzeShellCommand(command) {
   const actions = [];
   const paths = [];
@@ -535,9 +552,20 @@ async function evaluatePolicy(toolName, args, agent) {
     if (INLINE_EXEC_PATTERN.test(shellCommand.trim())) {
       return { decision: "review", blockedByLabel: "Node9 Standard (Inline Execution)" };
     }
+    if (isSqlTool(toolName, config.policy.toolInspection)) {
+      const sqlDanger = checkDangerousSql(shellCommand);
+      if (sqlDanger) return { decision: "review", blockedByLabel: `SQL Safety: ${sqlDanger}` };
+      allTokens = allTokens.filter((t) => !SQL_DML_KEYWORDS.has(t.toLowerCase()));
+      actionTokens = actionTokens.filter((t) => !SQL_DML_KEYWORDS.has(t.toLowerCase()));
+    }
   } else {
     allTokens = tokenize(toolName);
     actionTokens = [toolName];
+    if (args && typeof args === "object") {
+      const flattenedArgs = JSON.stringify(args).toLowerCase();
+      const extraTokens = flattenedArgs.split(/[^a-zA-Z0-9]+/).filter((t) => t.length > 1);
+      allTokens.push(...extraTokens);
+    }
   }
   const isManual = agent === "Terminal";
   if (isManual) {
@@ -604,6 +632,285 @@ async function evaluatePolicy(toolName, args, agent) {
   }
   return { decision: "allow" };
 }
+async function explainPolicy(toolName, args) {
+  const steps = [];
+  const globalPath = path.join(os.homedir(), ".node9", "config.json");
+  const projectPath = path.join(process.cwd(), "node9.config.json");
+  const credsPath = path.join(os.homedir(), ".node9", "credentials.json");
+  const waterfall = [
+    {
+      tier: 1,
+      label: "Env vars",
+      status: "env",
+      note: process.env.NODE9_MODE ? `NODE9_MODE=${process.env.NODE9_MODE}` : "not set"
+    },
+    {
+      tier: 2,
+      label: "Cloud policy",
+      status: fs.existsSync(credsPath) ? "active" : "missing",
+      note: fs.existsSync(credsPath) ? "credentials found (not evaluated in explain mode)" : "not connected \u2014 run: node9 login"
+    },
+    {
+      tier: 3,
+      label: "Project config",
+      status: fs.existsSync(projectPath) ? "active" : "missing",
+      path: projectPath
+    },
+    {
+      tier: 4,
+      label: "Global config",
+      status: fs.existsSync(globalPath) ? "active" : "missing",
+      path: globalPath
+    },
+    {
+      tier: 5,
+      label: "Defaults",
+      status: "active",
+      note: "always active"
+    }
+  ];
+  const config = getConfig();
+  if (matchesPattern(toolName, config.policy.ignoredTools)) {
+    steps.push({
+      name: "Ignored tools",
+      outcome: "allow",
+      detail: `"${toolName}" matches ignoredTools pattern \u2192 fast-path allow`,
+      isFinal: true
+    });
+    return { tool: toolName, args, waterfall, steps, decision: "allow" };
+  }
+  steps.push({
+    name: "Ignored tools",
+    outcome: "checked",
+    detail: `"${toolName}" not in ignoredTools list`
+  });
+  let allTokens = [];
+  let actionTokens = [];
+  let pathTokens = [];
+  const shellCommand = extractShellCommand(toolName, args, config.policy.toolInspection);
+  if (shellCommand) {
+    const analyzed = await analyzeShellCommand(shellCommand);
+    allTokens = analyzed.allTokens;
+    actionTokens = analyzed.actions;
+    pathTokens = analyzed.paths;
+    const patterns = Object.keys(config.policy.toolInspection);
+    const matchingPattern = patterns.find((p) => matchesPattern(toolName, p));
+    const fieldName = matchingPattern ? config.policy.toolInspection[matchingPattern] : "command";
+    steps.push({
+      name: "Input parsing",
+      outcome: "checked",
+      detail: `Shell command via toolInspection["${matchingPattern ?? toolName}"] \u2192 field "${fieldName}": "${shellCommand}"`
+    });
+    const INLINE_EXEC_PATTERN = /^(python3?|bash|sh|zsh|perl|ruby|node|php|lua)\s+(-c|-e|-eval)\s/i;
+    if (INLINE_EXEC_PATTERN.test(shellCommand.trim())) {
+      steps.push({
+        name: "Inline execution",
+        outcome: "review",
+        detail: 'Inline code execution detected (e.g. "bash -c ...") \u2014 always requires review',
+        isFinal: true
+      });
+      return {
+        tool: toolName,
+        args,
+        waterfall,
+        steps,
+        decision: "review",
+        blockedByLabel: "Node9 Standard (Inline Execution)"
+      };
+    }
+    steps.push({
+      name: "Inline execution",
+      outcome: "checked",
+      detail: "No inline execution pattern detected"
+    });
+    if (isSqlTool(toolName, config.policy.toolInspection)) {
+      const sqlDanger = checkDangerousSql(shellCommand);
+      if (sqlDanger) {
+        steps.push({
+          name: "SQL safety",
+          outcome: "review",
+          detail: sqlDanger,
+          isFinal: true
+        });
+        return {
+          tool: toolName,
+          args,
+          waterfall,
+          steps,
+          decision: "review",
+          blockedByLabel: `SQL Safety: ${sqlDanger}`
+        };
+      }
+      allTokens = allTokens.filter((t) => !SQL_DML_KEYWORDS.has(t.toLowerCase()));
+      actionTokens = actionTokens.filter((t) => !SQL_DML_KEYWORDS.has(t.toLowerCase()));
+      steps.push({
+        name: "SQL safety",
+        outcome: "checked",
+        detail: "DELETE/UPDATE have a WHERE clause \u2014 scoped mutation, safe"
+      });
+    }
+  } else {
+    allTokens = tokenize(toolName);
+    actionTokens = [toolName];
+    let detail = `No toolInspection match for "${toolName}" \u2014 tokens: [${allTokens.join(", ")}]`;
+    if (args && typeof args === "object") {
+      const flattenedArgs = JSON.stringify(args).toLowerCase();
+      const extraTokens = flattenedArgs.split(/[^a-zA-Z0-9]+/).filter((t) => t.length > 1);
+      allTokens.push(...extraTokens);
+      const preview = extraTokens.slice(0, 8).join(", ") + (extraTokens.length > 8 ? "\u2026" : "");
+      detail += ` + deep scan of args: [${preview}]`;
+    }
+    steps.push({ name: "Input parsing", outcome: "checked", detail });
+  }
+  const uniqueTokens = [...new Set(allTokens)];
+  steps.push({
+    name: "Tokens scanned",
+    outcome: "checked",
+    detail: `[${uniqueTokens.join(", ")}]`
+  });
+  if (pathTokens.length > 0 && config.policy.sandboxPaths.length > 0) {
+    const allInSandbox = pathTokens.every((p) => matchesPattern(p, config.policy.sandboxPaths));
+    if (allInSandbox) {
+      steps.push({
+        name: "Sandbox paths",
+        outcome: "allow",
+        detail: `[${pathTokens.join(", ")}] all match sandbox patterns \u2192 auto-allow`,
+        isFinal: true
+      });
+      return { tool: toolName, args, waterfall, steps, decision: "allow" };
+    }
+    const unmatched = pathTokens.filter((p) => !matchesPattern(p, config.policy.sandboxPaths));
+    steps.push({
+      name: "Sandbox paths",
+      outcome: "checked",
+      detail: `[${unmatched.join(", ")}] not in sandbox \u2014 not auto-allowed`
+    });
+  } else {
+    steps.push({
+      name: "Sandbox paths",
+      outcome: "skip",
+      detail: pathTokens.length === 0 ? "No path tokens found in input" : "No sandbox paths configured"
+    });
+  }
+  let ruleMatched = false;
+  for (const action of actionTokens) {
+    const rule = config.policy.rules.find(
+      (r) => r.action === action || matchesPattern(action, r.action)
+    );
+    if (rule) {
+      ruleMatched = true;
+      if (pathTokens.length > 0) {
+        const anyBlocked = pathTokens.some((p) => matchesPattern(p, rule.blockPaths || []));
+        if (anyBlocked) {
+          steps.push({
+            name: "Policy rules",
+            outcome: "review",
+            detail: `Rule "${rule.action}" matched + path is in blockPaths`,
+            isFinal: true
+          });
+          return {
+            tool: toolName,
+            args,
+            waterfall,
+            steps,
+            decision: "review",
+            blockedByLabel: `Project/Global Config \u2014 rule "${rule.action}" (path blocked)`
+          };
+        }
+        const allAllowed = pathTokens.every((p) => matchesPattern(p, rule.allowPaths || []));
+        if (allAllowed) {
+          steps.push({
+            name: "Policy rules",
+            outcome: "allow",
+            detail: `Rule "${rule.action}" matched + all paths are in allowPaths`,
+            isFinal: true
+          });
+          return { tool: toolName, args, waterfall, steps, decision: "allow" };
+        }
+      }
+      steps.push({
+        name: "Policy rules",
+        outcome: "review",
+        detail: `Rule "${rule.action}" matched \u2014 default block (no path exception)`,
+        isFinal: true
+      });
+      return {
+        tool: toolName,
+        args,
+        waterfall,
+        steps,
+        decision: "review",
+        blockedByLabel: `Project/Global Config \u2014 rule "${rule.action}" (default block)`
+      };
+    }
+  }
+  if (!ruleMatched) {
+    steps.push({
+      name: "Policy rules",
+      outcome: "skip",
+      detail: config.policy.rules.length === 0 ? "No rules configured" : `No rule matched [${actionTokens.join(", ")}]`
+    });
+  }
+  let matchedDangerousWord;
+  const isDangerous = uniqueTokens.some(
+    (token) => config.policy.dangerousWords.some((word) => {
+      const w = word.toLowerCase();
+      const hit = token === w || (() => {
+        try {
+          return new RegExp(`\\b${w}\\b`, "i").test(token);
+        } catch {
+          return false;
+        }
+      })();
+      if (hit && !matchedDangerousWord) matchedDangerousWord = word;
+      return hit;
+    })
+  );
+  if (isDangerous) {
+    steps.push({
+      name: "Dangerous words",
+      outcome: "review",
+      detail: `"${matchedDangerousWord}" found in token list`,
+      isFinal: true
+    });
+    return {
+      tool: toolName,
+      args,
+      waterfall,
+      steps,
+      decision: "review",
+      blockedByLabel: `Project/Global Config \u2014 dangerous word: "${matchedDangerousWord}"`,
+      matchedToken: matchedDangerousWord
+    };
+  }
+  steps.push({
+    name: "Dangerous words",
+    outcome: "checked",
+    detail: `No dangerous words matched`
+  });
+  if (config.settings.mode === "strict") {
+    steps.push({
+      name: "Strict mode",
+      outcome: "review",
+      detail: 'Mode is "strict" \u2014 all tools require approval unless explicitly allowed',
+      isFinal: true
+    });
+    return {
+      tool: toolName,
+      args,
+      waterfall,
+      steps,
+      decision: "review",
+      blockedByLabel: "Global Config (Strict Mode Active)"
+    };
+  }
+  steps.push({
+    name: "Strict mode",
+    outcome: "skip",
+    detail: `Mode is "${config.settings.mode}" \u2014 no catch-all review`
+  });
+  return { tool: toolName, args, waterfall, steps, decision: "allow" };
+}
 function isIgnoredTool(toolName) {
   const config = getConfig();
   return matchesPattern(toolName, config.policy.ignoredTools);
@@ -766,8 +1073,7 @@ async function authorizeHeadless(toolName, args, allowTerminalFallback = false,
   const cloudEnforced = approvers.cloud && !!creds?.apiKey;
   if (cloudEnforced) {
     try {
-      const envConfig = getActiveEnvironment(getConfig());
-      const initResult = await initNode9SaaS(toolName, args, creds, envConfig?.slackChannel, meta);
+      const initResult = await initNode9SaaS(toolName, args, creds, meta);
       if (!initResult.pending) {
         return {
           approved: !!initResult.approved,
@@ -1021,6 +1327,7 @@ function getConfig() {
     if (s.enableHookLogDebug !== void 0)
       mergedSettings.enableHookLogDebug = s.enableHookLogDebug;
     if (s.approvers) mergedSettings.approvers = { ...mergedSettings.approvers, ...s.approvers };
+    if (s.environment !== void 0) mergedSettings.environment = s.environment;
     if (p.sandboxPaths) mergedPolicy.sandboxPaths.push(...p.sandboxPaths);
     if (p.ignoredTools) mergedPolicy.ignoredTools.push(...p.ignoredTools);
     if (p.dangerousWords) mergedPolicy.dangerousWords = [...p.dangerousWords];
@@ -1050,7 +1357,7 @@ function tryLoadConfig(filePath) {
   }
 }
 function getActiveEnvironment(config) {
-  const env = process.env.NODE_ENV || "development";
+  const env = config.settings.environment || process.env.NODE_ENV || "development";
   return config.environments[env] ?? null;
 }
 function getCredentials() {
@@ -1106,7 +1413,7 @@ function auditLocalAllow(toolName, args, checkedBy, creds, meta) {
   }).catch(() => {
   });
 }
-async function initNode9SaaS(toolName, args, creds, slackChannel, meta) {
+async function initNode9SaaS(toolName, args, creds, meta) {
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), 1e4);
   try {
@@ -1116,7 +1423,6 @@ async function initNode9SaaS(toolName, args, creds, slackChannel, meta) {
       body: JSON.stringify({
         toolName,
         args,
-        slackChannel,
         context: {
           agent: meta?.agent,
           mcpServer: meta?.mcpServer,
@@ -2914,8 +3220,34 @@ import { spawnSync } from "child_process";
 import fs4 from "fs";
 import path4 from "path";
 import os4 from "os";
+var SNAPSHOT_STACK_PATH = path4.join(os4.homedir(), ".node9", "snapshots.json");
 var UNDO_LATEST_PATH = path4.join(os4.homedir(), ".node9", "undo_latest.txt");
-async function createShadowSnapshot() {
+var MAX_SNAPSHOTS = 10;
+function readStack() {
+  try {
+    if (fs4.existsSync(SNAPSHOT_STACK_PATH))
+      return JSON.parse(fs4.readFileSync(SNAPSHOT_STACK_PATH, "utf-8"));
+  } catch {
+  }
+  return [];
+}
+function writeStack(stack) {
+  const dir = path4.dirname(SNAPSHOT_STACK_PATH);
+  if (!fs4.existsSync(dir)) fs4.mkdirSync(dir, { recursive: true });
+  fs4.writeFileSync(SNAPSHOT_STACK_PATH, JSON.stringify(stack, null, 2));
+}
+function buildArgsSummary(tool, args) {
+  if (!args || typeof args !== "object") return "";
+  const a = args;
+  const filePath = a.file_path ?? a.path ?? a.filename;
+  if (typeof filePath === "string") return filePath;
+  const cmd = a.command ?? a.cmd;
+  if (typeof cmd === "string") return cmd.slice(0, 80);
+  const sql = a.sql ?? a.query;
+  if (typeof sql === "string") return sql.slice(0, 80);
+  return tool;
+}
+async function createShadowSnapshot(tool = "unknown", args = {}) {
   try {
     const cwd = process.cwd();
     if (!fs4.existsSync(path4.join(cwd, ".git"))) return null;
@@ -2933,30 +3265,59 @@ async function createShadowSnapshot() {
       `Node9 AI Snapshot: ${(/* @__PURE__ */ new Date()).toISOString()}`
     ]);
     const commitHash = commitRes.stdout.toString().trim();
-    if (commitHash && commitRes.status === 0) {
-      const dir = path4.dirname(UNDO_LATEST_PATH);
-      if (!fs4.existsSync(dir)) fs4.mkdirSync(dir, { recursive: true });
-      fs4.writeFileSync(UNDO_LATEST_PATH, commitHash);
-      return commitHash;
-    }
+    if (!commitHash || commitRes.status !== 0) return null;
+    const stack = readStack();
+    const entry = {
+      hash: commitHash,
+      tool,
+      argsSummary: buildArgsSummary(tool, args),
+      cwd,
+      timestamp: Date.now()
+    };
+    stack.push(entry);
+    if (stack.length > MAX_SNAPSHOTS) stack.splice(0, stack.length - MAX_SNAPSHOTS);
+    writeStack(stack);
+    fs4.writeFileSync(UNDO_LATEST_PATH, commitHash);
+    return commitHash;
   } catch (err) {
-    if (process.env.NODE9_DEBUG === "1") {
-      console.error("[Node9 Undo Engine Error]:", err);
-    }
+    if (process.env.NODE9_DEBUG === "1") console.error("[Node9 Undo Engine Error]:", err);
   }
   return null;
 }
-function applyUndo(hash) {
+function getSnapshotHistory() {
+  return readStack();
+}
+function computeUndoDiff(hash, cwd) {
   try {
-    const restore = spawnSync("git", ["restore", "--source", hash, "--staged", "--worktree", "."]);
+    const result = spawnSync("git", ["diff", hash, "--stat", "--", "."], { cwd });
+    const stat = result.stdout.toString().trim();
+    if (!stat) return null;
+    const diff = spawnSync("git", ["diff", hash, "--", "."], { cwd });
+    const raw = diff.stdout.toString();
+    if (!raw) return null;
+    const lines = raw.split("\n").filter(
+      (l) => !l.startsWith("diff --git") && !l.startsWith("index ") && !l.startsWith("Binary")
+    );
+    return lines.join("\n") || null;
+  } catch {
+    return null;
+  }
+}
+function applyUndo(hash, cwd) {
+  try {
+    const dir = cwd ?? process.cwd();
+    const restore = spawnSync("git", ["restore", "--source", hash, "--staged", "--worktree", "."], {
+      cwd: dir
+    });
     if (restore.status !== 0) return false;
-    const lsTree = spawnSync("git", ["ls-tree", "-r", "--name-only", hash]);
+    const lsTree = spawnSync("git", ["ls-tree", "-r", "--name-only", hash], { cwd: dir });
     const snapshotFiles = new Set(lsTree.stdout.toString().trim().split("\n").filter(Boolean));
-    const tracked = spawnSync("git", ["ls-files"]).stdout.toString().trim().split("\n").filter(Boolean);
-    const untracked = spawnSync("git", ["ls-files", "--others", "--exclude-standard"]).stdout.toString().trim().split("\n").filter(Boolean);
+    const tracked = spawnSync("git", ["ls-files"], { cwd: dir }).stdout.toString().trim().split("\n").filter(Boolean);
+    const untracked = spawnSync("git", ["ls-files", "--others", "--exclude-standard"], { cwd: dir }).stdout.toString().trim().split("\n").filter(Boolean);
     for (const file of [...tracked, ...untracked]) {
-      if (!snapshotFiles.has(file) && fs4.existsSync(file)) {
-        fs4.unlinkSync(file);
+      const fullPath = path4.join(dir, file);
+      if (!snapshotFiles.has(file) && fs4.existsSync(fullPath)) {
+        fs4.unlinkSync(fullPath);
       }
     }
     return true;
@@ -2964,10 +3325,6 @@ function applyUndo(hash) {
     return false;
   }
 }
-function getLatestSnapshotHash() {
-  if (!fs4.existsSync(UNDO_LATEST_PATH)) return null;
-  return fs4.readFileSync(UNDO_LATEST_PATH, "utf-8").trim();
-}
 
 // src/cli.ts
 import { confirm as confirm3 } from "@inquirer/prompts";
@@ -2994,6 +3351,59 @@ function parseDuration(str) {
 function sanitize(value) {
   return value.replace(/[\x00-\x1F\x7F]/g, "");
 }
+function buildNegotiationMessage(blockedByLabel, isHumanDecision, humanReason) {
+  if (isHumanDecision) {
+    return `NODE9: The human user rejected this action.
+REASON: ${humanReason || "No specific reason provided."}
+INSTRUCTIONS:
+- Do NOT retry this exact command.
+- Acknowledge the block to the user and ask if there is an alternative approach.
+- If you believe this action is critical, explain your reasoning and ask them to run "node9 pause 15m" to proceed.`;
+  }
+  const label = blockedByLabel.toLowerCase();
+  if (label.includes("sql safety") && label.includes("delete without where")) {
+    return `NODE9: Blocked \u2014 DELETE without WHERE clause would wipe the entire table.
+INSTRUCTION: Add a WHERE clause to scope the deletion (e.g. WHERE id = <value>).
+Do NOT retry without a WHERE clause.`;
+  }
+  if (label.includes("sql safety") && label.includes("update without where")) {
+    return `NODE9: Blocked \u2014 UPDATE without WHERE clause would update every row.
+INSTRUCTION: Add a WHERE clause to scope the update (e.g. WHERE id = <value>).
+Do NOT retry without a WHERE clause.`;
+  }
+  if (label.includes("dangerous word")) {
+    const match = blockedByLabel.match(/dangerous word: "([^"]+)"/i);
+    const word = match?.[1] ?? "a dangerous keyword";
+    return `NODE9: Blocked \u2014 command contains forbidden keyword "${word}".
+INSTRUCTION: Do NOT use "${word}". Use a non-destructive alternative.
+Do NOT attempt to bypass this with shell tricks or aliases \u2014 it will be blocked again.`;
+  }
+  if (label.includes("path blocked") || label.includes("sandbox")) {
+    return `NODE9: Blocked \u2014 operation targets a path outside the allowed sandbox.
+INSTRUCTION: Move your output to an allowed directory such as /tmp/ or the project directory.
+Do NOT retry on the same path.`;
+  }
+  if (label.includes("inline execution")) {
+    return `NODE9: Blocked \u2014 inline code execution (e.g. bash -c "...") is not allowed.
+INSTRUCTION: Use individual tool calls instead of embedding code in a shell string.`;
+  }
+  if (label.includes("strict mode")) {
+    return `NODE9: Blocked \u2014 strict mode is active. All tool calls require explicit human approval.
+INSTRUCTION: Inform the user this action is pending approval. Wait for them to approve via the dashboard or run "node9 pause".`;
+  }
+  if (label.includes("rule") && label.includes("default block")) {
+    const match = blockedByLabel.match(/rule "([^"]+)"/i);
+    const rule = match?.[1] ?? "a policy rule";
+    return `NODE9: Blocked \u2014 action "${rule}" is forbidden by security policy.
+INSTRUCTION: Do NOT use "${rule}". Find a read-only or non-destructive alternative.
+Do NOT attempt to bypass this rule.`;
+  }
+  return `NODE9: Action blocked by security policy [${blockedByLabel}].
+INSTRUCTIONS:
+- Do NOT retry this exact command or attempt to bypass the rule.
+- Pivot to a non-destructive or read-only alternative.
+- Inform the user which security rule was triggered and ask how to proceed.`;
+}
 function openBrowserLocal() {
   const url = `http://${DAEMON_HOST2}:${DAEMON_PORT2}/`;
   try {
@@ -3046,7 +3456,7 @@ async function runProxy(targetCommand) {
   const child = spawn3(executable, args, {
     stdio: ["pipe", "pipe", "inherit"],
     // We control STDIN and STDOUT
-    shell: true,
+    shell: false,
     env: { ...process.env, FORCE_COLOR: "1" }
   });
   const agentIn = readline.createInterface({ input: process.stdin, terminal: false });
@@ -3067,12 +3477,24 @@ async function runProxy(targetCommand) {
           agent: "Proxy/MCP"
         });
         if (!result.approved) {
+          console.error(chalk5.red(`
+\u{1F6D1} Node9 Sudo: Action Blocked`));
+          console.error(chalk5.gray(`   Tool: ${name}`));
+          console.error(chalk5.gray(`   Reason: ${result.reason || "Security Policy"}
+`));
+          const blockedByLabel = result.blockedByLabel ?? result.reason ?? "Security Policy";
+          const isHuman = blockedByLabel.toLowerCase().includes("user") || blockedByLabel.toLowerCase().includes("daemon") || blockedByLabel.toLowerCase().includes("decision");
+          const aiInstruction = buildNegotiationMessage(blockedByLabel, isHuman, result.reason);
           const errorResponse = {
             jsonrpc: "2.0",
-            id: message.id,
+            id: message.id ?? null,
             error: {
               code: -32e3,
-              message: `Node9: Action denied. ${result.reason || ""}`
+              message: aiInstruction,
+              data: {
+                reason: result.reason,
+                blockedBy: result.blockedByLabel
+              }
             }
           };
           process.stdout.write(JSON.stringify(errorResponse) + "\n");
@@ -3160,6 +3582,237 @@ program.command("addto").description("Integrate Node9 with an AI agent").addHelp
   console.error(chalk5.red(`Unknown target: "${target}". Supported: claude, gemini, cursor`));
   process.exit(1);
 });
+program.command("setup").description('Alias for "addto" \u2014 integrate Node9 with an AI agent').addHelpText("after", "\n  Supported targets:  claude  gemini  cursor").argument("[target]", "The agent to protect: claude | gemini | cursor").action(async (target) => {
+  if (!target) {
+    console.log(chalk5.cyan("\n\u{1F6E1}\uFE0F  Node9 Setup \u2014 integrate with your AI agent\n"));
+    console.log("  Usage:  " + chalk5.white("node9 setup <target>") + "\n");
+    console.log("  Targets:");
+    console.log("    " + chalk5.green("claude") + "   \u2014 Claude Code (hook mode)");
+    console.log("    " + chalk5.green("gemini") + "   \u2014 Gemini CLI (hook mode)");
+    console.log("    " + chalk5.green("cursor") + "   \u2014 Cursor (hook mode)");
+    console.log("");
+    return;
+  }
+  const t = target.toLowerCase();
+  if (t === "gemini") return await setupGemini();
+  if (t === "claude") return await setupClaude();
+  if (t === "cursor") return await setupCursor();
+  console.error(chalk5.red(`Unknown target: "${target}". Supported: claude, gemini, cursor`));
+  process.exit(1);
+});
+program.command("doctor").description("Check that Node9 is installed and configured correctly").action(() => {
+  const homeDir2 = os5.homedir();
+  let failures = 0;
+  function pass(msg) {
+    console.log(chalk5.green("  \u2705 ") + msg);
+  }
+  function fail(msg, hint) {
+    console.log(chalk5.red("  \u274C ") + msg);
+    if (hint) console.log(chalk5.gray("       " + hint));
+    failures++;
+  }
+  function warn(msg, hint) {
+    console.log(chalk5.yellow("  \u26A0\uFE0F  ") + msg);
+    if (hint) console.log(chalk5.gray("       " + hint));
+  }
+  function section(title) {
+    console.log("\n" + chalk5.bold(title));
+  }
+  console.log(chalk5.cyan.bold(`
+\u{1F6E1}\uFE0F  Node9 Doctor  v${version}
+`));
+  section("Binary");
+  try {
+    const which = execSync("which node9", { encoding: "utf-8" }).trim();
+    pass(`node9 found at ${which}`);
+  } catch {
+    warn("node9 not found in $PATH \u2014 hooks may not find it", "Run: npm install -g @node9/proxy");
+  }
+  const nodeMajor = parseInt(process.versions.node.split(".")[0], 10);
+  if (nodeMajor >= 18) {
+    pass(`Node.js ${process.versions.node}`);
+  } else {
+    fail(
+      `Node.js ${process.versions.node} (requires \u226518)`,
+      "Upgrade Node.js: https://nodejs.org"
+    );
+  }
+  try {
+    const gitVersion = execSync("git --version", { encoding: "utf-8" }).trim();
+    pass(gitVersion);
+  } catch {
+    warn(
+      "git not found \u2014 Undo Engine will be disabled",
+      "Install git to enable snapshot-based undo"
+    );
+  }
+  section("Configuration");
+  const globalConfigPath = path5.join(homeDir2, ".node9", "config.json");
+  if (fs5.existsSync(globalConfigPath)) {
+    try {
+      JSON.parse(fs5.readFileSync(globalConfigPath, "utf-8"));
+      pass("~/.node9/config.json found and valid");
+    } catch {
+      fail("~/.node9/config.json is invalid JSON", "Run: node9 init --force");
+    }
+  } else {
+    warn("~/.node9/config.json not found (using defaults)", "Run: node9 init");
+  }
+  const projectConfigPath = path5.join(process.cwd(), "node9.config.json");
+  if (fs5.existsSync(projectConfigPath)) {
+    try {
+      JSON.parse(fs5.readFileSync(projectConfigPath, "utf-8"));
+      pass("node9.config.json found and valid (project)");
+    } catch {
+      fail("node9.config.json is invalid JSON", "Fix the JSON or delete it and run: node9 init");
+    }
+  }
+  const credsPath = path5.join(homeDir2, ".node9", "credentials.json");
+  if (fs5.existsSync(credsPath)) {
+    pass("Cloud credentials found (~/.node9/credentials.json)");
+  } else {
+    warn(
+      "No cloud credentials \u2014 running in local-only mode",
+      "Run: node9 login <apiKey>  (or skip for local-only)"
+    );
+  }
+  section("Agent Hooks");
+  const claudeSettingsPath = path5.join(homeDir2, ".claude", "settings.json");
+  if (fs5.existsSync(claudeSettingsPath)) {
+    try {
+      const cs = JSON.parse(fs5.readFileSync(claudeSettingsPath, "utf-8"));
+      const hasHook = cs.hooks?.PreToolUse?.some(
+        (m) => m.hooks.some((h) => h.command?.includes("node9") || h.command?.includes("cli.js"))
+      );
+      if (hasHook) pass("Claude Code \u2014 PreToolUse hook active");
+      else
+        fail("Claude Code \u2014 hooks file found but node9 hook missing", "Run: node9 setup claude");
+    } catch {
+      fail("Claude Code \u2014 ~/.claude/settings.json is invalid JSON");
+    }
+  } else {
+    warn("Claude Code \u2014 not configured", "Run: node9 setup claude");
+  }
+  const geminiSettingsPath = path5.join(homeDir2, ".gemini", "settings.json");
+  if (fs5.existsSync(geminiSettingsPath)) {
+    try {
+      const gs = JSON.parse(fs5.readFileSync(geminiSettingsPath, "utf-8"));
+      const hasHook = gs.hooks?.BeforeTool?.some(
+        (m) => m.hooks.some((h) => h.command?.includes("node9") || h.command?.includes("cli.js"))
+      );
+      if (hasHook) pass("Gemini CLI  \u2014 BeforeTool hook active");
+      else
+        fail("Gemini CLI  \u2014 hooks file found but node9 hook missing", "Run: node9 setup gemini");
+    } catch {
+      fail("Gemini CLI  \u2014 ~/.gemini/settings.json is invalid JSON");
+    }
+  } else {
+    warn("Gemini CLI  \u2014 not configured", "Run: node9 setup gemini  (skip if not using Gemini)");
+  }
+  const cursorHooksPath = path5.join(homeDir2, ".cursor", "hooks.json");
+  if (fs5.existsSync(cursorHooksPath)) {
+    try {
+      const cur = JSON.parse(fs5.readFileSync(cursorHooksPath, "utf-8"));
+      const hasHook = cur.hooks?.preToolUse?.some(
+        (h) => h.command?.includes("node9") || h.command?.includes("cli.js")
+      );
+      if (hasHook) pass("Cursor      \u2014 preToolUse hook active");
+      else
+        fail("Cursor      \u2014 hooks file found but node9 hook missing", "Run: node9 setup cursor");
+    } catch {
+      fail("Cursor      \u2014 ~/.cursor/hooks.json is invalid JSON");
+    }
+  } else {
+    warn("Cursor      \u2014 not configured", "Run: node9 setup cursor  (skip if not using Cursor)");
+  }
+  section("Daemon (optional)");
+  if (isDaemonRunning()) {
+    pass(`Browser dashboard running \u2192 http://${DAEMON_HOST2}:${DAEMON_PORT2}/`);
+  } else {
+    warn("Daemon not running \u2014 browser approvals unavailable", "Run: node9 daemon --background");
+  }
+  console.log("");
+  if (failures === 0) {
+    console.log(chalk5.green.bold("  All checks passed. Node9 is ready.\n"));
+  } else {
+    console.log(chalk5.red.bold(`  ${failures} check(s) failed. See hints above.
+`));
+    process.exit(1);
+  }
+});
+program.command("explain").description(
+  "Show exactly how Node9 evaluates a tool call \u2014 waterfall + step-by-step policy trace"
+).argument("<tool>", "Tool name (e.g. bash, str_replace_based_edit_tool, execute_query)").argument("[args]", "Tool arguments as JSON, or a plain command string for shell tools").action(async (tool, argsRaw) => {
+  let args = {};
+  if (argsRaw) {
+    const trimmed = argsRaw.trim();
+    if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+      try {
+        args = JSON.parse(trimmed);
+      } catch {
+        console.error(chalk5.red(`
+\u274C Invalid JSON: ${trimmed}
+`));
+        process.exit(1);
+      }
+    } else {
+      args = { command: trimmed };
+    }
+  }
+  const result = await explainPolicy(tool, args);
+  console.log("");
+  console.log(chalk5.cyan.bold("\u{1F6E1}\uFE0F  Node9 Explain"));
+  console.log("");
+  console.log(`   ${chalk5.bold("Tool:")}    ${chalk5.white(result.tool)}`);
+  if (argsRaw) {
+    const preview = argsRaw.length > 80 ? argsRaw.slice(0, 77) + "\u2026" : argsRaw;
+    console.log(`   ${chalk5.bold("Input:")}   ${chalk5.gray(preview)}`);
+  }
+  console.log("");
+  console.log(chalk5.bold("Config Sources (Waterfall):"));
+  for (const tier of result.waterfall) {
+    const num = chalk5.gray(`  ${tier.tier}.`);
+    const label = tier.label.padEnd(16);
+    let statusStr;
+    if (tier.tier === 1) {
+      statusStr = chalk5.gray(tier.note ?? "");
+    } else if (tier.status === "active") {
+      const loc = tier.path ? chalk5.gray(tier.path) : "";
+      const note = tier.note ? chalk5.gray(`(${tier.note})`) : "";
+      statusStr = chalk5.green("\u2713 active") + (loc ? "  " + loc : "") + (note ? "  " + note : "");
+    } else {
+      statusStr = chalk5.gray("\u25CB " + (tier.note ?? "not found"));
+    }
+    console.log(`${num} ${chalk5.white(label)} ${statusStr}`);
+  }
+  console.log("");
+  console.log(chalk5.bold("Policy Evaluation:"));
+  for (const step of result.steps) {
+    const isFinal = step.isFinal;
+    let icon;
+    if (step.outcome === "allow") icon = chalk5.green("  \u2705");
+    else if (step.outcome === "review") icon = chalk5.red("  \u{1F534}");
+    else if (step.outcome === "skip") icon = chalk5.gray("  \u2500 ");
+    else icon = chalk5.gray("  \u25CB ");
+    const name = step.name.padEnd(18);
+    const nameStr = isFinal ? chalk5.white.bold(name) : chalk5.white(name);
+    const detail = isFinal ? chalk5.white(step.detail) : chalk5.gray(step.detail);
+    const arrow = isFinal ? chalk5.yellow("  \u2190 STOP") : "";
+    console.log(`${icon} ${nameStr} ${detail}${arrow}`);
+  }
+  console.log("");
+  if (result.decision === "allow") {
+    console.log(chalk5.green.bold("  Decision: \u2705 ALLOW") + chalk5.gray("  \u2014 no approval needed"));
+  } else {
+    console.log(
+      chalk5.red.bold("  Decision: \u{1F534} REVIEW") + chalk5.gray("  \u2014 human approval required")
+    );
+    if (result.blockedByLabel) {
+      console.log(chalk5.gray(`  Reason:   ${result.blockedByLabel}`));
+    }
+  }
+  console.log("");
+});
 program.command("init").description("Create ~/.node9/config.json with default policy (safe to run multiple times)").option("--force", "Overwrite existing config").option("-m, --mode <mode>", "Set initial security mode (standard, strict, audit)", "standard").action((options) => {
   const configPath = path5.join(os5.homedir(), ".node9", "config.json");
   if (fs5.existsSync(configPath) && !options.force) {
@@ -3297,7 +3950,6 @@ RAW: ${raw}
           );
         }
         process.exit(0);
-        return;
       }
       if (payload.cwd) {
         try {
@@ -3327,26 +3979,7 @@ RAW: ${raw}
         console.error(chalk5.gray(`   Triggered by: ${blockedByContext}`));
         if (result2?.changeHint) console.error(chalk5.cyan(`   To change:  ${result2.changeHint}`));
         console.error("");
-        let aiFeedbackMessage = "";
-        if (isHumanDecision) {
-          aiFeedbackMessage = `NODE9 SECURITY INTERVENTION: The human user specifically REJECTED this action.
-REASON: ${msg || "No specific reason provided by user."}
-
-INSTRUCTIONS FOR AI AGENT:
-- Do NOT retry this exact command immediately.
-- Explain to the user that you understand they blocked the action.
-- Ask the user if there is an alternative approach they would prefer, or if they intended to block this action entirely.
-- If you believe this action is critical, explain your reasoning to the user and ask them to run 'node9 pause 15m' to allow you to proceed.`;
-        } else {
-          aiFeedbackMessage = `NODE9 SECURITY INTERVENTION: Action blocked by automated policy [${blockedByContext}].
-REASON: ${msg}
-
-INSTRUCTIONS FOR AI AGENT:
-- This command violates the current security configuration.
-- Do NOT attempt to bypass this rule with bash syntax tricks; it will be blocked again.
-- Pivot to a non-destructive or read-only alternative.
-- Inform the user which security rule was triggered.`;
-        }
+        const aiFeedbackMessage = buildNegotiationMessage(blockedByContext, isHumanDecision, msg);
         console.error(chalk5.dim(`   (Detailed instructions sent to AI agent)`));
         process.stdout.write(
           JSON.stringify({
@@ -3368,17 +4001,16 @@ INSTRUCTIONS FOR AI AGENT:
       }
       const meta = { agent, mcpServer };
       const STATE_CHANGING_TOOLS_PRE = [
-        "bash",
-        "shell",
         "write_file",
         "edit_file",
+        "edit",
         "replace",
         "terminal.execute",
         "str_replace_based_edit_tool",
         "create_file"
       ];
       if (config.settings.enableUndo && STATE_CHANGING_TOOLS_PRE.includes(toolName.toLowerCase())) {
-        await createShadowSnapshot();
+        await createShadowSnapshot(toolName, toolInput);
       }
       const result = await authorizeHeadless(toolName, toolInput, false, meta);
       if (result.approved) {
@@ -3566,24 +4198,77 @@ program.argument("[command...]", "The agent command to run (e.g., gemini)").acti
     program.help();
   }
 });
-program.command("undo").description("Revert the project to the state before the last AI action").action(async () => {
-  const hash = getLatestSnapshotHash();
-  if (!hash) {
-    console.log(chalk5.yellow("\n\u2139\uFE0F  No Undo snapshot found for this machine.\n"));
+program.command("undo").description(
+  "Revert files to a pre-AI snapshot. Shows a diff and asks for confirmation before reverting. Use --steps N to go back N actions."
+).option("--steps <n>", "Number of snapshots to go back (default: 1)", "1").action(async (options) => {
+  const steps = Math.max(1, parseInt(options.steps, 10) || 1);
+  const history = getSnapshotHistory();
+  if (history.length === 0) {
+    console.log(chalk5.yellow("\n\u2139\uFE0F  No undo snapshots found.\n"));
+    return;
+  }
+  const idx = history.length - steps;
+  if (idx < 0) {
+    console.log(
+      chalk5.yellow(
+        `
+\u2139\uFE0F  Only ${history.length} snapshot(s) available, cannot go back ${steps}.
+`
+      )
+    );
     return;
   }
-  console.log(chalk5.magenta.bold("\n\u23EA NODE9 UNDO ENGINE"));
-  console.log(chalk5.white(`Target Snapshot: ${chalk5.gray(hash.slice(0, 7))}`));
+  const snapshot = history[idx];
+  const age = Math.round((Date.now() - snapshot.timestamp) / 1e3);
+  const ageStr = age < 60 ? `${age}s ago` : age < 3600 ? `${Math.round(age / 60)}m ago` : `${Math.round(age / 3600)}h ago`;
+  console.log(chalk5.magenta.bold(`
+\u23EA  Node9 Undo${steps > 1 ? ` (${steps} steps back)` : ""}`));
+  console.log(
+    chalk5.white(
+      `    Tool:  ${chalk5.cyan(snapshot.tool)}${snapshot.argsSummary ? chalk5.gray(" \u2192 " + snapshot.argsSummary) : ""}`
+    )
+  );
+  console.log(chalk5.white(`    When:  ${chalk5.gray(ageStr)}`));
+  console.log(chalk5.white(`    Dir:   ${chalk5.gray(snapshot.cwd)}`));
+  if (steps > 1)
+    console.log(
+      chalk5.yellow(`    Note:  This will also undo the ${steps - 1} action(s) after it.`)
+    );
+  console.log("");
+  const diff = computeUndoDiff(snapshot.hash, snapshot.cwd);
+  if (diff) {
+    const lines = diff.split("\n");
+    for (const line of lines) {
+      if (line.startsWith("+++") || line.startsWith("---")) {
+        console.log(chalk5.bold(line));
+      } else if (line.startsWith("+")) {
+        console.log(chalk5.green(line));
+      } else if (line.startsWith("-")) {
+        console.log(chalk5.red(line));
+      } else if (line.startsWith("@@")) {
+        console.log(chalk5.cyan(line));
+      } else {
+        console.log(chalk5.gray(line));
+      }
+    }
+    console.log("");
+  } else {
+    console.log(
+      chalk5.gray("    (no diff available \u2014 working tree may already match snapshot)\n")
+    );
+  }
   const proceed = await confirm3({
-    message: "Revert all files to the state before the last AI action?",
+    message: `Revert to this snapshot?`,
     default: false
   });
   if (proceed) {
-    if (applyUndo(hash)) {
-      console.log(chalk5.green("\u2705 Project reverted successfully.\n"));
+    if (applyUndo(snapshot.hash, snapshot.cwd)) {
+      console.log(chalk5.green("\n\u2705 Reverted successfully.\n"));
     } else {
-      console.error(chalk5.red("\u274C Undo failed. Ensure you are in a Git repository.\n"));
+      console.error(chalk5.red("\n\u274C Undo failed. Ensure you are in a Git repository.\n"));
     }
+  } else {
+    console.log(chalk5.gray("\nCancelled.\n"));
   }
 });
 process.on("unhandledRejection", (reason) => {