@niroai/niro 0.3.6 → 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,109 @@
+# Changelog
+
+Notable changes to `@niroai/niro`. Dates are release dates.
+
+## Unreleased
+
+### Upgrading from 0.3.x — one manual step
+
+```bash
+npm install -g @niroai/niro@latest
+niro mcp install            # once per assistant you use
+```
+
+**The second command is required.** niro's hooks and instruction files are written to your disk at
+install time, so upgrading the package alone leaves the old versions in place — including the
+once-per-session reminder this release fixes. Restart your assistant afterwards; hooks are read at
+startup.
+
+Nothing else is required.
+
+### Added
+
+- **You can now see what Niro did, without asking.** At the end of a task you get one line:
+
+  ```
+  [NIRO] Mapped 29 callers across 8 files that a grep would have missed · 3 calls instead of ~14 searches
+  ```
+
+  The call count is measured by the server. The number of searches it stands in for, and the
+  description, are the assistant's own account of its own work, so that number always carries a `~`
+  to mark it as an estimate. We would rather you trusted a smaller number than doubted a bigger one.
+
+  On a turn where Niro found nothing useful, the description is dropped rather than invented, and
+  you see the bare call count.
+
+- **It also tells you when Niro went unused.** On a turn where the assistant searched your code
+  without asking Niro, you get `[NIRO] Not consulted: this turn used grep and file reads instead`.
+  Until now a skipped turn looked exactly like Niro not being installed, which meant every one of
+  our failures was invisible. Nothing is printed after a turn that did no code work.
+
+- **On by default, including on upgrade.** Turn it off with `niro mcp receipt --off` and back on
+  with `--on`; run it with no flags to see the current state. The setting is per machine.
+
+  Works the same in all twelve supported assistants: the line travels back inside the
+  `mark_task_complete` tool result and your assistant prints it, wrapped in backticks so it renders
+  as code rather than as more of its own prose. If the assistant never calls `mark_task_complete`,
+  no line appears.
+
+### Fixed
+
+- **Codex no longer asks permission for every Niro tool call.** Two causes, both fixed by re-running
+  `niro mcp install`:
+
+  The approval mode was set to `"auto"`, which asks Codex to decide for itself — and it decides to
+  ask. It is now `"writes"`: prompt only for tools that write, and Niro writes nothing. An existing
+  `"auto"` is migrated; a value you chose yourself is left alone.
+
+  Codex also records a per-tool override whenever you answer a prompt with "approve once" rather than
+  "always allow", and a per-tool setting beats the default. Those are now cleared on install.
+
+- **A malformed tool response when a reply contained a backslash, tab or quote.** The
+  `mark_task_complete` response was assembled by a hand-written JSON builder that escaped only the
+  double quote. That was survivable while every value was a fixed keyword, but any free text
+  containing a Windows path or a tab produced JSON the client could not parse, losing the whole
+  response. All control characters are now escaped.
+
+- **The reminder to prefer niro's tools no longer goes quiet mid-session.** Claude Code's
+  `Grep|Glob|Read` hook deduplicated to once per session, per repo, per branch — so it fired early
+  in a session and then said nothing, which is precisely when an agent drifts back to `grep`. It now
+  fires on every native search.
+- **The same reminder was permanently silent in some folders.** It resolved the repo with
+  `git rev-parse --show-toplevel` and gave up when that was empty, so a folder tracked by niro but
+  not a git checkout never got a reminder at all. It now walks up for the `.niro-project` marker
+  directly, and resolves symlinks, so a path reached through a symlinked directory works too.
+- **The reminder's wording let the agent excuse itself.** It offered an "out of scope" escape hatch,
+  which is the exit drift actually takes. Removed; the legitimate native-tool cases (config, docs,
+  logs, generated files) are now named explicitly instead.
+- **A typed project name is now treated as an account-scoped alias.** It was sent as `project_id` and
+  checked with a global lookup, so a name already used by an unrelated account read as taken — or
+  returned a 403 — for a name that was genuinely free for you. The server now assigns the opaque id,
+  and availability is checked against your own account.
+- **`niro init` no longer records a broken project pin.** If the create response carried no
+  `project_id`, the literal text `undefined` was written into `.niro-project` while init reported
+  success; every later tool call then failed with `Project 'undefined' not found`. It now fails
+  loudly at that boundary and pins nothing.
+
+### Added
+
+- The bridge now reports its version and identifies itself (`X-Niro-Cli-Version`,
+  `X-Niro-Bridge`) so the server can tell an out-of-date install to upgrade. The notice is off until
+  a server is deployed with `niro.mcp.cli.min-version` set.
+
+### Not shipped
+
+Two features were built during this cycle and pulled before release. Both are recorded here so the
+reasoning is in the repo rather than only in commit messages.
+
+- **A serve-time self-heal** that would have refreshed stale hooks automatically. Three independent
+  reviews found it deleting users' own settings, widening file permissions on a file that can hold
+  API keys, replacing symlinked configs with regular files, and — with `HOME` unset, the normal case
+  on Windows — writing into the current project folder instead of the home directory. Refreshing
+  hooks stays a manual `niro mcp install`.
+- **A per-prompt reminder hook for Codex.** Codex does support hooks, and the approach works, but
+  installing one means editing `~/.codex/config.toml` — the same file that holds
+  `[mcp_servers.niro]`, so a malformed edit makes Codex reject the whole file and takes niro's
+  registration down with it. Three review rounds found successive defects in that editing, including
+  an uninstall that could delete a hook of the user's own and leave a config Codex would not load.
+  Held back rather than shipped on a fourth attempt; the risk sat entirely in the config surgery,
+  not in the idea.

package/docs/connect-your-ai-assistant.md

