ashlr-plugin 1.36.4

package/hooks/pretooluse-common.ts

@@ -0,0 +1,985 @@
+/**
+ * pretooluse-common.ts — Shared helpers for the pretooluse-{read,grep,edit}
+ * hooks. Each hook shells out via its own `bun run` entry in hooks.json, so we
+ * keep this module dependency-free and side-effect-free.
+ *
+ * Every helper is designed around the "fail open" contract: if anything looks
+ * unexpected we let the built-in tool call proceed by exiting 0, rather than
+ * blocking the agent with an error.
+ */
+
+import { existsSync, readFileSync, realpathSync, statSync } from "fs";
+import { homedir } from "os";
+import { resolve, dirname, join, sep } from "path";
+import { fileURLToPath } from "url";
+
+import {
+  findSummarizer,
+  isLargeDiffCommand,
+} from "../servers/_bash-summarizers-registry";
+import {
+  appendHookTimingBatch,
+  HOOK_TIMING_BATCH_MAX_BYTES,
+} from "./_hook-timing-ledger";
+
+/**
+ * True when enforcement is disabled — the hook should exit 0 immediately.
+ *
+ * Enforcement is OFF by default. Only enable when `ASHLR_ENFORCE=1` is set,
+ * and still honor `ASHLR_NO_ENFORCE=1` as a kill switch for back-compat.
+ */
+export function enforcementDisabled(): boolean {
+  return process.env.ASHLR_ENFORCE !== "1" || process.env.ASHLR_NO_ENFORCE === "1";
+}
+
+/** Read the full stdin payload as a UTF-8 string (trimmed). */
+export function readStdin(): Promise<string> {
+  // Parameter name avoids shadowing the `resolve` imported from "path" above.
+  return new Promise((done) => {
+    const chunks: Buffer[] = [];
+    process.stdin.on("data", (c: Buffer) => chunks.push(c));
+    process.stdin.on("end", () => {
+      done(Buffer.concat(chunks).toString("utf-8").trim());
+    });
+  });
+}
+
+export interface PreToolUsePayload {
+  tool_name: string;
+  file_path: string;
+  pattern: string;
+  search_path: string;
+  command: string;
+  bypass: boolean;
+  // v1.22: Edit-specific fields surfaced so the micro-edit guard can size
+  // the proposed change without re-parsing stdin. Empty for non-Edit tools.
+  old_string: string;
+  new_string: string;
+}
+
+/**
+ * Parse a pretooluse JSON payload. Returns null if the input is empty or
+ * malformed (the caller should exit 0 in that case). Missing fields come back
+ * as empty strings / false so call-sites can stay uniform.
+ */
+export function parsePayload(raw: string): PreToolUsePayload | null {
+  if (!raw) return null;
+  try {
+    const p = JSON.parse(raw);
+    const input = p?.tool_input ?? {};
+    const toolName =
+      typeof p?.tool_name === "string"
+        ? p.tool_name
+        : typeof p?.toolName === "string"
+          ? p.toolName
+          : typeof p?.tool === "string"
+            ? p.tool
+            : "";
+    const filePath =
+      typeof input.file_path === "string"
+        ? input.file_path
+        : typeof input.path === "string" && (toolName === "Read" || toolName === "Edit" || toolName === "Write")
+          ? input.path
+          : "";
+    return {
+      tool_name: toolName,
+      file_path: filePath,
+      pattern: typeof input.pattern === "string" ? input.pattern : "",
+      search_path: typeof input.path === "string" ? input.path : "",
+      command:
+        typeof input.command === "string"
+          ? input.command
+          : typeof input.cmd === "string"
+            ? input.cmd
+            : typeof p?.command === "string"
+              ? p.command
+              : typeof p?.cmd === "string"
+                ? p.cmd
+                : "",
+      bypass: input.bypassSummary === true,
+      old_string: typeof input.old_string === "string" ? input.old_string : "",
+      new_string: typeof input.new_string === "string" ? input.new_string : "",
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** Absolute path to the plugin root, derived from the calling hook's URL. */
+export function pluginRootFrom(moduleUrl: string): string {
+  return resolve(dirname(fileURLToPath(moduleUrl)), "..");
+}
+
+/** True when `p` lies inside the plugin's own directory tree. */
+export function isInsidePluginRoot(p: string, pluginRoot: string): boolean {
+  if (!p) return false;
+  if (p === pluginRoot) return true;
+  return p.startsWith(pluginRoot + sep);
+}
+
+/**
+ * True when the absolute path `p` lies inside the working directory `cwd`.
+ * Used by redirect mode as a safety net — we never block tool calls against
+ * paths the user didn't explicitly bring into scope (e.g. /tmp, /etc, other
+ * projects). Falls back to nudge in that case.
+ *
+ * Canonicalizes via realpath when possible so symlinked roots (notably
+ * macOS's /tmp → /private/tmp) match correctly. Plain `resolve()` only
+ * normalizes `..`/`.` segments — it does NOT follow symlinks.
+ */
+
+// ---------------------------------------------------------------------------
+// Memoized realpath — resolves each unique path only once per hook process.
+// Calling realpathSync twice per hook (once for cwd, once for the target) on
+// NFS/cloud-mount drives adds measurable latency when hooks fire 3-5× per MCP
+// call. The cache is process-scoped so test isolation is automatic.
+// ---------------------------------------------------------------------------
+const _realpathCache = new Map<string, string>();
+function cachedRealpath(p: string): string {
+  const cached = _realpathCache.get(p);
+  if (cached !== undefined) return cached;
+  let result: string;
+  try {
+    result = realpathSync(p);
+  } catch {
+    result = p;
+  }
+  _realpathCache.set(p, result);
+  return result;
+}
+
+export function isInsideCwd(p: string, cwd: string = process.cwd()): boolean {
+  if (!p) return false;
+  try {
+    const absP = resolve(p);
+    const absCwd = resolve(cwd);
+    const realP = cachedRealpath(absP);
+    const realCwd = cachedRealpath(absCwd);
+    for (const base of new Set([absCwd, realCwd])) {
+      for (const target of new Set([absP, realP])) {
+        if (target === base) return true;
+        if (target.startsWith(base + sep)) return true;
+      }
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Hook-mode resolution — v1.18 redirect vs. nudge vs. off
+// ---------------------------------------------------------------------------
+//
+// "redirect" (default): PreToolUse hooks BLOCK the native Read/Grep/Edit call
+// and instruct the agent to call the equivalent ashlr__* MCP tool instead.
+// The block is emitted as structured JSON on stdout using the PreToolUse
+// `permissionDecision: "deny"` contract so Claude Code surfaces the reason
+// back to the model without raising a user permission prompt.
+//
+// "nudge" (escape hatch, ASHLR_HOOK_MODE=nudge): preserves the pre-v1.18
+// behavior — the pretooluse hooks never block; instead they inject
+// `additionalContext` as a soft suggestion the model may or may not follow.
+// Previously this was the job of the now-retired hooks/tool-redirect.ts —
+// the nudge text and thresholds have been absorbed into this module so we
+// ship a single PreToolUse hook per tool rather than two.
+//
+// "off" (total pass-through): no block, no nudge. Selected by the legacy
+// `~/.ashlr/settings.json { "toolRedirect": false }` kill switch, or by
+// setting `ASHLR_HOOK_MODE=off` / `hookMode: "off"` in config.json.
+//
+// Priority order (highest first):
+//   1. `ASHLR_HOOK_MODE` env var — "redirect" | "nudge" | "off"
+//   2. `~/.ashlr/config.json` `hookMode` field
+//   3. `~/.ashlr/settings.json` `toolRedirect: false` → resolves to "off"
+//   4. Default: "redirect"
+//
+// Legacy back-compat: `ASHLR_ENFORCE=1` still selects the exit-code-based
+// block path in the individual hooks. That flag is honored independently so
+// older harness configurations (and the pretouse hook-timings tests that
+// spawn with `ASHLR_ENFORCE=1`) keep working unchanged.
+
+export type HookMode = "redirect" | "nudge" | "off";
+
+function normalizeMode(v: unknown): HookMode | null {
+  if (typeof v !== "string") return null;
+  const s = v.trim().toLowerCase();
+  if (s === "redirect" || s === "nudge" || s === "off") return s;
+  return null;
+}
+
+/**
+ * True when the legacy `~/.ashlr/settings.json { toolRedirect: false }` kill
+ * switch is in effect. Absent file, malformed JSON, or any other error →
+ * treated as "not disabled" (safe default).
+ *
+ * This helper was ported from the retired hooks/tool-redirect.ts so the
+ * settings-based opt-out keeps working after that hook is removed.
+ */
+export function isRedirectEnabled(home: string = process.env.HOME ?? homedir()): boolean {
+  try {
+    const settingsPath = join(home, ".ashlr", "settings.json");
+    if (!existsSync(settingsPath)) return true;
+    const raw = JSON.parse(readFileSync(settingsPath, "utf-8")) as {
+      toolRedirect?: boolean;
+    };
+    return raw.toolRedirect !== false;
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * Read a per-hook mode override from settings.json or config.json.
+ * Returns the matching mode if found, or null if no override applies.
+ *
+ * Looks for `{ "hookModes": { "<hookKey>": "redirect" | "nudge" | "off" } }`
+ * in either file. settings.json wins over config.json (per audit feedback —
+ * settings is where users put intent, config is plugin-managed state).
+ */
+function getPerHookOverride(hookKey: string, home: string): HookMode | null {
+  for (const file of ["settings.json", "config.json"]) {
+    try {
+      const p = join(home, ".ashlr", file);
+      if (!existsSync(p)) continue;
+      const raw = JSON.parse(readFileSync(p, "utf-8")) as {
+        hookModes?: Record<string, unknown>;
+      };
+      const m = normalizeMode(raw?.hookModes?.[hookKey]);
+      if (m) return m;
+    } catch {
+      /* ignore — try next file */
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve the active hook mode. Never throws — on any read/parse error we
+ * fall through to the default ("redirect").
+ */
+export function getHookMode(home: string = process.env.HOME ?? homedir()): HookMode {
+  const envMode = normalizeMode(process.env.ASHLR_HOOK_MODE);
+  if (envMode) return envMode;
+  if (process.env.ASHLR_MCP_HOST === "codex-cli") {
+    const codexMode = normalizeMode(process.env.ASHLR_CODEX_HOOK_MODE);
+    return codexMode ?? "nudge";
+  }
+  try {
+    const cfgPath = join(home, ".ashlr", "config.json");
+    if (existsSync(cfgPath)) {
+      const raw = JSON.parse(readFileSync(cfgPath, "utf-8")) as { hookMode?: unknown };
+      const fileMode = normalizeMode(raw?.hookMode);
+      if (fileMode) return fileMode;
+    }
+  } catch {
+    /* ignore — fall through to next check */
+  }
+  // Legacy kill switch: ~/.ashlr/settings.json { toolRedirect: false } → "off"
+  if (!isRedirectEnabled(home)) return "off";
+  return "redirect";
+}
+
+/**
+ * Per-hook variant of {@link getHookMode}. When called with a hook key
+ * like "task" or "read", looks for a per-hook override in
+ * `~/.ashlr/settings.json { "hookModes": { "<key>": "redirect|nudge|off" } }`
+ * (or config.json) before falling back to the global resolution.
+ *
+ * `ASHLR_HOOK_MODE` env still wins as a global panic switch.
+ *
+ * Priority order:
+ *   1. ASHLR_HOOK_MODE env (global panic switch)
+ *   2. hookModes[hookKey] in settings.json
+ *   3. hookModes[hookKey] in config.json
+ *   4. hookMode (global) in config.json
+ *   5. toolRedirect: false in settings.json (legacy → "off")
+ *   6. Default: "redirect"
+ *
+ * Hooks should call this with their own key; tests/back-compat callers
+ * should keep using {@link getHookMode} (no key) for unchanged behavior.
+ */
+export function getHookModeFor(
+  hookKey: string,
+  home: string = process.env.HOME ?? homedir(),
+): HookMode {
+  const envMode = normalizeMode(process.env.ASHLR_HOOK_MODE);
+  if (envMode) return envMode;
+  if (process.env.ASHLR_MCP_HOST === "codex-cli") {
+    const codexMode = normalizeMode(process.env.ASHLR_CODEX_HOOK_MODE);
+    if (codexMode) return codexMode;
+  }
+  const perHook = getPerHookOverride(hookKey, home);
+  if (perHook) return perHook;
+  return getHookMode(home);
+}
+
+/**
+ * File-first variant of {@link getHookMode}. Use from long-lived MCP server
+ * processes whose `process.env.ASHLR_HOOK_MODE` was inherited at spawn time
+ * and may be stale after the user updates their config. Reads the config
+ * file as the source of truth (representing the user's *intent*), falls back
+ * to env only when no file exists, then to legacy / default.
+ *
+ * Hooks themselves should keep using getHookMode() — they need env-first
+ * priority so an explicit per-invocation override (`ASHLR_HOOK_MODE=off bun
+ * run …`) takes effect immediately. The savings opportunity engine and
+ * other diagnostic surfaces should use this function so the UI reflects
+ * the user's current configuration without requiring a Claude Code restart.
+ */
+export function getConfiguredHookMode(home: string = process.env.HOME ?? homedir()): HookMode {
+  try {
+    const cfgPath = join(home, ".ashlr", "config.json");
+    if (existsSync(cfgPath)) {
+      const raw = JSON.parse(readFileSync(cfgPath, "utf-8")) as { hookMode?: unknown };
+      const fileMode = normalizeMode(raw?.hookMode);
+      if (fileMode) return fileMode;
+    }
+  } catch {
+    /* ignore — fall through to env */
+  }
+  const envMode = normalizeMode(process.env.ASHLR_HOOK_MODE);
+  if (envMode) return envMode;
+  if (!isRedirectEnabled(home)) return "off";
+  return "redirect";
+}
+
+/**
+ * Per-hook variant of {@link getConfiguredHookMode}. Reads file as source
+ * of truth (intent) with per-hook override beating global. Mirrors
+ * {@link getHookModeFor} but file-first for use from long-lived MCP server
+ * processes whose env was inherited stale.
+ */
+export function getConfiguredHookModeFor(
+  hookKey: string,
+  home: string = process.env.HOME ?? homedir(),
+): HookMode {
+  const perHook = getPerHookOverride(hookKey, home);
+  if (perHook) return perHook;
+  return getConfiguredHookMode(home);
+}
+
+/**
+ * Hook-output shape for a PreToolUse block that routes the agent to an
+ * ashlr__* MCP tool. Claude Code surfaces `permissionDecisionReason` back to
+ * the model so it can re-issue the call against the suggested tool without
+ * raising a user-facing permission prompt.
+ */
+export interface RedirectBlockOutput {
+  hookSpecificOutput: {
+    hookEventName: "PreToolUse";
+    permissionDecision: "deny";
+    permissionDecisionReason: string;
+  };
+}
+
+/** Build a redirect-block JSON payload. Pure — no side effects. */
+export function buildRedirectBlock(reason: string): RedirectBlockOutput {
+  return {
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: reason,
+    },
+  };
+}
+
+/**
+ * Tool-specific redirect block builder — v1.22 Track E.
+ *
+ * Emits a structured redirect message that Claude can act on immediately:
+ *   1. `bypass` instruction front-loaded (first 60 chars) — v1.21 invariant.
+ *   2. Full canonical MCP tool name so Claude can copy-paste the call.
+ *   3. Pre-filled `args` JSON block ready to substitute into a tool_use.
+ *   4. One-line "why" explaining the savings rationale.
+ *
+ * Format:
+ *   [ashlr bypass: ...] Token savings: ~<N>%. Call this instead:
+ *
+ *     tool_use: mcp__plugin_ashlr_ashlr__ashlr__<tool>
+ *     args: { ... }
+ *
+ *   Why: <savings rationale>
+ *
+ * Style guide for hooks that don't exist in this worktree (Tracks B/C):
+ *   - mcpToolName: full canonical name, e.g. "mcp__plugin_ashlr_ashlr__ashlr__websearch"
+ *   - shortToolName: short form, e.g. "ashlr__websearch"
+ *   - argsJson: single-line JSON args object, e.g. '{ "query": "<your query>" }'
+ *   - why: one sentence, e.g. "native WebSearch returns raw HTML; ashlr__websearch filters to text"
+ *   - savingsPct: estimated token savings (0–100), e.g. 80
+ *   - bypassNote: how to disable this redirect, e.g. "set ASHLR_HOOK_MODE=nudge"
+ */
+export function buildToolRedirectBlock(opts: {
+  mcpToolName: string;
+  argsJson: string;
+  why: string;
+  savingsPct: number;
+  bypassNote?: string;
+}): RedirectBlockOutput {
+  const bypass = opts.bypassNote ?? "set ASHLR_HOOK_MODE=nudge in ~/.ashlr/config.json";
+  const reason =
+    `[ashlr bypass: ${bypass}] ~${opts.savingsPct}% token savings. Call this instead:\n\n` +
+    `  tool_use: ${opts.mcpToolName}\n` +
+    `  args: ${opts.argsJson}\n\n` +
+    `Why: ${opts.why}`;
+  return buildRedirectBlock(reason);
+}
+
+/**
+ * Empty pass-through JSON — used in "off" mode and for out-of-scope paths
+ * where we want Claude Code to proceed with the native tool unaltered.
+ */
+export function buildPassThrough(): {
+  hookSpecificOutput: { hookEventName: "PreToolUse" };
+} {
+  return { hookSpecificOutput: { hookEventName: "PreToolUse" } };
+}
+
+/**
+ * Hook-output shape for a soft nudge — inject `additionalContext` so the
+ * agent sees the ashlr__* suggestion, but NEVER set `permissionDecision`
+ * (doing so would force a permission prompt even in bypassPermissions mode).
+ * The native Read/Grep/Edit call proceeds unchanged.
+ */
+export interface NudgeOutput {
+  hookSpecificOutput: {
+    hookEventName: "PreToolUse";
+    additionalContext: string;
+  };
+}
+
+/**
+ * Size threshold below which Read nudges are skipped — tiny files have
+ * nothing to compact, so we pass through silently. Matches the snipCompact
+ * threshold used by the efficiency-server's ashlr__read implementation.
+ *
+ * Kept as a named constant so it can be overridden in tests and shared
+ * across the redirect + nudge paths for consistency.
+ */
+export const NUDGE_READ_THRESHOLD = 2048;
+
+/**
+ * Pick a nudge variant index by hashing the call-site string.
+ * Produces values 0..N-1 stable across calls with the same key so
+ * repeated nudges on the same file rotate through the phrasing set
+ * rather than always showing the same message.
+ *
+ * @internal
+ */
+export function nudgeVariantIndex(key: string, count: number): number {
+  if (count <= 0) return 0;
+  let h = 0;
+  for (let i = 0; i < key.length; i++) {
+    h = Math.imul(31, h) + key.charCodeAt(i) | 0;
+  }
+  return Math.abs(h) % count;
+}
+
+function nudgeToolName(shortName: string): string {
+  if (process.env.ASHLR_MCP_HOST === "codex-cli") return shortName;
+  if (process.env.ASHLR_MCP_HOST && process.env.ASHLR_MCP_HOST !== "claude-code") return shortName;
+  return `mcp__plugin_ashlr_ashlr__${shortName}`;
+}
+
+/**
+ * Build the `additionalContext` nudge payload for a given tool invocation.
+ * Returns null when the tool is uninteresting (unknown name, tiny file, etc.)
+ * so the caller can fall back to {@link buildPassThrough}.
+ *
+ * Nudge copy is action-specific: each message names the exact MCP tool to call,
+ * includes the file size or pattern where relevant, and stays ≤80 chars of
+ * signal. 3-4 phrasings per tool are rotated by hashing the call-site key
+ * (filePath or pattern) so repeated nudges don't read as identical.
+ *
+ * Never throws. Any filesystem / parse error → null (silent pass-through).
+ */
+export function buildNudgeContext(
+  toolName: string,
+  toolInput: Record<string, unknown>,
+): NudgeOutput | null {
+  switch (toolName) {
+    case "Read": {
+      const filePath =
+        typeof toolInput.file_path === "string" ? toolInput.file_path : null;
+      if (!filePath) return null;
+      const size = fileSize(filePath);
+      if (size === null) return null;
+      if (size <= NUDGE_READ_THRESHOLD) return null;
+      const sizeKb = (size / 1024).toFixed(1);
+      const compactKb = ((size * 0.2) / 1024).toFixed(1);
+      const tool = nudgeToolName("ashlr__read");
+      const variants = [
+        `[ashlr] ashlr__read on this ${sizeKb}KB file returns ~${compactKb}KB (80% less). ` +
+          `Call ${tool} { "path": "${filePath}" }.`,
+        `[ashlr] Native Read echoes all ${sizeKb}KB; ashlr__read returns ~${compactKb}KB (head+tail). ` +
+          `Call ${tool} { "path": "${filePath}" }.`,
+        `[ashlr] ${sizeKb}KB file — prefer ashlr__read (~${compactKb}KB output, 80% savings). ` +
+          `${tool} { "path": "${filePath}" }.`,
+      ];
+      const text = variants[nudgeVariantIndex(filePath, variants.length)];
+      return {
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          additionalContext: text,
+        },
+      };
+    }
+    case "Grep": {
+      const pattern =
+        typeof toolInput.pattern === "string" ? toolInput.pattern : "<pattern>";
+      const tool = nudgeToolName("ashlr__grep");
+      const variants = [
+        `[ashlr] ashlr__grep saves ~80% vs native Grep (genome-aware or truncated ripgrep). ` +
+          `Call ${tool} { "pattern": ${JSON.stringify(pattern)} }.`,
+        `[ashlr] Native Grep returns raw rg output; ashlr__grep compresses to relevant chunks. ` +
+          `${tool} { "pattern": ${JSON.stringify(pattern)} }.`,
+        `[ashlr] Prefer ashlr__grep — genome-aware retrieval or truncated ripgrep, ~80% smaller. ` +
+          `${tool} { "pattern": ${JSON.stringify(pattern)} }.`,
+      ];
+      const text = variants[nudgeVariantIndex(pattern, variants.length)];
+      return {
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          additionalContext: text,
+        },
+      };
+    }
+    case "Edit": {
+      const filePath =
+        typeof toolInput.file_path === "string" ? toolInput.file_path : "<path>";
+      const tool = nudgeToolName("ashlr__edit");
+      const variants = [
+        `[ashlr] ashlr__edit returns a compact diff (~60% smaller than native Edit). ` +
+          `${tool} { "path": "${filePath}", "search": ..., "replace": ..., "strict": true }.`,
+        `[ashlr] Native Edit echoes the full file; ashlr__edit returns only the changed lines. ` +
+          `${tool} { "path": "${filePath}", "search": ..., "replace": ... }.`,
+        `[ashlr] Use ashlr__edit for 60% token savings — strict search/replace + diff output. ` +
+          `${tool} { "path": "${filePath}", "search": ..., "replace": ... }.`,
+      ];
+      const text = variants[nudgeVariantIndex(filePath, variants.length)];
+      return {
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          additionalContext: text,
+        },
+      };
+    }
+    case "Write": {
+      const filePath =
+        typeof toolInput.file_path === "string" ? toolInput.file_path : "<path>";
+      // Only nudge for rewrites of existing files — Write on a new file has
+      // no ashlr equivalent (ashlr__edit requires a search string).
+      if (fileSize(filePath) === null) return null;
+      const tool = nudgeToolName("ashlr__edit");
+      const variants = [
+        `[ashlr] Rewriting existing file — ashlr__edit returns only a diff (~60% less). ` +
+          `${tool} { "path": "${filePath}", "search": ..., "replace": ... }.`,
+        `[ashlr] Native Write echoes the full new file; ashlr__edit returns only changed lines. ` +
+          `${tool} { "path": "${filePath}", "search": ..., "replace": ..., "strict": true }.`,
+        `[ashlr] Prefer ashlr__edit for targeted rewrites — compact diff output, 60% savings. ` +
+          `${tool} { "path": "${filePath}", "search": ..., "replace": ... }.`,
+      ];
+      const text = variants[nudgeVariantIndex(filePath, variants.length)];
+      return {
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          additionalContext: text,
+        },
+      };
+    }
+    case "MultiEdit": {
+      const filePath =
+        typeof toolInput.file_path === "string" ? toolInput.file_path : "<path>";
+      const tool = nudgeToolName("ashlr__multi_edit");
+      const variants = [
+        `[ashlr] ashlr__multi_edit applies all edits atomically and returns one diff summary. ` +
+          `${tool} { "edits": [{ "path": "${filePath}", "search": ..., "replace": ... }] }.`,
+        `[ashlr] Prefer ashlr__multi_edit — atomic apply + consolidated diff, ~60% token savings. ` +
+          `${tool} { "edits": [{ "path": "${filePath}", "search": ..., "replace": ... }] }.`,
+      ];
+      const text = variants[nudgeVariantIndex(filePath, variants.length)];
+      return {
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          additionalContext: text,
+        },
+      };
+    }
+    case "apply_patch":
+    case "functions.apply_patch": {
+      const text =
+        "[ashlr] For large or repeated file edits, consider ashlr__multi_edit after gathering the exact replacements. " +
+        "Keep apply_patch for direct patch application when it is already the shortest path.";
+      return {
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          additionalContext: text,
+        },
+      };
+    }
+    case "Bash": {
+      const command =
+        typeof toolInput.command === "string" ? toolInput.command : "";
+      if (!command) return null;
+      // Only nudge for commands where ashlr__bash can actually compress output.
+      // Quiet commands (echo, pwd, mv, rm, simple greps) pass through silently
+      // so the agent isn't pestered on every shell call. The match is the
+      // same predicate ashlr__bash uses internally to decide whether to apply
+      // a structured summarizer (findSummarizer) or LLM diff compression
+      // (isLargeDiffCommand) — so a nudge here means "real savings are on
+      // the table for this exact command."
+      const matches =
+        findSummarizer(command) !== null || isLargeDiffCommand(command);
+      if (!matches) return null;
+      const tool = nudgeToolName("ashlr__bash");
+      const variants = [
+        `[ashlr] This shell command typically produces verbose output. ` +
+          `Prefer the MCP tool \`ashlr__bash\` — it auto-compresses long stdout ` +
+          `(head + tail with elided middle) and emits structured summaries for ` +
+          `common commands (git status/log, npm/bun install, test runners, ` +
+          `find, ls, ps, docker ps, tsc). Call it with { "command": ${JSON.stringify(command)} }.`,
+        `[ashlr] ashlr__bash compresses verbose stdout (structured summaries for git/npm/bun/tsc). ` +
+          `${tool} { "command": ${JSON.stringify(command)} }.`,
+        `[ashlr] Native Bash returns raw output; ashlr__bash applies head+tail compression + summaries. ` +
+          `${tool} { "command": ${JSON.stringify(command)} }.`,
+      ];
+      const text = variants[nudgeVariantIndex(command, variants.length)];
+      return {
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          additionalContext: text,
+        },
+      };
+    }
+    default:
+      return null;
+  }
+}
+
+/**
+ * Return the file size in bytes, or null if the path isn't a regular file
+ * (doesn't exist, is a dir, permission denied, etc.). Never throws.
+ */
+export function fileSize(filePath: string): number | null {
+  try {
+    const st = statSync(filePath);
+    if (!st.isFile()) return null;
+    return st.size;
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Hook-timing telemetry
+// ---------------------------------------------------------------------------
+//
+// Every PreToolUse hook is a separate subprocess spawned by Claude Code.
+// Users who suspect hooks are slow (common on network-drive projects) have
+// no way to see which hook is the culprit. These helpers append a single
+// JSONL record per invocation to `~/.ashlr/hook-timings.jsonl` so
+// `/ashlr-hook-timings` can surface real p50/p95 numbers.
+//
+// Design rules:
+//   - Never throw. Telemetry that breaks the hook is worse than no telemetry.
+//   - Respect `ASHLR_HOOK_TIMINGS=0` as a kill switch.
+//   - Cap record size — no arbitrary fields from the caller.
+//   - Async + batched: writes are queued in memory and flushed via
+//     setImmediate (end of current event loop turn) + a 1-second interval
+//     guard. On process exit the pending queue is drained synchronously so
+//     short-lived subprocess hooks always persist their record before dying.
+
+/** Resolve the timings log path at call time so tests overriding HOME work. */
+function hookTimingsPath(): string {
+  return join(process.env.HOME ?? homedir(), ".ashlr", "hook-timings.jsonl");
+}
+
+function timingsEnabled(): boolean {
+  return process.env.ASHLR_HOOK_TIMINGS !== "0";
+}
+
+// ---------------------------------------------------------------------------
+// Async write batcher — collects JSONL lines and flushes them as a single
+// appendFile call. setImmediate drains at end of the current event-loop turn;
+// a 1-second interval is a safety net for long-running hooks.
+// On process exit, any remaining lines are written synchronously so that
+// short-lived subprocess hooks (which call process.exit immediately after
+// recording) always persist their record.
+// ---------------------------------------------------------------------------
+let _pending: Array<{ path: string; line: string }> = [];
+let _flushScheduled = false;
+
+const HOOK_TIMING_TEXT_MAX_BYTES = 512;
+const HOOK_TIMING_RECORD_MAX_BYTES = 4096;
+
+/**
+ * Drain the pending queue into a path→concatenated-lines map. Each entry
+ * captured its target path at RECORD time (recordHookTiming), so a deferred
+ * flush — or a concurrent test that swapped process.env.HOME — can never
+ * misroute it. In prod HOME never changes, so this is a single-entry map and
+ * behaviour is identical to the old join(); it only matters for test isolation
+ * (Bun runs test files in one process; deferred flushes used to leak across
+ * files via the shared HOME).
+ */
+function _takePendingByPath(): Map<string, string[]> {
+  const byPath = new Map<string, string[]>();
+  for (const { path, line } of _pending) {
+    const batches = byPath.get(path) ?? [];
+    const last = batches[batches.length - 1];
+    if (
+      last === undefined ||
+      Buffer.byteLength(last, "utf8") + Buffer.byteLength(line, "utf8") > HOOK_TIMING_BATCH_MAX_BYTES
+    ) batches.push(line);
+    else batches[batches.length - 1] = last + line;
+    byPath.set(path, batches);
+  }
+  _pending = [];
+  return byPath;
+}
+let _flushInterval: ReturnType<typeof setInterval> | null = null;
+let _exitHandlerInstalled = false;
+let _activeFlush: Promise<void> | null = null;
+
+interface TimingWorkerResponse {
+  contended: Array<{ path: string; batch: string }>;
+}
+
+function _requeueBatches(entries: Array<{ path: string; batch: string }>): void {
+  if (entries.length === 0) return;
+  _pending = [
+    ...entries.map(({ path, batch }) => ({ path, line: batch })),
+    ..._pending,
+  ];
+}
+
+function _runTimingWorker(entries: Map<string, string[]>): Promise<TimingWorkerResponse> {
+  return new Promise((resolve) => {
+    let settled = false;
+    const all = [...entries].flatMap(([path, batches]) =>
+      batches.map((batch) => ({ path, batch })),
+    );
+    const finish = (response: TimingWorkerResponse) => {
+      if (settled) return;
+      settled = true;
+      resolve(response);
+    };
+    try {
+      const workerUrl = new URL("./_hook-timing-ledger.ts", import.meta.url);
+      workerUrl.searchParams.set("hookTimingWorker", "1");
+      const worker = new Worker(workerUrl.href);
+      worker.onmessage = (event: MessageEvent<TimingWorkerResponse>) => {
+        const response = event.data;
+        void worker.terminate();
+        finish(response);
+      };
+      worker.onerror = () => {
+        void worker.terminate();
+        finish({ contended: all });
+      };
+      worker.postMessage({
+        entries: [...entries].map(([path, batches]) => ({ path, batches })),
+      });
+    } catch {
+      finish({ contended: all });
+    }
+  });
+}
+
+function _writeEntries(entries: Map<string, string[]>): Promise<void> {
+  const prior = _activeFlush;
+  const current = (async () => {
+    if (prior) await prior;
+    const response = await _runTimingWorker(entries);
+    _requeueBatches(response.contended);
+  })();
+  _activeFlush = current;
+  void current.finally(() => {
+    if (_activeFlush === current) _activeFlush = null;
+  });
+  return current;
+}
+
+async function _drainPending(maxAttempts: number): Promise<void> {
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    if (_activeFlush) await _activeFlush;
+    if (_pending.length === 0) return;
+    await _writeEntries(_takePendingByPath());
+    if (_pending.length === 0) return;
+    await new Promise((done) => setTimeout(done, 10));
+  }
+}
+
+function _ensureFlushInterval(): void {
+  if (_flushInterval !== null) return;
+  _flushInterval = setInterval(_flushBatchAsync, 1000);
+  // Don't keep the process alive for the interval alone.
+  if (typeof _flushInterval.unref === "function") _flushInterval.unref();
+}
+
+function _ensureExitHandler(): void {
+  if (_exitHandlerInstalled) return;
+  _exitHandlerInstalled = true;
+  // process.on("exit") fires synchronously on process.exit(); it is the
+  // last chance to do synchronous I/O before the process dies. We drain
+  // any pending lines here so subprocess hooks that call process.exit(0)
+  // immediately after recordHookTiming() always write their record.
+  process.on("exit", () => {
+    if (_pending.length === 0) return;
+    for (const [path, batches] of _takePendingByPath()) {
+      for (const batch of batches) appendHookTimingBatch(path, batch, { lockWaitMs: 0 });
+    }
+  });
+}
+
+function _flushBatchAsync(): void {
+  _flushScheduled = false;
+  if (_pending.length === 0) return;
+  void _drainPending(1);
+}
+
+function truncateUtf8(value: string, maxBytes: number): string {
+  if (Buffer.byteLength(value, "utf8") <= maxBytes) return value;
+  let result = "";
+  let bytes = 0;
+  for (const character of value) {
+    const size = Buffer.byteLength(character, "utf8");
+    if (bytes + size > maxBytes) break;
+    result += character;
+    bytes += size;
+  }
+  return result;
+}
+
+function serializeHookTiming(record: {
+  hook: string;
+  tool?: string;
+  durationMs: number;
+  outcome: HookOutcome;
+}): string {
+  let hook = truncateUtf8(String(record.hook), HOOK_TIMING_TEXT_MAX_BYTES);
+  let tool = record.tool === undefined
+    ? null
+    : truncateUtf8(String(record.tool), HOOK_TIMING_TEXT_MAX_BYTES);
+  const durationMs = Number.isFinite(record.durationMs)
+    ? Math.max(0, Math.round(record.durationMs))
+    : 0;
+  const outcome: HookOutcome = (
+    record.outcome === "ok" ||
+    record.outcome === "bypass" ||
+    record.outcome === "block" ||
+    record.outcome === "error" ||
+    record.outcome === "timeout"
+  ) ? record.outcome : "error";
+  const makeLine = () => JSON.stringify({
+    ts: new Date().toISOString(),
+    hook,
+    tool,
+    durationMs,
+    outcome,
+  }) + "\n";
+  let line = makeLine();
+  while (Buffer.byteLength(line, "utf8") > HOOK_TIMING_RECORD_MAX_BYTES) {
+    hook = truncateUtf8(hook, Math.floor(Buffer.byteLength(hook, "utf8") * 0.75));
+    if (tool !== null) {
+      tool = truncateUtf8(tool, Math.floor(Buffer.byteLength(tool, "utf8") * 0.75));
+    }
+    line = makeLine();
+  }
+  return line;
+}
+
+/**
+ * Record one hook invocation to the timings log. Non-blocking — the write is
+ * queued and flushed asynchronously (or synchronously on process exit). Never
+ * throws.
+ */
+export type HookOutcome = "ok" | "bypass" | "block" | "error" | "timeout";
+
+export function recordHookTiming(record: {
+  hook: string;
+  tool?: string;
+  durationMs: number;
+  outcome: HookOutcome;
+}): void {
+  if (!timingsEnabled()) return;
+  try {
+    const line = serializeHookTiming(record);
+    _pending.push({ path: hookTimingsPath(), line });
+    _ensureFlushInterval();
+    _ensureExitHandler();
+    if (!_flushScheduled) {
+      _flushScheduled = true;
+      setImmediate(_flushBatchAsync);
+    }
+  } catch {
+    /* swallow */
+  }
+}
+
+/**
+ * Flush any pending timing lines. Exposed for tests that need to assert on
+ * file contents without waiting for the async batcher or process exit.
+ * Returns a Promise that resolves once the write completes (or immediately if
+ * the queue is empty).
+ */
+export async function flushHookTimings(): Promise<void> {
+  _flushScheduled = false;
+  await _drainPending(3);
+}
+
+/**
+ * Wrap a hook's main function in timing instrumentation. The callback returns
+ * the hook's outcome classification so the timings log distinguishes
+ * "took 2ms and did nothing" from "took 300ms and blocked the call".
+ */
+export async function withHookTiming<T>(
+  hookName: string,
+  fn: () => Promise<{ value: T; outcome: HookOutcome; tool?: string }>,
+): Promise<T> {
+  const start = Date.now();
+  try {
+    const { value, outcome, tool } = await fn();
+    recordHookTiming({ hook: hookName, tool, durationMs: Date.now() - start, outcome });
+    return value;
+  } catch (err) {
+    recordHookTiming({ hook: hookName, durationMs: Date.now() - start, outcome: "error" });
+    throw err;
+  }
+}
+
+/**
+ * Install a top-level safety timeout for a hook. If the hook hasn't exited
+ * within `timeoutMs`, log a timeout event and force-exit 0 so the user's
+ * tool call isn't blocked indefinitely.
+ *
+ * Call this once at the top of each hook's entry script, before any I/O.
+ * The timer is unref'd so it never extends the hook's natural lifetime —
+ * if the hook completes on its own, the timeout silently goes away.
+ *
+ * Env override: `ASHLR_HOOK_TIMEOUT_MS` (per-process). Default 2000ms.
+ */
+export function installHookTimeout(hookName: string, timeoutMs?: number): void {
+  const envMs = Number(process.env.ASHLR_HOOK_TIMEOUT_MS);
+  const ms = timeoutMs ?? (Number.isFinite(envMs) && envMs > 0 ? envMs : 2000);
+  const start = Date.now();
+  const timer = setTimeout(() => {
+    try {
+      process.stderr.write(
+        `[ashlr ${hookName}] hook timeout — exceeded ${ms}ms, forcing exit 0\n`,
+      );
+      recordHookTiming({
+        hook: hookName,
+        durationMs: Date.now() - start,
+        outcome: "timeout",
+      });
+    } catch {
+      /* never throw from the safety net */
+    }
+    // flushHookTimings is async; give it a tick, then exit unconditionally.
+    void flushHookTimings().finally(() => process.exit(0));
+    // Belt-and-suspenders: if the flush hangs too, kill the process after 200ms.
+    const killer = setTimeout(() => process.exit(0), 200);
+    if (typeof killer.unref === "function") killer.unref();
+  }, ms);
+  if (typeof timer.unref === "function") timer.unref();
+}