@raymondchins/agentmap 0.2.3 → 0.3.0

package/README.md

@@ -133,15 +133,24 @@ the installed `agentmap` binary, then `npx --no-install @raymondchins/agentmap`.
 
 ### 2. Force the agent to use it — `PreToolUse` hook
 
-[`hooks/agentmap-nudge.mjs`](./hooks/agentmap-nudge.mjs) is a **non-blocking** `PreToolUse(Grep)`
-hook for Claude Code. When a `Grep` looks like a dependency / who-imports / component-usage /
-reuse search, it injects a reminder steering the agent to `agentmap --any` first. It never
-denies the grep, and stays silent for raw-string / Tailwind-class / lowercase-HTML-tag
-sweeps — so it's high-signal, not nagging.
-
-`--install-hooks` writes this into `.claude/settings.json` for you (merge-safe — it
-preserves existing settings and won't duplicate on re-run). For reference, or to wire
-it by hand:
+[`hooks/agentmap-nudge.mjs`](./hooks/agentmap-nudge.mjs) is a **non-blocking** hook for
+Claude Code that covers **both** the `Grep` tool and raw Bash text-searchers
+(`grep`/`rg`/`egrep`/`fgrep`/`ag`/`ack`). When either looks like a dependency /
+who-imports / component-usage / reuse / where-is-symbol search, it injects a reminder
+steering the agent to `agentmap --any` first. It never denies the call, and stays silent
+for raw-string / Tailwind-class / lowercase-HTML-tag sweeps and for pipe-filtered commands
+like `ps aux | grep node` — so it's high-signal, not nagging.
+
+**Fires on:** `import`/`require`/`export`/`from '...'` patterns, JSX component tags
+(`<Hero`, `<ProviderCard`), explicit intent words (`where is`, `who imports`, `reuse`,
+`existing component`), and — in the Bash branch — bare multi-hump PascalCase identifiers
+(`ProviderCard`, `TopProviders`) that almost always mean "where is this symbol / who uses
+it". The Bash branch only fires when the searcher is the *primary* command (at the start,
+or after `;`/`&&`); piped log-filters stay silent.
+
+`--install-hooks` writes both matchers into `.claude/settings.json` for you (merge-safe —
+preserves existing settings, won't duplicate on re-run). The single hook file dispatches
+internally on `tool_name`. For reference, or to wire it by hand:
 
 ```json
 {
@@ -149,9 +158,11 @@ it by hand:
     "PreToolUse": [
       {
         "matcher": "Grep",
-        "hooks": [
-          { "type": "command", "command": "node ./hooks/agentmap-nudge.mjs" }
-        ]
+        "hooks": [{ "type": "command", "command": "node ./hooks/agentmap-nudge.mjs" }]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [{ "type": "command", "command": "node ./hooks/agentmap-nudge.mjs" }]
       }
     ]
   }
@@ -159,7 +170,7 @@ it by hand:
 ```
 
 That's the "forced to use it" in the tagline: the map stays current on its own, and the
-agent is steered to it the moment it reaches for a dependency-shaped grep.
+agent is steered to it the moment it reaches for a dependency-shaped grep or Bash search.
 
 ---
 

package/agentmap.mjs

@@ -545,7 +545,7 @@ function fileBlock(key, f) {
 // ---------------------------------------------------------------------------
 // --install-hooks: copy the package post-commit hook into .git/hooks, ensure
 // .claude/agentmap.json is gitignored, and auto-wire the Claude Code
-// PreToolUse(Grep) nudge into the project's .claude/settings.json so map
+// PreToolUse(Grep|Bash) nudge into the project's .claude/settings.json so map
 // enforcement is ON by default (no manual copy-paste). Merge-safe + idempotent.
 // Throws on any failure so the caller can stderr+exit 1.
 // ---------------------------------------------------------------------------
@@ -574,11 +574,13 @@ function installHooks() {
     writeFileSync(".gitignore", IGNORE_LINE + "\n");
   }
 
-  // Auto-wire the PreToolUse(Grep) enforcement nudge into the PROJECT settings
-  // (.claude/settings.json) so "the agent is forced to use the map" is ON by
-  // default — not a manual paste. Merge-safe + idempotent: preserves any
-  // existing settings/hooks, never duplicates our entry. Uses a project-relative
-  // command so a committed settings.json stays portable across machines.
+  // Auto-wire the PreToolUse(Grep|Bash) enforcement nudge into the PROJECT
+  // settings (.claude/settings.json) so "the agent is forced to use the map"
+  // is ON by default — not a manual paste. Merge-safe + idempotent: preserves
+  // any existing settings/hooks, never duplicates our entry. Uses a project-
+  // relative command so a committed settings.json stays portable across machines.
+  // Both the Grep tool AND raw Bash searchers (grep/rg/ag/ack) are covered by
+  // a single hook file — the nudge routes internally based on tool_name.
   const NUDGE_CMD = "node node_modules/@raymondchins/agentmap/hooks/agentmap-nudge.mjs";
   const settingsPath = ".claude/settings.json";
   let settings = {};
@@ -588,11 +590,21 @@ function installHooks() {
   }
   settings.hooks ??= {};
   settings.hooks.PreToolUse ??= [];
-  const alreadyWired = settings.hooks.PreToolUse.some(
-    (e) => Array.isArray(e?.hooks) && e.hooks.some((h) => typeof h?.command === "string" && h.command.includes("agentmap-nudge")),
+  // Check whether BOTH matchers are already present.
+  const hasGrep = settings.hooks.PreToolUse.some(
+    (e) => e?.matcher === "Grep" && Array.isArray(e?.hooks) && e.hooks.some((h) => typeof h?.command === "string" && h.command.includes("agentmap-nudge")),
   );
-  if (!alreadyWired) {
+  const hasBash = settings.hooks.PreToolUse.some(
+    (e) => e?.matcher === "Bash" && Array.isArray(e?.hooks) && e.hooks.some((h) => typeof h?.command === "string" && h.command.includes("agentmap-nudge")),
+  );
+  const alreadyWired = hasGrep && hasBash;
+  if (!hasGrep) {
     settings.hooks.PreToolUse.push({ matcher: "Grep", hooks: [{ type: "command", command: NUDGE_CMD }] });
+  }
+  if (!hasBash) {
+    settings.hooks.PreToolUse.push({ matcher: "Bash", hooks: [{ type: "command", command: NUDGE_CMD }] });
+  }
+  if (!alreadyWired) {
     mkdirSync(".claude", { recursive: true });
     writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
   }
@@ -601,8 +613,8 @@ function installHooks() {
   console.log(`installed post-commit hook → ${dest}`);
   console.log(ignoredAlready ? `.gitignore already has ${IGNORE_LINE}` : `added ${IGNORE_LINE} to .gitignore`);
   console.log(alreadyWired
-    ? `${settingsPath} already wires the PreToolUse(Grep) → agentmap nudge — left as-is`
-    : `wired PreToolUse(Grep) → agentmap nudge into ${settingsPath} (map enforcement on by default)`);
+    ? `${settingsPath} already wires the PreToolUse(Grep|Bash) → agentmap nudge — left as-is`
+    : `wired PreToolUse(Grep|Bash) → agentmap nudge into ${settingsPath} (map enforcement on by default)`);
   console.log("\nDone — the map auto-refreshes on commit, and greps are nudged to agentmap first.");
 }
 

package/hooks/agentmap-nudge.mjs

@@ -1,24 +1,35 @@
 #!/usr/bin/env node
 // SPDX-License-Identifier: MIT
 // ============================================================================
-//  agentmap — PreToolUse(Grep) nudge hook
+//  agentmap — PreToolUse nudge hook (Grep tool + Bash text-searchers)
 //
-//  Steers dependency / who-imports / reuse / component-usage greps toward the
-//  agentmap repo-map instead of serial grep. NON-BLOCKING: only ever injects a
-//  reminder via `additionalContext`; never denies the Grep. Exits 0 on every
-//  path. Dependency-free (Node stdlib only) — Claude Code pipes the tool-call
-//  JSON on stdin.
+//  Steers dependency / who-imports / reuse / component-usage / where-is-symbol
+//  searches toward the agentmap repo-map instead of serial grep. NON-BLOCKING:
+//  only ever injects a reminder via `additionalContext`; never denies the call.
+//  Exits 0 on every path. Dependency-free (Node stdlib only) — Claude Code
+//  pipes the tool-call JSON on stdin.
 //
-//  Heuristic: fires when the grep PATTERN looks like (a) a dependency hunt
+//  Why the Bash branch: the original hook only watched the Grep TOOL, so any
+//  search run as raw `grep`/`rg` via Bash bypassed the nudge entirely — the
+//  exact gap that let an agent forget agentmap and fall back to manual
+//  Read/sed/awk. This closes it.
+//
+//  Heuristic: fires when the search looks like (a) a dependency hunt
 //  (import/require/export / "from '..." / who-imports), (b) a component /
 //  "where-is" / reuse lookup (a JSX component tag like <Heading, or where-is /
-//  who-uses / reuse / existing-component intent words). A raw string or
-//  Tailwind-class search (e.g. "bg-white", "text-3xl") and lowercase HTML-tag
-//  sweeps (<div, <h1) produce NO output — no nagging.
+//  who-uses / reuse / existing-component intent words), (c) — Bash only — a
+//  bare multi-hump PascalCase identifier (ProviderCard, TopProviders), almost
+//  always a "where is this symbol / who uses it" hunt. A raw string or
+//  Tailwind-class search (bg-white, text-3xl) and lowercase HTML-tag sweeps
+//  (<div, <h1) produce NO output — no nagging.
+//
+//  Bash branch only fires when grep/rg/ag is the PRIMARY command (at start, or
+//  after `;` / `&&` — NOT after a pipe, so `… | grep SomeError` log-filtering
+//  stays silent).
 //
-//  agentmap's `--any` router falls back to a live git-grep on its own, so it
-//  still covers the raw-string / copy case — but only when the agent reaches
-//  for it deliberately, not on every content sweep.
+//  Injection-safe: the user's pattern/command is ONLY regex-tested, never
+//  interpolated into the emitted message or executed. Output is a single fixed
+//  JSON object.
 // ============================================================================
 
 let raw = "";
@@ -27,14 +38,8 @@ process.stdin.on("data", (c) => (raw += c));
 process.stdin.on("end", () => {
   try {
     const payload = JSON.parse(raw || "{}");
+    const tool = String(payload.tool_name || "");
     const ti = payload.tool_input || {};
-    const pattern = String(ti.pattern || "");
-
-    // Defensive guard: pathological-input belt-and-suspenders.
-    // If the pattern is unreasonably long, skip nudging entirely.
-    if (pattern.length > 2000) {
-      process.exit(0);
-    }
 
     // (a) Dependency / who-imports / reuse intent signals in the pattern itself.
     const DEP_RE =
@@ -45,11 +50,14 @@ process.stdin.on("end", () => {
     // raw HTML/content sweeps of <div>/<h1> silent, so it stays high-signal for
     // "where is this component used/defined".
     //
-    // Denylist: common TS generic/utility type containers that start with an
-    // uppercase letter but are NOT React components. Without this, a grep for
-    // `<Promise<` or `<Record<string` fires the nudge spuriously.
+    // Denylist: common TS generic/utility type containers (e.g. <Promise<,
+    // <Record<string) that look like a component tag but are NOT React components.
+    // NOT ^-anchored — matches ANYWHERE, because the Bash branch tests the whole
+    // command (the generic sits mid-string, e.g. `rg "<Promise<Foo>"`) and a
+    // generic can also appear mid-pattern in Grep (e.g. useState<Promise>). The
+    // `\b` after the name keeps real components like <PromiseCard / <MapView firing.
     const GENERIC_DENYLIST =
-      /^<(Promise|Array|Map|Set|Record|Partial|Readonly|Pick|Omit|Required|Exclude|Extract|NonNullable|ReturnType|Awaited|Parameters|InstanceType)\b/;
+      /<(Promise|Array|Map|Set|Record|Partial|Readonly|Pick|Omit|Required|Exclude|Extract|NonNullable|ReturnType|Awaited|Parameters|InstanceType)\b/;
     const COMPONENT_TAG_RE = /<[A-Z][\w.]*/;
 
     // (c) Explicit reuse / "where-is" intent words (case-insensitive): "where is",
@@ -58,21 +66,55 @@ process.stdin.on("end", () => {
     const INTENT_RE =
       /\bwhere\s+is\b|\bwho\s+(imports|uses|renders)\b|\breuse\b|\b(existing|shared)\s+(util|component|hook|helper)\b|\bis\s+there\s+(an?\s+)?(existing|shared)\b/i;
 
-    if (
-      pattern &&
-      (DEP_RE.test(pattern) ||
-        (COMPONENT_TAG_RE.test(pattern) && !GENERIC_DENYLIST.test(pattern)) ||
-        INTENT_RE.test(pattern))
-    ) {
+    // (d) Bare multi-hump PascalCase identifier (e.g. ProviderCard, TopProviders).
+    // Bash branch only. Two humps required so all-caps (TODO, API), single-word
+    // (Error, Button) and lowercase (useState) stay silent → high signal, no
+    // Tailwind/raw-string noise.
+    const SYMBOL_RE = /\b[A-Z][a-z0-9]+[A-Z][A-Za-z0-9]*\b/;
+
+    let fire = false;
+
+    if (tool === "Grep") {
+      const pattern = String(ti.pattern || "");
+
+      // Defensive guard: pathological-input belt-and-suspenders.
+      // If the pattern is unreasonably long, skip nudging entirely.
+      if (pattern.length > 2000) {
+        process.exit(0);
+      }
+
+      fire =
+        !!pattern &&
+        (DEP_RE.test(pattern) ||
+          (COMPONENT_TAG_RE.test(pattern) && !GENERIC_DENYLIST.test(pattern)) ||
+          INTENT_RE.test(pattern));
+    } else if (tool === "Bash") {
+      const cmd = String(ti.command || "");
+      // Only when grep/rg/ag is the PRIMARY command (start, or after ; / && — NOT
+      // after a pipe, so `… | grep SomeError` log-filtering stays silent). Then
+      // test the whole command, plus the symbol rule for bare-identifier symbol
+      // hunts.
+      const SEARCHER_RE = /(^|[;&]\s*)(rg|ripgrep|grep|egrep|fgrep|ag|ack)\b/;
+      if (SEARCHER_RE.test(cmd)) {
+        fire =
+          DEP_RE.test(cmd) ||
+          (COMPONENT_TAG_RE.test(cmd) && !GENERIC_DENYLIST.test(cmd)) ||
+          INTENT_RE.test(cmd) ||
+          SYMBOL_RE.test(cmd);
+      }
+    }
+
+    if (fire) {
+      const AM = "node node_modules/@raymondchins/agentmap/agentmap.mjs";
       const msg =
-        "This Grep looks like a dependency / component / who-imports / reuse search. " +
-        "Use agentmap FIRST — it's faster than serial grep. Easiest: " +
-        "`npx @raymondchins/agentmap --any <query>` (or `node agentmap.mjs --any <query>`) " +
-        "— one command, auto-routes file → symbol → feature → live content. " +
-        "Or be specific: `--relates <path>` (blast radius / who-imports), " +
-        "`--find <symbol>` (reuse-before-rebuild / where a component is defined), " +
-        "`--feature <name>` (files in a feature), `--hubs` (most-imported files). " +
-        "Rebuild the map with `npx @raymondchins/agentmap` (or `node agentmap.mjs`) if it's stale. " +
+        "This looks like a dependency / component / who-imports / reuse / where-is-symbol " +
+        "search. Use agentmap FIRST — it's faster than serial grep. Easiest: " +
+        "`" + AM + " --any <query>` " +
+        "(one command — auto-routes file → symbol → feature → live content). " +
+        "Or be specific: `" + AM + " --relates <path>` (blast radius / who-imports), " +
+        "`" + AM + " --find <symbol>` (reuse-before-rebuild / where a component is defined), " +
+        "`" + AM + " --feature <name>` (files in a feature). " +
+        "Rebuild the map with `npm run agentmap` (or `npx @raymondchins/agentmap`) if it's stale. " +
         "Only fall back to grep if agentmap doesn't cover it.";
       process.stdout.write(
         JSON.stringify({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raymondchins/agentmap",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "publishConfig": {
     "access": "public"
   },