@@ -54,6 +54,10 @@ the shared `niro-skill` + `niro-cli` skill to `~/.agents/skills/` (also read by
 
 Verify: `/mcp` inside the Codex TUI.
 
+Note that `AGENTS.md` is read once at the start of a session, so on a long task the reminder to
+prefer niro's tools carries less weight than it does in Claude Code, where a per-tool-call hook
+reinforces it. A per-prompt hook for Codex is in progress.
+
 ## Cursor
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@niroai/niro",
-  "version": "0.3.6",
+  "version": "0.5.0",
   "description": "Niro — one package: the niro CLI plus the Niro MCP server (code intelligence for AI coding assistants).",
   "keywords": [
     "niro",
@@ -27,7 +27,8 @@
     "bin",
     "src",
     "docs/*.md",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=18"

package/src/commands/add-project.js

@@ -11,6 +11,7 @@ const prompt = require("../lib/prompt");
 const color = require("../lib/color");
 const watchState = require("../lib/watchState");
 const niroProjectFile = require("../lib/niroProjectFile");
+const { normalizeProjects, projectIdFromCreateResponse } = require("../lib/resolveContext");
 const { login } = require("./login");
 const { watchStatus } = require("./build");
 
@@ -108,14 +109,17 @@ async function addProject(opts = {}) {
        deriveNameFromUrl(selectedRepos[0].repository_url || selectedRepos[0].repositoryUrl))
     : "my-project";
 
-  let projectId;
+  // The typed name is an ALIAS (account-scoped; duplicates across accounts are
+  // allowed by design) — never the opaque project_id, which the server assigns
+  // on create below.
+  let alias;
   while (true) {
     const candidate = await prompt.ask("  Project name", defaultName);
     if (!candidate) { console.error(color.red("Project name is required.")); return; }
-    if (await projectNameTaken(candidate)) {
+    if (await aliasTaken(candidate, opts)) {
       console.log(color.yellow(`  "${candidate}" already exists — pick another.`));
     } else {
-      projectId = candidate;
+      alias = candidate;
       break;
     }
   }
@@ -126,11 +130,14 @@ async function addProject(opts = {}) {
     gitIdToMapping[repo.id || repo.gitId] = {};
   }
 
-  console.log(`\n  Creating project "${color.bold(projectId)}"...`);
+  console.log(`\n  Creating project "${color.bold(alias)}"...`);
   const project = await api.post("/api/projects", {
-    project_id: projectId,
+    alias,
     git_id_to_mapping: gitIdToMapping,
   });
+  // Throws rather than proceeding with a falsy id — see projectIdFromCreateResponse. Below, this is
+  // written into watchState and the .niro-project pin for every selected repo.
+  const projectId = projectIdFromCreateResponse(project);
 
   // Update local state with projectId for each local repo
   for (const repo of selectedRepos) {
@@ -141,7 +148,7 @@ async function addProject(opts = {}) {
     }
   }
 
-  console.log(`  ${color.green("✓")} Project created: ${color.bold(projectId)}`);
+  console.log(`  ${color.green("✓")} Project created: ${color.bold(alias)}`);
 
   const shouldBuild = await prompt.confirm("  Trigger a full index build now?", true);
   if (shouldBuild) {
@@ -161,16 +168,17 @@ async function addProject(opts = {}) {
   console.log(`\n${color.green("✓ Done.")} Run ${color.cyan("niro mcp install")} to configure Claude Code / Cursor / Windsurf.`);
 }
 
-async function projectNameTaken(projectId) {
-  try {
-    await api.get(`/api/projects/${encodeURIComponent(projectId)}`);
-    return true;
-  } catch (err) {
-    const body = err && err.body;
-    const msg = (body && (body.error || body.message)) || err.message || "";
-    if (/not found/i.test(String(msg))) return false;
-    throw err;
-  }
+/**
+ * True when the alias is already used on this account. Checked BEFORE anything is created, so a
+ * collision does not leave a half-registered repo behind.
+ *
+ * `apiUrl` is threaded through to match init.js's copy. It is largely inert today (this command reaches
+ * the API through credentials written by login), but the two had diverged, which invites the next edit to
+ * fix one and miss the other.
+ */
+async function aliasTaken(alias, opts = {}) {
+  const data = await api.get("/api/projects/resolve", { query: { alias }, apiUrl: opts.apiUrl });
+  return normalizeProjects(data).length > 0;
 }
 
 function deriveNameFromUrl(url) {

package/src/commands/init.js

@@ -30,7 +30,7 @@ const fs = require("fs");
 const api = require("../lib/api");
 const agentApi = require("../lib/agentApi");
 const watchState = require("../lib/watchState");
-const { resolveContext } = require("../lib/resolveContext");
+const { resolveContext, normalizeProjects, projectIdFromCreateResponse } = require("../lib/resolveContext");
 const folderSync = require("../lib/folderSync");
 const credentials = require("../lib/credentials");
 const prompt = require("../lib/prompt");
@@ -234,8 +234,13 @@ async function init(pathArg, opts = {}) {
   // EXISTING mode attaches the new repo's gitId to target.projectId; NEW mode
   // POSTs /api/projects to create it. The repo register/upload steps below are
   // identical for both — they don't depend on new-vs-existing.
+  //
+  // In NEW mode, target.projectId is the user-chosen ALIAS, not a real
+  // project_id yet — the server assigns the opaque project_id on create (see
+  // the POST below), and `projectId` is reassigned to that real value so
+  // every downstream call (pin file, env-vars, build, status) targets it.
   const isExisting = target.isExisting;
-  const projectId = target.projectId;
+  let projectId = target.projectId;
 
   const cliModuleExcludes = Array.isArray(opts.moduleExclude) ? opts.moduleExclude : [];
   const cliFileExcludes = Array.isArray(opts.fileExclude) ? opts.fileExclude : [];
@@ -439,10 +444,18 @@ async function init(pathArg, opts = {}) {
     );
   } else {
     console.log(`  ${step("2/3")}  Creating project "${color.bold(projectId)}" and scanning for environment variables...`);
+    // Send the chosen name as `alias` (account-scoped, duplicates across
+    // accounts allowed by design) — never as `project_id`. Letting the server
+    // assign the opaque project_id avoids colliding with an unrelated
+    // account's project whose project_id happens to equal this alias.
     project = await api.post("/api/projects", {
-      project_id: projectId,
+      alias: projectId,
       git_id_to_mapping: { [gitId]: {} },
     });
+    // Throws rather than pinning a falsy id — see projectIdFromCreateResponse. The pin write and
+    // watchState.update below both consume this, so a missing key would otherwise be recorded as the
+    // literal string "undefined" and every later tool call would fail with no clue why.
+    projectId = projectIdFromCreateResponse(project);
   }
 
   // If this folder was already onboarded to a different project, note the re-pin so
@@ -783,11 +796,18 @@ const GLOB_INCLUDE_EXAMPLES = "e.g. src/**/*.py, lib/**/*.ts";
 const GLOB_EXCLUDE_EXAMPLES = "e.g. **/test/**, **/*.generated.*, vendor/**";
 
 /**
- * Resolve a project name that is guaranteed to be free on this account.
+ * Resolve a project ALIAS that is guaranteed to be free on this account.
+ *
+ * The typed name is an alias, not the project_id — aliases are only unique
+ * per account (the server explicitly allows the same alias across different
+ * accounts), so this checks GET /api/projects/resolve?alias= (account-scoped)
+ * rather than GET /api/projects/{id} (a global project_id lookup, which used
+ * to 403 whenever some OTHER account already owned a project whose opaque
+ * project_id happened to equal the typed name).
  *
- * We probe GET /api/projects/{id} before registering anything — previously
- * the CLI only discovered a collision after the POST, by which point the
- * repo had already been registered in step 1 and we left an orphan.
+ * We probe before registering anything — previously the CLI only discovered
+ * a collision after the POST, by which point the repo had already been
+ * registered in step 1 and we left an orphan.
  *
  * Two modes:
  *   - --project-name supplied: check once; if taken, fail fast with guidance.
@@ -798,7 +818,7 @@ const GLOB_EXCLUDE_EXAMPLES = "e.g. **/test/**, **/*.generated.*, vendor/**";
  */
 async function resolveAvailableProjectName({ defaultName, opts }) {
   if (opts.projectName) {
-    if (await projectNameTaken(opts.projectName)) {
+    if (await aliasTaken(opts.projectName, opts)) {
       console.error(
         fail(`Project "${opts.projectName}" already exists on this account.`) +
         ` Pick a different name or delete it first (niro delete ${opts.projectName}).`
@@ -812,7 +832,7 @@ async function resolveAvailableProjectName({ defaultName, opts }) {
   // for collisions below). Non-interactive without --defaults/--project-name:
   // fail loudly rather than hang on a prompt.
   if (opts.defaults) {
-    if (await projectNameTaken(defaultName)) {
+    if (await aliasTaken(defaultName, opts)) {
       console.error(
         fail(`Project "${defaultName}" already exists on this account.`) +
         ` Pass --project-name <name> or delete it first (niro delete ${defaultName}).`
@@ -836,24 +856,15 @@ async function resolveAvailableProjectName({ defaultName, opts }) {
       console.error(fail("Project name is required."));
       return null;
     }
-    if (!(await projectNameTaken(answer))) return answer;
+    if (!(await aliasTaken(answer, opts))) return answer;
     console.log(`  ${warn("⚠")} "${color.bold(answer)}" already exists on this account — pick another.`);
     candidate = answer;
   }
 }
 
-async function projectNameTaken(projectId) {
-  try {
-    await api.get(`/api/projects/${encodeURIComponent(projectId)}`);
-    return true;
-  } catch (err) {
-    const body = err && err.body;
-    const msg = (body && (body.error || body.message)) || err.message || "";
-    if (/not found/i.test(String(msg))) return false;
-    // Any other error (network, 401, 500) we surface — don't silently treat
-    // as "available" or we'll create a project we can't manage.
-    throw err;
-  }
+async function aliasTaken(alias, opts = {}) {
+  const data = await api.get("/api/projects/resolve", { query: { alias }, apiUrl: opts.apiUrl });
+  return normalizeProjects(data).length > 0;
 }
 
 /**

package/src/commands/mcp.js

@@ -37,4 +37,32 @@ function serve() {
   require("../mcp/server");
 }
 
-module.exports = { install, uninstall, serve };
+/**
+ * `niro mcp receipt` — the per-developer off switch for the end-of-task line.
+ *
+ * The line itself is printed by the model from the tool result; nothing here displays it. This
+ * command only records the preference, which the bridge reads to decide whether to strip the
+ * receipt before the model ever sees it.
+ *
+ * `--pop` and `--hook` are gone. They served the Claude Code Stop hook, which was retired because
+ * Claude Code labels hook output "Stop says: …" — a system-warning framing for what is meant to be
+ * a quiet note from Niro.
+ */
+function receipt(opts = {}) {
+  const store = require("../lib/receiptStore");
+
+  if (opts.off || opts.on) {
+    const changed = store.setDisabled(!!opts.off);
+    const state = opts.off ? "off" : "on";
+    console.log(changed
+      ? `  End-of-task Niro line is now ${state}.`
+      : `  End-of-task Niro line was already ${state}.`);
+    return;
+  }
+
+  console.log(store.isDisabled()
+    ? "  End-of-task Niro line: off  (turn it on with `niro mcp receipt --on`)"
+    : "  End-of-task Niro line: on   (turn it off with `niro mcp receipt --off`)");
+}
+
+module.exports = { install, uninstall, serve, receipt };

package/src/index.js

@@ -265,6 +265,12 @@ function main() {
     .command("serve")
     .description("Run the Niro MCP server over stdio (used by your editor's MCP config).")
     .action(() => { require("./commands/mcp").serve(); });
+  mcp
+    .command("receipt")
+    .description("Turn the end-of-task Niro line on or off for this machine. No flags shows the current state.")
+    .option("--on", "Turn the end-of-task line back on.")
+    .option("--off", "Stop showing the end-of-task line.")
+    .action((opts) => { require("./commands/mcp").receipt(opts); });
 
   program.parseAsync(process.argv).catch((err) => {
     console.error(err && err.message ? err.message : err);

package/src/lib/receiptStore.js

@@ -0,0 +1,85 @@
+/**
+ * The per-developer off switch for the end-of-task receipt line.
+ *
+ * The line itself is composed by the server and travels back inside the mark_task_complete tool
+ * result, which the model prints wrapped in backticks. Nothing is stored locally to display it.
+ *
+ * This file used to be a letterbox: the bridge wrote each receipt to disk and a Claude Code Stop
+ * hook printed it. That worked, but Claude Code prefixes anything a Stop hook prints with
+ * "Stop says: …", which read as a system warning rather than a note from Niro. Printing from the
+ * model reads better and works in all twelve clients instead of one, so the hook, the letterbox and
+ * the terminal colouring all went with it.
+ *
+ * What remains is the switch. It stays local because it is a personal preference: the server serves
+ * a whole account and cannot know that one developer wants the line quiet. The bridge reads it and
+ * strips the receipt from the tool result, so the model never sees it and cannot print it.
+ */
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+/** ~/.niro, resolved the same way as the rest of the CLI (Windows has no HOME). */
+function niroHome() {
+  const home = process.env.HOME || process.env.USERPROFILE || os.homedir() || "";
+  return path.join(home, ".niro");
+}
+
+/**
+ * Presence of this file switches the line off.
+ *
+ * A file rather than a key inside projects.json so that toggling it can never corrupt, or be
+ * corrupted by, the sync state the watch daemon depends on.
+ */
+function disabledFlagPath() {
+  return path.join(niroHome(), "receipts-off");
+}
+
+function isDisabled() {
+  try {
+    return fs.existsSync(disabledFlagPath());
+  } catch {
+    // Cannot read the home directory: treat as ON. Failing to a silent state would make the
+    // feature look broken with nothing to explain why.
+    return false;
+  }
+}
+
+/** Turn the line on or off. Returns true when the state actually changed. */
+function setDisabled(disabled) {
+  const flag = disabledFlagPath();
+  try {
+    if (disabled) {
+      if (fs.existsSync(flag)) return false;
+      fs.mkdirSync(path.dirname(flag), { recursive: true, mode: 0o700 });
+      fs.writeFileSync(flag, "", { mode: 0o600 });
+      return true;
+    }
+    if (!fs.existsSync(flag)) return false;
+    fs.unlinkSync(flag);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Remove the off switch and any leftovers from the retired letterbox.
+ *
+ * Used by `niro mcp uninstall`, and worth keeping past the letterbox itself: anyone who ran a
+ * version that wrote receipts to disk still has that directory, and an uninstall that leaves files
+ * behind is not an uninstall.
+ */
+function purge() {
+  try {
+    fs.rmSync(path.join(niroHome(), "receipts"), { recursive: true, force: true });
+  } catch {
+    /* best effort */
+  }
+  try {
+    fs.rmSync(disabledFlagPath(), { force: true });
+  } catch {
+    /* best effort */
+  }
+}
+
+module.exports = { disabledFlagPath, isDisabled, setDisabled, purge };

package/src/lib/resolveContext.js

@@ -105,4 +105,28 @@ function normalizeProjects(data) {
     .filter(Boolean);
 }
 
-module.exports = { resolveContext, normalizeProjects };
+/**
+ * The project_id from a `POST /api/projects` response, or throws.
+ *
+ * Accepts either casing for the same reason normalizeProjects does — the server response shape varies
+ * across versions and deployments — and refuses to return a falsy id. That refusal is the point: callers
+ * assign this straight into the `.niro-project` pin file and watchState, so a missing key used to write
+ * the literal string "undefined" into the pin while `niro init` still printed success and exited 0. Every
+ * later MCP tool call then failed with `Project 'undefined' not found` and `niro build` targeted
+ * /api/graph/undefined/build, with nothing pointing at the cause.
+ *
+ * A create response with no id is a protocol violation, so it fails loudly at the boundary instead of
+ * degrading into a broken pin.
+ */
+function projectIdFromCreateResponse(project) {
+  const id = project && (project.project_id || project.projectId || project.id);
+  if (!id || typeof id !== "string" || !id.trim()) {
+    throw new Error(
+      "The server created the project but returned no project_id. Nothing was pinned. " +
+      "This usually means the backend predates account-scoped aliases — upgrade it, or report this."
+    );
+  }
+  return id.trim();
+}
+
+module.exports = { resolveContext, normalizeProjects, projectIdFromCreateResponse };

package/src/mcp/server.js

@@ -42,6 +42,7 @@ const readline = require("readline");
 const { execSync } = require("child_process");
 const niroProjectFile = require("../lib/niroProjectFile");
 const { redactRemoteCreds } = require("../lib/git");
+const receiptStore = require("../lib/receiptStore");
 
 /** Absolute path to ~/.niro/projects.json. Uses os.homedir() so it also resolves on Windows, where HOME is
  *  normally unset — `process.env.HOME || ""` there produced a relative path that never existed, silently
@@ -52,6 +53,32 @@ function niroProjectsFilePath() {
 }
 const { createPendingTracker, isTrackableRequest, resolveTimeoutMs } = require("../lib/pendingRequests");
 
+/**
+ * This package's version, sent as X-Niro-Cli-Version so the server can tell an out-of-date install to
+ * upgrade. That notice is the only channel that reaches a user who installed long ago, because everything
+ * else niro writes (hooks, CLAUDE.md/AGENTS.md sections, rules files) is frozen on their disk at install
+ * time and nothing prompts them to re-run `niro mcp install`.
+ *
+ * Paired with the X-Niro-Bridge marker below, which is what actually identifies this bridge. An earlier
+ * version had the server treat a MISSING version as out-of-date, reasoning that the header and the check
+ * shipped together so its absence proved an older bridge. That was wrong: @niroai/mcp-server is a
+ * separate published bridge (a documented install path, and an internal dependency of two packages here)
+ * that connects to the same /mcp/sse endpoint and sends no such header. Those users would have been told
+ * to upgrade @niroai/niro, which they do not have installed, on every session, with no remedy.
+ *
+ * So the version is advisory and the marker is the gate. A read failure here must not stop the bridge
+ * from starting, hence the empty-string fallback rather than a throw; an empty value simply means the
+ * server cannot judge the version and says nothing.
+ */
+const CLI_VERSION = (() => {
+  try {
+    return require("../../package.json").version || "";
+  } catch (e) {
+    process.stderr.write(`[niro-mcp] WARN: could not read own package version: ${e.message}\n`);
+    return "";
+  }
+})();
+
 const API_KEY = process.env.NIRO_API_KEY;
 
 /**
@@ -410,6 +437,13 @@ function connectSse() {
     };
     if (CLI_TOKEN) sseHeaders["X-Niro-Cli-Token"] = CLI_TOKEN;
     if (API_KEY) sseHeaders["X-Niro-Api-Key"] = API_KEY;
+    // Sent on every session so the server can spot an out-of-date install (see CLI_VERSION). The
+    // marker is what identifies THIS bridge: @niroai/mcp-server is a separate published bridge that
+    // hits the same /mcp/sse endpoint and sends neither header, so the server must not infer "old
+    // niro CLI" from a missing version alone — it would tell those users to upgrade a package they do
+    // not have installed, on every session, with no way to stop it.
+    sseHeaders["X-Niro-Bridge"] = "niro-cli";
+    if (CLI_VERSION) sseHeaders["X-Niro-Cli-Version"] = CLI_VERSION;
     if (PROJECT_ID) {
       sseHeaders["X-Niro-Project-Id"] = PROJECT_ID;
     } else {
@@ -474,6 +508,7 @@ function connectSse() {
             // Swallow the response to an internally-replayed initialize (sentinel id) so the host
             // never sees a duplicate initialize result after a transparent reconnect.
             let swallowed = false;
+            let rewritten = null;
             try {
               const msg = JSON.parse(data);
               // ADR-018 handshake: only an initialize result carries capabilities. When the server
@@ -495,9 +530,12 @@ function connectSse() {
               } else {
                 // Cancel the client-side deadline when a delivered result matches an in-flight request.
                 pending.onIncoming(msg);
+                rewritten = captureReceipt(msg);
               }
             } catch (_) { /* not correlatable JSON — forward unchanged */ }
-            if (!swallowed) process.stdout.write(data + "\n");
+            // captureReceipt returns a rewritten payload when it stripped the receipt field so the
+            // Stop hook can print it instead; otherwise the original bytes go through untouched.
+            if (!swallowed) process.stdout.write((rewritten || data) + "\n");
           }
         }
       });
@@ -629,6 +667,56 @@ function sendMessage(message) {
   });
 }
 
+/**
+ * Stash the end-of-task receipt line, if this incoming message carries one.
+ *
+ * The server composes the line and returns it inside the mark_task_complete tool result. The model
+ * is asked to print it, but a model can forget an instruction; the Claude Code Stop hook prints it
+ * whether or not the model cooperates, and this is where it gets the text. See
+ * `docs/usecases/task-receipt.md`.
+ *
+ * Deliberately does NOT filter by tool name: the bridge does not track which request id belonged to
+ * which tool, and a `receipt` string in a result is unambiguous enough on its own. Any future tool
+ * that wants to say something at end of task gets this for free.
+ *
+ * Silent on every failure. This sits on the path that hands results back to the developer's
+ * assistant, so a malformed message, an unwritable home directory, or an unexpected shape must cost
+ * the receipt and nothing else.
+ */
+function captureReceipt(msg) {
+  // Nothing to do unless the developer has switched the line off. The receipt is displayed by the
+  // model printing it from the tool result — there is no local copy and no hook any more.
+  if (!receiptStore.isDisabled()) return null;
+  try {
+    const content = msg && msg.result && msg.result.content;
+    if (!Array.isArray(content)) return null;
+    for (const item of content) {
+      if (!item || typeof item.text !== "string") continue;
+      // Cheap reject before parsing: tool results are frequently large, and almost none of them
+      // are the one message per task that carries a receipt.
+      if (!item.text.includes('"receipt"')) continue;
+      let parsed;
+      try {
+        parsed = JSON.parse(item.text);
+      } catch (_) {
+        continue; // not JSON — some other tool's prose that happens to contain the word
+      }
+      if (parsed && typeof parsed.receipt === "string") {
+        // Strip it here rather than asking the server not to send it. The switch is per developer
+        // and lives on this machine; the server serves a whole account and cannot know that one
+        // person wants it quiet.
+        delete parsed.receipt;
+        item.text = JSON.stringify(parsed);
+        return JSON.stringify(msg);
+      }
+    }
+  } catch (_) {
+    /* never let this disturb the message path */
+  }
+  return null;
+}
+
+
 /**
  * Enrich an outgoing tools/call: send the folder's `.niro-project` pin as `_niroPin` (ADR-018 — a
  * SOURCE binding the server's routing ladder consumes, NOT an explicit project choice), and

package/src/mcp/setup.js

@@ -16,6 +16,7 @@
  */
 
 const fs = require("fs");
+const os = require("os");
 const path = require("path");
 const readline = require("readline");
 const { execSync } = require("child_process");
@@ -45,11 +46,11 @@ const NIRO_MD_MARKER = "<!-- niro-mcp -->";
  * Explore-first rule, shared by every client's markdown section. Prose alone is weak, but this is the
  * one lever some clients (Codex, Copilot CLI, Factory, OpenCode, Windsurf) have — they support no hooks,
  * so their ONLY always-on nudge is this file. For Claude Code it reinforces the PreToolUse Grep|Glob|Read
- * hook (NIRO_EXPLORE_COMMAND), which fires once per session/repo/branch; this stays in force for the rest
- * of the session. Wording is imperative and names concrete tools so the agent knows what to call instead
- * of native search.
+ * hook (NIRO_EXPLORE_COMMAND), which fires on every native search. On the hookless clients this prose is
+ * 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.";
+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_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`;
@@ -126,6 +127,17 @@ function isNiroPreToolUseHook(h) {
   return cmds.some((c) => c.includes("should_create_temp_project") || c.includes("should_sandbox_repo"));
 }
 
+/**
+ * True if `h` is niro's Stop hook (the end-of-task receipt). Keyed on the exact subcommand it runs,
+ * which no other tool would have a reason to invoke. Shared by installer and uninstaller.
+ */
+function isNiroStopHook(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("mcp receipt --hook"));
+}
+
 /**
  * True if `h` is niro's PreToolUse explore-first reminder entry (matcher Grep|Glob|Read). Keyed on the
  * unique `niro-explore-` marker-file prefix so a foreign PreToolUse hook on the same matcher is never
@@ -564,6 +576,7 @@ async function setupClaudeCode(apiKey, mcpServerUrl) {
   addClaudeCodeUserPromptHook();
   addClaudeCodePreToolUseHook();
   addClaudeCodeExploreHook();
+  removeStaleNiroStopHook();
   addClaudeCodeMemory();
   addClaudeCodeSkill();
   addClaudeCodeCliSkill();
@@ -652,6 +665,31 @@ function addClaudeCodeMemory() {
   }
 }
 
+/**
+ * The niro UserPromptSubmit hook command. Module-level so tests can execute the real string under
+ * /bin/sh: it is shell, so asserting on its text proves nothing about whether it runs, and this body
+ * shipped once with no execution coverage at all.
+ *
+ * Folder-gated: walks up from the project dir and only emits the reminder when a `.niro-project`
+ * marker exists (i.e. this tree is actually indexed). It keeps ONE conditional clause — "if the niro
+ * tools are not in your toolset at all" — because a shell hook cannot see which MCP tools Claude has
+ * loaded, so the reminder must stay correct when Niro is disabled or an A/B session exposes a subset.
+ * The old wording also let the agent excuse itself whenever it judged a query "out of scope", which is
+ * the escape hatch drift actually walks through; that clause is gone, and the legitimate native-tool
+ * cases are now named explicitly instead.
+ *
+ * Reads the prompt on stdin so it can add a temporary-project reminder when the message asks to
+ * create or switch a branch — the exact moment a repo's local state diverges from what Niro indexed
+ * (ADR-017). The branch match is a coarse keyword heuristic (a shell hook cannot call an LLM); a false
+ * positive only shows an extra harmless reminder, never gates behaviour.
+ */
+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.'; " +
+    "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";
+
 /**
  * Adds a UserPromptSubmit hook to ~/.claude/settings.json so Claude is reminded
  * about Niro tools + the `niro` skill before every prompt. This is the lightweight,
@@ -660,21 +698,7 @@ function addClaudeCodeMemory() {
  */
 function addClaudeCodeUserPromptHook() {
   const settingsPath = path.join(process.env.HOME || "", ".claude", "settings.json");
-  // Folder-gated: walks up from the project dir and only emits the reminder when a
-  // `.niro-project` marker exists (i.e. this tree is actually indexed). The wording is
-  // conditional ("IF the niro tools are present") because a shell hook cannot see which
-  // MCP tools Claude has loaded — so it stays correct when Niro is disabled or an A/B
-  // session exposes only a subset of niro tools.
-  // Reads the prompt on stdin so it can add a SANDBOX reminder when the message asks to create/switch a
-  // branch — the exact moment a repo's local state diverges from what Niro indexed (ADR-017). The branch
-  // match is a coarse keyword heuristic (a shell hook can't call an LLM); a false positive only shows an
-  // extra harmless reminder, never gates behaviour. Base reminder is unchanged and still `.niro-project`-gated.
-  const hookCommand =
-    "IN=\"$(cat)\"; d=\"${CLAUDE_PROJECT_DIR:-$PWD}\"; while [ -n \"$d\" ] && [ \"$d\" != \"/\" ]; do " +
-    "if [ -f \"$d/.niro-project\" ]; then echo 'This repo is indexed by Niro. IF the niro MCP tools are present in your current toolset, prefer them over grep/read for codebase questions (structure, call chains, blast radius, impact, data flows, reuse) and call find_reusable_code before writing new code. If the niro tools are absent (disabled or A/B-limited) or a query is out of scope, 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";
+  const hookCommand = NIRO_USER_PROMPT_COMMAND;
 
   let settings = {};
   try {
@@ -757,6 +781,47 @@ const NIRO_PRETOOL_COMMAND = [
   `printf '%s' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":"Niro temporary project check: you are editing a Niro-indexed repo on its CURRENT branch. The temporary project answer is per branch, so a check you ran on a different branch (e.g. before switching) does NOT count here. Call should_create_temp_project(git_url, branch=current branch, project_id from its .niro-project) for THIS repo now and run niro new-temp-project if it returns needs_temp_project. Shown once per repo per branch per session."}}'`,
 ].join('; ');
 
+/**
+ * Removes a Stop hook left behind by an earlier version of this installer.
+ *
+ * Niro used to print the end-of-task receipt from a Claude Code Stop hook. It worked, but Claude
+ * Code labels anything a Stop hook prints with "Stop says: …", which read as a confusing system
+ * warning rather than a note from Niro. The receipt is now printed by the model itself, wrapped in
+ * backticks, which renders as code in every client rather than just this one.
+ *
+ * Anyone who installed the hook version still has it on disk, and hooks are frozen there until an
+ * install re-runs — so a plain upgrade would leave them seeing "Stop says:" for ever. Hence removing
+ * it here rather than only in uninstall. Other Stop hooks, including the developer's own, are
+ * matched by our exact subcommand and never touched.
+ */
+function removeStaleNiroStopHook() {
+  const settingsPath = path.join(process.env.HOME || "", ".claude", "settings.json");
+  let settings;
+  try {
+    if (!fs.existsSync(settingsPath)) return;
+    settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+  } catch {
+    return; // unreadable or malformed — leave it alone rather than risk rewriting it
+  }
+  const stop = settings.hooks && settings.hooks.Stop;
+  if (!Array.isArray(stop)) return;
+
+  const kept = stop.filter((h) => !isNiroStopHook(h));
+  if (kept.length === stop.length) return;
+
+  settings.hooks.Stop = kept;
+  if (kept.length === 0) delete settings.hooks.Stop;
+  if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+
+  try {
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    console.log("  Removed the old Stop hook — the end-of-task line now comes from Niro directly,");
+    console.log("  without the \"Stop says:\" prefix Claude Code adds to hook output.\n");
+  } catch (err) {
+    console.warn(`  Could not update ~/.claude/settings.json: ${err.message}`);
+  }
+}
+
 /**
  * Adds the PreToolUse (Edit|Write) temporary project-reminder hook to ~/.claude/settings.json. Idempotent:
  * upgrades a stale niro entry in place, never touches a foreign PreToolUse hook (matched by the
@@ -805,38 +870,57 @@ function addClaudeCodePreToolUseHook() {
  * UserPromptSubmit hook, the niro skill) tell Claude to prefer niro tools for code exploration, but in
  * practice that only sticks when a task is phrased as a discovery question — a task phrased as "fix X" or
  * "add Y" skips straight to native search with no interruption. This hook is the deterministic backstop:
- * once per (session, repo, branch), the first native Grep/Glob/Read call in a niro-indexed repo gets an
- * advisory reminder to prefer niro's structural tools instead — regardless of how the task was phrased.
+ * EVERY native Grep/Glob/Read call in a niro-indexed repo gets an advisory reminder to prefer niro's
+ * structural tools instead — regardless of how the task was phrased, and regardless of how far into the
+ * session it happens.
+ *
+ * It used to dedupe to once per (session, repo, branch). That was the bug: the reminder landed on the
+ * first native search of a session and then went quiet, so a long session drifted straight back to grep
+ * with nothing to correct it. Repeating the nudge on every call costs about 99 tokens per native search
+ * (394 characters of additionalContext) and is the only thing that survives a 100-turn session. Note that
+ * Claude issues Reads in parallel batches, so one turn can carry several copies of that text.
  *
  * Dependency-free (no jq): reads the PreToolUse JSON on stdin. Read supplies `file_path`; Grep/Glob supply
- * `path` (often omitted, meaning cwd) — so this tries file_path, then path, then the hook's own `cwd`
- * field, then falls back to $PWD. Walks up for a `.niro-project` marker (silent outside indexed repos)
- * and dedupes via a marker file keyed by session_id + repo root + branch, same scheme as the Edit|Write
- * temp-project hook but under the distinct `niro-explore-` prefix so the two hooks never collide.
+ * `path` (often omitted, meaning cwd) — so this tries file_path, then path, then the payload's own `cwd`,
+ * then CLAUDE_PROJECT_DIR, then $PWD. Relative targets resolve against the payload `cwd`, symlinks are
+ * resolved with `cd -P`, and it then walks up for a `.niro-project` marker (silent outside indexed repos)
+ * without requiring a git checkout. Carries `niro-explore-` as an inert identity token so
+ * isNiroExploreHook still recognises it for upgrade and uninstall.
  */
 const NIRO_EXPLORE_COMMAND = [
   'IN="$(cat)"',
   // Read gives file_path; Grep/Glob give path (may be absent); fall back to cwd, then $PWD.
   `f="$(printf '%s' "$IN" | grep -oE '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed -E 's/.*:[[:space:]]*"([^"]*)"/\\1/')"`,
   `[ -z "$f" ] && f="$(printf '%s' "$IN" | grep -oE '"path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed -E 's/.*:[[:space:]]*"([^"]*)"/\\1/')"`,
-  `[ -z "$f" ] && f="$(printf '%s' "$IN" | grep -oE '"cwd"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed -E 's/.*:[[:space:]]*"([^"]*)"/\\1/')"`,
-  '[ -z "$f" ] && f="$PWD"',
+  // The session's own directory, from the payload's top-level `cwd`. Serves two jobs: the base for a
+  // relative target path, and the fallback when the call names no path at all — which is the COMMON
+  // case, since Grep and Glob usually omit `path`. Resolving a relative path against the hook process's
+  // own $PWD instead silently misses the marker whenever the two differ; the payload states the right
+  // directory, so use it.
+  `c="$(printf '%s' "$IN" | grep -oE '"cwd"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed -E 's/.*:[[:space:]]*"([^"]*)"/\\1/')"`,
+  '[ -z "$c" ] && c="${CLAUDE_PROJECT_DIR:-$PWD}"',
+  '[ -z "$f" ] && f="$c"',
+  'case "$f" in /*) ;; *) f="$c/$f" ;; esac',
   'd0="$f"; [ -d "$d0" ] || d0="$(dirname "$f")"',
-  'r="$(git -C "$d0" rev-parse --show-toplevel 2>/dev/null)"',
-  '[ -z "$r" ] && exit 0',
-  // only remind inside a niro-indexed tree
-  'd="$r"; ok=0; while [ -n "$d" ] && [ "$d" != "/" ]; do if [ -f "$d/.niro-project" ]; then ok=1; break; fi; d="$(dirname "$d")"; done',
+  // Resolve symlinks before walking up. The `git rev-parse --show-toplevel` this replaced did that for
+  // free, so removing it without this line reintroduced the very failure the change set out to kill,
+  // through another door: a Read through a symlinked subdirectory walks lexical parents that never hold
+  // the marker. Falls back to the lexical path when the directory does not exist yet (a Write creating
+  // a new folder).
+  `d0="$(cd -P "$d0" 2>/dev/null && pwd -P || printf '%s' "$d0")"`,
+  // Indexed-tree gate, git-independent on purpose: niro indexes plain folders too, so a repo can carry
+  // .niro-project with no .git at all. The previous `git rev-parse --show-toplevel` bail made this hook
+  // permanently silent in exactly those repos — no nudge, ever. Walk up from the path itself instead.
+  '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',
-  `s="$(printf '%s' "$IN" | grep -oE '"session_id"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed -E 's/.*:[[:space:]]*"([^"]*)"/\\1/')"`,
-  // Branch-aware dedup, same rationale as the Edit|Write hook: a stale answer from a different branch must not
-  // silence the reminder after a branch switch.
-  'b="$(git -C "$r" rev-parse --abbrev-ref HEAD 2>/dev/null)"',
-  `k="$(printf '%s\\n%s\\n%s' "$s" "$r" "$b" | cksum | cut -d' ' -f1)"`,
-  'm="${TMPDIR:-/tmp}/niro-explore-$k"',
-  '[ -f "$m" ] && exit 0',
-  'touch "$m"',
+  // No once-per-session marker file, deliberately: this fires on EVERY native search. The drift it exists
+  // to stop happens late in a session, long after a one-shot reminder at turn 4 has scrolled out of
+  // attention — dedup was the reason the hook stopped working, not a cost saving worth keeping.
+  // `niro-explore-` stays verbatim as this hook's identity token: isNiroExploreHook and teardown match on
+  // it, so dropping the string would orphan the hook on upgrade and on uninstall.
+  'NIRO_HOOK_ID=niro-explore-alwayson',
   // Advisory context injection ONLY — no permissionDecision, so it never blocks the read/search.
-  `printf '%s' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":"This is a niro-indexed repo. For code structure/behavior/call-chain/impact/reuse questions - including ones that come up mid-task while implementing or fixing something, not just standalone discovery questions - prefer niro MCP tools (get_source_code, code_grep, get_call_chain, get_blast_radius, get_impact_analysis, find_reusable_code, get_class_structure, etc.) over native Grep/Glob/Read. Fall back to native tools silently for out-of-scope questions (config files, docs, runtime state, non-code content). Shown once per repo per branch per session."}}'`,
+  `printf '%s' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":"NIRO ACTIVE. Native search on a niro-indexed repo. Prefer niro tools, every time and mid-task too: code_grep (content), get_source_code or resolve_fqn (known symbol), find_handler or find_api_endpoints (entry points), get_call_chain, get_blast_radius, get_impact_analysis (connections), find_reusable_code (before new code). Native tools only for config, docs, logs, generated or non-code text."}}'`,
 ].join('; ');
 
 /**
@@ -873,8 +957,8 @@ function addClaudeCodeExploreHook() {
     fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
     fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
     console.log(`  PreToolUse explore-first hook ${hadStale ? "upgraded" : "added"} in ~/.claude/settings.json`);
-    console.log("  → Before the first native Grep/Glob/Read in a niro-indexed repo, Claude is reminded once/session/branch");
-    console.log("    to prefer niro tools — even mid-task, not just for standalone discovery questions.\n");
+    console.log("  → On every native Grep/Glob/Read in a niro-indexed repo, Claude is reminded to prefer");
+    console.log("    niro tools — even mid-task and late in a long session, not just for discovery questions.\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");
@@ -1396,53 +1480,222 @@ async function setupCodex(apiKey, mcpServerUrl) {
 
 /**
  * After `codex mcp add` writes [mcp_servers.niro], set
- * `default_tools_approval_mode = "auto"` — niro tools are all read-only, so no per-tool
- * approval prompts (codex mcp add has no flag for this; we insert it directly after the
- * table header, which is valid TOML — bare keys precede any sub-table). Idempotent and a
- * safe no-op if the file/table is missing. Also prints the optional `required = true`
- * recommendation (left off by default: it would make niro a hard Codex startup dependency).
+ * `default_tools_approval_mode = "writes"` — prompt only for tools that write, and niro writes
+ * nothing, so nothing prompts.
+ *
+ * It was "auto" until a developer reported being asked to approve every single call. Codex accepts
+ * four values (`auto`, `prompt`, `writes`, `approve` — confirmed from its own validation error on a
+ * bad one), and "auto" means Codex decides for itself. It decides to ask. "writes" states the fact
+ * about niro that makes asking unnecessary, rather than delegating the judgement.
+ *
+ * Inserted directly after the table header, which is valid TOML — bare keys precede any sub-table.
+ * Idempotent and a safe no-op if the file or table is missing. Also prints the optional
+ * `required = true` recommendation (left off by default: it would make niro a hard Codex startup
+ * dependency).
  */
-function hardenCodexServerConfig() {
-  const cfgPath = path.join(process.env.HOME || "", ".codex", "config.toml");
-  const header = "[mcp_servers.niro]";
+/**
+ * Write ~/.codex/config.toml, then prove Codex can still load it — rolling back if it cannot.
+ *
+ * This file holds [mcp_servers.niro] itself, so a malformed edit does not merely fail: it makes
+ * Codex reject the whole file and takes the developer's Niro registration down with it. That is the
+ * failure mode that got a Codex hook built and pulled twice (ae7bdaa, dcc4f7f), and the lesson from
+ * it was that every write here needs a verify-and-rollback rather than care alone.
+ *
+ * Atomic temp-then-rename, with the original file mode preserved. Widening permissions matters:
+ * this file can hold API keys, and an earlier version of the pulled work reset 0600 to 0644 on
+ * rollback.
+ *
+ * Verification runs the real binary. `codex mcp get niro` parses the config and prints the server,
+ * so a non-zero exit means Codex would not load what we just wrote. If the binary is missing we
+ * cannot verify, and the write is skipped entirely — an unverifiable edit to this file is not worth
+ * the risk it carries.
+ */
+function writeCodexConfigVerified(cfgPath, contents) {
+  const { execSync } = require("child_process");
+
+  try {
+    execSync("command -v codex >/dev/null 2>&1", { stdio: "ignore", shell: "/bin/sh" });
+  } catch {
+    throw new Error("codex is not on PATH, so the edit cannot be verified — leaving the file alone");
+  }
 
+  const previous = fs.readFileSync(cfgPath, "utf-8");
+  let mode = 0o600;
+  try {
+    mode = fs.statSync(cfgPath).mode & 0o777;
+  } catch {
+    /* fall back to the conservative default above */
+  }
+
+  const tmp = `${cfgPath}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, contents, { mode });
+  fs.renameSync(tmp, cfgPath);
+
+  try {
+    execSync("codex mcp get niro", { stdio: "ignore", timeout: 15000 });
+  } catch (err) {
+    // Put it back exactly as it was, mode included, then report.
+    const rollback = `${cfgPath}.${process.pid}.rollback`;
+    fs.writeFileSync(rollback, previous, { mode });
+    fs.renameSync(rollback, cfgPath);
+    throw new Error("Codex could not load the edited config — rolled back, nothing changed");
+  }
+}
+
+/**
+ * Remove [mcp_servers.niro.tools.*] approval overrides from ~/.codex/config.toml.
+ *
+ * Codex writes one of these each time a developer answers a tool prompt with "approve once", and a
+ * per-tool setting overrides default_tools_approval_mode. The result is a config that looks correctly
+ * configured and prompts on every single call.
+ *
+ * Only niro's own sub-tables are touched, matched by their full prefix. This is the file that holds
+ * [mcp_servers.niro] itself, so a careless edit costs the developer their whole Niro registration —
+ * the reason a Codex hook was built and pulled twice (ae7bdaa, dcc4f7f). Hence: read, rewrite in
+ * memory, and only write when the result still parses as something Codex will load.
+ *
+ * Returns how many tables were removed; 0 on any failure, having changed nothing.
+ */
+function clearCodexPerToolApprovals(cfgPath) {
   let toml;
   try {
     toml = fs.readFileSync(cfgPath, "utf-8");
   } catch {
-    console.warn("  Could not read ~/.codex/config.toml to set the approval mode — skipping.\n");
-    return;
+    return 0;
   }
 
-  const idx = toml.indexOf(header);
-  if (idx === -1) {
-    console.warn("  [mcp_servers.niro] not found in config.toml — skipping approval-mode hardening.\n");
-    return;
+  // A table runs from its header to the next header at any level, or end of file.
+  const pattern = /\n\[mcp_servers\.niro\.tools\.[^\]]+\]\n(?:(?!\n?\[)[^\n]*\n)*/g;
+  const matches = toml.match(pattern);
+  if (!matches || matches.length === 0) return 0;
+
+  const rewritten = toml.replace(pattern, "\n").replace(/\n{3,}/g, "\n\n");
+
+  // Refuse to write anything that lost the niro server itself. Cheap, and the failure it guards
+  // against is the one that matters.
+  if (!rewritten.includes("[mcp_servers.niro]")) {
+    console.warn("  Skipped clearing Codex tool approvals — the edit would have dropped [mcp_servers.niro].\n");
+    return 0;
   }
 
-  // Limit the "already set?" check to the niro table body (up to the next table header).
-  const after = toml.slice(idx + header.length);
-  const nextTableRel = after.search(/\n\s*\[/);
-  const tableBody = nextTableRel === -1 ? after : after.slice(0, nextTableRel);
+  try {
+    writeCodexConfigVerified(cfgPath, rewritten);
+  } catch (err) {
+    console.warn(`  Could not clear Codex per-tool approvals: ${err.message}\n`);
+    return 0;
+  }
+
+  console.log(`  Cleared ${matches.length} per-tool approval override${matches.length === 1 ? "" : "s"} for niro.`);
+  console.log("  → those beat default_tools_approval_mode and made every call prompt.\n");
+  return matches.length;
+}
+
+/**
+ * Absolute path to Codex's config.toml, honouring CODEX_HOME.
+ *
+ * `codex mcp add` writes wherever CODEX_HOME points, so reading from a hard-coded ~/.codex would
+ * edit a file Codex never loads while reporting success — the server registered in one place and the
+ * approval mode set in another.
+ *
+ * Returns null rather than a relative path when no home resolves. userHome() can be "", and
+ * path.join("", ".codex", "config.toml") yields ".codex/config.toml" relative to the current working
+ * directory, which on some machines is a git-tracked project folder.
+ */
+function codexConfigPath() {
+  const codexHome = process.env.CODEX_HOME && process.env.CODEX_HOME.trim();
+  if (codexHome) return path.join(codexHome, "config.toml");
+  const home = userHome();
+  if (!home) return null;
+  return path.join(home, ".codex", "config.toml");
+}
+
+function hardenCodexServerConfig() {
+  const cfgPath = codexConfigPath();
+  if (!cfgPath) {
+    console.warn("  Could not resolve ~/.codex/config.toml — skipping approval-mode hardening.\n");
+    return;
+  }
 
   console.log("  Tip: for a hard dependency, add `required = true` under [mcp_servers.niro]");
   console.log("       (Codex then fails startup if niro is unreachable — off by default).\n");
 
-  if (/^\s*default_tools_approval_mode\s*=/m.test(tableBody)) {
-    console.log("  Codex approval mode already set — skipping.\n");
+  // Clear per-tool overrides FIRST. Codex writes a [mcp_servers.niro.tools.<name>] table with
+  // approval_mode = "approve" whenever the developer answers a prompt with "approve once" rather
+  // than "always allow", and a per-tool setting BEATS default_tools_approval_mode. So the default
+  // below can be correct while every call still prompts — exactly what a developer reported.
+  //
+  // This rewrites the file, so everything after it must work from freshly read contents. An earlier
+  // version computed byte offsets BEFORE this call and spliced with them afterwards, which inserted
+  // text into the middle of an unrelated line whenever the rewrite shortened anything above the niro
+  // header. That produced invalid TOML, and Codex refuses to load a config it cannot parse — taking
+  // [mcp_servers.niro] and every other server's credentials down with it.
+  clearCodexPerToolApprovals(cfgPath);
+
+  const located = locateCodexNiroTable(cfgPath);
+  if (!located) {
+    console.warn("  [mcp_servers.niro] not found in config.toml — skipping approval-mode hardening.\n");
     return;
   }
+  const { toml, bodyStart, bodyEnd, body } = located;
+
+  const existing = body.match(/^[ \t]*default_tools_approval_mode[ \t]*=[ \t]*"([^"]*)"/m);
+
+  if (existing && existing[1] !== "auto") {
+    console.log(`  Codex approval mode already set to "${existing[1]}" — leaving your choice alone.\n`);
+    return;
+  }
+
+  // Every edit below is confined to niro's own table slice. Replacing across the whole file with a
+  // single /m regex rewrote the FIRST matching line anywhere in it — which, since `codex mcp add`
+  // appends niro last, was reliably ANOTHER server's line. That silently relaxed a third party's
+  // approval settings and left niro's untouched, while printing that it had succeeded.
+  let newBody;
+  let message;
+  if (existing) {
+    newBody = body.replace(/^([ \t]*default_tools_approval_mode[ \t]*=[ \t]*)"auto"/m, '$1"writes"');
+    message = ['  Changed Codex approval mode from "auto" to "writes".',
+               '  -> "auto" let Codex decide, and it decided to ask on every call.'];
+  } else {
+    // A bare key must precede any sub-table, so it goes at the very top of the body.
+    newBody = '\ndefault_tools_approval_mode = "writes"' + body;
+    message = ['  Set default_tools_approval_mode = "writes" in ~/.codex/config.toml',
+               "  -> niro is read-only, so its tools run without per-call approval prompts."];
+  }
 
-  const insertAt = idx + header.length;
-  const newToml = toml.slice(0, insertAt) + '\ndefault_tools_approval_mode = "auto"' + toml.slice(insertAt);
+  if (newBody === body) return; // nothing to do
 
   try {
-    fs.writeFileSync(cfgPath, newToml);
-    console.log('  Set default_tools_approval_mode = "auto" in ~/.codex/config.toml');
-    console.log("  → niro is read-only, so its tools run without per-call approval prompts.\n");
+    writeCodexConfigVerified(cfgPath, toml.slice(0, bodyStart) + newBody + toml.slice(bodyEnd));
+    message.forEach((line) => console.log(line));
+    console.log("");
   } catch (err) {
-    console.warn(`  Could not update ~/.codex/config.toml: ${err.message}\n`);
+    console.warn(`  Could not update the Codex approval mode: ${err.message}\n`);
+  }
+}
+
+/**
+ * Locate [mcp_servers.niro]'s body in the CURRENT contents of config.toml.
+ *
+ * Returns the whole file plus the byte range of the table body (everything after the header, up to
+ * the next table header at any level). Read fresh on every call: any offset computed before another
+ * function rewrote the file is a splice into the wrong place waiting to happen.
+ */
+function locateCodexNiroTable(cfgPath) {
+  const header = "[mcp_servers.niro]";
+  let toml;
+  try {
+    toml = fs.readFileSync(cfgPath, "utf-8");
+  } catch {
+    return null;
   }
+  const idx = toml.indexOf(header);
+  if (idx === -1) return null;
+
+  const bodyStart = idx + header.length;
+  const after = toml.slice(bodyStart);
+  const nextTableRel = after.search(/\n[ \t]*\[/);
+  const bodyEnd = nextTableRel === -1 ? toml.length : bodyStart + nextTableRel;
+  return { toml, bodyStart, bodyEnd, body: toml.slice(bodyStart, bodyEnd) };
 }
 
 /**
@@ -2087,7 +2340,6 @@ module.exports = {
   addClaudeCodeCliSkill,
   addAgentsSkill,
   addAgentsCliSkill,
-  // Shared with teardown.js so uninstall removes exactly what install wrote.
   CLIENTS,
   NIRO_MD_MARKER,
   NIRO_MD_SECTIONS,
@@ -2095,7 +2347,15 @@ module.exports = {
   isNiroUserPromptHook,
   isNiroPreToolUseHook,
   isNiroExploreHook,
+  isNiroStopHook,
+  clearCodexPerToolApprovals,
+  hardenCodexServerConfig,
   userHome,
+  // Exposed for tests: the hook bodies are shell, so the only way to prove they still fire (and still
+  // carry their identity token) is to execute the real string.
+  NIRO_EXPLORE_COMMAND,
+  NIRO_PRETOOL_COMMAND,
+  NIRO_USER_PROMPT_COMMAND,
   // Exposed for content regression tests (e.g. the cross-project routing guidance).
   NIRO_SKILL,
   NIRO_CLI_SKILL,

package/src/mcp/teardown.js

@@ -6,7 +6,8 @@
  * `niro mcp uninstall` removes everything `niro mcp install` wrote, per editor:
  *   - the MCP server registration (claude/codex CLI, or the editor's JSON config)
  *   - the niro hooks in ~/.claude/settings.json (PostCompact + UserPromptSubmit + PreToolUse: both the
- *     Edit|Write temp-project reminder and the Grep|Glob|Read explore-first reminder)
+ *     Edit|Write temp-project reminder and the Grep|Glob|Read explore-first reminder + Stop: the
+ *     end-of-task receipt line), and any receipts still pending on disk
  *   - the niro section in markdown config (CLAUDE.md / AGENTS.md / Windsurf rules)
  *   - the generated skills (~/.claude/skills, the shared ~/.agents/skills)
  *   - Cursor's "niro:*" allowlist entry and project rule
@@ -36,6 +37,7 @@ const {
   CLIENTS,
   NIRO_MD_MARKER,
   NIRO_MD_SECTIONS,
+  isNiroStopHook,
   isNiroPostCompactHook,
   isNiroUserPromptHook,
   isNiroPreToolUseHook,
@@ -154,6 +156,12 @@ function filterNiroHooks(settings) {
     removed += before - hooks.PreToolUse.length;
     if (hooks.PreToolUse.length === 0) delete hooks.PreToolUse;
   }
+  if (Array.isArray(hooks.Stop)) {
+    const before = hooks.Stop.length;
+    hooks.Stop = hooks.Stop.filter((h) => !isNiroStopHook(h));
+    removed += before - hooks.Stop.length;
+    if (hooks.Stop.length === 0) delete hooks.Stop;
+  }
   if (Object.keys(hooks).length === 0) delete settings.hooks;
 
   return { settings, removed };
@@ -375,6 +383,14 @@ function uninstallClaudeCode() {
   const home = userHome();
   runMcpRemove("claude", ["mcp", "remove", "niro", "--scope", "user"]);
   stripNiroHooksFromSettings(path.join(home, ".claude", "settings.json"));
+  // Claude Code is the only client with the Stop hook, so its pending receipts have nothing left to
+  // read them. Leaving them behind would mean a reinstall months later opens with a line describing
+  // a task the developer has long forgotten.
+  try {
+    require("../lib/receiptStore").purge();
+  } catch {
+    /* best effort — never block an uninstall on cleaning up a cache */
+  }
   stripMarkerFromFile(path.join(home, ".claude", "CLAUDE.md"), "Claude Code memory");
   deleteFileIfPresent(path.join(home, ".claude", "skills", "niro-skill", "SKILL.md"), "niro skill");
   deleteFileIfPresent(path.join(home, ".claude", "skills", "niro-cli", "SKILL.md"), "niro-cli skill");