ashlr-plugin 1.36.4

package/hooks/pretooluse-eco-router.ts

@@ -0,0 +1,196 @@
+#!/usr/bin/env bun
+/**
+ * pretooluse-eco-router.ts — Auto-route question-shaped Task calls to ashlr:ashlr:explore.
+ *
+ * PreToolUse hook. When ASHLR_ECO=1 and the Task tool is invoked without an
+ * explicit subagent_type, AND the prompt starts with a question word, inject
+ * subagent_type: "ashlr:ashlr:explore" into the tool input.
+ *
+ * Question word regex: /^(what|where|how|find|explain|why|which|when|who)\b/i
+ *
+ * If subagent_type is already set, passes through unchanged.
+ * If ASHLR_ECO is not set or is "0", passes through unchanged.
+ * If the tool is not "Task", passes through unchanged.
+ *
+ * Emits nudge event "eco_router_redirected" when a redirect occurs.
+ *
+ * Design:
+ *   - Never blocks (always exits 0).
+ *   - Best-effort stdin parse — falls through on any error.
+ *
+ * Hook contract (PreToolUse):
+ *   stdin  → { tool_name, tool_input? }
+ *   stdout → { hookSpecificOutput: { hookEventName: "PreToolUse", additionalContext? } }
+ *             OR (when injecting): { hookSpecificOutput: { hookEventName: "PreToolUse",
+ *                                    toolInputOverride: { ...original_input, subagent_type: "ashlr:ashlr:explore" } } }
+ */
+
+import { appendFileSync, mkdirSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+
+import { installHookTimeout } from "./pretooluse-common";
+
+if (import.meta.main) installHookTimeout("pretooluse-eco-router");
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface HookOutput {
+  hookSpecificOutput: {
+    hookEventName: "PreToolUse";
+    additionalContext?: string;
+    toolInputOverride?: Record<string, unknown>;
+  };
+}
+
+interface Payload {
+  tool_name?: string;
+  tool_input?: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const QUESTION_RE = /^(what|where|how|find|explain|why|which|when|who)\b/i;
+const TARGET_SUBAGENT = "ashlr:ashlr:explore";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function passThrough(): HookOutput {
+  return { hookSpecificOutput: { hookEventName: "PreToolUse" } };
+}
+
+function home(): string {
+  return (
+    process.env.ASHLR_HOME_OVERRIDE?.trim() ||
+    process.env.HOME ||
+    homedir()
+  );
+}
+
+function emitRedirectEvent(): void {
+  try {
+    const p = join(home(), ".ashlr", "nudge-events.jsonl");
+    mkdirSync(dirname(p), { recursive: true });
+    const line = JSON.stringify({
+      ts: new Date().toISOString(),
+      event: "eco_router_redirected",
+      subagent_type: TARGET_SUBAGENT,
+    });
+    appendFileSync(p, line + "\n", "utf-8");
+  } catch {
+    // best-effort
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Core decision (exported for tests)
+// ---------------------------------------------------------------------------
+
+export interface RouteOpts {
+  /** Override ASHLR_ECO env for testing. */
+  ecoMode?: string;
+}
+
+export interface RouteResult {
+  action: "pass" | "inject";
+  subagent_type?: string;
+  reason?: string;
+}
+
+export function route(payload: Payload, opts: RouteOpts = {}): RouteResult {
+  const eco = opts.ecoMode ?? process.env.ASHLR_ECO;
+
+  // Not in eco mode → pass.
+  if (!eco || eco === "0") {
+    return { action: "pass", reason: "eco_off" };
+  }
+
+  // Not a Task call → pass.
+  if (payload.tool_name !== "Task") {
+    return { action: "pass", reason: "not_task" };
+  }
+
+  const input = payload.tool_input ?? {};
+
+  // Already has subagent_type → respect it, pass through.
+  if (input.subagent_type != null) {
+    return { action: "pass", reason: "subagent_already_set" };
+  }
+
+  // Check if the prompt is question-shaped.
+  const prompt = typeof input.prompt === "string" ? input.prompt.trim() : "";
+  if (!QUESTION_RE.test(prompt)) {
+    return { action: "pass", reason: "not_question_shaped" };
+  }
+
+  return { action: "inject", subagent_type: TARGET_SUBAGENT };
+}
+
+export function buildOutput(payload: Payload, result: RouteResult): HookOutput {
+  if (result.action !== "inject") {
+    return passThrough();
+  }
+
+  const overrideInput: Record<string, unknown> = {
+    ...(payload.tool_input ?? {}),
+    subagent_type: TARGET_SUBAGENT,
+  };
+
+  return {
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      additionalContext:
+        `[ashlr eco] Task routed to ${TARGET_SUBAGENT} (question-shaped prompt, eco mode on).`,
+      toolInputOverride: overrideInput,
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Stdin reading
+// ---------------------------------------------------------------------------
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin as AsyncIterable<Buffer | string>) {
+    chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+  }
+  return Buffer.concat(chunks).toString("utf-8");
+}
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+async function main(): Promise<void> {
+  let payload: Payload = {};
+  try {
+    const raw = await readStdin();
+    if (raw.trim()) payload = JSON.parse(raw) as Payload;
+  } catch {
+    process.stdout.write(JSON.stringify(passThrough()));
+    process.exit(0);
+  }
+
+  try {
+    const result = route(payload);
+    if (result.action === "inject") {
+      emitRedirectEvent();
+    }
+    process.stdout.write(JSON.stringify(buildOutput(payload, result)));
+  } catch {
+    process.stdout.write(JSON.stringify(passThrough()));
+  }
+
+  process.exit(0);
+}
+
+if (import.meta.main) {
+  await main();
+}

package/hooks/pretooluse-edit.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# ashlr-plugin PreToolUse:Edit enforcement hook.
+#
+# Blocks the built-in Edit tool on files larger than 5KB and redirects the
+# agent to ashlr__edit, which applies an in-place strict-by-default
+# search/replace and returns only a compact diff summary — saves ~80% tokens
+# vs shipping the full before+after file contents.
+#
+# Contract (Claude Code PreToolUse):
+#   stdin  → JSON { tool_name, tool_input: { file_path, ... }, ... }
+#   exit 0 → allow the built-in call
+#   exit 2 → block; stderr is shown to the agent as a tool error
+#
+# Exceptions (pass-through):
+#   - File < 5 KB (round-trip cost is small)
+#   - File does not exist (new-file creation via Edit is a rare/edge path;
+#     pass through rather than block a legitimate create)
+#   - Path is inside this plugin's own source tree
+#   - $ASHLR_NO_ENFORCE=1
+#   - tool_input.bypassSummary === true
+
+set -u
+
+THRESHOLD=5120
+
+# Enforcement off by default; see pretooluse-read.sh for the full rationale.
+# Day-to-day nudging/redirecting is handled by the .ts replacement
+# (pretooluse-edit.ts); this .sh stays as a fallback for bun-less shells.
+if [ "${ASHLR_ENFORCE:-0}" != "1" ]; then
+  exit 0
+fi
+if [ "${ASHLR_NO_ENFORCE:-0}" = "1" ]; then
+  exit 0
+fi
+
+STDIN_JSON=$(cat)
+if [ -z "${STDIN_JSON// }" ]; then
+  exit 0
+fi
+
+PARSED=$(printf '%s' "$STDIN_JSON" | bun -e '
+  let raw = "";
+  process.stdin.on("data", (c) => (raw += c));
+  process.stdin.on("end", () => {
+    try {
+      const p = JSON.parse(raw);
+      const name = p?.tool_name ?? "";
+      const input = p?.tool_input ?? {};
+      const fp = typeof input.file_path === "string" ? input.file_path : "";
+      const bypass = input.bypassSummary === true ? "1" : "0";
+      process.stdout.write(`${name}\t${fp}\t${bypass}`);
+    } catch {
+      process.stdout.write("\t\t0");
+    }
+  });
+' 2>/dev/null)
+
+TOOL_NAME="${PARSED%%$'\t'*}"
+REST="${PARSED#*$'\t'}"
+FILE_PATH="${REST%%$'\t'*}"
+BYPASS="${REST##*$'\t'}"
+
+if [ "$TOOL_NAME" != "Edit" ]; then
+  exit 0
+fi
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+if [ "$BYPASS" = "1" ]; then
+  exit 0
+fi
+
+PLUGIN_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+case "$FILE_PATH" in
+  "$PLUGIN_ROOT"/*) exit 0 ;;
+esac
+
+if [ ! -f "$FILE_PATH" ]; then
+  exit 0
+fi
+
+SIZE=$(stat -f%z "$FILE_PATH" 2>/dev/null || stat -c%s "$FILE_PATH" 2>/dev/null || echo 0)
+
+if [ -z "$SIZE" ] || [ "$SIZE" -le "$THRESHOLD" ] 2>/dev/null; then
+  exit 0
+fi
+
+cat >&2 <<EOF
+ashlr: refusing full Edit on large file $FILE_PATH ($SIZE bytes). Call ashlr__edit with diff-format to save ~80% tokens. Set ASHLR_NO_ENFORCE=1 to disable this guard.
+EOF
+exit 2

package/hooks/pretooluse-edit.ts

@@ -0,0 +1,197 @@
+#!/usr/bin/env bun
+/**
+ * pretooluse-edit.ts — Cross-platform replacement for pretooluse-edit.sh.
+ *
+ * v1.18: by default, this hook BLOCKS the native Edit/Write/MultiEdit tools
+ * for existing files larger than 5KB and routes the agent to the matching
+ * ashlr__edit / ashlr__multi_edit MCP tool (diff-format, ~80% token savings).
+ * Set `ASHLR_HOOK_MODE=nudge` to downgrade to a soft `additionalContext`
+ * suggestion (the old v1.17 tool-redirect.ts behavior, absorbed into this
+ * hook after tool-redirect.ts was retired). Set `ASHLR_HOOK_MODE=off` — or
+ * `~/.ashlr/settings.json { toolRedirect: false }` — for total pass-through.
+ *
+ * v1.20.2: extended from Edit-only to Edit/Write/MultiEdit. The original
+ * v1.18 build only matched "Edit", which left ~200 Write calls/day and the
+ * MultiEdit volume completely unrouted. The new matcher in hooks.json fans
+ * Edit|Write|MultiEdit into this hook, and the per-tool branch below maps
+ * each to its ashlr__* equivalent. Write is special-cased: when the file
+ * doesn't exist yet (new-file creation) there's no ashlr equivalent, so we
+ * pass through silently rather than refuse.
+ *
+ * Edit-redirect carries more risk than read-redirect (write semantics), so
+ * the hook is conservative:
+ *   - Only redirects when file size > 5KB (built-in Edit is fine for small
+ *     files; the diff-summary savings don't materialize until payloads grow).
+ *   - Never redirects inside CLAUDE_PLUGIN_ROOT (agents edit plugin code).
+ *   - Never redirects outside cwd (user didn't bring the path into scope).
+ *   - Skips Write on a non-existent path (new-file creation, no equivalent).
+ *
+ * Legacy: `ASHLR_ENFORCE=1` continues to use the exit-2 + stderr protocol
+ * for back-compat with existing harness configs and the hook-timings tests.
+ */
+
+import {
+  buildNudgeContext,
+  buildPassThrough,
+  buildToolRedirectBlock,
+  enforcementDisabled,
+  fileSize,
+  flushHookTimings,
+  getHookModeFor,
+  isInsideCwd,
+  isInsidePluginRoot,
+  parsePayload,
+  pluginRootFrom,
+  readStdin,
+  recordHookTiming,
+} from "./pretooluse-common";
+import { installHookTimeout } from "./pretooluse-common";
+
+if (import.meta.main) installHookTimeout("pretooluse-edit");
+import { recordBlock } from "./_recent-blocks";
+
+// Lowered from 5120 (5KB) to 2048 (2KB) based on 30-day edit distribution:
+// 30.8% of edits were below 5KB (missed savings); dropping to 2KB captures
+// an additional 20.2% of calls (2-5KB bucket) while only passing through
+// 10.6% of volume — the <2KB micro-edits where MCP round-trip overhead
+// would exceed the diff-summary savings.
+const THRESHOLD = 2048;
+/**
+ * ASHLR_EDIT_MIN_CHARS (default 80): minimum combined length of old_string +
+ * new_string for a redirect to fire. Edits below this threshold are too small
+ * to benefit from the diff-format round-trip — at p90 they produce negative
+ * savings because the MCP overhead exceeds the content savings. When a
+ * redirect would otherwise fire but the edit is below this threshold, the hook
+ * logs a `tool_skip_micro_edit` event and passes through to native Edit.
+ */
+const EDIT_MIN_CHARS = (() => {
+  const v = parseInt(process.env.ASHLR_EDIT_MIN_CHARS ?? "", 10);
+  return Number.isFinite(v) && v > 0 ? v : 80;
+})();
+const hookStartedAt = Date.now();
+
+async function exit(code: number, outcome: "ok" | "bypass" | "block" | "error", tool?: string): Promise<never> {
+  recordHookTiming({ hook: "pretooluse-edit", tool, durationMs: Date.now() - hookStartedAt, outcome });
+  await flushHookTimings();
+  process.exit(code);
+}
+
+const raw = await readStdin();
+const payload = parsePayload(raw);
+if (!payload) await exit(0, "ok");
+
+const tool = payload!.tool_name || undefined;
+const HANDLED_TOOLS = new Set(["Edit", "Write", "MultiEdit", "apply_patch", "functions.apply_patch"]);
+if (!HANDLED_TOOLS.has(payload!.tool_name)) await exit(0, "ok", tool);
+
+if (payload!.tool_name === "apply_patch" || payload!.tool_name === "functions.apply_patch") {
+  const mode = getHookModeFor("edit");
+  if (mode === "off") {
+    process.stdout.write(JSON.stringify(buildPassThrough()));
+    await exit(0, "ok", tool);
+  }
+  const nudge = buildNudgeContext(payload!.tool_name, {});
+  process.stdout.write(JSON.stringify(nudge ?? buildPassThrough()));
+  await exit(0, "ok", tool);
+}
+
+if (!payload!.file_path) await exit(0, "ok", tool);
+if (payload!.bypass) await exit(0, "bypass", tool);
+
+const pluginRoot = pluginRootFrom(import.meta.url);
+// Never redirect edits inside the plugin's own tree — agents need direct
+// access to modify plugin files without being rerouted into ashlr__edit.
+if (isInsidePluginRoot(payload!.file_path, pluginRoot)) await exit(0, "ok", tool);
+
+// Per-tool redirect targets. The MCP-prefixed name is the canonical Claude
+// Code tool name; the short name appears in the nudge fallback message.
+const TOOL_TARGETS: Record<string, { mcp: string; short: string; verb: string }> = {
+  Edit:      { mcp: "mcp__plugin_ashlr_ashlr__ashlr__edit",       short: "ashlr__edit",       verb: "Edit" },
+  Write:     { mcp: "mcp__plugin_ashlr_ashlr__ashlr__edit",       short: "ashlr__edit",       verb: "Write" },
+  MultiEdit: { mcp: "mcp__plugin_ashlr_ashlr__ashlr__multi_edit", short: "ashlr__multi_edit", verb: "MultiEdit" },
+};
+const target = TOOL_TARGETS[payload!.tool_name]!;
+
+// Resolve hook mode up-front. "off" short-circuits without touching the
+// filesystem; "nudge" fires for every matched tool regardless of file size
+// (matches the retired tool-redirect.ts behavior where Edit was always nudged).
+const mode = getHookModeFor("edit");
+if (mode === "off") {
+  process.stdout.write(JSON.stringify(buildPassThrough()));
+  await exit(0, "ok", tool);
+}
+if (mode === "nudge") {
+  // Port of the retired hooks/tool-redirect.ts nudge: soft suggestion only,
+  // no permission decision. The built-in tool call proceeds unchanged. The
+  // nudge builder for "Write" returns null on non-existent files (Write of
+  // a new file has no ashlr equivalent), which falls through to passThrough.
+  const nudge = buildNudgeContext(payload!.tool_name, { file_path: payload!.file_path });
+  process.stdout.write(JSON.stringify(nudge ?? buildPassThrough()));
+  await exit(0, "ok", tool);
+}
+
+const size = fileSize(payload!.file_path);
+// Write on a non-existent path = new-file creation. No ashlr equivalent
+// (ashlr__edit needs a search string). Pass through silently — refusing
+// would force the agent into a no-win loop with no fallback.
+if (size === null) await exit(0, "ok", tool);
+if (size! <= THRESHOLD) await exit(0, "ok", tool);
+
+// Micro-edit guard: if the combined old+new content is smaller than
+// EDIT_MIN_CHARS, the diff-format round-trip costs more than it saves.
+// Pass through to native Edit and log a skip event so it's observable.
+// Only fires when we actually have edit content — an Edit payload missing
+// both strings is treated as "unknown size" and falls through to redirect.
+if (payload!.tool_name === "Edit") {
+  const oldLen = payload!.old_string.length;
+  const newLen = payload!.new_string.length;
+  const combined = oldLen + newLen;
+  const haveContent = oldLen > 0 || newLen > 0;
+  if (haveContent && combined < EDIT_MIN_CHARS) {
+    // Emit a skip event to the session log (best-effort, fire-and-forget).
+    import("../servers/_events").then(({ logEvent }) => {
+      logEvent("tool_skip_micro_edit", {
+        tool: "Edit",
+        reason: "micro-edit",
+        extra: { combinedChars: combined, threshold: EDIT_MIN_CHARS },
+      }).catch(() => {});
+    }).catch(() => {});
+    process.stdout.write(JSON.stringify(buildPassThrough()));
+    await exit(0, "ok", tool);
+  }
+}
+
+// Legacy back-compat: `ASHLR_ENFORCE=1` → exit-code-based block on stderr.
+if (!enforcementDisabled()) {
+  process.stderr.write(
+    `ashlr: refusing full ${target.verb} on large file ${payload!.file_path} (${size} bytes). Call ${target.short} with diff-format to save ~80% tokens. Set ASHLR_NO_ENFORCE=1 to disable this guard.\n`,
+  );
+  await exit(2, "block", tool);
+}
+
+// v1.18: default redirect mode. Fall back to nudge for paths outside cwd —
+// never block on files the user didn't explicitly bring into scope.
+if (!isInsideCwd(payload!.file_path)) {
+  const nudge = buildNudgeContext(payload!.tool_name, { file_path: payload!.file_path });
+  process.stdout.write(JSON.stringify(nudge ?? buildPassThrough()));
+  await exit(0, "ok", tool);
+}
+
+// JSON.stringify so Windows path backslashes get escaped — naive template
+// interpolation produced invalid JSON like `"path": "D:\a\..."` which
+// downstream parsers (and the v1.22 nudge tests) couldn't decode.
+const argsJson = payload!.tool_name === "MultiEdit"
+  ? JSON.stringify({ edits: [{ path: payload!.file_path, search: "...", replace: "..." }] })
+  : JSON.stringify({ path: payload!.file_path, search: "...", replace: "...", strict: true });
+const why = payload!.tool_name === "MultiEdit"
+  ? `native MultiEdit echoes the full file; ${target.short} applies all edits atomically and returns one consolidated diff summary (~80% token savings).`
+  : `native ${target.verb} on ${payload!.file_path} (${size} bytes) echoes the full file; ${target.short} applies a strict search/replace and returns only a compact diff summary (~80% token savings).`;
+// Track G: record block for posttooluse-correlate (best-effort, never throws).
+recordBlock({ ts: Date.now(), toolName: payload!.tool_name, filePath: payload!.file_path });
+process.stdout.write(JSON.stringify(buildToolRedirectBlock({
+  mcpToolName: target.mcp,
+  argsJson,
+  why,
+  savingsPct: 80,
+})));
+await exit(0, "block", tool);

package/hooks/pretooluse-glob.ts

@@ -0,0 +1,70 @@
+#!/usr/bin/env bun
+/**
+ * pretooluse-glob.ts — PreToolUse hook for the Glob tool.
+ *
+ * Glob has no direct ashlr__* equivalent, so this hook never blocks.
+ * Its purpose is audit-trail coverage: every Glob invocation is logged to
+ * hook-timings.jsonl so `/ashlr-hook-timings` shows a complete picture of
+ * all built-in tool activity, not just Read/Grep/Edit.
+ *
+ * In nudge mode we emit a soft `additionalContext` reminding the agent that
+ * ashlr__grep can serve many of the same discovery use-cases with genome-
+ * aware ranking. In redirect and off modes we pass through silently.
+ */
+
+import {
+  buildPassThrough,
+  flushHookTimings,
+  getHookModeFor,
+  parsePayload,
+  readStdin,
+  recordHookTiming,
+} from "./pretooluse-common";
+import { installHookTimeout } from "./pretooluse-common";
+
+if (import.meta.main) installHookTimeout("pretooluse-glob");
+
+const hookStartedAt = Date.now();
+
+async function exit(code: number, outcome: "ok" | "bypass" | "block" | "error", tool?: string): Promise<never> {
+  recordHookTiming({ hook: "pretooluse-glob", tool, durationMs: Date.now() - hookStartedAt, outcome });
+  await flushHookTimings();
+  process.exit(code);
+}
+
+const raw = await readStdin();
+const payload = parsePayload(raw);
+if (!payload) await exit(0, "ok");
+
+const tool = payload!.tool_name || undefined;
+if (payload!.tool_name !== "Glob") await exit(0, "ok", tool);
+
+const mode = getHookModeFor("glob");
+if (mode === "nudge") {
+  // Soft suggestion: ashlr__grep can handle many Glob-like discovery queries
+  // with genome-aware ranking when a genome exists.
+  let pattern = "*";
+  try {
+    const parsed = JSON.parse(raw) as { tool_input?: { pattern?: string } };
+    if (typeof parsed?.tool_input?.pattern === "string") pattern = parsed.tool_input.pattern;
+  } catch {
+    /* ignore */
+  }
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        additionalContext:
+          `[ashlr] For file discovery with ranking, consider \`ashlr__grep\` — ` +
+          `when .ashlrcode/genome/ exists it returns the most relevant sections ` +
+          `instead of a flat glob list. Pattern: ${JSON.stringify(pattern)}.`,
+      },
+    }),
+  );
+  await exit(0, "ok", tool);
+}
+
+// redirect or off: pass through silently (Glob has no ashlr equivalent to
+// block toward; audit trail is captured via the timing record above).
+process.stdout.write(JSON.stringify(buildPassThrough()));
+await exit(0, "ok", tool);

package/hooks/pretooluse-grep.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# ashlr-plugin PreToolUse:Grep enforcement hook.
+#
+# Blocks the built-in Grep tool and redirects the agent to ashlr__grep, which
+# routes through genome-aware RAG (when .ashlrcode/genome/ exists) or a
+# truncated ripgrep fallback — saves tokens on every project-level search.
+#
+# Contract (Claude Code PreToolUse):
+#   stdin  → JSON { tool_name, tool_input: { pattern, path?, ... }, ... }
+#   exit 0 → allow the built-in call
+#   exit 2 → block; stderr is shown to the agent as a tool error
+#
+# Exceptions (pass-through):
+#   - $ASHLR_NO_ENFORCE=1 (global escape hatch)
+#   - tool_input.bypassSummary === true (explicit override)
+#   - Search scoped entirely inside the plugin's own source tree
+#
+# Note: We always enforce on project-level Grep. ashlr__grep has a truncated
+# rg fallback when no genome exists, so there is no "small project" exemption
+# — raw rg output streams unbounded matches and is always wasteful relative
+# to ashlr__grep.
+
+set -u
+
+# Enforcement off by default; see pretooluse-read.sh for the full rationale.
+# Day-to-day nudging/redirecting is handled by the .ts replacement
+# (pretooluse-grep.ts); this .sh stays as a fallback for bun-less shells.
+if [ "${ASHLR_ENFORCE:-0}" != "1" ]; then
+  exit 0
+fi
+if [ "${ASHLR_NO_ENFORCE:-0}" = "1" ]; then
+  exit 0
+fi
+
+STDIN_JSON=$(cat)
+if [ -z "${STDIN_JSON// }" ]; then
+  exit 0
+fi
+
+PARSED=$(printf '%s' "$STDIN_JSON" | bun -e '
+  let raw = "";
+  process.stdin.on("data", (c) => (raw += c));
+  process.stdin.on("end", () => {
+    try {
+      const p = JSON.parse(raw);
+      const name = p?.tool_name ?? "";
+      const input = p?.tool_input ?? {};
+      const pattern = typeof input.pattern === "string" ? input.pattern : "";
+      const path = typeof input.path === "string" ? input.path : "";
+      const bypass = input.bypassSummary === true ? "1" : "0";
+      // Escape tabs/newlines in pattern so the shell split stays clean.
+      const safe = pattern.replace(/[\t\n\r]/g, " ");
+      process.stdout.write(`${name}\t${safe}\t${path}\t${bypass}`);
+    } catch {
+      process.stdout.write("\t\t\t0");
+    }
+  });
+' 2>/dev/null)
+
+IFS=$'\t' read -r TOOL_NAME PATTERN SEARCH_PATH BYPASS <<< "$PARSED"
+
+if [ "$TOOL_NAME" != "Grep" ]; then
+  exit 0
+fi
+
+if [ "${BYPASS:-0}" = "1" ]; then
+  exit 0
+fi
+
+# Exempt searches confined to the plugin's own tree.
+PLUGIN_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+if [ -n "${SEARCH_PATH:-}" ]; then
+  case "$SEARCH_PATH" in
+    "$PLUGIN_ROOT"|"$PLUGIN_ROOT"/*) exit 0 ;;
+  esac
+fi
+
+# Escape double-quotes and backslashes for the redirect message.
+SAFE_PATTERN="${PATTERN//\\/\\\\}"
+SAFE_PATTERN="${SAFE_PATTERN//\"/\\\"}"
+
+cat >&2 <<EOF
+ashlr: routing Grep through ashlr__grep for genome-aware retrieval (saves tokens when genome exists, truncates otherwise). Call ashlr__grep with pattern='${SAFE_PATTERN}'. Set ASHLR_NO_ENFORCE=1 to disable this guard.
+EOF
+exit 2