@niroai/niro 0.10.1 → 0.12.0

package/src/mcp/setup.js

@@ -50,19 +50,30 @@ 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.";
-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_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_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_MULTI_REPO_SENTENCE}\n`;
+/**
+ * Impact-both-ways rule, shared by every client's markdown section. The explore-first sentence above
+ * governs READING code; this one governs CHANGING it. The failure it exists to stop is an agent that
+ * reads the one file it was pointed at, proposes an edit, and never learns which callers that edit
+ * breaks or which dependency constrains it. get_blast_radius is named first because it answers BOTH
+ * sides in a single call, so the rule costs one tool call and skipping it costs a broken caller nobody
+ * looked for. It is worded "before you plan or propose", not "before you edit", because once the plan
+ * 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. 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`;
 /**
  * Shared generic section for clients whose "always-on instructions" file has no companion
  * skill mechanism we've verified (Gemini CLI's GEMINI.md, GitHub Copilot CLI's
  * copilot-instructions.md, Factory's AGENTS.md, OpenCode's AGENTS.md) — one wording, reused
  * across those destination files (teardown matches it per-file, so reuse is safe).
  */
-const NIRO_GENERIC_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP code-intelligence tools are available (call chains, blast radius, impact analysis, source lookup). Prefer them over grep/read for questions about this codebase. 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_MULTI_REPO_SENTENCE}\n`;
+const NIRO_GENERIC_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP code-intelligence tools are available (call chains, blast radius, impact analysis, source lookup). Prefer them over grep/read for questions about this codebase. 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`;
 
 /** All niro markdown sections — the uninstaller tries each for an exact removal. */
 const NIRO_MD_SECTIONS = [NIRO_CLAUDE_MD_SECTION, NIRO_CODEX_MD_SECTION, NIRO_WINDSURF_MD_SECTION, NIRO_GENERIC_MD_SECTION];
