@niroai/niro 0.3.5 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,65 @@
+# 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.
+
+### Fixed
+
+- **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.5",
+  "version": "0.4.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/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

@@ -52,6 +52,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 +436,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 {

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");
@@ -41,17 +42,27 @@ const NIRO_MD_MARKER = "<!-- niro-mcp -->";
  * own notes added below the block survive uninstall — see teardown.js removeMarkerSection).
  * Each begins with a leading "\n" because install does `existing + section`.
  */
+/**
+ * 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 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. 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_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_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_MULTI_REPO_SENTENCE}\n`;
+const NIRO_CLAUDE_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP tools are available for code intelligence. Use them (call chains, blast radius, impact analysis, source lookup) before falling back to native grep/read for code questions.\nBefore adding/writing any new code, you MUST use the find_reusable_code tool from niro to figure out if there is anything reusable.\n${NIRO_EXPLORE_FIRST_SENTENCE}\n${NIRO_MULTI_REPO_SENTENCE}\n`;
+const NIRO_CODEX_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP code-intelligence tools and the \`niro-skill\` are available (call chains, blast radius, impact analysis, source lookup). Prefer them over grep/read for questions about this codebase; the niro-skill has the full tool-routing playbook. Before adding or writing any new code, use find_reusable_code to check for reusable code. If the niro tools are not present or the repo is not indexed, use native tools.\n${NIRO_EXPLORE_FIRST_SENTENCE}\n${NIRO_MULTI_REPO_SENTENCE}\n`;
+const NIRO_WINDSURF_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP code-intelligence tools and the niro-skill are available. Prefer them over grep/read for questions about this codebase (structure, call chains, blast radius, impact, data flows, reuse); the niro-skill has the full routing playbook. Before writing any new code, use find_reusable_code. If the niro tools are not present or the repo is not indexed, use native tools.\n${NIRO_EXPLORE_FIRST_SENTENCE}\n${NIRO_MULTI_REPO_SENTENCE}\n`;
 /**
  * Shared generic section for clients whose "always-on instructions" file has no companion
  * skill mechanism we've verified (Gemini CLI's GEMINI.md, GitHub Copilot CLI's
  * copilot-instructions.md, Factory's AGENTS.md, OpenCode's AGENTS.md) — one wording, reused
  * across those destination files (teardown matches it per-file, so reuse is safe).
  */
-const NIRO_GENERIC_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP code-intelligence tools are available (call chains, blast radius, impact analysis, source lookup). Prefer them over grep/read for questions about this codebase. Before adding or writing any new code, use find_reusable_code to check for reusable code. If the niro tools are not present or the repo is not indexed, use native tools.\n${NIRO_MULTI_REPO_SENTENCE}\n`;
+const NIRO_GENERIC_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP code-intelligence tools are available (call chains, blast radius, impact analysis, source lookup). Prefer them over grep/read for questions about this codebase. Before adding or writing any new code, use find_reusable_code to check for reusable code. If the niro tools are not present or the repo is not indexed, use native tools.\n${NIRO_EXPLORE_FIRST_SENTENCE}\n${NIRO_MULTI_REPO_SENTENCE}\n`;
 
 /** All niro markdown sections — the uninstaller tries each for an exact removal. */
 const NIRO_MD_SECTIONS = [NIRO_CLAUDE_MD_SECTION, NIRO_CODEX_MD_SECTION, NIRO_WINDSURF_MD_SECTION, NIRO_GENERIC_MD_SECTION];
