@niroai/niro 0.11.0 → 0.13.0

package/src/mcp/setup.js

@@ -50,7 +50,7 @@ const NIRO_MD_MARKER = "<!-- niro-mcp -->";
  * read once per session, which is why it now states its own non-expiry explicitly. Wording is imperative
  * and names concrete tools so the agent knows what to call instead of native search.
  */
-const NIRO_EXPLORE_FIRST_SENTENCE = "MUST FOLLOW: before you run grep, find, glob, or open a file to hunt for something, first check whether a Niro tool answers it (code_grep for content search, resolve_fqn and get_source_code for a known symbol, find_handler and find_api_endpoints for entry points). Use the connection tools (get_call_chain, get_reverse_call_chain, get_blast_radius, get_impact_analysis, get_service_topology) to understand how code connects BEFORE deciding which file to read or search next, rather than reading files to rebuild that picture by hand. Native search is the fallback for what Niro does not cover (config files, docs, logs, generated output, non-code text) or when the tools are unavailable. This rule does not expire: it holds on the first turn and on the fiftieth, mid-task as much as at the start of a session, and a long conversation is not a reason to drift back to native search.";
+const NIRO_EXPLORE_FIRST_SENTENCE = "MUST FOLLOW: before you run grep, find, glob, or open a file to hunt for something, first check whether a Niro tool answers it (code_grep for content search, resolve_fqn and get_source_code for a known symbol, find_handler and find_api_endpoints for entry points). Use the connection tools (get_call_chain, get_reverse_call_chain, get_blast_radius, get_impact_analysis, get_service_topology, get_exception_flow for which exceptions can escape a method) to understand how code connects BEFORE deciding which file to read or search next, rather than reading files to rebuild that picture by hand. Native search is the fallback for what Niro does not cover (config files, docs, logs, generated output, non-code text) or when the tools are unavailable. This rule does not expire: it holds on the first turn and on the fiftieth, mid-task as much as at the start of a session, and a long conversation is not a reason to drift back to native search.";
 
 const NIRO_MULTI_REPO_SENTENCE = "The temporary project answer is per (repo, BRANCH): after you create/switch a branch in a repo — and before your first edit on that branch — call should_create_temp_project with the repo's git url, its CURRENT branch, and its `.niro-project` id if present, then run `niro new-temp-project` in its folder if needs_temp_project is true. Re-check after every branch change (a `false` from another branch does NOT carry over); this applies to every repo you touch, including when the session started in a parent folder that is not itself a git repo.";
 /**
@@ -63,7 +63,7 @@ const NIRO_MULTI_REPO_SENTENCE = "The temporary project answer is per (repo, BRA
  * is agreed the wrong basis is already baked in; and it says the size of the diff does not excuse it,
  * because a one-line change to shared code reaches further than a rewrite of a standalone tool.
  */