@@ -150,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:
@@ -578,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",
@@ -593,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();
@@ -620,9 +699,59 @@ async function setupClaudeCode(apiKey, mcpServerUrl) {
  * about Niro tools after context compaction (the point where tool awareness
  * most commonly degrades in long sessions).
  */
+/**
+ * The opening of every PostCompact command niro has ever generated. Verified against all four commits
+ * that ever touched the string (ffeb4e0, ce017c7, d3ff3d8, 84e2e7b): the generated text has always been
+ * byte-identical and has always started here.
+ */
+const NIRO_POST_COMPACT_PREFIX = "echo 'Niro MCP tools are available for code intelligence";
+
+/**
+ * Narrow identity for the DESTRUCTIVE half of the upgrade path: did NIRO ITSELF generate this entry?
+ *
+ * isNiroPostCompactHook matches the bare substring "Niro MCP", which is the right question for "is a
+ * niro hook already here" and the WRONG one for "may I delete this entry". A hook the USER wrote that
+ * merely mentions Niro MCP (a reminder about a Niro MCP dashboard, say) matches that substring too, and
+ * the filter below would delete their hook and put ours in its place. Matching the generated prefix
+ * instead recognises every real niro install while leaving anything a human wrote alone.
+ *
+ * Deliberately narrower than isNiroPostCompactHook, and the asymmetry is the point: a false negative
+ * here appends a second niro entry (noisy, recoverable), a false positive destroys a user's hook.
+ * Handles both entry shapes, the nested `hooks` array and the legacy flat `command`.
+ */
+function isNiroGeneratedPostCompactHook(h) {
+  if (!h || typeof h !== "object") return false;
+  const commands = Array.isArray(h.hooks) ? h.hooks.map((i) => i && i.command) : [h.command];
+  return commands.some((c) => typeof c === "string" && c.startsWith(NIRO_POST_COMPACT_PREFIX));
+}
+
+/**
+ * The PostCompact reminder. Compaction is the moment tool awareness degrades in a long session, so this
+ * is the one reminder that fires precisely when the agent has just lost the plan it made earlier — which
+ * is exactly when it is most likely to resume editing without re-checking who calls the code. It carries
+ * the impact rule for that reason. Kept as a named constant (like the other hook bodies) so the
+ * regression test can assert on the real string the installer writes.
+ *
+ * MUST keep the literal "Niro MCP": isNiroPostCompactHook identifies niro entries by that substring, and
+ * the uninstaller shares the predicate. Dropping it would strand the hook in a user's settings.json.
+ */
+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. "
+  + "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
+  // no longer starts with the generated prefix, every install would append a fresh entry instead of
+  // replacing the old one. Fail loudly at the boundary rather than quietly stacking hooks.
+  if (!NIRO_POST_COMPACT_COMMAND.startsWith(NIRO_POST_COMPACT_PREFIX)) {
+    throw new Error("NIRO_POST_COMPACT_COMMAND must start with NIRO_POST_COMPACT_PREFIX, or upgrade-in-place breaks");
+  }
+
   const settingsPath = path.join(process.env.HOME || "", ".claude", "settings.json");
-  const hookCommand = "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.'";
+  const hookCommand = NIRO_POST_COMPACT_COMMAND;
 
   let settings = {};
   try {
@@ -636,13 +765,21 @@ function addClaudeCodePostCompactHook() {
   if (!settings.hooks) settings.hooks = {};
   if (!settings.hooks.PostCompact) settings.hooks.PostCompact = [];
 
-  const alreadyPresent = settings.hooks.PostCompact.some(isNiroPostCompactHook);
-
-  if (alreadyPresent) {
-    console.log("    PostCompact hook already configured. Skipping.\n");
+  // Exact-match the CURRENT command first: only then is there nothing to do. Matching the loose niro
+  // signature instead (the old behaviour) meant an existing user with the previous reminder text was
+  // skipped forever and never received an updated one.
+  const alreadyCurrent = settings.hooks.PostCompact.some(
+    (h) => Array.isArray(h.hooks) && h.hooks.some((i) => i && i.command === hookCommand),
+  );
+  if (alreadyCurrent) {
+    console.log("    PostCompact hook already up to date. Skipping.\n");
     return;
   }
 
+  // Narrow predicate on purpose: this REMOVES entries from the user's settings.json, so it must only
+  // ever match hooks niro generated, never a user hook that happens to mention Niro MCP.
+  const hadStale = settings.hooks.PostCompact.some(isNiroGeneratedPostCompactHook);
+  settings.hooks.PostCompact = settings.hooks.PostCompact.filter((h) => !isNiroGeneratedPostCompactHook(h));
   settings.hooks.PostCompact.push({
     matcher: "",
     hooks: [{ type: "command", command: hookCommand }],
@@ -652,7 +789,7 @@ function addClaudeCodePostCompactHook() {
   try {
     fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
     fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
-    console.log("    PostCompact hook added to ~/.claude/settings.json\n");
+    console.log(`    PostCompact hook ${hadStale ? "upgraded" : "added"} in ~/.claude/settings.json\n`);
   } catch (err) {
     console.warn(`    Could not write ~/.claude/settings.json: ${err.message}`);
     console.warn("    Add manually to the PostCompact array in ~/.claude/settings.json:\n");
@@ -714,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. 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";
@@ -725,7 +862,51 @@ const NIRO_USER_PROMPT_COMMAND =
  * always-on pointer that fixes "Claude forgets Niro mid-session"; the long-form
  * guidance lives in the skill, so this is deliberately terse.
  */
+/**
+ * Openings of every main reminder the UserPromptSubmit hook has ever written, current first. Verified
+ * across every commit that touched the hook (`git log --all -S"UserPromptSubmit" -- src/mcp/setup.js`,
+ * 9 commits): the payload has had exactly these two forms. Long, machine-written sentences on purpose —
+ * they are what makes "niro wrote this" a safe question to answer.
+ */
+const NIRO_USER_PROMPT_GENERATED_MARKERS = [
+  "NIRO ACTIVE. Standing rule for this whole session",
+  "This repo is indexed by Niro. IF the niro MCP tools are present in your current toolset",
+];
+
+/**
+ * Narrow identity for the DESTRUCTIVE half of the UserPromptSubmit upgrade path: did NIRO ITSELF write
+ * this entry?
+ *
+ * isNiroUserPromptHook answers "is a niro hook already here" by looking for `.niro-project`,
+ * `find_reusable_code` or "`niro` skill" anywhere in the command. That is the right question for
+ * detection and the wrong one for deletion: a hook the USER wrote that mentions find_reusable_code (an
+ * ordinary thing to put in your own prompt reminder) matches it, and the filter below would delete it.
+ * This matters now in a way it did not before: the installer only reaches the filter when the reminder
+ * text has CHANGED, so every reword of the reminder runs this delete across every existing user at once.
+ *
+ * Matching a generated payload marker instead recognises both historical niro versions while leaving
+ * anything a human wrote alone. An unknown older variant would be a false negative: a duplicate entry,
+ * noisy and recoverable, and still removed by the broad predicate at uninstall. That asymmetry is the
+ * whole point — a false positive here destroys a user's hook.
+ *
+ * Same failure this repo already reverted a feature over (84e2e7b: "the niro matchers are substring
+ * tests on prose, so a user hook merely mentioning find_reusable_code was captured and overwritten").
+ */
+function isNiroGeneratedUserPromptHook(h) {
+  if (!h || typeof h !== "object") return false;
+  const commands = Array.isArray(h.hooks) ? h.hooks.map((i) => i && i.command) : [h.command];
+  return commands.some(
+    (c) => typeof c === "string" && NIRO_USER_PROMPT_GENERATED_MARKERS.some((marker) => c.includes(marker)),
+  );
+}
+
 function addClaudeCodeUserPromptHook() {
+  // Guard the invariant that keeps upgrade-in-place working: if the reminder is reworded so it no longer
+  // carries a known generated marker, every install would append a fresh entry instead of replacing the
+  // old one. Fail loudly at the boundary rather than quietly stacking hooks in the user's settings.
+  if (!NIRO_USER_PROMPT_GENERATED_MARKERS.some((m) => NIRO_USER_PROMPT_COMMAND.includes(m))) {
+    throw new Error("NIRO_USER_PROMPT_COMMAND must contain a known generated marker, or upgrade-in-place breaks");
+  }
   const settingsPath = path.join(process.env.HOME || "", ".claude", "settings.json");
   const hookCommand = NIRO_USER_PROMPT_COMMAND;
 
@@ -751,8 +932,10 @@ function addClaudeCodeUserPromptHook() {
     return;
   }
 
-  const hadStale = settings.hooks.UserPromptSubmit.some(isNiroUserPromptHook);
-  settings.hooks.UserPromptSubmit = settings.hooks.UserPromptSubmit.filter((h) => !isNiroUserPromptHook(h));
+  // Narrow predicate on purpose: this REMOVES entries from the user's settings.json, so it must only
+  // ever match hooks niro generated, never a user hook that happens to mention find_reusable_code.
+  const hadStale = settings.hooks.UserPromptSubmit.some(isNiroGeneratedUserPromptHook);
+  settings.hooks.UserPromptSubmit = settings.hooks.UserPromptSubmit.filter((h) => !isNiroGeneratedUserPromptHook(h));
   // UserPromptSubmit hooks have no tool matcher — just the hooks array.
   settings.hooks.UserPromptSubmit.push({
     hooks: [{ type: "command", command: hookCommand }],
@@ -989,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
@@ -1016,6 +1358,31 @@ stays the fallback for what Niro does not cover, and when the tools are unavaila
 \`project_id\` auto-resolves from a \`.niro-project\` file at the repo root — omit it. If there
 is no such file, call \`list_projects\` and pass the chosen \`project_id\`.
 
+## Check both directions before you change anything (MUST FOLLOW)
+
+Reading the file you are about to edit tells you what it does, not what it holds up. Before you
+plan, propose, or start any change to existing code, establish both sides:
+
+- **Upstream: what depends on this?** Callers in this service, callers in other services over HTTP
+  or events, and the tests and config that name it. This is what your change can break.
+- **Downstream: what does this depend on?** What it calls, the collections and tables it touches,
+  the events it publishes. This is what constrains the change.
+
+\`get_blast_radius\` answers both sides in ONE call (callers, callees, cross-service callers and
+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
+diff.
+
 ## Availability self-check — read FIRST
 
 Niro is not always applicable. Check these before relying on it, and fall back to native
@@ -1167,6 +1534,10 @@ Also available (catalog / utility, use when the above don't fit): \`list_project
 ## Hard rules
 
 - **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. 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
@@ -1419,6 +1790,17 @@ get_reverse_call_chain, get_blast_radius, get_impact_analysis, get_service_topol
 how the code connects BEFORE deciding which file to read or search next. Native search is the
 fallback for what niro does not cover, and when the tools are unavailable.
 
+MUST FOLLOW (check both directions before changing anything): before you plan, propose or start
+any change to existing code, establish who depends on it (upstream callers, including 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. 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
 native tools silently and do not mention Niro.
@@ -1882,6 +2264,17 @@ something, check whether a niro tool answers it (\`code_grep\`, \`resolve_fqn\`
 \`get_service_topology\`) to see how the code connects BEFORE deciding which file to read or
 search next. Native search is the fallback for what niro does not cover.
 
+MUST FOLLOW (check both directions before changing anything): before you plan, propose or start
+any change to existing code, establish who depends on it (upstream callers, including callers in
+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. 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.
 `;
@@ -1927,6 +2320,17 @@ something, check whether a niro tool answers it (\`code_grep\`, \`resolve_fqn\`
 \`get_service_topology\`) to see how the code connects BEFORE deciding which file to read or
 search next. Native search is the fallback for what niro does not cover.
 
+MUST FOLLOW (check both directions before changing anything): before you plan, propose or start
+any change to existing code, establish who depends on it (upstream callers, including callers in
+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. 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.
 `;
@@ -2385,6 +2789,11 @@ module.exports = {
   isNiroUserPromptHook,
   isNiroPreToolUseHook,
   isNiroExploreHook,
+  isNiroImpactHook,
+  NIRO_IMPACT_COMMAND,
+  setupClaudeCode,
+  planClaudeRegistration,
+  registeredServerUrl,
   isNiroStopHook,
   clearCodexPerToolApprovals,
   hardenCodexServerConfig,
@@ -2394,11 +2803,20 @@ module.exports = {
   NIRO_EXPLORE_COMMAND,
   NIRO_PRETOOL_COMMAND,
   NIRO_USER_PROMPT_COMMAND,
+  NIRO_POST_COMPACT_COMMAND,
+  // Exposed for tests: the stale-hook upgrade path is only observable by running the real installer.
+  addClaudeCodePostCompactHook,
+  isNiroGeneratedPostCompactHook,
+  isNiroGeneratedUserPromptHook,
+  NIRO_USER_PROMPT_GENERATED_MARKERS,
+  addClaudeCodeUserPromptHook,
+  NIRO_POST_COMPACT_PREFIX,
   // Exposed for content regression tests (e.g. the cross-project routing guidance).
   NIRO_SKILL,
   NIRO_CLI_SKILL,
   // Exposed for tests: the explore-first rule must reach EVERY client's always-on instruction surface.
   NIRO_EXPLORE_FIRST_SENTENCE,
+  NIRO_IMPACT_BOTH_WAYS_SENTENCE,
   NIRO_CURSOR_RULE,
   NIRO_CLINE_RULE,
   NIRO_KIRO_STEERING,