ashlr-plugin 1.36.4

package/hooks/posttooluse-native-nudge.ts

@@ -0,0 +1,205 @@
+#!/usr/bin/env bun
+/**
+ * posttooluse-native-nudge.ts — PostToolUse hook: missed-save nudge.
+ *
+ * Fires AFTER a native Read / Grep / Edit / Write / MultiEdit call completes.
+ * When the tool was called on a file inside cwd (and not inside the plugin
+ * tree) that COULD have been redirected by ashlr but wasn't (either because
+ * ASHLR_HOOK_MODE=nudge or because the cwd-clamp let it through), this hook
+ * emits a `additionalContext` nudge into the next assistant turn.
+ *
+ * Two escalation levels:
+ *   1. Basic missed-save nudge (first time, throttled to 1/min):
+ *        [ashlr nudge] You called native Read on big_file.ts (8.2KB).
+ *        ashlr__read would have returned ~1.6KB. Try
+ *        mcp__plugin_ashlr_ashlr__ashlr__read next time.
+ *
+ *   2. Repeat-offender escalation (3+ calls of same tool in 10 min):
+ *        [ashlr nudge] You've called native Grep 3 times in the last
+ *        10 minutes. ashlr__grep would have saved ~80% on each. Set
+ *        ASHLR_HOOK_MODE=redirect to enforce the swap automatically:
+ *        `bun ${CLAUDE_PLUGIN_ROOT}/scripts/set-hook-mode.ts redirect`.
+ *
+ * Constraints:
+ *   - Only fires in ASHLR_HOOK_MODE=nudge. In redirect mode the PreToolUse
+ *     hook already blocked and explained — double-talk is annoying.
+ *   - Only fires for in-cwd, non-plugin-tree files (mirrors PreToolUse guard).
+ *   - Throttled to ≤1 nudge per 60 seconds (see _nudge-throttle.ts).
+ *   - Kill switch: ASHLR_SESSION_LOG=0.
+ *   - Best-effort: any error → exit 0, no nudge.
+ *
+ * PostToolUse hook contract:
+ *   stdin  → JSON { tool_name, tool_input: { ... }, tool_response: { ... } }
+ *   stdout → JSON { hookSpecificOutput: { hookEventName: "PostToolUse",
+ *                     additionalContext: "..." } }   (nudge)
+ *             OR empty / "{}" (no nudge)
+ *   exit 0 always (never block post-tool execution)
+ */
+
+import { basename } from "path";
+import {
+  flushHookTimings,
+  fileSize,
+  getHookMode,
+  isInsideCwd,
+  isInsidePluginRoot,
+  nudgeVariantIndex,
+  parsePayload,
+  pluginRootFrom,
+  readStdin,
+  recordHookTiming,
+} from "./pretooluse-common";
+import { recordNativeCall } from "./_nudge-throttle";
+
+const hookStartedAt = Date.now();
+
+// Kill switch
+if (process.env.ASHLR_SESSION_LOG === "0") {
+  process.stdout.write("{}");
+  process.exit(0);
+}
+
+async function exit(code: number, outcome: "ok" | "error" = "ok"): Promise<never> {
+  recordHookTiming({
+    hook: "posttooluse-native-nudge",
+    durationMs: Date.now() - hookStartedAt,
+    outcome,
+  });
+  await flushHookTimings();
+  process.exit(code);
+}
+
+/** No-nudge pass-through — write empty JSON and exit 0. */
+async function passThrough(): Promise<never> {
+  process.stdout.write("{}");
+  await exit(0);
+  // unreachable; satisfies `never` return type
+  throw new Error("unreachable");
+}
+
+// Tool → ashlr equivalent mapping
+const NATIVE_TO_ASHLR: Record<string, { ashlrTool: string; mcpTool: string; savingsPct: number }> = {
+  Read:      { ashlrTool: "ashlr__read",       mcpTool: "mcp__plugin_ashlr_ashlr__ashlr__read",       savingsPct: 80 },
+  Grep:      { ashlrTool: "ashlr__grep",       mcpTool: "mcp__plugin_ashlr_ashlr__ashlr__grep",       savingsPct: 80 },
+  Edit:      { ashlrTool: "ashlr__edit",       mcpTool: "mcp__plugin_ashlr_ashlr__ashlr__edit",       savingsPct: 60 },
+  Write:     { ashlrTool: "ashlr__edit",       mcpTool: "mcp__plugin_ashlr_ashlr__ashlr__edit",       savingsPct: 60 },
+  MultiEdit: { ashlrTool: "ashlr__multi_edit", mcpTool: "mcp__plugin_ashlr_ashlr__ashlr__multi_edit", savingsPct: 60 },
+};
+
+const READ_THRESHOLD = 2048; // bytes — mirrors pretooluse-read.ts
+
+// Parse stdin
+const raw = await readStdin();
+let payload: Record<string, unknown> = {};
+try {
+  payload = JSON.parse(raw) as Record<string, unknown>;
+} catch {
+  await passThrough();
+}
+
+const toolName = payload.tool_name as string | undefined;
+if (!toolName) await passThrough();
+
+const equiv = NATIVE_TO_ASHLR[toolName as string];
+if (!equiv) await passThrough();
+
+// Only fire in nudge mode — redirect mode already blocked + explained.
+if (getHookMode() !== "nudge") await passThrough();
+
+// Extract file path from tool_input
+const toolInput = (payload.tool_input ?? {}) as Record<string, unknown>;
+const filePath = (toolInput.file_path as string | undefined)
+  ?? (toolInput.path as string | undefined)
+  ?? "";
+
+// For Read: only nudge on files above the threshold (tiny reads have no savings).
+if (toolName === "Read") {
+  if (!filePath) await passThrough();
+  const size = fileSize(filePath);
+  if (size === null || size <= READ_THRESHOLD) await passThrough();
+}
+
+// For Grep: always try (no size guard needed).
+// For Edit/Write/MultiEdit: only nudge when filePath is present.
+if ((toolName === "Edit" || toolName === "Write" || toolName === "MultiEdit") && !filePath) {
+  await passThrough();
+}
+
+// Safety: only nudge for in-cwd, non-plugin-tree paths.
+const pluginRoot = pluginRootFrom(import.meta.url);
+if (filePath) {
+  if (isInsidePluginRoot(filePath, pluginRoot)) await passThrough();
+  if (!isInsideCwd(filePath)) await passThrough();
+}
+
+// Throttle check + repeat-offender detection.
+const { emitNudge, emitEscalation, recentCallCount } = recordNativeCall(toolName as string);
+
+if (!emitNudge && !emitEscalation) await passThrough();
+
+// Build the nudge message.
+let nudgeText: string;
+const pluginRoot2 = process.env.CLAUDE_PLUGIN_ROOT ?? pluginRoot;
+
+if (emitEscalation) {
+  // Escalation: 3+ same-tool calls in 10 min — give actionable set-hook-mode instruction.
+  const escalationVariants = [
+    `[ashlr nudge] ${recentCallCount}x native ${toolName} in 10 min — ${equiv.ashlrTool} saves ~${equiv.savingsPct}% each. ` +
+      `Enforce: \`bun ${pluginRoot2}/scripts/set-hook-mode.ts redirect\`.`,
+    `[ashlr nudge] You've used native ${toolName} ${recentCallCount} times (last 10 min). ` +
+      `${equiv.mcpTool} would save ~${equiv.savingsPct}% per call. ` +
+      `Auto-redirect: \`bun ${pluginRoot2}/scripts/set-hook-mode.ts redirect\`.`,
+    `[ashlr nudge] ${recentCallCount} native ${toolName} calls = missed savings. ` +
+      `Set ASHLR_HOOK_MODE=redirect or run \`bun ${pluginRoot2}/scripts/set-hook-mode.ts redirect\` once.`,
+  ];
+  nudgeText = escalationVariants[nudgeVariantIndex(`${toolName}:${recentCallCount}`, escalationVariants.length)];
+} else {
+  // Basic missed-save nudge — include exact size + MCP tool name to call.
+  if (toolName === "Read" && filePath) {
+    const size = fileSize(filePath);
+    const sizeKb = size !== null ? (size / 1024).toFixed(1) + "KB" : "?KB";
+    const compactKb = size !== null
+      ? ((size * (1 - equiv.savingsPct / 100)) / 1024).toFixed(1) + "KB"
+      : "~20%";
+    const fname = basename(filePath) || filePath;
+    const variants = [
+      `[ashlr nudge] ${fname} (${sizeKb}) — ${equiv.mcpTool} returns ~${compactKb} instead. Call it next time.`,
+      `[ashlr nudge] Native Read on ${fname} (${sizeKb}) costs ${equiv.savingsPct}% extra tokens. ` +
+        `Use ${equiv.mcpTool} { "path": "${filePath}" }.`,
+      `[ashlr nudge] ${equiv.ashlrTool} on ${fname}: ${sizeKb} → ~${compactKb}. ` +
+        `${equiv.mcpTool} { "path": "${filePath}" }.`,
+    ];
+    nudgeText = variants[nudgeVariantIndex(filePath, variants.length)];
+  } else if (toolName === "Grep") {
+    const pattern = (toolInput.pattern as string | undefined) ?? "<pattern>";
+    const variants = [
+      `[ashlr nudge] ${equiv.mcpTool} saves ~${equiv.savingsPct}% on Grep (genome-aware or compressed rg). ` +
+        `{ "pattern": ${JSON.stringify(pattern)} }.`,
+      `[ashlr nudge] Native Grep → raw output. ${equiv.ashlrTool} filters to relevant chunks (~${equiv.savingsPct}% smaller). ` +
+        `${equiv.mcpTool} { "pattern": ${JSON.stringify(pattern)} }.`,
+      `[ashlr nudge] Use ${equiv.mcpTool} instead of Grep — genome routing or truncated ripgrep, ~${equiv.savingsPct}% savings.`,
+    ];
+    nudgeText = variants[nudgeVariantIndex(pattern, variants.length)];
+  } else {
+    // Edit / Write / MultiEdit
+    const fname = filePath ? (basename(filePath) || filePath) : "<file>";
+    const variants = [
+      `[ashlr nudge] ${equiv.mcpTool} on ${fname} returns only a diff (~${equiv.savingsPct}% less than native ${toolName}).`,
+      `[ashlr nudge] Native ${toolName} echoes the full file; ${equiv.ashlrTool} returns compact diff only. ` +
+        `Try ${equiv.mcpTool} { "path": "${filePath}" }.`,
+      `[ashlr nudge] ${fname} — ${equiv.ashlrTool} saves ~${equiv.savingsPct}% by returning a diff summary. ` +
+        `${equiv.mcpTool} { "path": "${filePath}", "search": ..., "replace": ... }.`,
+    ];
+    nudgeText = variants[nudgeVariantIndex(filePath || fname, variants.length)];
+  }
+}
+
+const output = {
+  hookSpecificOutput: {
+    hookEventName: "PostToolUse",
+    additionalContext: nudgeText,
+  },
+};
+
+process.stdout.write(JSON.stringify(output));
+await exit(0);