@@ -642,6 +653,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,
@@ -650,21 +686,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 {
@@ -795,38 +817,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('; ');
 
 /**
@@ -863,8 +904,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");
@@ -886,6 +927,16 @@ code — structure, behavior, impact, data/event flows, semantics — prefer the
 native grep/read. For anything outside the indexed code (config files, docs, runtime state),
 use your native tools.
 
+## Explore first — MUST FOLLOW
+
+Before you run grep, find, glob, or open a file to hunt for something, check whether a Niro
+tool answers it: \`code_grep\` for content search, \`resolve_fqn\` + \`get_source_code\` for a known
+symbol, \`find_handler\` / \`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 the code connects BEFORE you decide which file to
+read or search next, instead of reading files to rebuild that picture by hand. Native search
+stays the fallback for what Niro does not cover, and when the tools are unavailable.
+
 \`project_id\` auto-resolves from a \`.niro-project\` file at the repo root — omit it. If there
 is no such file, call \`list_projects\` and pass the chosen \`project_id\`.
 
@@ -1287,6 +1338,13 @@ alwaysApply: false
 The niro MCP server exposes code-intelligence tools for this codebase. Prefer them over
 grep/read for any question answerable from the indexed code.
 
+MUST FOLLOW — explore first: before you run grep, find, glob, or open a file to hunt for
+something, check whether a niro tool answers it (code_grep, resolve_fqn + get_source_code,
+find_handler, find_api_endpoints). Use the connection tools (get_call_chain,
+get_reverse_call_chain, get_blast_radius, get_impact_analysis, get_service_topology) to see
+how the code connects BEFORE deciding which file to read or search next. Native search is the
+fallback for what niro does not cover, and when the tools are unavailable.
+
 Availability self-check FIRST — if the niro tools are not present in this session, or the
 repo is not indexed (no project resolves / a tool reports "not indexed"), fall back to
 native tools silently and do not mention Niro.
@@ -1574,6 +1632,13 @@ Niro code-intelligence MCP tools are available for the current codebase. Prefer
 grep/read for questions about structure, call chains, blast radius, impact, data flows, and
 reuse. Before writing or adding any new code, use \`find_reusable_code\` first.
 
+MUST FOLLOW — explore first: before you run grep, find, glob, or open a file to hunt for
+something, check whether a niro tool answers it (\`code_grep\`, \`resolve_fqn\` +
+\`get_source_code\`, \`find_handler\`, \`find_api_endpoints\`). Use the connection tools
+(\`get_call_chain\`, \`get_reverse_call_chain\`, \`get_blast_radius\`, \`get_impact_analysis\`,
+\`get_service_topology\`) to see how the code connects BEFORE deciding which file to read or
+search next. Native search is the fallback for what niro does not cover.
+
 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.
 `;
@@ -1612,6 +1677,13 @@ Niro code-intelligence MCP tools are available for the current codebase. Prefer
 grep/read for questions about structure, call chains, blast radius, impact, data flows, and
 reuse. Before writing or adding any new code, use \`find_reusable_code\` first.
 
+MUST FOLLOW — explore first: before you run grep, find, glob, or open a file to hunt for
+something, check whether a niro tool answers it (\`code_grep\`, \`resolve_fqn\` +
+\`get_source_code\`, \`find_handler\`, \`find_api_endpoints\`). Use the connection tools
+(\`get_call_chain\`, \`get_reverse_call_chain\`, \`get_blast_radius\`, \`get_impact_analysis\`,
+\`get_service_topology\`) to see how the code connects BEFORE deciding which file to read or
+search next. Native search is the fallback for what niro does not cover.
+
 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.
 `;
@@ -2046,7 +2118,6 @@ module.exports = {
   addClaudeCodeCliSkill,
   addAgentsSkill,
   addAgentsCliSkill,
-  // Shared with teardown.js so uninstall removes exactly what install wrote.
   CLIENTS,
   NIRO_MD_MARKER,
   NIRO_MD_SECTIONS,
@@ -2055,9 +2126,20 @@ module.exports = {
   isNiroPreToolUseHook,
   isNiroExploreHook,
   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,
+  // Exposed for tests: the explore-first rule must reach EVERY client's always-on instruction surface.
+  NIRO_EXPLORE_FIRST_SENTENCE,
+  NIRO_CURSOR_RULE,
+  NIRO_CLINE_RULE,
+  NIRO_KIRO_STEERING,
+  upsertNiroMarkerSection,
   // Exposed for tests: URL resolution replaced the install-time prompt.
   resolveMcpServerUrl,
   SAAS_URL,