ashlr-plugin 1.36.4

package/hooks/pretooluse-grep.ts

@@ -0,0 +1,96 @@
+#!/usr/bin/env bun
+/**
+ * pretooluse-grep.ts — Cross-platform replacement for pretooluse-grep.sh.
+ *
+ * v1.18: by default, this hook BLOCKS the native Grep tool and routes the
+ * agent to ashlr__grep (genome-aware RAG or truncated rg fallback). 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.
+ *
+ * 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,
+  flushHookTimings,
+  getHookModeFor,
+  isInsideCwd,
+  isInsidePluginRoot,
+  parsePayload,
+  pluginRootFrom,
+  readStdin,
+  recordHookTiming,
+} from "./pretooluse-common";
+import { installHookTimeout } from "./pretooluse-common";
+
+if (import.meta.main) installHookTimeout("pretooluse-grep");
+import { recordBlock } from "./_recent-blocks";
+
+const hookStartedAt = Date.now();
+
+async function exit(code: number, outcome: "ok" | "bypass" | "block" | "error", tool?: string): Promise<never> {
+  recordHookTiming({ hook: "pretooluse-grep", 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 !== "Grep") await exit(0, "ok", tool);
+if (payload!.bypass) await exit(0, "bypass", tool);
+
+const pluginRoot = pluginRootFrom(import.meta.url);
+// Never redirect a Grep that's explicitly scoped inside the plugin tree —
+// agents editing the plugin itself need direct access to rg behavior.
+if (payload!.search_path && isInsidePluginRoot(payload!.search_path, pluginRoot)) {
+  await exit(0, "ok", tool);
+}
+
+// Legacy back-compat: `ASHLR_ENFORCE=1` → exit-code-based block on stderr.
+if (!enforcementDisabled()) {
+  const safePattern = payload!.pattern.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+  process.stderr.write(
+    `ashlr: routing Grep through ashlr__grep for genome-aware retrieval (saves tokens when genome exists, truncates otherwise). Call ashlr__grep with pattern="${safePattern}". Set ASHLR_NO_ENFORCE=1 to disable this guard.\n`,
+  );
+  await exit(2, "block", tool);
+}
+
+// v1.18: default redirect mode. If the caller supplied a search_path that
+// lies outside cwd, fall back to nudge — never block on paths the user
+// didn't explicitly bring into scope. Grep without a path implicitly runs
+// in cwd, which is fine to redirect.
+const mode = getHookModeFor("grep");
+const outOfScope = !!payload!.search_path && !isInsideCwd(payload!.search_path);
+if (mode === "off") {
+  process.stdout.write(JSON.stringify(buildPassThrough()));
+  await exit(0, "ok", tool);
+}
+if (mode === "nudge" || outOfScope) {
+  const nudge = buildNudgeContext("Grep", { pattern: payload!.pattern });
+  process.stdout.write(JSON.stringify(nudge ?? buildPassThrough()));
+  await exit(0, "ok", tool);
+}
+
+// Track G: record block for posttooluse-correlate (best-effort, never throws).
+recordBlock({ ts: Date.now(), toolName: "Grep", pattern: payload!.pattern });
+// JSON.stringify so Windows path backslashes (search_path) and any
+// special characters in the pattern are escaped properly.
+const argsJson = payload!.search_path
+  ? JSON.stringify({ pattern: payload!.pattern, path: payload!.search_path })
+  : JSON.stringify({ pattern: payload!.pattern });
+process.stdout.write(JSON.stringify(buildToolRedirectBlock({
+  mcpToolName: "mcp__plugin_ashlr_ashlr__ashlr__grep",
+  argsJson,
+  why: "native Grep returns ~10× more bytes; ashlr__grep is genome-aware and uses LLM summarization for large result sets.",
+  savingsPct: 80,
+})));
+await exit(0, "block", tool);

package/hooks/pretooluse-notebookedit.ts

@@ -0,0 +1,121 @@
+#!/usr/bin/env bun
+/**
+ * pretooluse-notebookedit.ts — PreToolUse hook for the NotebookEdit tool.
+ *
+ * v1.22 (Track C): promoted from audit-only to redirect. The redirect target
+ * `ashlr__notebook_edit` now exists and returns a compressed cell-window
+ * response instead of echoing the full notebook state.
+ *
+ * Redirect applies only when:
+ *   - hook mode is "redirect" (default)
+ *   - the notebook path is inside cwd (same safety rule as pretooluse-edit)
+ *
+ * Pass-through when:
+ *   - hook mode is "nudge" or "off"
+ *   - path is outside cwd (can't redirect safely)
+ *   - NotebookEdit is called on a non-existent file (edge case, let Claude Code handle it)
+ */
+
+import {
+  buildNudgeContext,
+  buildPassThrough,
+  buildRedirectBlock,
+  flushHookTimings,
+  getHookModeFor,
+  isInsideCwd,
+  isInsidePluginRoot,
+  parsePayload,
+  pluginRootFrom,
+  readStdin,
+  recordHookTiming,
+} from "./pretooluse-common";
+import { installHookTimeout } from "./pretooluse-common";
+
+if (import.meta.main) installHookTimeout("pretooluse-notebookedit");
+
+const hookStartedAt = Date.now();
+
+async function exit(code: number, outcome: "ok" | "bypass" | "block" | "error", tool?: string): Promise<never> {
+  recordHookTiming({ hook: "pretooluse-notebookedit", 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 !== "NotebookEdit") await exit(0, "ok", tool);
+if (payload!.bypass) await exit(0, "bypass", tool);
+
+// NotebookEdit uses `notebook_path` in its input — check both field names for
+// robustness since the harness payload shape may vary across Claude Code versions.
+const rawInput = (() => {
+  try {
+    const p = JSON.parse(raw);
+    return p?.tool_input ?? {};
+  } catch {
+    return {};
+  }
+})();
+const notebookPath: string =
+  typeof rawInput.notebook_path === "string"
+    ? rawInput.notebook_path
+    : typeof rawInput.file_path === "string"
+      ? rawInput.file_path
+      : "";
+
+const pluginRoot = pluginRootFrom(import.meta.url);
+if (isInsidePluginRoot(notebookPath, pluginRoot)) await exit(0, "ok", tool);
+
+// NotebookEdit redirect target `ashlr__notebook_edit` exists as of v1.22. In
+// redirect mode we block and route. In nudge mode we hint at the canonical
+// MCP name. In off mode we pass through silently.
+const mode = getHookModeFor("notebookedit");
+if (mode === "off") {
+  process.stdout.write(JSON.stringify(buildPassThrough()));
+  await exit(0, "ok", tool);
+}
+
+if (mode === "nudge") {
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        additionalContext:
+          `[ashlr] For notebook cell edits, prefer mcp__plugin_ashlr_ashlr__ashlr__notebook_edit — ` +
+          `it applies the edit and returns only the edited cell and its immediate neighbors ` +
+          `instead of echoing the full notebook state. ` +
+          `Call shape: { "notebookPath": "<path>", "cellIndex": <n>, "newSource": "..." }.`,
+      },
+    }),
+  );
+  await exit(0, "ok", tool);
+}
+
+// redirect mode: block and route to ashlr__notebook_edit.
+if (!notebookPath || !isInsideCwd(notebookPath)) {
+  // Outside cwd or path unknown — nudge only, don't block.
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        additionalContext:
+          `[ashlr] For notebook cell edits, prefer \`ashlr__notebook_edit\` — ` +
+          `it returns only a cell-window summary instead of the full notebook.`,
+      },
+    }),
+  );
+  await exit(0, "ok", tool);
+}
+
+const mcp = "mcp__plugin_ashlr_ashlr__ashlr__notebook_edit";
+const reason =
+  `[ashlr] To bypass: set ASHLR_HOOK_MODE=nudge in ~/.ashlr/config.json. ` +
+  `Current rule: blocking built-in NotebookEdit on ${notebookPath || "<notebook>"} — ` +
+  `call ${mcp} instead, which applies the cell edit and returns only the edited cell ` +
+  `plus one cell above and below (full notebook never echoed). ` +
+  `Equivalent call: { "notebookPath": "${notebookPath}", "cellIndex": <n>, "newSource": "..." }.`;
+process.stdout.write(JSON.stringify(buildRedirectBlock(reason)));
+await exit(0, "block", tool);