-const NIRO_IMPACT_BOTH_WAYS_SENTENCE = "MUST FOLLOW: before you plan, propose, or start any change to existing code, establish BOTH sides of it. Upstream: what depends on the code you are about to touch, including callers in other services over HTTP or events, and the tests and config that name it. Downstream: what that code itself calls, and the data and events it relies on. Use get_blast_radius, which returns callers, callees, cross-service callers and impacted files in one call, or get_impact_analysis for the lighter upstream-only view. Put the result in the plan you show the user: name the callers you found, say which ones you will update, and say which ones you are deliberately leaving alone. This applies to a one-line change too, because how far a change reaches is decided by what depends on it, not by the size of the diff.";
+const NIRO_IMPACT_BOTH_WAYS_SENTENCE = "MUST FOLLOW: before you plan, propose, or start any change to existing code, establish BOTH sides of it. Upstream: what depends on the code you are about to touch, including callers in other services over HTTP or events, and the tests and config that name it. Downstream: what that code itself calls, and the data and events it relies on. Use get_blast_radius, which returns callers, callees, cross-service callers and impacted files in one call, or get_impact_analysis for the lighter upstream-only view. Put the result in the plan you show the user: name the callers you found, say which ones you will update, and say which ones you are deliberately leaving alone. This applies to a one-line change too, because how far a change reaches is decided by what depends on it, not by the size of the diff. Keep that list: after the edit, verify those flows still hold (run their tests, trace them, read the callers) and say what you verified. The graph updates only after your edit is synced and rebuilt, so do not re-query it to verify; use the list you captured before. A change that cannot alter behaviour at all (a log line, a comment, formatting) needs no map: say so in one sentence.";
 const NIRO_CLAUDE_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP tools are available for code intelligence. Use them (call chains, blast radius, impact analysis, source lookup) before falling back to native grep/read for code questions.\nBefore adding/writing any new code, you MUST use the find_reusable_code tool from niro to figure out if there is anything reusable.\n${NIRO_EXPLORE_FIRST_SENTENCE}\n${NIRO_IMPACT_BOTH_WAYS_SENTENCE}\n${NIRO_MULTI_REPO_SENTENCE}\n`;
 const NIRO_CODEX_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP code-intelligence tools and the \`niro-skill\` are available (call chains, blast radius, impact analysis, source lookup). Prefer them over grep/read for questions about this codebase; the niro-skill has the full tool-routing playbook. Before adding or writing any new code, use find_reusable_code to check for reusable code. If the niro tools are not present or the repo is not indexed, use native tools.\n${NIRO_EXPLORE_FIRST_SENTENCE}\n${NIRO_IMPACT_BOTH_WAYS_SENTENCE}\n${NIRO_MULTI_REPO_SENTENCE}\n`;
 const NIRO_WINDSURF_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP code-intelligence tools and the niro-skill are available. Prefer them over grep/read for questions about this codebase (structure, call chains, blast radius, impact, data flows, reuse); the niro-skill has the full routing playbook. Before writing any new code, use find_reusable_code. If the niro tools are not present or the repo is not indexed, use native tools.\n${NIRO_EXPLORE_FIRST_SENTENCE}\n${NIRO_IMPACT_BOTH_WAYS_SENTENCE}\n${NIRO_MULTI_REPO_SENTENCE}\n`;
@@ -161,6 +161,19 @@ function isNiroExploreHook(h) {
   return cmds.some((c) => c.includes("niro-explore-"));
 }
 
+/**
+ * True if `h` is niro's PreToolUse impact-gate entry (matcher Edit|Write). Keyed on the unique
+ * `niro-impact-` identity token so a foreign PreToolUse hook on the same matcher, and niro's own
+ * temp-project hook on the same matcher, are never matched or removed by mistake. Shared by installer
+ * (upgrade-in-place) and uninstaller (removal).
+ */
+function isNiroImpactHook(h) {
+  const cmds = [];
+  if (h && Array.isArray(h.hooks)) h.hooks.forEach((i) => i && typeof i.command === "string" && cmds.push(i.command));
+  if (h && typeof h.command === "string") cmds.push(h.command);
+  return cmds.some((c) => c.includes("niro-impact-"));
+}
+
 /**
  * Writes a niro-managed skill/rule file, refreshing it when the generated content has
  * changed. These files are GENERATED (not hand-edited), so refresh-on-change is correct:
@@ -589,8 +602,49 @@ function printClients({ all = false } = {}) {
   console.log("");
 }
 
-async function setupClaudeCode(apiKey, mcpServerUrl) {
+/** The URL an existing Claude Code registration points at, read off `claude mcp get niro`; null if none. */
+function registeredServerUrl(getOutput) {
+  const m = /NIRO_MCP_SERVER_URL=(\S+)/.exec(String(getOutput || ""));
+  return m ? m[1] : null;
+}
+
+/**
+ * What to do about the Claude Code registration before the hooks are written. Pure, so it is tested
+ * with the real `claude mcp get` output as a fixture.
+ *   "add"     nothing is registered (`claude mcp get niro` failed)
+ *   "keep"    registered and already pointing at the wanted URL
+ *   "replace" registered, but at another URL or in a shape this cannot read: remove, then add
+ */
+function planClaudeRegistration({ existingOutput, wantedUrl }) {
+  if (existingOutput == null) return "add";
+  const url = registeredServerUrl(existingOutput);
+  return url && url === wantedUrl ? "keep" : "replace";
+}
+
+/**
+ * Register the niro server with Claude Code, or keep the registration already there, then write the
+ * hooks, the memory section and the skills.
+ *
+ * `claude mcp add` refuses when a server of that name exists ("MCP server niro already exists in
+ * user config", exit 1). This function treated every failure of that command as "Claude Code is not
+ * installed" and returned before writing a single hook, so on any machine where niro had been set up
+ * once, `niro mcp install` refreshed nothing: not the hooks, not the CLAUDE.md section. That is the
+ * exact step the out-of-date notice tells users to run. Found 2026-09-05 when the new Edit|Write
+ * hook could not be installed on the machine it was written on.
+ *
+ * `deps` is for tests only: `get` returns the `claude mcp get niro` output or null, `run` runs a
+ * client command; both default to the real thing.
+ */
+async function setupClaudeCode(apiKey, mcpServerUrl, deps = {}) {
   console.log("\n    Configuring Claude Code...\n");
+  const run = deps.run || runClientCommand;
+  const get = deps.get || (() => {
+    try {
+      return execSync("claude mcp get niro", { stdio: ["ignore", "pipe", "pipe"], encoding: "utf8" });
+    } catch (_) {
+      return null; // not registered, or no `claude` on the PATH: `add` below tells the two apart
+    }
+  });
 
   const cmd = [
     "claude", "mcp", "add",
@@ -604,20 +658,34 @@ async function setupClaudeCode(apiKey, mcpServerUrl) {
   cmd.push("-e", `NIRO_MCP_SERVER_URL=${mcpServerUrl}`);
   cmd.push("--", "niro", "mcp", "serve");
 
-  try {
-    runClientCommand(cmd.join(" "));
-    console.log("    MCP server registered globally in Claude Code.\n");
-  } catch (err) {
-    console.error("    Failed to register MCP server. Is Claude Code installed?");
-    console.error("    Install: https://claude.ai/code\n");
-    console.error(`    Manual command:\n    ${cmd.join(" ")}\n`);
-    return false;
+  const plan = planClaudeRegistration({ existingOutput: get(), wantedUrl: mcpServerUrl });
+  if (plan === "keep") {
+    console.log(`    MCP server already registered in Claude Code at ${mcpServerUrl}. Keeping it.\n`);
+  } else {
+    if (plan === "replace") {
+      try {
+        run("claude mcp remove --scope user niro");
+      } catch (_) {
+        /* the add below reports what is wrong */
+      }
+    }
+    try {
+      run(cmd.join(" "));
+      console.log("    MCP server registered globally in Claude Code.\n");
+    } catch (err) {
+      const detail = String((err && (err.stderr || err.message)) || "").trim().split("\n")[0];
+      console.error(`    Failed to register MCP server${detail ? `: ${detail}` : ""}.`);
+      console.error("    If Claude Code is not installed: https://claude.ai/code\n");
+      console.error(`    Manual command:\n    ${cmd.join(" ")}\n`);
+      return false;
+    }
   }
 
   addClaudeCodePostCompactHook();
   addClaudeCodeUserPromptHook();
   addClaudeCodePreToolUseHook();
   addClaudeCodeExploreHook();
+  addClaudeCodeImpactHook();
   removeStaleNiroStopHook();
   addClaudeCodeMemory();
   addClaudeCodeSkill();
@@ -670,7 +738,9 @@ function isNiroGeneratedPostCompactHook(h) {
 const NIRO_POST_COMPACT_COMMAND =
   "echo 'Niro MCP tools are available for code intelligence (call chains, blast radius, impact analysis, source lookup). "
   + "Use niro tools before native grep/read for code questions. Before you plan or propose a change to existing code, call "
-  + "get_blast_radius (or get_impact_analysis) to see who calls it and what it calls, and put that impact in the plan.'";
+  + "get_blast_radius (or get_impact_analysis) to see who calls it and what it calls, and put that impact in the plan. "
+  + "Keep that list and verify those flows after the edit; the graph lags your edit, so do not re-query it to verify. "
+  + "A log line or comment needs no map.'";
 
 function addClaudeCodePostCompactHook() {
   // Guard the invariant that keeps upgrade-in-place working: if the reminder is ever reworded so it
@@ -781,7 +851,7 @@ function addClaudeCodeMemory() {
  */
 const NIRO_USER_PROMPT_COMMAND =
     "IN=\"$(cat)\"; d=\"${CLAUDE_PROJECT_DIR:-$PWD}\"; while [ -n \"$d\" ] && [ \"$d\" != \"/\" ]; do " +
-    "if [ -f \"$d/.niro-project\" ]; then echo 'NIRO ACTIVE. Standing rule for this whole session, at the start and mid-task alike: before Grep/Glob/Read or any native file hunt, use niro (code_grep, get_source_code, resolve_fqn, get_call_chain, get_blast_radius, get_impact_analysis). Before writing new code, call find_reusable_code. Before you plan or propose a change to existing code, call get_blast_radius (or get_impact_analysis) to see who calls it and what it calls, and put that impact in the plan. Native tools only for config, docs, logs, generated or non-code text. If the niro tools are not in your toolset at all, use native tools and do not mention Niro.'; " +
+    "if [ -f \"$d/.niro-project\" ]; then echo 'NIRO ACTIVE. Standing rule for this whole session, at the start and mid-task alike: before Grep/Glob/Read or any native file hunt, use niro (code_grep, get_source_code, resolve_fqn, get_call_chain, get_blast_radius, get_impact_analysis). Before writing new code, call find_reusable_code. Before you plan or propose a change to existing code, call get_blast_radius (or get_impact_analysis) to see who calls it and what it calls, and put that impact in the plan. Keep that list and verify those flows after the edit; the graph lags your edit, so do not re-query it to verify. A log line or comment needs no map. Native tools only for config, docs, logs, generated or non-code text. If the niro tools are not in your toolset at all, use native tools and do not mention Niro.'; " +
     "printf '%s' \"$IN\" | grep -qiE 'new branch|create[^.]{0,24}branch|switch[^.]{0,24}branch|checkout -b|change[^.]{0,24}branch|different branch|another branch' && " +
     "echo 'You appear to be about to create or switch a branch. The temporary project check is per (repo, branch), so do it AFTER you are on the new branch (not before) and pass that CURRENT branch: call should_create_temp_project(git_url, branch, project_id from its .niro-project) and run niro new-temp-project if needs_temp_project is true. A check you ran on the old branch does not count.'; break; fi; " +
     "d=\"$(dirname \"$d\")\"; done";
@@ -1102,6 +1172,165 @@ function addClaudeCodeExploreHook() {
   }
 }
 
+/**
+ * The three answers the impact hook can give. Built with JSON.stringify so the text is valid JSON by
+ * construction. All three are wrapped in single quotes inside the shell command, so no message may
+ * contain an apostrophe or a backtick; the test suite executes the command, which would break loudly
+ * if one crept in. None carries a permissionDecision: the hook advises, it never approves or refuses.
+ *
+ * Why advisory and not a refusal, in Niraj's words (2026-09-05): "The reason I said before editing
+ * any method, the impact of editing it should be measured is because I want the coding agent to verify
+ * that after the change as well, the flows connected with the current method are not breaking. [...]
+ * graph updating takes time after an edit is performed. The change does not take effect instantly.
+ * [...] it is not to enforce use of niro [...] now if someone is just adding a log message, that's not
+ * gonna affect anything so if the verification should happen or not is also subjective."
+ */
+const NIRO_IMPACT_UNMAPPED_JSON = JSON.stringify({
+  hookSpecificOutput: {
+    hookEventName: "PreToolUse",
+    additionalContext:
+      "Niro impact check, before you edit this file: decide whether this change can alter behaviour. " +
+      "A log line, a comment, formatting or a message string cannot, so say so in one sentence and go " +
+      "ahead. Anything else can, so map who depends on the method NOW with get_blast_radius or " +
+      "get_impact_analysis (a partial name such as ClassName.method resolves when it is unique; " +
+      "resolve_fqn on one that does not) and keep the list of callers and flows: it is your checklist " +
+      "for AFTER the edit. The graph updates only after your edit is synced and rebuilt, so do not " +
+      "re-query it to verify; verify the listed flows by running their tests, tracing them, or reading " +
+      "the callers, and say what you verified. Shown once per file per session.",
+  },
+});
+const NIRO_IMPACT_MAPPED_JSON = JSON.stringify({
+  hookSpecificOutput: {
+    hookEventName: "PreToolUse",
+    additionalContext:
+      "Niro impact check: an impact map for this file was recorded in the last hour. After this edit, " +
+      "go back to the callers and flows it listed and verify they still hold: run their tests, trace " +
+      "them, or read the callers, and say what you verified. The graph updates only after your edit is " +
+      "synced and rebuilt, so a fresh query would still show the old code; use the list you already " +
+      "have. Shown once per file per session.",
+  },
+});
+const NIRO_IMPACT_NO_BRIDGE_JSON = JSON.stringify({
+  hookSpecificOutput: {
+    hookEventName: "PreToolUse",
+    additionalContext:
+      "Niro impact check: you are editing indexed source with no impact map recorded for this file, " +
+      "and the Niro bridge has not answered in the last 30 minutes. If this change can alter behaviour " +
+      "(anything beyond a log line, a comment, formatting or a message string), map who depends on it " +
+      "as soon as Niro answers and verify those flows after the edit; the graph will lag your edit, so " +
+      "use the list you capture, not a fresh query. Shown once per file per session.",
+  },
+});
+
+/**
+ * The niro PreToolUse hook command (matcher Edit|Write): before an edit to indexed source, make the
+ * agent decide out loud whether the change can alter behaviour and, if so, map who depends on the
+ * method while the graph is still current, then carry that list across the edit as the checklist for
+ * afterwards. The prose rule (NIRO_IMPACT_BOTH_WAYS_SENTENCE) is on every instruction surface and
+ * still gets read past; a reminder at the moment of the edit is what survives a long session.
+ * Full design, the reasoning in Niraj's words, and the scenario table: docs/usecases/impact-gate.md.
+ *
+ * Advisory, never a refusal. The first cut denied the edit until an impact call named the file. That
+ * enforced a tool call, which was never the goal; it could not tell a log line from a signature change;
+ * and review found two ways it failed closed. Now every answer is additionalContext, and it never emits
+ * permissionDecision at all ("allow" would auto-approve every edit and bypass the permission prompt).
+ *
+ * The evidence comes from the bridge: src/lib/impactLog.js writes one JSON line per answered
+ * get_blast_radius / get_impact_analysis / get_reverse_call_chain call to ~/.niro/impact/<key>.jsonl,
+ * and touches <key>.alive whenever the server answers. <key> is the session folder with every
+ * non-alphanumeric byte replaced by "-": here `cd -P` + `tr -c`, there fs.realpathSync + a byte loop,
+ * and test/impactGateHook.test.js proves the two agree.
+ *
+ * Decision, top to bottom, first match wins: no file_path, the off switch, a file that does not exist
+ * yet, a non-source extension, a test path, or no `.niro-project` above the file -> silent. A log line
+ * from the last hour that names the file (a files entry ending "/Foo.java", or a name containing
+ * ".Foo.", "\"Foo.", ".Foo\"", "\"Foo\"," or "\"Foo\"]": always a VALUE, so a file called ts.js or
+ * tool.js is not matched by the record's own "ts"/"tool" keys) -> the MAPPED reminder: verify the
+ * listed flows after the edit, do not re-query the lagging graph. Otherwise, alive file touched in the
+ * last 30 minutes -> the UNMAPPED reminder: decide, and map now if the change can alter behaviour; no
+ * live bridge -> the short NO_BRIDGE form. Each reminder is shown once per (session, file), keyed like
+ * the temp-project hook's marker, so ten edits to one file do not produce ten copies.
+ *
+ * Dependency-free like its siblings (grep -oE, sed -E, tr, find -mmin, cksum: GNU + BSD).
+ * `niro-impact-` is the identity token isNiroImpactHook and teardown match on.
+ */
+const NIRO_IMPACT_COMMAND = [
+  'IN="$(cat)"',
+  `f="$(printf '%s' "$IN" | grep -oE '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed -E 's/.*:[[:space:]]*"([^"]*)"/\\1/')"`,
+  '[ -z "$f" ] && exit 0',
+  `c="$(printf '%s' "$IN" | grep -oE '"cwd"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed -E 's/.*:[[:space:]]*"([^"]*)"/\\1/')"`,
+  '[ -z "$c" ] && c="${CLAUDE_PROJECT_DIR:-$PWD}"',
+  'case "$f" in /*) ;; *) f="$c/$f" ;; esac',
+  'H="${HOME:-/tmp}"',
+  '[ -f "$H/.niro/impact-gate-off" ] && exit 0',
+  // A file that does not exist yet has no callers; a Write creating it is never gated.
+  '[ -f "$f" ] || exit 0',
+  'case "$f" in *.java|*.js|*.mjs|*.cjs|*.ts|*.tsx|*.jsx|*.py|*.go|*.rb|*.kt|*.kts|*.cs|*.php|*.rs|*.scala|*.swift|*.c|*.cc|*.cpp|*.h|*.hpp) ;; *) exit 0 ;; esac',
+  'case "$f" in */test/*|*/tests/*|*/__tests__/*|*/spec/*|*.test.*|*.spec.*|*Test.*|*Tests.*|*IT.java|*_test.*|*/test_*|*_spec.*|*/conftest.py) exit 0 ;; esac',
+  // Symlink-resolved walk-up for the .niro-project marker, same as the explore hook.
+  `d0="$(dirname "$f")"; d0="$(cd -P "$d0" 2>/dev/null && pwd -P || printf '%s' "$d0")"`,
+  'd="$d0"; ok=0; while [ -n "$d" ] && [ "$d" != "/" ] && [ "$d" != "." ]; do if [ -f "$d/.niro-project" ]; then ok=1; break; fi; p="$(dirname "$d")"; [ "$p" = "$d" ] && break; d="$p"; done',
+  '[ "$ok" = 0 ] && exit 0',
+  // The log key, byte for byte what impactLog.keyForCwd computes from the bridge's process.cwd().
+  `cr="$(cd -P "$c" 2>/dev/null && pwd -P || printf '%s' "$c")"`,
+  `k="$(printf '%s' "$cr" | tr -c 'A-Za-z0-9' '-')"`,
+  'L="$H/.niro/impact/$k.jsonl"; A="$H/.niro/impact/$k.alive"',
+  'b="$(basename "$f")"; n="${b%.*}"',
+  // The session + file key for the once-per-file markers, hashed the way the temp-project hook does.
+  `s="$(printf '%s' "$IN" | grep -oE '"session_id"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed -E 's/.*:[[:space:]]*"([^"]*)"/\\1/')"`,
+  `j="$(printf '%s\\n%s' "$s" "$f" | cksum | cut -d' ' -f1)"`,
+  'NIRO_HOOK_ID=niro-impact-gate',
+  // Mapped: the log was written in the last hour (the bridge prunes on write, so an older file holds
+  // only stale lines) and a line names this file or its class -> remind once to verify AFTER the edit.
+  `if [ -f "$L" ] && [ -n "$(find "$L" -mmin -60 2>/dev/null)" ] && grep -qF -e "/$b\\"" -e ".$n." -e "\\"$n." -e ".$n\\"" -e "\\"$n\\"," -e "\\"$n\\"]" "$L" 2>/dev/null; then m="\${TMPDIR:-/tmp}/niro-impact-after-$j"; [ -f "$m" ] && exit 0; touch "$m"; printf '%s' '${NIRO_IMPACT_MAPPED_JSON}'; exit 0; fi`,
+  // Unmapped: ask once per (session, file) for the decision; with no live bridge, the short form.
+  'm="${TMPDIR:-/tmp}/niro-impact-before-$j"; [ -f "$m" ] && exit 0; touch "$m"',
+  `if [ -f "$A" ] && [ -n "$(find "$A" -mmin -30 2>/dev/null)" ]; then printf '%s' '${NIRO_IMPACT_UNMAPPED_JSON}'; else printf '%s' '${NIRO_IMPACT_NO_BRIDGE_JSON}'; fi`,
+].join('; ');
+
+/**
+ * Adds the PreToolUse (Edit|Write) impact-gate hook to ~/.claude/settings.json. Idempotent: upgrades a
+ * stale niro entry in place, never touches a foreign PreToolUse hook on the same matcher nor niro's own
+ * temp-project hook (matched by the niro-impact- token via isNiroImpactHook).
+ */
+function addClaudeCodeImpactHook() {
+  const settingsPath = path.join(process.env.HOME || "", ".claude", "settings.json");
+  let settings = {};
+  try {
+    if (fs.existsSync(settingsPath)) settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+  } catch {
+    // Corrupt or missing — start fresh
+  }
+
+  if (!settings.hooks) settings.hooks = {};
+  if (!settings.hooks.PreToolUse) settings.hooks.PreToolUse = [];
+
+  const entry = { matcher: "Edit|Write", hooks: [{ type: "command", command: NIRO_IMPACT_COMMAND }] };
+  const alreadyCurrent = settings.hooks.PreToolUse.some(
+    (h) => Array.isArray(h.hooks) && h.hooks.some((i) => i && i.command === NIRO_IMPACT_COMMAND),
+  );
+  if (alreadyCurrent) {
+    console.log("    PreToolUse impact-gate hook already up to date. Skipping.\n");
+    return;
+  }
+
+  const hadStale = settings.hooks.PreToolUse.some(isNiroImpactHook);
+  settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter((h) => !isNiroImpactHook(h));
+  settings.hooks.PreToolUse.push(entry);
+
+  try {
+    fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    console.log(`    PreToolUse impact-gate hook ${hadStale ? "upgraded" : "added"} in ~/.claude/settings.json`);
+    console.log("    Before an edit to indexed source, Claude is asked to map who depends on the method and to");
+    console.log("    verify those flows after the edit. Advisory only. Off switch: touch ~/.niro/impact-gate-off\n");
+  } catch (err) {
+    console.warn(`    Could not write ~/.claude/settings.json: ${err.message}`);
+    console.warn("    Add manually to the PreToolUse array in ~/.claude/settings.json:\n");
+    console.warn(JSON.stringify(entry, null, 2) + "\n");
+  }
+}
+
 /** Body of the `niro` skill (long-form tool-routing playbook). */
 const NIRO_SKILL = `---
 name: niro-skill
@@ -1143,6 +1372,12 @@ plan, propose, or start any change to existing code, establish both sides:
 impacted files). \`get_impact_analysis\` is the lighter upstream-only view. Pass
 \`include_source_code=true\` when you need to read what you found.
 
+Keep the list. After the edit, go back to the callers and flows it named and verify they still
+hold: run their tests, trace them, read the callers, and say what you verified. The graph updates
+only after your edit is synced and rebuilt, so do not re-query it to verify; use the list you
+captured before. A change that cannot alter behaviour at all (a log line, a comment, formatting)
+needs no map: say so in one sentence.
+
 Put the answer in the plan you show the user, not just in your head: name the callers you found,
 say which ones you will update, and say which ones you are deliberately leaving alone. A one-line
 change is not exempt, because reach is decided by what depends on the code, not by the size of the
@@ -1301,7 +1536,8 @@ Also available (catalog / utility, use when the above don't fit): \`list_project
 - **Before adding or writing ANY new code, call \`find_reusable_code\` first.** Mandatory.
 - **Before you plan or propose a change to existing code, call \`get_blast_radius\` (or
   \`get_impact_analysis\`) and put the upstream and downstream impact in the plan.** Mandatory,
-  whatever the size of the change.
+  whatever the size of the change. Keep the list and verify those flows after the edit; the graph
+  lags your edit, so do not re-query it to verify. A log line or comment needs no map.
 - For comprehension / debugging, set \`purpose\` to COMPREHEND or DEBUG and, on
   \`get_blast_radius\` / \`get_impact_analysis\`, pass \`include_source_code=true\`.
 - If a result contains **⚠️ ACTION REQUIRED**, the graph is stale — read the listed files
@@ -1559,7 +1795,11 @@ any change to existing code, establish who depends on it (upstream callers, incl
 services over HTTP or events) and what it depends on (downstream callees, data, events). Use
 get_blast_radius, which returns both sides plus impacted files in one call, or
 get_impact_analysis for the upstream-only view. Name the callers you found in the plan and say
-which ones you will update. A one-line change is not exempt.
+which ones you will update. A one-line change is not exempt. Keep that list: after the edit, verify
+those flows still hold (run their tests, trace them, read the callers) and say what you verified.
+The graph updates only after your edit is synced and rebuilt, so do not re-query it to verify. A
+change that cannot alter behaviour at all (a log line, a comment, formatting) needs no map: say so
+in one sentence.
 
 Availability self-check FIRST — if the niro tools are not present in this session, or the
 repo is not indexed (no project resolves / a tool reports "not indexed"), fall back to
@@ -2029,7 +2269,11 @@ any change to existing code, establish who depends on it (upstream callers, incl
 other services over HTTP or events) and what it depends on (downstream callees, data, events). Use
 \`get_blast_radius\`, which returns both sides plus impacted files in one call, or
 \`get_impact_analysis\` for the upstream-only view. Name the callers you found in the plan and say
-which ones you will update. A one-line change is not exempt.
+which ones you will update. A one-line change is not exempt. Keep that list: after the edit, verify
+those flows still hold (run their tests, trace them, read the callers) and say what you verified.
+The graph updates only after your edit is synced and rebuilt, so do not re-query it to verify. A
+change that cannot alter behaviour at all (a log line, a comment, formatting) needs no map: say so
+in one sentence.
 
 If the niro tools are not present in this session, or the repo is not indexed (no project
 resolves), fall back to native tools silently — do not mention Niro's absence.
@@ -2081,7 +2325,11 @@ any change to existing code, establish who depends on it (upstream callers, incl
 other services over HTTP or events) and what it depends on (downstream callees, data, events). Use
 \`get_blast_radius\`, which returns both sides plus impacted files in one call, or
 \`get_impact_analysis\` for the upstream-only view. Name the callers you found in the plan and say
-which ones you will update. A one-line change is not exempt.
+which ones you will update. A one-line change is not exempt. Keep that list: after the edit, verify
+those flows still hold (run their tests, trace them, read the callers) and say what you verified.
+The graph updates only after your edit is synced and rebuilt, so do not re-query it to verify. A
+change that cannot alter behaviour at all (a log line, a comment, formatting) needs no map: say so
+in one sentence.
 
 If the niro tools are not present in this session, or the repo is not indexed (no project
 resolves), fall back to native tools silently — do not mention Niro's absence.
@@ -2535,12 +2783,20 @@ module.exports = {
   addAgentsSkill,
   addAgentsCliSkill,
   CLIENTS,
+  // Exported so `niro upgrade` can detect a configured Goose install by reading the same
+  // file setupGoose writes, instead of rebuilding that platform-specific path a second time.
+  gooseConfigPath,
   NIRO_MD_MARKER,
   NIRO_MD_SECTIONS,
   isNiroPostCompactHook,
   isNiroUserPromptHook,
   isNiroPreToolUseHook,
   isNiroExploreHook,
+  isNiroImpactHook,
+  NIRO_IMPACT_COMMAND,
+  setupClaudeCode,
+  planClaudeRegistration,
+  registeredServerUrl,
   isNiroStopHook,
   clearCodexPerToolApprovals,
   hardenCodexServerConfig,

package/src/mcp/teardown.js

@@ -42,6 +42,7 @@ const {
   isNiroUserPromptHook,
   isNiroPreToolUseHook,
   isNiroExploreHook,
+  isNiroImpactHook,
   userHome,
 } = require("./setup");
 
@@ -126,7 +127,7 @@ function removeMarkerSectionBounded(content, marker) {
 }
 
 /**
- * Strip niro's PostCompact, UserPromptSubmit, and PreToolUse (temp-project + explore-first) hook
+ * Strip niro's PostCompact, UserPromptSubmit, and PreToolUse (temp-project + explore-first + impact-gate) hook
  * entries from a parsed Claude Code settings object (mutates and returns it). Uses the same matchers
  * install uses. Empty arrays / an empty `hooks` object are pruned so the file stays tidy. Other hooks
  * are untouched. Returns { settings, removed } where `removed` is the count deleted.
@@ -152,7 +153,9 @@ function filterNiroHooks(settings) {
   }
   if (Array.isArray(hooks.PreToolUse)) {
     const before = hooks.PreToolUse.length;
-    hooks.PreToolUse = hooks.PreToolUse.filter((h) => !isNiroPreToolUseHook(h) && !isNiroExploreHook(h));
+    hooks.PreToolUse = hooks.PreToolUse.filter(
+      (h) => !isNiroPreToolUseHook(h) && !isNiroExploreHook(h) && !isNiroImpactHook(h),
+    );
     removed += before - hooks.PreToolUse.length;
     if (hooks.PreToolUse.length === 0) delete hooks.PreToolUse;
   }
@@ -388,6 +391,8 @@ function uninstallClaudeCode() {
   // a task the developer has long forgotten.
   try {
     require("../lib/receiptStore").purge();
+    // The impact gate's evidence files and off switch go with the hook that read them.
+    require("../lib/impactLog").purge();
   } catch {
     /* best effort — never block an uninstall on cleaning up a cache */
   }