@niroai/niro 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -2,6 +2,53 @@
 
 Notable changes to `@niroai/niro`. Dates are release dates.
 
+## Unreleased
+
+## 0.12.0 — 2026-09-06
+
+### Before an edit to indexed source, Claude is asked to map the method and to verify those flows afterwards
+
+Every instruction file niro writes tells the assistant to map who depends on a method before changing
+it. In practice the assistant finds the file, reads it, and edits; the rule is read early in a session
+and forgotten by the middle of it. And the map was always meant for afterwards: the point is to go back
+to the callers and flows once the edit is made and check they still hold.
+
+Claude Code now gets a third niro hook, on Edit and Write. Before an edit to source in an indexed repo
+it puts a short reminder in front of the assistant: decide whether the change can alter behaviour (a log
+line or a comment cannot, say so and go ahead); if it can, map who depends on the method now with
+get_blast_radius or get_impact_analysis and keep that list as the checklist for after the edit; and do
+not re-query the graph to verify, because it updates only after the edit is synced and rebuilt. If an
+impact call already named the file this session, the reminder instead says to go back to that list
+after the edit. Each reminder appears once per file per session. It is advisory: it never approves or
+refuses an edit. The evidence comes from the bridge, which writes one line per answered impact call
+under `~/.niro/impact/`. New files, tests, config and docs are never mentioned. Off switch:
+`touch ~/.niro/impact-gate-off`. `niro mcp uninstall` removes the hook and the evidence files.
+
+The same three points were added to every instruction surface niro writes: the rule sentence in each
+client's always-on file, the niro skill, the Cursor, Cline and Kiro rules, and the PostCompact and
+prompt hooks. The clients without hooks read them there. Details: `docs/usecases/impact-gate.md`.
+
+### `niro mcp install` now refreshes Claude Code hooks on a machine where niro was already set up
+
+Re-running the install on a machine with an existing registration failed at the first step, because
+`claude mcp add` refuses a name that already exists, and the installer read that refusal as "Claude
+Code is not installed" and stopped before writing any hook or the CLAUDE.md section. So the step the
+out-of-date notice asks for did nothing for anyone who had installed once. The installer now reads the
+existing registration first: same URL, it keeps it; a different `--url`, it replaces it; none, it adds
+it. Hooks and sections are written in every case.
+
+### CommonJS and ES-module files (.cjs, .mjs, .cts, .mts) are now uploaded for indexing
+
+When niro decided which files to upload for indexing, it skipped `.cjs`, `.mjs`, `.cts` and `.mts`,
+so a `build.cjs` or an `index.mjs` was never indexed and never appeared in the graph. Those four
+extensions are now included, matching the server's own file filter.
+
+### The niro rules now name get_exception_flow
+
+The explore-first rule niro writes into each client now mentions `get_exception_flow`, the tool that
+reports which exceptions can escape a method (and who must handle one). It is served by the niro
+backend; this only makes the assistants aware it exists.
+
 ## 0.11.0 — 2026-09-03
 
 ### The watcher stops pausing and resuming your uploads over and over

package/README.md

@@ -45,7 +45,9 @@ Then restart your assistant and ask it something:
 ```bash
 niro status
 ```
-Is my index up to date?
+Is my index up to date? It answers about the project this folder is synced to **on the branch you
+are on**, so once you have run `niro new-temp-project` it reports that copy rather than the shared
+project. Name one explicitly to ask about a different project: `niro status <project-id>`.
 
 ```bash
 niro start
@@ -65,7 +67,9 @@ Every project in your account.
 ```bash
 niro build
 ```
-Rebuild the index by hand and watch it finish.
+Rebuild the index by hand and watch it finish. Like `niro status`, it picks the project for the
+branch you are on, so on a branch with a temporary project it rebuilds that one. Name a project to
+rebuild a different one.
 
 ```bash
 niro doctor
@@ -224,7 +228,10 @@ Detach a repo from a project. Nothing is deleted.
 ```bash
 niro remove --project --confirm-name <name>
 ```
-Delete a whole project. Destructive, hence the confirmation.
+Delete a whole project. Destructive, hence the confirmation. It refuses on a temporary project and
+sends you to `niro discard-temp-project` instead, because that removes the copy **and** points this
+folder back at the shared project; deleting it here would leave the folder aimed at a project that
+no longer exists. `niro delete` refuses for the same reason.
 
 ---
 

