@niroai/niro 0.17.0 → 0.18.0

package/src/mcp/shellSearchHook.js

@@ -0,0 +1,509 @@
+/**
+ * The PreToolUse reminder on Claude Code's Bash tool: when a shell command searches or reads source
+ * code in an indexed folder, it adds the same "ask niro first" note that the Grep|Glob|Read hook adds
+ * (setup.js NIRO_EXPLORE_COMMAND). It never blocks the command: there is no permissionDecision.
+ *
+ * Why it exists. Agents mostly search with the shell, not with Claude Code's own search tools, so the
+ * Grep|Glob|Read reminder never fired for them. Ten days of our own sessions held 10,347 shell greps and
+ * reads of source code against 2,112 niro questions (dev-process review, 2026-11-10, proposal P8).
+ * Niraj approved it on 2026-11-10: "proposals 1 and 8 yes but we should first test them".
+ *
+ * How it decides, in one awk pass over the hook input (no jq, no node, no network):
+ *   1. Read `tool_input.command` and the session `cwd` out of the JSON.
+ *   2. Split the command the way a shell does: quotes, `&&`, `||`, `;`, `|`, `$(`, newlines; heredoc
+ *      bodies are skipped; a leading `cd` moves the folder later parts run in.
+ *   3. For each simple command, name the paths it would search or read:
+ *      - `grep egrep fgrep rg ag ack`, `git grep`: the paths given, or the current folder when the tool
+ *        searches it by default (rg, ag, ack, git grep, grep -r). A tool reading a pipe searches no file.
+ *        `git grep pattern <revision> -- path` searches another commit, which niro cannot answer: quiet.
+ *      - `cat head tail sed -n awk less more nl bat`: files with a source extension (or a glob of them).
+ *      - `find ... -name/-iname/-path/-regex` with a source extension.
+ *      - `xargs grep ...`: the current folder.
+ *   4. Leave out config, docs, logs and generated output: a file whose extension is not source, a path
+ *      through docs/, logs/, node_modules/, dist/, build/, target/ and the like, a search limited to
+ *      non-source files (`--include=*.md`, `rg -t md`), `tail -f`, `sed -i`, `--help` and `--version`.
+ *      build/, dist/, target/, out/ and logs/ count only as the first folder of the path the command names.
+ *   A variable set earlier in the same command (`f=src/a.py; sed -n 1,9p $f`, `export R=...`) is filled in;
+ *   one set from a command's output (`f=$(find ...)`) is not known, and a path that uses it is skipped.
+ * The shell then keeps a folder only if it exists, and a file only if it exists and was not changed in
+ * the last 10 minutes (a file just edited is being checked, not explored). On the first path that
+ * passes, it walks up for the indexed-folder marker as the explore hook does (localMode FAST_CLOUD_WALK),
+ * so localHook turns it into the niro-local check without any change here.
+ *
+ * `niro-shell-search-` is this hook's identity token: the installer and the uninstaller find it by
+ * that string. It must never contain `niro-explore-`, `niro-impact-` or `should_create_temp_project`,
+ * or another niro installer would take it for its own hook and delete it (checked when this module loads).
+ */
+const fs = require("fs");
+const path = require("path");
+const { FAST_CLOUD_WALK } = require("./localMode");
+
+/** Source file extensions. The impact hook's list (setup.js NIRO_IMPACT_COMMAND) plus a few more languages. */
+const SOURCE_EXTENSIONS = [
+  "java", "js", "mjs", "cjs", "ts", "tsx", "jsx", "mts", "cts", "py", "pyi", "go", "rb", "kt", "kts", "cs",
+  "php", "rs", "scala", "swift", "c", "cc", "cpp", "cxx", "h", "hh", "hpp", "m", "mm", "dart", "lua", "ex",
+  "exs", "clj", "groovy", "vue", "svelte", "erl", "hs", "ml", "fs", "vb",
+];
+
+/** ripgrep `-t` names for those languages. */
+const SOURCE_TYPES = [
+  "py", "python", "js", "javascript", "ts", "typescript", "jsx", "tsx", "java", "go", "rust", "rs", "c", "cpp",
+  "cs", "csharp", "kotlin", "kt", "ruby", "rb", "php", "swift", "scala", "lua", "dart", "elixir", "clojure",
+  "groovy", "objc", "objcpp", "vue", "svelte", "haskell", "erlang", "ocaml", "fsharp",
+];
+
+/** Folder names that hold docs, dependencies or caches wherever they appear in a path. */
+const EXCLUDED_FOLDERS = [
+  "docs", "doc", "node_modules", "coverage", ".git", "__pycache__", ".venv", "venv", "vendor", ".next",
+  ".nuxt", ".cache", "site-packages", ".gradle", ".pytest_cache", ".mypy_cache",
+];
+
+/**
+ * Folder names that hold logs or build output only as the first folder of the path the command names
+ * (`grep -r x build/`, `cat dist/app.js`). Deeper down they are often source packages: niro-local's own
+ * `src/niro_local/build/`, a Java `com/acme/log/` package. The trial missed 3 such reads before this split.
+ */
+const EXCLUDED_AT_TOP = ["build", "dist", "target", "out", "logs", "log", "tmp"];
+
+/**
+ * The classifier. Prints one line per path the command would search or read, at most four:
+ * `D/abs/folder` or `F/abs/file`. Prints nothing when the command is not a code search or read.
+ * POSIX awk only (mawk, BSD awk, gawk): no gensub, no arrays of arrays, no match() third argument.
+ * A backslash in the decoded command is held as \001, so the JSON and shell escapes never meet.
+ * It must contain no single quote, because the shell command wraps it in single quotes.
+ */
+const AWK_PROGRAM = String.raw`
+function setof(list, arr,    n, i, p) { n = split(list, p, " "); for (i = 1; i <= n; i++) arr[p[i]] = 1 }
+function jstr(s, key,    i, rest, t, e, b) {
+  rest = s
+  while ((i = index(rest, "\"" key "\"")) > 0) {
+    rest = substr(rest, i + length(key) + 2)
+    if (!match(rest, /^[ \t\r\n]*:[ \t\r\n]*"/)) continue
+    t = substr(rest, RLENGTH + 1, 16384)
+    gsub(/\\\\/, "\001", t)
+    if (substr(t, 1, 1) == "\"") return ""
+    if (match(t, /[^\\]"/)) t = substr(t, 1, RSTART)
+    gsub(/\\"/, "\"", t); gsub(/\\n/, "\n", t); gsub(/\\t/, "\t", t); gsub(/\\\//, "/", t)
+    gsub(/\\[rbf]/, " ", t); gsub(/\\u0027/, "\047", t); gsub(/\\u003[cC]/, "<", t); gsub(/\\u003[eE]/, ">", t)
+    gsub(/\\u0026/, "\\&", t); gsub(/\\u[0-9a-fA-F][0-9a-fA-F][0-9a-fA-F][0-9a-fA-F]/, "?", t)
+    return t
+  }
+  return ""
+}
+function tok(ty, v) { NT++; TT[NT] = ty; TV[NT] = v }
+function flush() { if (INW) tok("w", W0); W0 = ""; INW = 0 }
+function skiphd(b, i, hd,    rest, off, k, a, before) {
+  rest = substr(b, i + 1); off = 0
+  while ((k = index(rest, hd)) > 0) {
+    a = substr(rest, k + length(hd), 1)
+    before = substr(rest, 1, k - 1); sub(/\t*$/, "", before)
+    if ((a == "\n" || a == "") && (before == "" || substr(before, length(before), 1) == "\n")) return i + off + k + length(hd)
+    rest = substr(rest, k + 1); off += k
+  }
+  return length(b) + 1
+}
+function lex(b,    n, i, c, d, e, j, hd, hdw) {
+  n = length(b); i = 1; W0 = ""; INW = 0; NT = 0; hd = ""
+  while (i <= n) {
+    c = substr(b, i, 1); d = substr(b, i + 1, 1)
+    if (c == "\001") { if (d == "\n") { i += 2; continue } W0 = W0 d; INW = 1; i += 2; continue }
+    if (c == "\047") {
+      j = index(substr(b, i + 1), "\047")
+      if (j == 0) { W0 = W0 substr(b, i + 1); i = n + 1 } else { W0 = W0 substr(b, i + 1, j - 1); i += j + 1 }
+      INW = 1; continue
+    }
+    if (c == "\"") {
+      i++
+      while (i <= n) {
+        d = substr(b, i, 1)
+        if (d == "\"") { i++; break }
+        if (d == "\001") { e = substr(b, i + 1, 1); if (e == "\"" || e == "\001" || e == "$" || e == "\140") { W0 = W0 e; i += 2; continue } }
+        W0 = W0 d; i++
+      }
+      INW = 1; continue
+    }
+    if (c == " " || c == "\t") { flush(); i++; continue }
+    if (c == "#" && !INW) { j = index(substr(b, i), "\n"); if (j == 0) i = n + 1; else i += j - 1; continue }
+    if (c == "\n") { flush(); tok("o", ";"); if (hd != "") { i = skiphd(b, i, hd); hd = "" } else i++; continue }
+    if (c == ";") { flush(); tok("o", ";"); i += (d == ";") ? 2 : 1; continue }
+    if (c == "&") {
+      flush()
+      if (d == "&") { tok("o", ";"); i += 2 } else if (d == ">") { tok("r", ">"); i += 2; if (substr(b, i, 1) == ">") i++ } else { tok("o", ";"); i++ }
+      continue
+    }
+    if (c == "|") { flush(); if (d == "|") { tok("o", ";"); i += 2 } else { tok("o", "|"); i += (d == "&") ? 2 : 1 } continue }
+    if (c == "(" || c == "\140") { flush(); tok("o", "("); i++; continue }
+    if (c == ")") { flush(); tok("o", ";"); i++; continue }
+    if (c == "$" && d == "(") { flush(); tok("o", "("); i += 2; continue }
+    if (c == "<" || c == ">") {
+      if (W0 ~ /^[0-9]+$/) { W0 = ""; INW = 0 }
+      flush()
+      if (c == "<" && d == "<" && substr(b, i + 2, 1) == "<") { tok("r", "<<<"); i += 3; continue }
+      if (c == "<" && d == "<") {
+        i += 2; if (substr(b, i, 1) == "-") i++
+        while (substr(b, i, 1) == " ") i++
+        hdw = ""
+        while (i <= n) { e = substr(b, i, 1); if (e ~ /[ \t\n;&|<>()]/) break; if (e != "\047" && e != "\"" && e != "\001") hdw = hdw e; i++ }
+        if (hdw != "") hd = hdw
+        continue
+      }
+      if (c == "<" && d == "(") { tok("o", "("); i += 2; continue }
+      if (c == "<") { tok("r", (d == ">") ? ">" : "<"); i += (d == ">" || d == "&") ? 2 : 1; continue }
+      i++; if (d == ">" || d == "|" || d == "&") i++
+      tok("r", ">"); continue
+    }
+    W0 = W0 c; INW = 1; i++
+  }
+  flush()
+}
+function base(w,    k) { k = w; sub(/.*\//, "", k); return k }
+function extof(name,    k, r) {
+  if (name == "." || name == "..") return ""
+  r = name; if (!match(r, /\.[^.]*$/) || RSTART == 1) return ""
+  return tolower(substr(r, RSTART + 1))
+}
+function srcext(s,    n, i, p, e) {
+  s = tolower(s); gsub(/[{},()]/, "|.", s); n = split(s, p, "|")
+  for (i = 1; i <= n; i++) { if (!match(p[i], /\.[^.]*$/)) continue; e = substr(p[i], RSTART + 1); gsub(/[^a-z0-9+]/, "", e); if (e in SRC) return 1 }
+  return 0
+}
+function excl(p,    n, i, c, f) {
+  n = split(p, c, "/"); f = 0
+  for (i = 1; i <= n; i++) { if (c[i] in EXC) return 1; if (c[i] != "" && c[i] != "." && !f) { f = 1; if (substr(p, 1, 1) != "/" && (c[i] in TOP)) return 1 } }
+  return 0
+}
+function expand(s,    out, k, nm, rest, e) {
+  out = ""
+  while ((k = index(s, "$")) > 0) {
+    out = out substr(s, 1, k - 1); rest = substr(s, k + 1)
+    if (substr(rest, 1, 1) == "{") { e = index(rest, "}"); if (e == 0) return out "$" rest; nm = substr(rest, 2, e - 2); rest = substr(rest, e + 1) }
+    else if (match(rest, /^[A-Za-z_][A-Za-z0-9_]*/)) { nm = substr(rest, 1, RLENGTH); rest = substr(rest, RLENGTH + 1) }
+    else return out "$" rest
+    if (nm == "HOME") out = out HOME; else if (nm == "PWD") out = out CUR; else if (nm in VARS) out = out VARS[nm]; else return out "$" "{" nm "}" rest
+    s = rest
+  }
+  return out s
+}
+function tail3(p,    n, c, s, i) { n = split(p, c, "/"); s = ""; for (i = (n > 3 ? n - 2 : 1); i <= n; i++) s = s "/" c[i]; return s }
+function emit(k, a) {
+  gsub(/\/\.\//, "/", a); gsub(/\/\.\//, "/", a); sub(/\/\.$/, "", a); gsub(/\/\/+/, "/", a); if (a == "") a = "/"
+  if ((k a) in SEEN || NOUT >= 4) return
+  SEEN[k a] = 1; NOUT++; print k a
+}
+function cand(p, mode,    a, nc, cs, g, i, last, ext, pre, np, ps) {
+  if (p == "" || p == "-") return
+  if (p == "~") p = HOME; else if (substr(p, 1, 2) == "~/") p = HOME substr(p, 2)
+  p = expand(p); if (index(p, "$") > 0) return
+  a = (substr(p, 1, 1) == "/") ? p : CUR "/" p
+  if (excl(p)) return
+  if (substr(p, 1, 1) != "/" && excl(tail3(CUR))) return
+  np = split(p, ps, "/"); g = 0
+  for (i = 1; i <= np; i++) if (ps[i] ~ /[*?[]/) { g = i; break }
+  if (g > 0) {
+    last = ps[np]
+    if (index(last, ".") > 0) { if (!srcext(last)) return } else if (mode == "read") return
+    pre = ""; for (i = 1; i < g; i++) pre = pre (i > 1 ? "/" : "") ps[i]
+    if (substr(p, 1, 1) == "/") pre = (pre == "") ? "/" : pre; else pre = (pre == "") ? CUR : CUR "/" pre
+    emit("D", pre); return
+  }
+  nc = split(a, cs, "/")
+  while (nc > 1 && cs[nc] == "") nc--
+  ext = extof(cs[nc])
+  if (ext != "") { if (ext in SRC) emit("F", a); return }
+  if (mode == "read") return
+  emit("D", a)
+}
+function resolve(p) {
+  p = expand(p)
+  if (p == "" || p == "~") return HOME
+  if (substr(p, 1, 2) == "~/") return HOME substr(p, 2)
+  return (substr(p, 1, 1) == "/") ? p : CUR "/" p
+}
+function search(tool, j,    m, sv, lv, pat, rec, inc, incs, files, np, P, w, name, val, e, k, ch, endo) {
+  m = NW
+  if (tool == "rg") { sv = "efABCmgtTMjdrE"; lv = " regexp file glob iglob type type-not type-add max-count max-columns max-depth max-filesize replace encoding context after-context before-context sort sortr colors pre pre-glob ignore-file threads path-separator context-separator engine " }
+  else if (tool == "ag") { sv = "ABCmGgp"; lv = " file-search-regex ignore ignore-dir depth context after before max-count pager path-to-ignore workers " }
+  else if (tool == "ack") { sv = "ABCm"; lv = " ignore-dir context after-context before-context max-count " }
+  else if (tool == "gitgrep") { sv = "efABCm"; lv = " max-depth threads context after-context before-context max-count " }
+  else { sv = "efABCmdD"; lv = " include exclude exclude-dir exclude-from regexp file after-context before-context context max-count directories devices label binary-files " }
+  pat = 0; rec = 0; inc = 0; incs = 0; files = 0; np = 0; endo = 0
+  for (; j <= m; j++) {
+    w = WD[j]
+    if (!endo && w == "--") { if (tool == "gitgrep" && np > 0) return; endo = 1; continue }
+    if (!endo && w ~ /^--./) {
+      name = substr(w, 3); val = ""
+      if ((e = index(name, "=")) > 0) { val = substr(name, e + 1); name = substr(name, 1, e - 1) } else if (index(lv, " " name " ") > 0) { j++; val = WD[j] }
+      if (name == "help" || name == "version") return
+      if (name == "regexp" || name == "file" || name == "file-search-regex") pat = 1
+      if (name == "recursive" || name == "dereference-recursive" || (name == "directories" && val == "recurse")) rec = 1
+      if (name == "include" || ((name == "glob" || name == "iglob") && substr(val, 1, 1) != "!")) { inc = 1; if (srcext(val)) incs = 1 }
+      if (name == "file-search-regex") { inc = 1; if (srcext(val)) incs = 1 }
+      if (name == "type") { inc = 1; if (val in STY) incs = 1 }
+      if (name == "files" && tool == "rg") files = 1
+      continue
+    }
+    if (!endo && w ~ /^-[0-9]+$/) continue
+    if (!endo && w ~ /^-./) {
+      if (tool == "rg" && w == "-V") return
+      for (k = 2; k <= length(w); k++) {
+        ch = substr(w, k, 1)
+        if (index(sv, ch) > 0) {
+          val = substr(w, k + 1); if (val == "") { j++; val = WD[j] }
+          if (tool != "ag" && (ch == "e" || ch == "f")) pat = 1
+          if (tool == "ag" && ch == "g") pat = 1
+          if ((tool == "rg" && ch == "g" && substr(val, 1, 1) != "!") || (tool == "ag" && ch == "G")) { inc = 1; if (srcext(val)) incs = 1 }
+          if (tool == "rg" && ch == "t") { inc = 1; if (val in STY) incs = 1 }
+          if (tool == "grep" && ch == "d" && val == "recurse") rec = 1
+          break
+        }
+        if (tool == "grep" && (ch == "r" || ch == "R")) rec = 1
+      }
+      continue
+    }
+    if (!pat && !files) { pat = 1; continue }
+    P[++np] = w
+  }
+  if ((inc || files) && !incs) return
+  if (np == 0) {
+    if (NIN > 0) { for (k = 1; k <= NIN; k++) cand(IN[k], "read"); return }
+    if (PIN && !XARGS) return
+    if (tool == "grep" && !rec && !XARGS) return
+    cand(".", "search"); return
+  }
+  for (k = 1; k <= np; k++) cand(P[k], "search")
+}
+function readcmd(tool, j,    m, sv, lv, scr, nseen, inpl, foll, np, P, w, name, val, e, k, ch, endo) {
+  m = NW; sv = ""; lv = " "
+  if (tool == "head" || tool == "tail") { sv = "ncs"; lv = " lines bytes sleep-interval pid max-unchanged-stats " }
+  else if (tool == "sed") { sv = "efl"; lv = " expression file line-length " }
+  else if (tool == "awk") { sv = "fvF"; lv = " file assign field-separator " }
+  else if (tool == "bat") { sv = "lrHm"; lv = " language line-range highlight-line map-syntax style theme tabs wrap terminal-width pager decorations color italic-text file-name " }
+  else if (tool == "less") { sv = "bhjkoOpPtTxyz#" }
+  else if (tool == "nl") { sv = "bdfhilnsvw" }
+  scr = (tool == "sed" || tool == "awk") ? 0 : 1; nseen = 0; inpl = 0; foll = 0; np = 0; endo = 0
+  for (; j <= m; j++) {
+    w = WD[j]
+    if (!endo && w == "--") { endo = 1; continue }
+    if (!endo && w ~ /^--./) {
+      name = substr(w, 3)
+      if ((e = index(name, "=")) > 0) name = substr(name, 1, e - 1); else if (index(lv, " " name " ") > 0) j++
+      if (name == "help" || name == "version" || name == "in-place") return
+      if (name == "follow") foll = 1
+      if (name == "quiet" || name == "silent") nseen = 1
+      if (name == "expression" || name == "file") scr = 1
+      continue
+    }
+    if (!endo && w ~ /^-[0-9]+$/) continue
+    if (!endo && (tool == "head" || tool == "tail") && w ~ /^\+[0-9]+$/) continue
+    if (!endo && w ~ /^-./) {
+      for (k = 2; k <= length(w); k++) {
+        ch = substr(w, k, 1)
+        if (index(sv, ch) > 0) {
+          if (substr(w, k + 1) == "") j++
+          if ((tool == "sed" && (ch == "e" || ch == "f")) || (tool == "awk" && ch == "f")) scr = 1
+          break
+        }
+        if (tool == "sed" && ch == "n") nseen = 1
+        if (tool == "sed" && ch == "i") inpl = 1
+        if (tool == "tail" && (ch == "f" || ch == "F")) foll = 1
+      }
+      continue
+    }
+    if (!scr) { scr = 1; continue }
+    if (tool == "awk" && w ~ /^[A-Za-z_][A-Za-z0-9_]*=/) continue
+    P[++np] = w
+  }
+  if (foll || inpl || (tool == "sed" && !nseen)) return
+  if (np == 0) { for (k = 1; k <= NIN; k++) cand(IN[k], "read"); return }
+  for (k = 1; k <= np; k++) cand(P[k], "read")
+}
+function findcmd(j,    m, np, P, k, w, src) {
+  m = NW; np = 0; src = 0
+  while (j <= m && WD[j] ~ /^-[HLP]$|^-O[0-9]$/) j++
+  if (j <= m && WD[j] == "-D") j += 2
+  while (j <= m && WD[j] !~ /^[-(!]/) { P[++np] = WD[j]; j++ }
+  for (k = j; k < m; k++) if (WD[k] ~ /^-(i?name|i?path|i?wholename|i?regex|lname)$/ && srcext(WD[k + 1])) src = 1
+  if (!src) return
+  if (np == 0) { cand(".", "search"); return }
+  for (k = 1; k <= np; k++) cand(P[k], "search")
+}
+function assign(w,    e, nm, v) {
+  e = index(w, "="); nm = substr(w, 1, e - 1); v = substr(w, e + 1)
+  if (v == "~") v = HOME; else if (substr(v, 1, 2) == "~/") v = HOME substr(v, 2)
+  v = expand(v)
+  if (v == "" || index(v, "$") > 0) delete VARS[nm]; else VARS[nm] = v
+}
+function segment(    i, w, b, t, j, gd) {
+  i = 1; XARGS = 0
+  for (j = 1; j <= NW && WD[j] ~ /^[A-Za-z_][A-Za-z0-9_]*=/; j++) ;
+  if (j > NW || WD[j] == "export" || WD[j] == "local" || WD[j] == "readonly") {
+    for (j = 1; j <= NW; j++) if (WD[j] ~ /^[A-Za-z_][A-Za-z0-9_]*=/) assign(WD[j])
+    return
+  }
+  while (i <= NW) {
+    w = WD[i]; b = base(w)
+    if (w ~ /^[A-Za-z_][A-Za-z0-9_]*=/) { i++; continue }
+    if (w == "!" || w == "{" || b == "if" || b == "then" || b == "else" || b == "elif" || b == "do" || b == "while" || b == "until" || b == "time" || b == "nohup" || b == "builtin" || b == "exec" || b == "stdbuf" || b == "env") {
+      i++; while (i <= NW && WD[i] ~ /^-/) { if (b == "env" && WD[i] == "-u") i++; i++ } continue
+    }
+    if (b == "command") { if (WD[i + 1] ~ /^-[vV]/) return; i++; continue }
+    if (b == "sudo" || b == "nice" || b == "timeout" || b == "xargs") {
+      if (b == "xargs") XARGS = 1
+      i++
+      while (i <= NW && WD[i] ~ /^-/) { if (WD[i] ~ /^-[unsgkIPLdEa]$/) i++; i++ }
+      if (b == "timeout") i++
+      continue
+    }
+    break
+  }
+  if (i > NW) return
+  w = WD[i]; b = base(w)
+  if (b == "cd" || b == "pushd") {
+    if (XARGS) return
+    t = WD[i + 1]; if (t == "-P" || t == "-L" || t == "--") t = WD[i + 2]
+    if (t == "-") return
+    t = expand(t); if (index(t, "$") > 0) return
+    CUR = resolve(t); return
+  }
+  if (b == "git") {
+    j = i + 1; gd = CUR
+    while (j <= NW && WD[j] ~ /^-/) { if (WD[j] == "-C") { gd = resolve(WD[j + 1]); j++ } else if (WD[j] == "-c") j++; j++ }
+    if (WD[j] != "grep") return
+    t = CUR; CUR = gd; search("gitgrep", j + 1); CUR = t; return
+  }
+  if (b == "grep" || b == "egrep" || b == "fgrep") { search("grep", i + 1); return }
+  if (b == "rg" || b == "ag" || b == "ack") { search(b, i + 1); return }
+  if (b == "ack-grep") { search("ack", i + 1); return }
+  if (XARGS) return
+  if (b == "batcat") b = "bat"
+  if (b == "gawk" || b == "mawk" || b == "nawk") b = "awk"
+  if (b == "cat" || b == "bat" || b == "less" || b == "more" || b == "nl" || b == "head" || b == "tail" || b == "sed" || b == "awk") { readcmd(b, i + 1); return }
+  if (b == "find") { findcmd(i + 1); return }
+}
+function run(    k, rd) {
+  NW = 0; NIN = 0; PIN = 0; rd = ""
+  for (k = 1; k <= NT + 1; k++) {
+    if (k > NT || TT[k] == "o") {
+      if (NW > 0) segment()
+      NW = 0; NIN = 0; rd = ""
+      PIN = (k <= NT && TV[k] == "|") ? 1 : 0
+      continue
+    }
+    if (TT[k] == "r") { rd = TV[k]; continue }
+    if (rd != "") { if (rd == "<") IN[++NIN] = TV[k]; rd = ""; continue }
+    WD[++NW] = TV[k]
+  }
+}
+{ S = S $0 "\n" }
+END {
+  setof("${SOURCE_EXTENSIONS.join(" ")}", SRC); setof("${SOURCE_TYPES.join(" ")}", STY); setof("${EXCLUDED_FOLDERS.join(" ")}", EXC); setof("${EXCLUDED_AT_TOP.join(" ")}", TOP)
+  HOME = ENVIRON["HOME"]
+  CMD = jstr(S, "command"); if (CMD == "") exit
+  CUR = jstr(S, "cwd"); if (CUR == "") CUR = C
+  gsub(/\001/, "\\", CUR)
+  lex(CMD); run()
+}
+`;
+
+/** The reminder text. Built with JSON.stringify so it is valid JSON; no apostrophe, as it sits in single quotes. */
+const NIRO_SHELL_SEARCH_JSON = JSON.stringify({
+  hookSpecificOutput: {
+    hookEventName: "PreToolUse",
+    additionalContext:
+      "NIRO ACTIVE. This shell command searches or reads source code on a niro-indexed repo. Prefer niro " +
+      "tools, every time and mid-task too: code_grep (text in code), get_source_code or resolve_fqn (a known " +
+      "symbol or a line range), get_call_chain, get_reverse_call_chain, get_blast_radius, get_impact_analysis " +
+      "(how code connects). Shell tools only for config, docs, logs, generated or non-code text, or a file " +
+      "you just edited.",
+  },
+});
+
+/** The hook's identity token, matched by isNiroShellSearchHook. */
+const SHELL_SEARCH_TOKEN = "niro-shell-search-";
+
+/**
+ * The hook command (matcher Bash). The awk program prints the paths; the loop takes the first that
+ * exists (and, for a file, was not changed in the last 10 minutes) and asks whether it lies under an
+ * indexed folder. Only that one path is walked, with the walk that starts no process per folder level
+ * (localMode FAST_CLOUD_WALK): walking all four paths with the explore hook's walk put the slowest 1 in
+ * 100 calls at 75 ms in the trial.
+ * `IFS` is set to a newline so a path with a space survives the loop; `set -f` stops the shell from
+ * expanding a `*` that reached it. Every way out is `exit 0`: exit 2 would block the command.
+ */
+const NIRO_SHELL_SEARCH_COMMAND = [
+  'IN="$(cat)"',
+  `T="$(printf '%s' "$IN" | awk -v C="\${CLAUDE_PROJECT_DIR:-$PWD}" '${AWK_PROGRAM}' 2>/dev/null)"`,
+  '[ -z "$T" ] && exit 0',
+  `set -f; IFS="$(printf '\\n.')"; IFS="\${IFS%.}"; ok=0`,
+  'for t in $T; do k="${t%%/*}"; p="/${t#*/}"; ' +
+    'if [ "$k" = D ]; then [ -d "$p" ] || continue; d0="$p"; ' +
+    'else [ -f "$p" ] || continue; [ -n "$(find "$p" -mmin -10 2>/dev/null)" ] && continue; d0="$(dirname "$p")"; fi; ' +
+    `d0="$(cd -P "$d0" 2>/dev/null && pwd -P || printf '%s' "$d0")"; ` +
+    `${FAST_CLOUD_WALK}; break; done`,
+  '[ "$ok" = 1 ] || exit 0',
+  `NIRO_HOOK_ID=${SHELL_SEARCH_TOKEN}reminder`,
+  `printf '%s' '${NIRO_SHELL_SEARCH_JSON}'`,
+  'exit 0',
+].join("; ");
+
+for (const [what, text] of [["awk program", AWK_PROGRAM], ["reminder", NIRO_SHELL_SEARCH_JSON]]) {
+  if (text.includes("'")) throw new Error(`the shell search hook ${what} holds a single quote, which ends its shell quoting`);
+}
+for (const other of ["niro-explore-", "niro-impact-", "should_create_temp_project", "should_sandbox_repo"]) {
+  if (NIRO_SHELL_SEARCH_COMMAND.includes(other)) throw new Error(`the shell search hook holds ${other}, another hook's identity token`);
+}
+
+/** True if `h` is niro's Bash shell-search reminder entry. A foreign Bash hook is never matched. */
+function isNiroShellSearchHook(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(SHELL_SEARCH_TOKEN));
+}
+
+/**
+ * Adds the PreToolUse (Bash) shell-search reminder to ~/.claude/settings.json, the way the explore hook
+ * is added: the same command already there is left alone, an older niro entry is replaced in place, a
+ * foreign entry is never touched, and an unreadable file is started fresh.
+ */
+function addClaudeCodeShellSearchHook(hookCommand = NIRO_SHELL_SEARCH_COMMAND) {
+  const settingsPath = path.join(process.env.HOME || "", ".claude", "settings.json");
+  let settings = {};
+  try {
+    if (fs.existsSync(settingsPath)) settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+  } catch {
+    // Corrupt or missing: start fresh, as the other hook installers do.
+  }
+  if (!settings.hooks) settings.hooks = {};
+  if (!settings.hooks.PreToolUse) settings.hooks.PreToolUse = [];
+
+  const entry = { matcher: "Bash", hooks: [{ type: "command", command: hookCommand }] };
+  const alreadyCurrent = settings.hooks.PreToolUse.some(
+    (h) => Array.isArray(h.hooks) && h.hooks.some((i) => i && i.command === hookCommand),
+  );
+  if (alreadyCurrent) {
+    console.log("    PreToolUse shell-search hook already up to date. Skipping.\n");
+    return;
+  }
+  const hadStale = settings.hooks.PreToolUse.some(isNiroShellSearchHook);
+  settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter((h) => !isNiroShellSearchHook(h));
+  settings.hooks.PreToolUse.push(entry);
+  try {
+    fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    console.log(`    PreToolUse shell-search hook ${hadStale ? "upgraded" : "added"} in ~/.claude/settings.json`);
+  } catch (err) {
+    console.warn(`    Could not write ~/.claude/settings.json: ${err.message}`);
+    console.warn("    Add manually to the PreToolUse array in ~/.claude/settings.json:\n");
+    console.warn(JSON.stringify(entry, null, 2) + "\n");
+  }
+}
+
+module.exports = {
+  NIRO_SHELL_SEARCH_COMMAND,
+  NIRO_SHELL_SEARCH_JSON,
+  SHELL_SEARCH_TOKEN,
+  AWK_PROGRAM,
+  isNiroShellSearchHook,
+  addClaudeCodeShellSearchHook,
+};