package/hooks/posttooluse-stale-result.ts

@@ -0,0 +1,277 @@
+#!/usr/bin/env bun
+/**
+ * posttooluse-stale-result.ts — Track ashlr tool results for multi-turn staleness.
+ *
+ * PostToolUse hook. Records every ashlr__read / ashlr__grep / Read / Grep result
+ * into the per-session history JSONL so the freshness tracker can later identify
+ * stale accumulation.
+ *
+ * Also fires the once-per-session adaptive nudge when stale bytes exceed 50 KB.
+ *
+ * Design:
+ *   - Best-effort only — never throws, always exits 0.
+ *   - Kill switch: ASHLR_SESSION_LOG=0 disables everything.
+ *   - Only tracks read-class tools (Read, Grep, ashlr__read, ashlr__grep).
+ *     Edit/Write results don't accumulate stale read content.
+ *
+ * Hook contract (PostToolUse):
+ *   stdin  → { tool_name, tool_input?, tool_result? }
+ *   stdout → { hookSpecificOutput: { hookEventName: "PostToolUse",
+ *                                    additionalContext?: string } }
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+
+import {
+  recordResult,
+  readHistory,
+  resolveSessionId,
+  staleByteTotal,
+  STALE_BYTES_NUDGE_THRESHOLD,
+} from "../servers/_history-tracker";
+import { logPreCompactionNudgeEvent } from "../servers/_telemetry";
+// logMultiTurnStaleEvent removed in v1.30 (1.5) — multi_turn_stale_estimate was never populated.
+
+// ---------------------------------------------------------------------------
+// Tools to track
+// ---------------------------------------------------------------------------
+
+const TRACKED_TOOLS = new Set([
+  "Read",
+  "Grep",
+  "mcp__ashlr-efficiency__ashlr__read",
+  "mcp__ashlr-efficiency__ashlr__grep",
+  "mcp__plugin_ashlr_ashlr__ashlr__read",
+  "mcp__plugin_ashlr_ashlr__ashlr__grep",
+  "ashlr__read",
+  "ashlr__grep",
+]);
+
+// ---------------------------------------------------------------------------
+// Pre-compaction nudge constants
+// ---------------------------------------------------------------------------
+
+/** Token estimate heuristic: 4 bytes per token. */
+const BYTES_PER_TOKEN = 4;
+
+/** Fire the pre-compaction nudge when estimated tokens exceed this. */
+const PRECOMPACT_TOKEN_THRESHOLD = 65_000;
+
+/** Assumed auto-compact ceiling (used for percentage display). */
+const AUTOCOMPACT_TOKEN_CEILING = 80_000;
+
+// ---------------------------------------------------------------------------
+// Pre-compaction nudge state (once-per-session file flag)
+// ---------------------------------------------------------------------------
+
+function precompactNudgePath(homeDir: string, sessionId: string): string {
+  return join(homeDir, ".ashlr", "precompact-fired", sessionId);
+}
+
+function hasPrecompactNudgeFired(sessionId: string, homeDir: string): boolean {
+  try {
+    return existsSync(precompactNudgePath(homeDir, sessionId));
+  } catch {
+    return false;
+  }
+}
+
+function markPrecompactNudgeFired(sessionId: string, homeDir: string): void {
+  try {
+    const p = precompactNudgePath(homeDir, sessionId);
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, String(Date.now()), "utf-8");
+  } catch {
+    // Best-effort.
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Stale nudge state
+// ---------------------------------------------------------------------------
+
+function staleNudgePath(homeDir: string): string {
+  return join(homeDir, ".ashlr", "stale-nudge-state.json");
+}
+
+interface StaleNudgeState {
+  sessionId: string;
+  firedAt: number;
+}
+
+function hasNudgeFiredThisSession(sessionId: string, homeDir: string): boolean {
+  try {
+    const p = staleNudgePath(homeDir);
+    if (!existsSync(p)) return false;
+    const raw = JSON.parse(readFileSync(p, "utf-8")) as Partial<StaleNudgeState>;
+    return raw.sessionId === sessionId;
+  } catch {
+    return false;
+  }
+}
+
+function markNudgeFired(sessionId: string, homeDir: string, now: number): void {
+  try {
+    const p = staleNudgePath(homeDir);
+    mkdirSync(dirname(p), { recursive: true });
+    const state: StaleNudgeState = { sessionId, firedAt: now };
+    writeFileSync(p, JSON.stringify(state), "utf-8");
+  } catch {
+    // Best-effort.
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Result content extraction
+// ---------------------------------------------------------------------------
+
+function extractContent(payload: Record<string, unknown>): string {
+  const result = payload.tool_result ?? payload.tool_response ?? payload.tool_output;
+  if (result == null) return "";
+  if (typeof result === "string") return result;
+  try { return JSON.stringify(result); } catch { return ""; }
+}
+
+// ---------------------------------------------------------------------------
+// Hook output type
+// ---------------------------------------------------------------------------
+
+interface HookOutput {
+  hookSpecificOutput: {
+    hookEventName: "PostToolUse";
+    additionalContext?: string;
+  };
+}
+
+function passThrough(): HookOutput {
+  return { hookSpecificOutput: { hookEventName: "PostToolUse" } };
+}
+
+// ---------------------------------------------------------------------------
+// Main decision function (exported for tests)
+// ---------------------------------------------------------------------------
+
+export interface ProcessOpts {
+  home?: string;
+  sessionId?: string;
+  now?: number;
+}
+
+export function decide(
+  payload: Record<string, unknown>,
+  opts: ProcessOpts = {},
+): HookOutput {
+  if (process.env.ASHLR_SESSION_LOG === "0") return passThrough();
+
+  const toolName = payload?.tool_name;
+  if (typeof toolName !== "string" || !TRACKED_TOOLS.has(toolName)) {
+    return passThrough();
+  }
+
+  const homeDir =
+    opts.home ??
+    (process.env.ASHLR_HOME_OVERRIDE?.trim() || process.env.HOME || homedir());
+  const sessionId = opts.sessionId ?? resolveSessionId();
+  const now = opts.now ?? Date.now();
+
+  // Record this result in the history JSONL.
+  const content = extractContent(payload);
+  recordResult(toolName, content, sessionId, homeDir, now);
+
+  // -------------------------------------------------------------------------
+  // 2B — Pre-compaction nudge: warn once when cumulative bytes approach
+  //       the auto-compact ceiling (~80K tokens).
+  // -------------------------------------------------------------------------
+  if (!hasPrecompactNudgeFired(sessionId, homeDir)) {
+    try {
+      const allEntries = readHistory(sessionId, homeDir);
+      const cumulativeBytes = allEntries.reduce((acc, e) => acc + e.sizeBytes, 0);
+      const estimatedTokens = Math.floor(cumulativeBytes / BYTES_PER_TOKEN);
+      if (estimatedTokens > PRECOMPACT_TOKEN_THRESHOLD) {
+        const pct = Math.min(100, Math.round((estimatedTokens / AUTOCOMPACT_TOKEN_CEILING) * 100));
+        markPrecompactNudgeFired(sessionId, homeDir);
+        try {
+          logPreCompactionNudgeEvent({ cumulativeBytes, estimatedTokens, pct });
+        } catch {
+          // Telemetry never blocks.
+        }
+        const precompactNudge =
+          `[ashlr] context approaching auto-compact (~${pct}% of 80K). ` +
+          `Run /ashlr-compact now to dedupe stale results before lag hits.`;
+        return {
+          hookSpecificOutput: {
+            hookEventName: "PostToolUse",
+            additionalContext: precompactNudge,
+          },
+        };
+      }
+    } catch {
+      // Best-effort — never block tool call.
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Stale-result nudge (original behaviour)
+  // -------------------------------------------------------------------------
+
+  // Check if stale bytes exceed nudge threshold.
+  if (hasNudgeFiredThisSession(sessionId, homeDir)) return passThrough();
+
+  const { staleBytes, staleResults, sessionTurnCount } = staleByteTotal(sessionId, homeDir);
+
+  if (staleBytes < STALE_BYTES_NUDGE_THRESHOLD) return passThrough();
+
+  // Fire the once-per-session adaptive nudge.
+  markNudgeFired(sessionId, homeDir, now);
+
+  const staleKb = Math.round(staleBytes / 1024);
+  const nudge =
+    `[ashlr] ~${staleKb} KB of stale tool output is accumulating in this session ` +
+    `(${staleResults} result${staleResults === 1 ? "" : "s"} from 5+ turns ago). ` +
+    `Run \`/ashlr-compact\` to surface a recompression plan.`;
+
+  return {
+    hookSpecificOutput: {
+      hookEventName: "PostToolUse",
+      additionalContext: nudge,
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// 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: Record<string, unknown> = {};
+  try {
+    const raw = await readStdin();
+    if (raw.trim()) payload = JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    process.stdout.write(JSON.stringify(passThrough()));
+    return;
+  }
+  try {
+    process.stdout.write(JSON.stringify(decide(payload)));
+  } catch {
+    process.stdout.write(JSON.stringify(passThrough()));
+  }
+}
+
+if (import.meta.main) {
+  await main();
+}

package/hooks/pretooluse-bash.ts

@@ -0,0 +1,63 @@
+#!/usr/bin/env bun
+/**
+ * pretooluse-bash.ts — Nudges the agent toward ashlr__bash for shell commands
+ * that produce verbose output.
+ *
+ * Unlike pretooluse-{read,grep,edit}, this hook NEVER blocks regardless of
+ * ASHLR_HOOK_MODE. Bash has no 1:1 equivalent for arbitrary commands —
+ * forcing every shell call through MCP would strand the agent on commands
+ * that aren't in the summarizer registry, and changes how output renders to
+ * the user (MCP tool result vs. inline shell output). Nudge-only keeps the
+ * UX intact while letting the model voluntarily pick ashlr__bash for the
+ * commands where compression actually pays off.
+ *
+ * The nudge fires only when `findSummarizer(command)` returns non-null OR
+ * `isLargeDiffCommand(command)` returns true — i.e., commands where
+ * ashlr__bash would actually run a structured summarizer or LLM-compress the
+ * stdout. Quiet commands (echo, pwd, mv, rm) pass through silently.
+ *
+ * `ASHLR_HOOK_MODE=off` (or the legacy `~/.ashlr/settings.json
+ * { toolRedirect: false }` killswitch) disables the nudge entirely.
+ */
+
+import {
+  buildNudgeContext,
+  buildPassThrough,
+  flushHookTimings,
+  getHookModeFor,
+  parsePayload,
+  readStdin,
+  recordHookTiming,
+} from "./pretooluse-common";
+import { installHookTimeout } from "./pretooluse-common";
+
+if (import.meta.main) installHookTimeout("pretooluse-bash");
+
+const hookStartedAt = Date.now();
+
+async function exit(code: number, outcome: "ok" | "bypass" | "block" | "error", tool?: string): Promise<never> {
+  recordHookTiming({ hook: "pretooluse-bash", 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 handledTools = new Set(["Bash", "exec_command", "functions.exec_command"]);
+if (!handledTools.has(payload!.tool_name)) await exit(0, "ok", tool);
+if (!payload!.command) await exit(0, "ok", tool);
+
+const mode = getHookModeFor("bash");
+if (mode === "off") {
+  process.stdout.write(JSON.stringify(buildPassThrough()));
+  await exit(0, "ok", tool);
+}
+
+// buildNudgeContext("Bash", ...) returns null when the command isn't in the
+// summarizer registry — passing through silently in that case is intentional.
+const nudge = buildNudgeContext("Bash", { command: payload!.command });
+process.stdout.write(JSON.stringify(nudge ?? buildPassThrough()));
+await exit(0, "ok", tool);