package/docs/working-on-branches.md

@@ -46,6 +46,14 @@ It creates your own private copy of the project inside Niro.
 
 From then on, answers come from YOUR code.
 
+The commands follow too. `niro status` and `niro build` act on the copy for the branch you are on,
+not on the shared project, so "is my index up to date" and "rebuild it" mean what you expect while
+you are working on a branch. Name a project explicitly if you want a different one.
+
+`niro delete` and `niro remove --project` will not delete a private copy. They send you to
+`niro discard-temp-project`, which removes the copy AND points your folder back at the shared
+project. Deleting it any other way leaves your folder aimed at something that is gone.
+
 ## Switching branches
 
 Nothing to do. Niro checks which branch you are on for every question.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@niroai/niro",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Niro — one package: the niro CLI plus the Niro MCP server (code intelligence for AI coding assistants).",
   "keywords": [
     "niro",

package/src/commands/_resolveProject.js

@@ -7,11 +7,16 @@
  *        - an alias or git URL        -> resolved via GET /api/projects/resolve.
  *      If an alias/URL maps to MULTIPLE projects, a clear ambiguity error is
  *      thrown listing the candidates (we never silently pick the first).
- *   2. Walk up from cwd looking for .niro-project (same logic the MCP bridge uses).
+ *   2. The project THIS FOLDER IS CURRENTLY SYNCED TO, when it was recorded for the
+ *      branch that is checked out. See resolveFromSyncedFolder for why this comes
+ *      before the pin.
+ *   3. Walk up from cwd looking for .niro-project (same logic the MCP bridge uses).
  */
 const api = require("../lib/api");
 const prompt = require("../lib/prompt");
 const niroProjectFile = require("../lib/niroProjectFile");
+const git = require("../lib/git");
+const watchState = require("../lib/watchState");
 const { normalizeProjects, resolveContext } = require("../lib/resolveContext");
 
 // A canonical project_id is a UUID. Anything that doesn't look like one and
@@ -119,6 +124,36 @@ async function resolveProjectFromGit(opts = {}) {
   throw e;
 }
 
+/**
+ * The project this folder is actually synced to right now, when the recorded branch is the
+ * one checked out. Null when nothing is recorded, when the branch has moved on, or on any error.
+ *
+ * <p>Why this has to come BEFORE the .niro-project pin. The pin holds the SHARED project's id and
+ * never changes. When a developer runs `niro new-temp-project`, the folder starts syncing to a
+ * private temporary project that indexes their branch, and only ~/.niro/projects.json records it.
+ * Reading the pin therefore answers about a project the developer is not working in. Measured on
+ * 2026-09-08: in a repo on branch feat/shipping-wrap-rethrow, `niro status` reported the shared
+ * project with "Updated 2026-09-06T09:28", two days stale, while the branch's own project had
+ * finished a build four minutes earlier. `niro build` had the same fault and would have rebuilt the
+ * shared project.
+ *
+ * <p>The branch comparison is the safety catch. An entry recorded on another branch must not
+ * redirect the command, so a mismatch falls through to the pin, which is the old behaviour.
+ */
+function resolveFromSyncedFolder(opts = {}) {
+  try {
+    const ctx = git.inspect(process.cwd());
+    if (!ctx || !ctx.repoRoot) return null;
+    const entry = watchState.get(ctx.repoRoot, opts.apiUrl || api.currentBaseUrl());
+    if (!entry || !entry.projectId) return null;
+    if (entry.branch && ctx.branch && entry.branch !== ctx.branch) return null;
+    return entry.projectId;
+  } catch (_) {
+    // Never block a command on this: falling through to the pin is the previous behaviour.
+    return null;
+  }
+}
+
 async function resolveProjectId(explicit, opts = {}) {
   if (explicit) {
     // A UUID is used directly — unchanged behavior. Anything else is an
@@ -126,7 +161,10 @@ async function resolveProjectId(explicit, opts = {}) {
     if (looksLikeProjectId(explicit)) return explicit;
     return resolveAliasOrUrl(explicit, opts);
   }
-  // No explicit arg: prefer a .niro-project pin (walk up from cwd).
+  // No explicit arg: the project this folder is synced to on THIS branch wins over the pin.
+  const fromFolder = resolveFromSyncedFolder(opts);
+  if (fromFolder) return fromFolder;
+  // Then a .niro-project pin (walk up from cwd).
   const fromFile = readNiroProjectFile(process.cwd());
   if (fromFile) {
     // A pin that is already a project_id is used directly. A pin holding an
@@ -139,4 +177,22 @@ async function resolveProjectId(explicit, opts = {}) {
   return resolveProjectFromGit(opts);
 }
 
-module.exports = { resolveProjectId, readNiroProjectFile, resolveAliasOrUrl, looksLikeProjectId };
+/**
+ * The temporary project this id names, or null when it is an ordinary shared project.
+ *
+ * <p>Used by the destructive commands. Deleting a temporary project through `niro delete` leaves
+ * the folder pinned to a project that is gone and skips the local cleanup that
+ * `niro discard-temp-project` does, so those commands send the developer there instead.
+ * Never throws: if the project cannot be fetched, the caller carries on as before.
+ */
+async function tempProjectSourceId(projectId, opts = {}) {
+  try {
+    const project = await api.get(`/api/projects/${encodeURIComponent(projectId)}`, { apiUrl: opts.apiUrl });
+    return (project && (project.cloneOfProjectId || project.clone_of_project_id)) || null;
+  } catch (_) {
+    return null;
+  }
+}
+
+module.exports = { resolveProjectId, readNiroProjectFile, resolveAliasOrUrl, looksLikeProjectId,
+  resolveFromSyncedFolder, tempProjectSourceId };

package/src/commands/delete.js

@@ -14,12 +14,27 @@ const api = require("../lib/api");
 const credentials = require("../lib/credentials");
 const prompt = require("../lib/prompt");
 const color = require("../lib/color");
-const { resolveProjectId, readNiroProjectFile } = require("./_resolveProject");
+const { resolveProjectId, readNiroProjectFile, tempProjectSourceId } = require("./_resolveProject");
 
 async function deleteProject(projectIdArg, opts = {}) {
   credentials.requireCreds();
   const projectId = await resolveProjectId(projectIdArg, { apiUrl: opts.apiUrl });
 
+  // A temporary project is not deleted through here. It belongs to a folder and a branch, and
+  // `discard-temp-project` is what unwinds both: it removes the project AND points the folder back
+  // at the shared one, repairing the local pin. Deleting it server-side does neither, so the folder
+  // is left aimed at a project that no longer exists. Refusing costs one command; the alternative is
+  // a broken checkout the developer then has to work out how to repair.
+  const cloneOf = await tempProjectSourceId(projectId, opts);
+  if (cloneOf) {
+    console.log(`${color.yellow("⚠")}  ${color.bold(projectId)} is a temporary project for your branch, not a shared one.`);
+    console.log(color.dim(`    It is a private copy of ${cloneOf}.`));
+    console.log(`    Use ${color.bold("niro discard-temp-project")} in this folder instead — that removes it AND`);
+    console.log(`    points this folder back at the shared project. ${color.dim("Nothing has been deleted.")}`);
+    process.exitCode = 1;
+    return;
+  }
+
   if (!opts.yes) {
     console.log(`${color.yellow("⚠")}  About to delete project ${color.bold(projectId)}.`);
     console.log(color.dim("    This removes the project and its graph from the server. Registered repos stay."));

package/src/commands/remove.js

@@ -57,14 +57,27 @@ async function remove(opts = {}) {
   // --project: destructive. Fetch the project so we can match --confirm-name
   // against either the alias or the project_id.
   let alias = null;
+  let cloneOf = null;
   try {
     const project = await api.get(`/api/projects/${encodeURIComponent(projectId)}`, { apiUrl: opts.apiUrl });
     alias = (project && (project.alias)) || null;
+    cloneOf = (project && (project.cloneOfProjectId || project.clone_of_project_id)) || null;
   } catch (err) {
     // If we can't read the project, fall back to matching the id only.
     alias = null;
   }
 
+  // Same rule as `niro delete`: a temporary project is unwound by discard-temp-project, which also
+  // points this folder back at the shared project. Removing it here would leave the folder aimed at
+  // a project that is gone. Read from the fetch above rather than a second request.
+  if (cloneOf) {
+    console.log(`${color.yellow("⚠")}  ${color.bold(projectId)} is a temporary project for your branch, not a shared one.`);
+    console.log(color.dim(`    It is a private copy of ${cloneOf}.`));
+    console.log(`    Use ${color.bold("niro discard-temp-project")} in this folder instead. ${color.dim("Nothing has been removed.")}`);
+    process.exitCode = 1;
+    return;
+  }
+
   const confirm = opts.confirmName == null ? null : String(opts.confirmName).trim();
   const matches = confirm != null && (confirm === projectId || (alias != null && confirm === alias));
   if (!matches) {

package/src/lib/folderSync.js

@@ -36,6 +36,7 @@ const color = require("./color");
 const BATCH_SIZE = 50;
 const SOURCE_EXTENSIONS = new Set([
   ".java", ".py", ".go", ".js", ".ts", ".tsx", ".jsx",
+  ".cjs", ".mjs", ".cts", ".mts",
   ".kt", ".scala", ".rs", ".rb", ".php", ".cs", ".swift",
   ".c", ".cpp", ".h", ".hpp", ".dart",
 ]);

package/src/lib/impactLog.js

@@ -0,0 +1,251 @@
+/**
+ * Record of the impact checks an agent made through the bridge, read by the Edit|Write impact gate.
+ *
+ * Why this exists: CLAUDE.md, the niro skill and the UserPromptSubmit hook all tell the agent to map
+ * who depends on code before changing it (get_blast_radius, get_impact_analysis). Prose decays over a
+ * session: the agent obeys early, then reads a method with sed and edits it. Niraj, 2026-09-04: "I
+ * always felt that before you make any code changes in any method you would want to check what's
+ * the impact of that but you hardly ever care to check." The only thing that survives a long session
+ * is a check at the moment of the edit. The PreToolUse hook in setup.js (NIRO_IMPACT_COMMAND) is that
+ * check, and it needs evidence of what the agent actually called. The bridge sees every tools/call and
+ * every answer, so it keeps that evidence here.
+ *
+ * What is written: one JSON line per answered impact call under ~/.niro/impact/<key>.jsonl, where
+ * <key> is the bridge's working directory, symlinks resolved, with every byte that is not an ASCII
+ * letter or digit replaced by "-". The hook derives the same key from the payload's cwd with
+ * `cd -P` and `tr -c 'A-Za-z0-9' '-'`, so the two sides agree without sharing code (tested in
+ * test/impactGateHook.test.js). A line carries the tool name, the names the agent asked about
+ * (method_fqn, class_fqn and friends) and every source path the answer mentioned. Lines older than
+ * WINDOW_MS are pruned on every write, so the file cannot grow past one hour of checks.
+ *
+ * Liveness: <key>.alive is touched whenever the server answers. The hook denies an unchecked edit only
+ * while that file is fresh; with the bridge gone it can only advise, so Niro being unreachable never
+ * blocks an edit. Fail-open by design.
+ *
+ * Every function here swallows filesystem errors: this sits on the message path between the host and
+ * the server, and a full disk or an unwritable home must cost the gate and nothing else.
+ */
+const fs = require("fs");
+const path = require("path");
+const { niroHome } = require("./receiptStore");
+
+/** The calls that count as "checked who depends on it". Downstream-only walks (get_call_chain) do not. */
+const IMPACT_TOOLS = new Set(["get_blast_radius", "get_impact_analysis", "get_reverse_call_chain"]);
+/** How long a recorded check keeps a file unlocked. */
+const WINDOW_MS = 60 * 60 * 1000;
+const MAX_LINES = 500;
+const MAX_NAMES = 50;
+const MAX_FILES = 200;
+const MAX_IN_FLIGHT = 100;
+/** The alive file is rewritten at most this often; answers arrive far more frequently than that. */
+const ALIVE_TOUCH_MIN_MS = 10 * 1000;
+/** Argument names across the impact tools that carry what the agent asked about. */
+const NAME_ARGS = [
+  "method_fqn", "method_fqns", "class_fqn", "entity_fqn", "entity_fqns", "fqn", "fqns", "targets",
+  "http_path", "event_fqn",
+];
+const SOURCE_EXT = "java|js|mjs|cjs|ts|tsx|jsx|py|go|rb|kt|kts|cs|php|rs|scala|swift|c|cc|cpp|h|hpp";
+/**
+ * A source path inside an answer: optional leading "/", slash-separated segments, a known extension,
+ * bounded by whitespace, quotes, brackets, ":" or ",". The ":" lets `repo::src/a/B.java` yield the
+ * repo-relative path, which is what the hook compares against the edited file's path.
+ */
+const PATH_RE = new RegExp(
+  "(?:^|[\\s\"'(:,])(/?(?:[A-Za-z0-9_.\\-]+/)*[A-Za-z0-9_.\\-]+\\.(?:" + SOURCE_EXT + "))(?=$|[\\s\"'),:])",
+  "g",
+);
+
+function impactDir() {
+  return path.join(niroHome(), "impact");
+}
+
+/** Presence of this file switches the gate off for every session on this machine. */
+function offSwitchPath() {
+  return path.join(niroHome(), "impact-gate-off");
+}
+
+/**
+ * The per-folder key, byte for byte what `printf '%s' "$(cd -P dir && pwd -P)" | tr -c 'A-Za-z0-9' '-'`
+ * produces. Byte-based on purpose: tr works on bytes, so a non-ASCII character becomes several dashes
+ * there and must here too, or the hook looks for a file the bridge never wrote.
+ */
+function keyForCwd(cwd) {
+  let real = String(cwd || "");
+  try {
+    real = fs.realpathSync(real);
+  } catch (_) {
+    /* a folder that does not exist keeps its lexical path, as the hook's `cd -P || printf` fallback does */
+  }
+  let out = "";
+  for (const b of Buffer.from(real, "utf8")) {
+    const alnum = (b >= 48 && b <= 57) || (b >= 65 && b <= 90) || (b >= 97 && b <= 122);
+    out += alnum ? String.fromCharCode(b) : "-";
+  }
+  return out;
+}
+
+function logPathFor(cwd) {
+  return path.join(impactDir(), keyForCwd(cwd) + ".jsonl");
+}
+
+function alivePathFor(cwd) {
+  return path.join(impactDir(), keyForCwd(cwd) + ".alive");
+}
+
+function toolNameOf(message) {
+  if (!message || message.method !== "tools/call" || !message.params) return null;
+  return typeof message.params.name === "string" ? message.params.name : null;
+}
+
+function isImpactCall(message) {
+  const name = toolNameOf(message);
+  return !!name && IMPACT_TOOLS.has(name);
+}
+
+/** The strings the agent asked about, deduplicated and bounded; routing extras like _niroPin are ignored. */
+function namesFromArgs(args) {
+  const out = [];
+  const push = (v) => {
+    if (typeof v !== "string") return;
+    const s = v.trim().slice(0, 300);
+    if (s && !out.includes(s)) out.push(s);
+  };
+  if (args && typeof args === "object") {
+    for (const key of NAME_ARGS) {
+      const v = args[key];
+      if (Array.isArray(v)) v.forEach(push);
+      else push(v);
+    }
+  }
+  return out.slice(0, MAX_NAMES);
+}
+
+/** All text parts of a tool result, joined; "" for anything that is not a text result. */
+function resultText(msg) {
+  const content = msg && msg.result && msg.result.content;
+  if (!Array.isArray(content)) return "";
+  return content.map((c) => (c && typeof c.text === "string" ? c.text : "")).join("\n");
+}
+
+/** Every distinct source path an answer mentions, in order of appearance, bounded. */
+function filesFromResultText(text) {
+  const out = [];
+  if (typeof text !== "string" || !text) return out;
+  PATH_RE.lastIndex = 0;
+  let m;
+  while ((m = PATH_RE.exec(text)) && out.length < MAX_FILES) {
+    if (!out.includes(m[1])) out.push(m[1]);
+  }
+  return out;
+}
+
+/** Drop lines older than the window, then cap the count; the newest lines win. */
+function pruneLines(lines, now) {
+  const cutoff = now - WINDOW_MS;
+  const kept = lines.filter((line) => {
+    const m = /"ts":(\d+)/.exec(line);
+    return !!m && Number(m[1]) >= cutoff;
+  });
+  return kept.length > MAX_LINES ? kept.slice(kept.length - MAX_LINES) : kept;
+}
+
+/** Append one record, pruning first. Returns false, never throws, when the file cannot be written. */
+function appendRecord(file, record, now) {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    let lines = [];
+    try {
+      lines = fs.readFileSync(file, "utf8").split("\n").filter(Boolean);
+    } catch (_) {
+      /* first record for this folder */
+    }
+    lines = pruneLines(lines, now);
+    lines.push(JSON.stringify(record));
+    fs.writeFileSync(file, lines.join("\n") + "\n", { mode: 0o600 });
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * One recorder per bridge process. `noteRequest` on every outgoing message, `noteResult` and
+ * `touchAlive` on every incoming one; each returns true only when it wrote something, which the
+ * tests use and the bridge ignores.
+ */
+function createImpactRecorder({ cwd = process.cwd(), now = Date.now } = {}) {
+  const inFlight = new Map();
+  let lastAlive = 0;
+  return {
+    noteRequest(message) {
+      if (!isImpactCall(message) || message.id === undefined || message.id === null) return false;
+      const args = message.params.arguments || {};
+      inFlight.set(message.id, { tool: message.params.name, names: namesFromArgs(args), ts: now() });
+      if (inFlight.size > MAX_IN_FLIGHT) inFlight.delete(inFlight.keys().next().value);
+      return true;
+    },
+    noteResult(msg) {
+      if (!msg || msg.id === undefined || msg.id === null) return false;
+      const meta = inFlight.get(msg.id);
+      if (!meta) return false;
+      inFlight.delete(msg.id);
+      // An error answer is still recorded: the agent asked, which is the behaviour the gate exists to
+      // produce, and a name the server could not resolve must not leave the file locked.
+      const files = filesFromResultText(resultText(msg));
+      return appendRecord(logPathFor(cwd), { ts: meta.ts, tool: meta.tool, names: meta.names, files }, now());
+    },
+    clearAlive() {
+      try {
+        fs.rmSync(alivePathFor(cwd), { force: true });
+        return true;
+      } catch (_) {
+        return false;
+      }
+    },
+    touchAlive() {
+      const t = now();
+      if (t - lastAlive < ALIVE_TOUCH_MIN_MS) return false;
+      lastAlive = t;
+      try {
+        fs.mkdirSync(impactDir(), { recursive: true, mode: 0o700 });
+        fs.writeFileSync(alivePathFor(cwd), String(t), { mode: 0o600 });
+        return true;
+      } catch (_) {
+        return false;
+      }
+    },
+  };
+}
+
+/** Remove the evidence files and the off switch. Used by `niro mcp uninstall`. Best effort. */
+function purge() {
+  try {
+    fs.rmSync(impactDir(), { recursive: true, force: true });
+  } catch (_) {
+    /* best effort */
+  }
+  try {
+    fs.rmSync(offSwitchPath(), { force: true });
+  } catch (_) {
+    /* best effort */
+  }
+}
+
+module.exports = {
+  purge,
+  IMPACT_TOOLS,
+  WINDOW_MS,
+  MAX_LINES,
+  keyForCwd,
+  impactDir,
+  offSwitchPath,
+  logPathFor,
+  alivePathFor,
+  isImpactCall,
+  namesFromArgs,
+  resultText,
+  filesFromResultText,
+  pruneLines,
+  appendRecord,
+  createImpactRecorder,
+};

package/src/lib/receiptStore.js

@@ -82,4 +82,4 @@ function purge() {
   }
 }
 
-module.exports = { disabledFlagPath, isDisabled, setDisabled, purge };
+module.exports = { niroHome, disabledFlagPath, isDisabled, setDisabled, purge };

package/src/mcp/server.js

@@ -52,6 +52,12 @@ function niroProjectsFilePath() {
   return path.join(home, ".niro", "projects.json");
 }
 const { createPendingTracker, isTrackableRequest, resolveTimeoutMs } = require("../lib/pendingRequests");
+const { createImpactRecorder } = require("../lib/impactLog");
+
+// Evidence for the Edit|Write impact gate (docs/usecases/impact-gate.md): which impact tools this
+// session called, and that the server is answering. Keyed by this process's working directory, which
+// is the session folder the hook sees as `cwd` (checked on 8 live bridges, 2026-09-04).
+const impact = createImpactRecorder({ cwd: process.cwd() });
 
 /**
  * This package's version, sent as X-Niro-Cli-Version so the server can tell an out-of-date install to
@@ -150,17 +156,26 @@ function resolveProjectIdFromNiroProjects() {
 }
 
 /**
- * Step 3: Detect the git remote URL and current branch for server-side project resolution.
- * Used when no project_id could be resolved locally. The server matches the remote URL
- * against stored project git mappings.
- * Returns { remote, branch } or null if not in a git repo or git is unavailable.
+ * Step 3: Detect the current git branch, HEAD and dirty state — plus the origin remote when there is
+ * one — for the freshness/takeover notices, server-side project resolution, and per-branch temp routing.
+ * The gate is HEAD (is this a git repo with a commit?), NOT origin: a local repo with commits but no
+ * origin remote (a `local://` niro project, or a repo not yet pushed) still has a branch that drives
+ * routing, so its git state must be reported with a null remote rather than dropped entirely.
+ * Returns { remote (nullable), branch, commit, dirty } or null if not a git repo / no commit / git unavailable.
  */
 function detectGitContext(dir) {
   try {
     const opts = { encoding: "utf8", timeout: 3000, stdio: ["ignore", "pipe", "ignore"] };
     if (dir) opts.cwd = dir;
-    const remote = execSync("git remote get-url origin 2>/dev/null", opts).trim();
-    if (!remote) return null;
+    // HEAD first: this is the "real git repo with a commit?" test. The old `if (!remote) return null`
+    // bailed on a MISSING ORIGIN and so discarded the branch + commit of every no-origin repo — those
+    // repos then sent no _niroGit and never routed to their temp project. The owned-temp match needs
+    // only the branch, not the remote, so keep going and let the remote be null.
+    let commit = null;
+    try { commit = execSync("git rev-parse HEAD 2>/dev/null", opts).trim(); } catch (_) {}
+    if (!commit) return null; // not a git repo, or a repo with no commit yet — nothing to report
+    let remote = null;
+    try { remote = execSync("git remote get-url origin 2>/dev/null", opts).trim() || null; } catch (_) {}
     // normalizeBranch, not a bare trim: on a detached HEAD this command PRINTS "HEAD" instead of
     // failing, and sending that verbatim told the server the checkout was on a branch called "HEAD".
     // Nothing indexes such a branch, so the routing ladder read every bisect / tag checkout as
@@ -168,10 +183,6 @@ function detectGitContext(dir) {
     // a null branch. `git.inspect` has always collapsed "HEAD" to null; this shares that one rule.
     let branch = null;
     try { branch = normalizeBranch(execSync("git rev-parse --abbrev-ref HEAD 2>/dev/null", opts)); } catch (_) {}
-    // The freshness/takeover notices compare the local HEAD + dirty state against what Niro indexed, so
-    // the bridge must report them — without git_commit the server-side check no-ops entirely.
-    let commit = null;
-    try { commit = execSync("git rev-parse HEAD 2>/dev/null", opts).trim(); } catch (_) {}
     let dirty = false;
     try { dirty = execSync("git status --porcelain 2>/dev/null", opts).trim().length > 0; } catch (_) {}
     return { remote, branch, commit, dirty };
@@ -535,6 +546,8 @@ function connectSse() {
               } else {
                 // Cancel the client-side deadline when a delivered result matches an in-flight request.
                 pending.onIncoming(msg);
+                impact.noteResult(msg);
+                impact.touchAlive();
                 rewritten = captureReceipt(msg);
               }
             } catch (_) { /* not correlatable JSON — forward unchanged */ }
@@ -827,6 +840,7 @@ async function main() {
     // Remember the host's initialize so we can replay it verbatim to re-authenticate a fresh
     // session after a transparent reconnect.
     if (message.method === "initialize") initializeRaw = line;
+    impact.noteRequest(message);
 
     // Arm the deadline for a real request before sending; a delivered result (or the
     // send-failure path below) cancels it.
@@ -836,6 +850,9 @@ async function main() {
       await sendMessage(message);
     } catch (err) {
       process.stderr.write(`[niro-mcp] Failed to send message: ${err.message}\n`);
+      // The attempt still counts for the impact gate: a server that cannot be reached must not leave
+      // the file locked until the alive marker ages out (review finding, 2026-09-05).
+      impact.noteResult({ jsonrpc: "2.0", id: message.id, error: { code: -32001, message: err.message } });
       // The POST never reached the server, so no result will arrive: fail this request fast
       // instead of waiting out the deadline.
       if (trackable) {
@@ -852,6 +869,9 @@ async function main() {
   rl.on("close", () => {
     process.exit(0);
   });
+  // A bridge that is gone must not keep the impact gate denying edits for up to 30 minutes on the
+  // strength of a stale alive marker. A hard kill still leaves it; the hook ages it out.
+  process.on("exit", () => impact.clearAlive());
 }
 
 main();

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.
@@ -2541,6 +2789,11 @@ module.exports = {
   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 */
   }