package/hooks/pretooluse-read.sh

@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+# ashlr-plugin PreToolUse:Read enforcement hook.
+#
+# Blocks the built-in Read tool on files larger than 2KB and redirects the
+# agent to ashlr__read, which returns a snipCompact-truncated view (head +
+# tail, elided middle) saving ~60-95% of tokens on large files.
+#
+# 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 < 2 KB (no meaningful savings)
+#   - File does not exist or cannot be stat'd (let built-in produce the real error)
+#   - Path is inside this plugin's own source tree (dogfooding / self-edits)
+#   - $ASHLR_NO_ENFORCE=1 (global escape hatch)
+#   - tool_input.bypassSummary === true (explicit override by agent)
+#
+# Design notes:
+#   - Uses `bun -e` for JSON parsing (bun is already a plugin dependency).
+#   - Single stat call, no other subprocess work, typical runtime <30ms.
+
+set -u
+
+THRESHOLD=2048
+
+# Enforcement is OFF by default. The hard-block via `exit 2` was too
+# aggressive — it interrupted the user in `bypassPermissions` mode when all
+# they wanted was a silent suggestion. The .ts replacement (pretooluse-read.ts)
+# now covers both the redirect (JSON deny) and nudge (additionalContext)
+# paths; this .sh is kept only for environments that can't run bun hooks.
+#
+# To re-enable hard enforcement (e.g. on CI where you want zero tolerance
+# for full-file reads), set ASHLR_ENFORCE=1. `ASHLR_NO_ENFORCE=1` remains
+# honored for backwards compatibility with anyone scripting against the
+# old flag name.
+if [ "${ASHLR_ENFORCE:-0}" != "1" ]; then
+  exit 0
+fi
+if [ "${ASHLR_NO_ENFORCE:-0}" = "1" ]; then
+  exit 0
+fi
+
+# Slurp stdin JSON; malformed or empty → pass-through.
+STDIN_JSON=$(cat)
+if [ -z "${STDIN_JSON// }" ]; then
+  exit 0
+fi
+
+# Parse tool_name, file_path, bypassSummary via bun. Output is tab-separated:
+#   <tool_name>\t<file_path>\t<bypassSummary>
+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'}"
+
+# Only enforce on Read. Any other tool name → pass-through (defensive).
+if [ "$TOOL_NAME" != "Read" ]; then
+  exit 0
+fi
+
+# Missing or empty path → let built-in handle it.
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Explicit bypass by caller.
+if [ "$BYPASS" = "1" ]; then
+  exit 0
+fi
+
+# Plugin's own source tree is exempt (users editing the plugin itself).
+PLUGIN_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+case "$FILE_PATH" in
+  "$PLUGIN_ROOT"/*) exit 0 ;;
+esac
+
+# File must exist and be a regular file to enforce; else pass-through.
+if [ ! -f "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Portable stat: macOS uses -f%z, Linux uses -c%s.
+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
+
+# Rough token-savings estimate: snipCompact keeps ~head+tail (~1KB), so savings
+# are approximately (SIZE - 1024) / 4 tokens (4 bytes/token avg).
+SAVED_BYTES=$(( SIZE - 1024 ))
+SAVED_TOKENS=$(( SAVED_BYTES / 4 ))
+if [ "$SAVED_TOKENS" -lt 0 ]; then SAVED_TOKENS=0; fi
+
+# Block and redirect.
+cat >&2 <<EOF
+ashlr: refusing full Read of $FILE_PATH ($SIZE bytes). Call ashlr__read instead for snipCompact truncation — saves ~${SAVED_TOKENS} tokens. Pass bypassSummary: true on ashlr__read if you truly need the raw file. Set ASHLR_NO_ENFORCE=1 to disable this guard.
+EOF
+exit 2

package/hooks/pretooluse-read.ts

@@ -0,0 +1,118 @@
+#!/usr/bin/env bun
+/**
+ * pretooluse-read.ts — Cross-platform replacement for pretooluse-read.sh.
+ *
+ * v1.18: by default, this hook BLOCKS the native Read tool for files larger
+ * than the snipCompact threshold and routes the agent to ashlr__read instead
+ * ("redirect" mode). Set `ASHLR_HOOK_MODE=nudge` to fall back to a soft
+ * `additionalContext` suggestion (the old v1.17 tool-redirect.ts behavior,
+ * since 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 with no nudge at all.
+ *
+ * Contract (Claude Code PreToolUse):
+ *   stdin  -> JSON { tool_name, tool_input: { file_path, ... }, ... }
+ *   stdout -> JSON { hookSpecificOutput: {
+ *                      hookEventName: "PreToolUse",
+ *                      permissionDecision: "deny",
+ *                      permissionDecisionReason: "..."
+ *                    } }                       (redirect mode, blocks)
+ *   stdout -> JSON { hookSpecificOutput: {
+ *                      hookEventName: "PreToolUse",
+ *                      additionalContext: "..."
+ *                    } }                       (nudge mode)
+ *   stdout -> JSON { hookSpecificOutput: { hookEventName: "PreToolUse" } }
+ *                                              (off mode / pass-through)
+ *   exit 0 -> allow / proceed (with stdout JSON above, if any)
+ *   exit 2 -> legacy block (stderr is shown as a tool error). Only taken
+ *             when `ASHLR_ENFORCE=1` is set — preserved for back-compat with
+ *             harness configurations and the hook-timings test suite.
+ *
+ * Safety: we never block on files outside `cwd` or inside CLAUDE_PLUGIN_ROOT.
+ * Those fall through to a silent pass-through even in redirect mode, so the
+ * agent can edit/read plugin internals and other-project files without being
+ * rerouted into ashlr__*.
+ */
+
+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-read");
+import { recordBlock } from "./_recent-blocks";
+
+const THRESHOLD = 2048;
+const hookStartedAt = Date.now();
+
+async function exit(code: number, outcome: "ok" | "bypass" | "block" | "error", tool?: string): Promise<never> {
+  recordHookTiming({ hook: "pretooluse-read", 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 !== "Read") 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 reads inside the plugin's own tree — agents editing the
+// ashlr-plugin itself need direct access without being rerouted.
+if (isInsidePluginRoot(payload!.file_path, pluginRoot)) await exit(0, "ok", tool);
+
+const size = fileSize(payload!.file_path);
+if (size === null) await exit(0, "ok", tool);
+if (size! <= THRESHOLD) await exit(0, "ok", tool);
+
+// Legacy back-compat: `ASHLR_ENFORCE=1` → exit-code-based block on stderr.
+if (!enforcementDisabled()) {
+  const savedTokens = Math.max(0, Math.floor((size! - 1024) / 4));
+  process.stderr.write(
+    `ashlr: refusing full Read of ${payload!.file_path} (${size} bytes). Call ashlr__read instead for snipCompact truncation — saves ~${savedTokens} tokens. Pass bypassSummary: true on ashlr__read if you truly need the raw file. Set ASHLR_NO_ENFORCE=1 to disable this guard.\n`,
+  );
+  await exit(2, "block", tool);
+}
+
+// v1.18: default redirect mode. Fall back to nudge when the file lies
+// outside cwd (e.g. /tmp, unrelated repos) — we only block paths the user
+// has actually brought into scope.
+const mode = getHookModeFor("read");
+if (mode === "off") {
+  process.stdout.write(JSON.stringify(buildPassThrough()));
+  await exit(0, "ok", tool);
+}
+if (mode === "nudge" || !isInsideCwd(payload!.file_path)) {
+  const nudge = buildNudgeContext("Read", { file_path: payload!.file_path });
+  process.stdout.write(JSON.stringify(nudge ?? buildPassThrough()));
+  await exit(0, "ok", tool);
+}
+
+const savedTokens = Math.max(0, Math.floor((size! - 1024) / 4));
+const savingsPct = Math.min(90, Math.round((savedTokens / Math.max(1, size! / 4)) * 100));
+// Track G: record block for posttooluse-correlate (best-effort, never throws).
+recordBlock({ ts: Date.now(), toolName: "Read", filePath: payload!.file_path });
+process.stdout.write(JSON.stringify(buildToolRedirectBlock({
+  mcpToolName: "mcp__plugin_ashlr_ashlr__ashlr__read",
+  // JSON.stringify so Windows path backslashes are escaped properly.
+  argsJson: JSON.stringify({ path: payload!.file_path }),
+  why: `native Read returns all ${size} bytes; ashlr__read returns snipCompact-truncated view (head + tail, elided middle), saving ~${savedTokens} tokens. Pass bypassSummary:true to get the full file.`,
+  savingsPct,
+})));
+await exit(0, "block", tool);

package/hooks/pretooluse-task.ts

@@ -0,0 +1,130 @@
+#!/usr/bin/env bun
+/**
+ * pretooluse-task.ts — PreToolUse hook for TaskList and TaskGet tools.
+ *
+ * In redirect mode (default) this hook BLOCKS the native TaskList/TaskGet
+ * calls and routes the agent to ashlr__task_list / ashlr__task_get, which
+ * filter, paginate, and truncate task payloads to save tokens.
+ *
+ * TaskCreate and TaskUpdate are NOT intercepted — they're tiny inputs.
+ *
+ * Escape valves (in order of granularity):
+ *   - `ASHLR_TASK_PASSTHROUGH=1` env — pass through TaskList/TaskGet for this
+ *     invocation only. Use from skills like `/deep-work` that orchestrate
+ *     many subagents and need the raw, full task list.
+ *   - `~/.ashlr/settings.json { "hookModes": { "task": "nudge" } }` — soft
+ *     suggestion instead of block, permanently.
+ *   - `ASHLR_HOOK_MODE=nudge` env — same as above but global (all hooks).
+ *   - `ASHLR_HOOK_MODE=off` (or `settings.json { toolRedirect: false }`) —
+ *     total pass-through, all hooks.
+ */
+
+import {
+  buildPassThrough,
+  buildRedirectBlock,
+  flushHookTimings,
+  getHookModeFor,
+  installHookTimeout,
+  parsePayload,
+  readStdin,
+  recordHookTiming,
+} from "./pretooluse-common";
+
+if (import.meta.main) installHookTimeout("pretooluse-task");
+
+const hookStartedAt = Date.now();
+
+async function exit(code: number, outcome: "ok" | "bypass" | "block" | "error", tool?: string): Promise<never> {
+  recordHookTiming({ hook: "pretooluse-task", 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 toolName = payload!.tool_name;
+const tool = toolName || undefined;
+
+if (toolName !== "TaskList" && toolName !== "TaskGet") await exit(0, "ok", tool);
+if (payload!.bypass) await exit(0, "bypass", tool);
+
+// Per-invocation escape valve. Skills that legitimately need the full task
+// list (e.g. multi-agent orchestrators like /deep-work) can set this in their
+// prelude before issuing TaskList/TaskGet.
+if (process.env.ASHLR_TASK_PASSTHROUGH === "1") {
+  process.stdout.write(JSON.stringify(buildPassThrough()));
+  await exit(0, "bypass", tool);
+}
+
+const mode = getHookModeFor("task");
+if (mode === "off") {
+  process.stdout.write(JSON.stringify(buildPassThrough()));
+  await exit(0, "ok", tool);
+}
+
+// Parse tool input for a more helpful redirect message.
+let taskId = "<taskId>";
+let status = "<status>";
+try {
+  const parsed = JSON.parse(raw) as { tool_input?: { task_id?: string; taskId?: string; status?: string } };
+  const input = parsed?.tool_input ?? {};
+  if (typeof input.task_id === "string") taskId = input.task_id;
+  if (typeof input.taskId === "string") taskId = input.taskId;
+  if (typeof input.status === "string") status = input.status;
+} catch {
+  /* ignore */
+}
+
+if (mode === "nudge") {
+  const ashlrTool = toolName === "TaskList" ? "ashlr__task_list" : "ashlr__task_get";
+  const exampleCall =
+    toolName === "TaskList"
+      ? `{ "status": ${JSON.stringify(status !== "<status>" ? status : undefined)} }`
+      : `{ "taskId": ${JSON.stringify(taskId)} }`;
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        additionalContext:
+          `[ashlr] Prefer the MCP tool \`${ashlrTool}\` over the built-in ${toolName}. ` +
+          (toolName === "TaskList"
+            ? "It filters by status/owner, limits to 30 rows by default, and returns a compact column view (taskId, status, subject, ageMin). "
+            : "It snipCompacts descriptions > 2KB and returns a compact structured view. ") +
+          `Call it with ${exampleCall}.`,
+      },
+    }),
+  );
+  await exit(0, "ok", tool);
+}
+
+// Default: redirect mode.
+const escapeValves =
+  `Escape valves: ASHLR_TASK_PASSTHROUGH=1 (one-shot pass-through, ` +
+  `intended for skills like /deep-work that need the full list); ` +
+  `~/.ashlr/settings.json { "hookModes": { "task": "nudge" } } (soft hint ` +
+  `instead of block); ASHLR_HOOK_MODE=nudge (global soft hint).`;
+
+let reason: string;
+if (toolName === "TaskList") {
+  const safeStatus = status.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+  reason =
+    `[ashlr] Blocking the built-in TaskList. Call ` +
+    `mcp__plugin_ashlr_ashlr__ashlr__task_list instead — it filters by status/owner, ` +
+    `limits to 30 rows by default, and returns a compact column view (taskId, status, ` +
+    `subject, ageMin) saving 50-80% tokens on large task lists. ` +
+    `Equivalent call: { "status": "${safeStatus}" }. ` +
+    escapeValves;
+} else {
+  const safeTaskId = taskId.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+  reason =
+    `[ashlr] Blocking the built-in TaskGet. Call ` +
+    `mcp__plugin_ashlr_ashlr__ashlr__task_get instead — it snipCompacts descriptions ` +
+    `> 2KB (head + tail with elision marker) to save tokens on tasks with long bodies. ` +
+    `Equivalent call: { "taskId": "${safeTaskId}" }. ` +
+    escapeValves;
+}
+
+process.stdout.write(JSON.stringify(buildRedirectBlock(reason)));
+await exit(0, "block", tool);

package/hooks/pretooluse-webfetch.ts

@@ -0,0 +1,66 @@
+#!/usr/bin/env bun
+/**
+ * pretooluse-webfetch.ts — PreToolUse hook for the WebFetch tool.
+ *
+ * WebFetch has no ashlr__* equivalent. This hook provides audit-trail
+ * coverage so every WebFetch call appears in hook-timings.jsonl. In nudge
+ * mode it reminds the agent that ashlr__webfetch compresses large HTML
+ * responses, returning only the main content with the boilerplate stripped.
+ *
+ * Never blocks in any mode — WebFetch is a read-only network tool and the
+ * agent must always be able to fetch documentation or API responses.
+ */
+
+import {
+  buildPassThrough,
+  flushHookTimings,
+  getHookModeFor,
+  parsePayload,
+  readStdin,
+  recordHookTiming,
+} from "./pretooluse-common";
+import { installHookTimeout } from "./pretooluse-common";
+
+if (import.meta.main) installHookTimeout("pretooluse-webfetch");
+
+const hookStartedAt = Date.now();
+
+async function exit(code: number, outcome: "ok" | "bypass" | "block" | "error", tool?: string): Promise<never> {
+  recordHookTiming({ hook: "pretooluse-webfetch", 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 !== "WebFetch") await exit(0, "ok", tool);
+
+const mode = getHookModeFor("webfetch");
+if (mode === "nudge") {
+  let url = "<url>";
+  try {
+    const parsed = JSON.parse(raw) as { tool_input?: { url?: string } };
+    if (typeof parsed?.tool_input?.url === "string") url = parsed.tool_input.url;
+  } catch {
+    /* ignore */
+  }
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        additionalContext:
+          `[ashlr] Prefer the MCP tool \`ashlr__webfetch\` over the built-in WebFetch. ` +
+          `It strips HTML boilerplate and returns only the main content, saving tokens ` +
+          `on documentation pages and API references. ` +
+          `Call it with { "url": ${JSON.stringify(url)} }.`,
+      },
+    }),
+  );
+  await exit(0, "ok", tool);
+}
+
+process.stdout.write(JSON.stringify(buildPassThrough()));
+await exit(0, "ok", tool);