ashlr-plugin 1.36.4

package/hooks/orient-nudge-hook.ts

@@ -0,0 +1,242 @@
+#!/usr/bin/env bun
+/**
+ * ashlr orient-nudge PostToolUse hook.
+ *
+ * Detects the "orientation" anti-pattern: 3+ Read/Grep calls inside a rolling
+ * 60s window without an intervening Edit/Write. When detected, nudges the
+ * agent to use the `ashlr__orient` tool, which folds tree scan + grep +
+ * selective reads into a single synthesized call.
+ *
+ * State lives in ~/.ashlr/orient-state.json:
+ *   {
+ *     "pid": 12345,                  // session-scoped: resets when PID changes
+ *     "events": [{ "tool": "Read", "at": 171.. }, ...],
+ *     "lastNudgeAt": 171..            // unix-ms of last nudge (for debounce)
+ *   }
+ *
+ * Hook contract (PostToolUse):
+ *   stdin  → { tool_name, tool_input?, ... }
+ *   stdout → { hookSpecificOutput: { hookEventName: "PostToolUse",
+ *                                    additionalContext?: string } }
+ *
+ * Trigger:
+ *   - On Edit/Write/ashlr__edit: clear events (user is now editing, not
+ *     orienting). Never nudges on these.
+ *   - On Read/Grep/ashlr__read/ashlr__grep: append event, prune to last 60s.
+ *     If window has ≥3 events AND we haven't nudged in past 5 minutes → nudge.
+ *     Note: we fire regardless of whether the grep returned results — the
+ *     signal is "agent is scanning" not "agent found something". That's the
+ *     whole point: empty greps are the most expensive kind of orienting.
+ *
+ * Debounce: after firing, set lastNudgeAt; suppress further nudges for 5 min
+ * even if the agent keeps Read/Grep'ing. The window continues filling up so
+ * once the 5min elapses, if they're still orienting, they get nudged again.
+ *
+ * Opt-out: { "ashlr": { "orientNudge": false } } in ~/.claude/settings.json.
+ *
+ * Design rules:
+ *   - Never throw. Malformed input, fs errors, malformed settings → pass-through.
+ *   - Only Read/Grep/ashlr__read/ashlr__grep append events. Edit/Write/
+ *     ashlr__edit clear. Other tools → pass-through untouched.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+
+import { noteHookError } from "./_hook-errors";
+
+export const READ_TOOL_NAMES = 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",
+]);
+
+export const EDIT_TOOL_NAMES = new Set([
+  "Edit",
+  "Write",
+  "MultiEdit",
+  "mcp__ashlr-efficiency__ashlr__edit",
+  "mcp__plugin_ashlr_ashlr__ashlr__edit",
+  "mcp__plugin_ashlr_ashlr__ashlr__multi_edit",
+  "mcp__plugin_ashlr_ashlr__ashlr__edit_structural",
+  "ashlr__edit",
+]);
+
+export const WINDOW_MS = 60_000;
+export const NUDGE_THRESHOLD = 3;
+export const DEBOUNCE_MS = 5 * 60_000;
+
+export const NUDGE_MESSAGE =
+  "[ashlr] You've done 3+ Read/Grep calls in the last minute without editing. " +
+  "If you're orienting, try `ashlr__orient` with a natural-language query — " +
+  "it runs a tree scan + grep + selective reads in one call with a synthesized answer.";
+
+interface PostToolUsePayload {
+  tool_name?: string;
+  tool_input?: Record<string, unknown>;
+}
+
+export interface OrientEvent {
+  tool: string;
+  at: number;
+}
+
+export interface OrientState {
+  pid: number;
+  events: OrientEvent[];
+  lastNudgeAt?: number;
+}
+
+interface HookOutput {
+  hookSpecificOutput: {
+    hookEventName: "PostToolUse";
+    additionalContext?: string;
+  };
+}
+
+export function passThrough(): HookOutput {
+  return { hookSpecificOutput: { hookEventName: "PostToolUse" } };
+}
+
+export function statePath(home: string = homedir()): string {
+  return join(home, ".ashlr", "orient-state.json");
+}
+
+export function settingsPath(home: string = homedir()): string {
+  return join(home, ".claude", "settings.json");
+}
+
+export function isOptedOut(home: string = homedir()): boolean {
+  try {
+    const p = settingsPath(home);
+    if (!existsSync(p)) return false;
+    const raw = JSON.parse(readFileSync(p, "utf-8")) as {
+      ashlr?: { orientNudge?: unknown };
+    };
+    return raw?.ashlr?.orientNudge === false;
+  } catch (e) {
+    noteHookError("orient-nudge", "settings-parse", e);
+    return false;
+  }
+}
+
+export function loadState(path: string, currentPid: number): OrientState {
+  try {
+    if (!existsSync(path)) return { pid: currentPid, events: [] };
+    const raw = JSON.parse(readFileSync(path, "utf-8")) as Partial<OrientState>;
+    if (typeof raw.pid !== "number" || raw.pid !== currentPid) {
+      return { pid: currentPid, events: [] };
+    }
+    const events = Array.isArray(raw.events)
+      ? raw.events.filter(
+          (e): e is OrientEvent =>
+            !!e &&
+            typeof (e as OrientEvent).tool === "string" &&
+            typeof (e as OrientEvent).at === "number",
+        )
+      : [];
+    const lastNudgeAt =
+      typeof raw.lastNudgeAt === "number" ? raw.lastNudgeAt : undefined;
+    return { pid: currentPid, events, lastNudgeAt };
+  } catch (e) {
+    noteHookError("orient-nudge", "load-state", e);
+    return { pid: currentPid, events: [] };
+  }
+}
+
+export function saveState(path: string, state: OrientState): void {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(state));
+  } catch (e) {
+    noteHookError("orient-nudge", "save-state", e);
+  }
+}
+
+export interface DecideOpts {
+  home?: string;
+  pid?: number;
+  now?: number;
+}
+
+export function decide(
+  payload: PostToolUsePayload,
+  opts: DecideOpts = {},
+): HookOutput {
+  const name = payload?.tool_name;
+  if (!name) return passThrough();
+
+  const home = opts.home ?? homedir();
+  const pid = opts.pid ?? process.pid;
+  const now = opts.now ?? Date.now();
+
+  if (isOptedOut(home)) return passThrough();
+
+  const path = statePath(home);
+  const state = loadState(path, pid);
+
+  // Edit/Write tools end the orientation phase — clear events.
+  if (EDIT_TOOL_NAMES.has(name)) {
+    saveState(path, { pid, events: [], lastNudgeAt: state.lastNudgeAt });
+    return passThrough();
+  }
+
+  // Not a tool we care about.
+  if (!READ_TOOL_NAMES.has(name)) return passThrough();
+
+  // Prune stale events and record this one.
+  const fresh = state.events.filter((e) => now - e.at <= WINDOW_MS);
+  fresh.push({ tool: name, at: now });
+
+  const debounced =
+    typeof state.lastNudgeAt === "number" &&
+    now - state.lastNudgeAt < DEBOUNCE_MS;
+
+  if (fresh.length >= NUDGE_THRESHOLD && !debounced) {
+    saveState(path, { pid, events: fresh, lastNudgeAt: now });
+    return {
+      hookSpecificOutput: {
+        hookEventName: "PostToolUse",
+        additionalContext: NUDGE_MESSAGE,
+      },
+    };
+  }
+
+  saveState(path, { pid, events: fresh, lastNudgeAt: state.lastNudgeAt });
+  return passThrough();
+}
+
+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");
+}
+
+async function main(): Promise<void> {
+  let payload: PostToolUsePayload = {};
+  try {
+    const raw = await readStdin();
+    if (raw.trim()) payload = JSON.parse(raw) as PostToolUsePayload;
+  } catch {
+    process.stdout.write(JSON.stringify(passThrough()));
+    return;
+  }
+  try {
+    process.stdout.write(JSON.stringify(decide(payload)));
+  } catch (e) {
+    noteHookError("orient-nudge", "decide", e);
+    process.stdout.write(JSON.stringify(passThrough()));
+  }
+}
+
+if (import.meta.main) {
+  await main();
+}

package/hooks/policy-enforce.ts

@@ -0,0 +1,214 @@
+#!/usr/bin/env bun
+/**
+ * policy-enforce.ts — PreToolUse hook.
+ *
+ * Runs before every Edit, Write, Bash, MultiEdit call (and ashlr equivalents).
+ * Fetches /policy/current (5-min in-process cache) and applies rules:
+ *
+ *   deny          → exit 2, writes JSON reason to stdout (blocks the tool)
+ *   requireConfirm → writes permissionDecision:"ask" JSON to stdout (Claude prompts user)
+ *   allow / no match → exit 0 silently (proceeds)
+ *
+ * Precedence: deny > requireConfirm > allow.
+ *
+ * Kill switch: set ASHLR_POLICY_ENFORCE=0 to disable entirely.
+ *
+ * Registered in hooks.json:
+ *   PreToolUse matcher: Edit|Write|Bash|MultiEdit|mcp__ashlr-efficiency__ashlr__edit|mcp__ashlr-multi-edit__*
+ */
+
+import { tmpdir } from "os";
+import { join } from "path";
+import { minimatch } from "minimatch";
+import { flushHookTimings, installHookTimeout, recordHookTiming } from "./pretooluse-common";
+import { noteHookError } from "./_hook-errors";
+
+if (import.meta.main) installHookTimeout("policy-enforce");
+
+const hookStartedAt = Date.now();
+let observedTool: string | undefined;
+let outcome: "ok" | "bypass" | "block" | "error" = "ok";
+
+async function exit(code: number): Promise<never> {
+  if (outcome === "ok" && code === 2) outcome = "block";
+  recordHookTiming({
+    hook: "policy-enforce",
+    tool: observedTool,
+    durationMs: Date.now() - hookStartedAt,
+    outcome,
+  });
+  await flushHookTimings();
+  process.exit(code);
+}
+
+const token   = process.env["ASHLR_PRO_TOKEN"];
+const baseUrl = process.env["ASHLR_API_URL"] ?? "https://api.ashlr.ai";
+const enforce = process.env["ASHLR_POLICY_ENFORCE"] !== "0";
+
+if (!token || !enforce) {
+  await exit(0);
+}
+
+// ---------------------------------------------------------------------------
+// In-process policy cache (5-min TTL, reset on each process start — this hook
+// is short-lived, so the "cache" is just a module-level variable reused within
+// a single invocation; for a long-running daemon it would survive across calls)
+// ---------------------------------------------------------------------------
+
+interface PolicyRule {
+  match: string;
+  kind: "tool" | "path" | "shell";
+  reason?: string;
+}
+
+interface PolicyRules {
+  allow: PolicyRule[];
+  deny: PolicyRule[];
+  requireConfirm: PolicyRule[];
+}
+
+interface CachedPolicy {
+  rules: PolicyRules;
+  fetchedAt: number;
+  etag: string;
+}
+
+// Persist cache in a temp file so multiple short-lived hook invocations share it.
+// Use os.tmpdir() + path.join so this works on Windows (where /tmp/ does not
+// exist and the silent failure otherwise disables policy enforcement entirely).
+const CACHE_PATH = join(
+  tmpdir(),
+  `.ashlr-policy-cache-${Buffer.from(token!).toString("base64url").slice(0, 16)}.json`,
+);
+const TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+async function loadCachedPolicy(): Promise<CachedPolicy | null> {
+  try {
+    const raw = await Bun.file(CACHE_PATH).text();
+    const cached = JSON.parse(raw) as CachedPolicy;
+    if (Date.now() - cached.fetchedAt < TTL_MS) return cached;
+  } catch {
+    // Cache miss or parse error
+  }
+  return null;
+}
+
+async function fetchPolicy(): Promise<PolicyRules | null> {
+  const cached = await loadCachedPolicy();
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${token}`,
+  };
+  if (cached) headers["if-none-match"] = cached.etag;
+
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 3000);
+    const res = await fetch(`${baseUrl}/policy/current`, { headers, signal: controller.signal });
+    clearTimeout(timeout);
+
+    if (res.status === 304 && cached) return cached.rules;
+    if (res.status === 404) return null; // No policy configured — allow all
+    if (!res.ok) return cached?.rules ?? null;
+
+    const data = await res.json() as { rules: PolicyRules };
+    const etag = res.headers.get("etag") ?? "";
+    const entry: CachedPolicy = { rules: data.rules, fetchedAt: Date.now(), etag };
+    await Bun.write(CACHE_PATH, JSON.stringify(entry));
+    return entry.rules;
+  } catch (e) {
+    // Network error — fail open (allow) to avoid blocking all tools, but
+    // surface the failure: silent policy bypass is a security concern.
+    noteHookError("policy-enforce", "fetch-policy", e);
+    return cached?.rules ?? null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Read hook input from stdin
+// ---------------------------------------------------------------------------
+
+let payload: Record<string, unknown> = {};
+try {
+  const raw = await Bun.stdin.text();
+  if (raw.trim()) payload = JSON.parse(raw) as Record<string, unknown>;
+} catch {
+  await exit(0);
+}
+
+const toolName  = (payload["tool_name"] as string | undefined) ?? "";
+observedTool = toolName || undefined;
+const toolInput = (payload["tool_input"] as Record<string, unknown> | undefined) ?? {};
+
+// ---------------------------------------------------------------------------
+// Build match subject strings for each rule kind
+// ---------------------------------------------------------------------------
+
+/** Returns true if the rule matches the current tool call. */
+function ruleMatches(rule: PolicyRule): boolean {
+  switch (rule.kind) {
+    case "tool":
+      // Match against tool name, e.g. "mcp__ashlr-*" or "Bash"
+      return minimatch(toolName, rule.match, { nocase: true });
+
+    case "path": {
+      // Extract path arguments from tool input
+      const pathArgs = [
+        toolInput["file_path"],
+        toolInput["path"],
+        toolInput["file"],
+      ].filter((v): v is string => typeof v === "string");
+      return pathArgs.some((p) => minimatch(p, rule.match));
+    }
+
+    case "shell": {
+      // Match against Bash command string
+      const cmd = (toolInput["command"] as string | undefined) ?? "";
+      // Rule like "Bash(rm *)" — extract the inner pattern if present
+      const inner = rule.match.match(/^Bash\((.+)\)$/);
+      const pattern = inner ? inner[1] : rule.match;
+      return minimatch(cmd, pattern!) || cmd.startsWith(pattern!.replace(/\s*\*$/, "").trimEnd());
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Evaluate rules
+// ---------------------------------------------------------------------------
+
+const rules = await fetchPolicy();
+
+if (!rules) {
+  // No policy or fetch failed — allow
+  await exit(0);
+}
+
+// Deny takes highest precedence
+for (const rule of rules!.deny) {
+  if (ruleMatches(rule)) {
+    const reason = rule.reason ?? `Blocked by policy rule: deny ${rule.kind} "${rule.match}"`;
+    process.stdout.write(
+      JSON.stringify({
+        type: "block",
+        reason,
+      }) + "\n",
+    );
+    await exit(2);
+  }
+}
+
+// requireConfirm
+for (const rule of rules!.requireConfirm) {
+  if (ruleMatches(rule)) {
+    const reason = `Policy requires confirmation: ${rule.kind} "${rule.match}"`;
+    process.stdout.write(
+      JSON.stringify({
+        permissionDecision: "ask",
+        reason,
+      }) + "\n",
+    );
+    await exit(0);
+  }
+}
+
+// Allow (explicit or no match) — proceed silently
+await exit(0);

package/hooks/post-tool-use-embedding.ts

@@ -0,0 +1,93 @@
+#!/usr/bin/env bun
+/**
+ * post-tool-use-embedding.ts — Re-embed edited files after ashlr__edit / ashlr__multi_edit.
+ *
+ * PostToolUse hook. Reads the tool result JSON from stdin, extracts the file
+ * path(s), then queues re-embedding in a completely detached child process so
+ * the hook returns immediately (fire-and-forget, < 1 ms impact on tool chain).
+ *
+ * Honors:
+ *   ASHLR_CONTEXT_DB_DISABLE=1  — exits immediately; no-op
+ *   ASHLR_EMBED_URL             — forwarded to child (remote embedder)
+ *   ASHLR_EMBED_MODEL           — forwarded to child
+ */
+
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+import { flushHookTimings, recordHookTiming } from "./pretooluse-common";
+
+const hookStartedAt = Date.now();
+let observedTool: string | undefined;
+let outcome: "ok" | "error" = "ok";
+
+async function exit(code: number): Promise<never> {
+  recordHookTiming({
+    hook: "post-tool-use-embedding",
+    tool: observedTool,
+    durationMs: Date.now() - hookStartedAt,
+    outcome,
+  });
+  await flushHookTimings();
+  process.exit(code);
+}
+
+if (process.env.ASHLR_CONTEXT_DB_DISABLE === "1") await exit(0);
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT ?? resolve(scriptDir, "..");
+
+const chunks: Buffer[] = [];
+process.stdin.on("data", (c: Buffer) => chunks.push(c));
+process.stdin.on("end", async () => {
+  let payload: Record<string, unknown> = {};
+  try {
+    payload = JSON.parse(Buffer.concat(chunks).toString("utf-8")) as Record<string, unknown>;
+  } catch {
+    outcome = "error";
+    await exit(0);
+  }
+  observedTool = (payload.tool_name as string | undefined) || undefined;
+
+  // Extract file paths from tool input (works for both ashlr__edit and ashlr__multi_edit).
+  const paths: string[] = [];
+
+  const input = payload.tool_input as Record<string, unknown> | undefined;
+  if (input) {
+    // ashlr__edit: { path: string }
+    if (typeof input.path === "string") paths.push(input.path);
+    // ashlr__multi_edit: { edits: Array<{ path: string }> }
+    if (Array.isArray(input.edits)) {
+      for (const e of input.edits as Array<Record<string, unknown>>) {
+        if (typeof e.path === "string") paths.push(e.path);
+      }
+    }
+  }
+
+  if (paths.length === 0) await exit(0);
+
+  // Spawn detached worker — inherits env, writes to /dev/null, exits on its own.
+  const workerScript = resolve(pluginRoot, "scripts", "embed-file-worker.ts");
+
+  try {
+    const proc = Bun.spawn(
+      ["bun", "run", workerScript, ...paths],
+      {
+        stdin: "ignore",
+        stdout: "ignore",
+        stderr: "ignore",
+        // detached so it outlives this hook process
+        env: {
+          ...process.env,
+          ASHLR_CONTEXT_DB_DISABLE: process.env.ASHLR_CONTEXT_DB_DISABLE ?? "0",
+        },
+      }
+    );
+    // Don't await — fire-and-forget.
+    proc.unref?.();
+  } catch {
+    outcome = "error";
+    /* best-effort */
+  }
+
+  await exit(0);
+});

package/hooks/post-tool-use-genome.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# ashlr-plugin PostToolUse: auto-propose genome updates.
+#
+# Streams the PostToolUse JSON payload into scripts/genome-auto-propose.ts,
+# which decides whether to append a proposal to the nearest `.ashlrcode/
+# genome/proposals.jsonl`. This is a fire-and-forget observer: it must NEVER
+# block the agent and must NEVER emit output on stdout (the harness reads
+# stdout as hook JSON).
+#
+# Honors:
+#   ASHLR_GENOME_AUTO=0          — env-var kill switch
+#   ~/.ashlr/config.json         — { "genomeAuto": false } disables
+#   ~/.claude/settings.json      — user-level global settings (handled in TS)
+
+set +e
+
+# Short-circuit before we even spawn Bun if the user disabled auto-genome.
+if [ "${ASHLR_GENOME_AUTO:-1}" = "0" ]; then
+  exit 0
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$SCRIPT_DIR")}"
+PROPOSE_TS="$PLUGIN_ROOT/scripts/genome-auto-propose.ts"
+
+# No bun or missing script → pass through without error.
+if ! command -v bun >/dev/null 2>&1; then
+  exit 0
+fi
+if [ ! -f "$PROPOSE_TS" ]; then
+  exit 0
+fi
+
+# Pipe stdin through; suppress stdout so we don't pollute the hook channel.
+bun run "$PROPOSE_TS" >/dev/null 2>&1 || true
+
+exit 0

package/hooks/post-tool-use-genome.ts

@@ -0,0 +1,69 @@
+#!/usr/bin/env bun
+/**
+ * post-tool-use-genome.ts — Cross-platform replacement for post-tool-use-genome.sh.
+ *
+ * Streams the PostToolUse JSON payload into scripts/genome-auto-propose.ts,
+ * which decides whether to append a proposal to the nearest .ashlrcode/genome/
+ * proposals.jsonl. Fire-and-forget: must never block the agent, must never
+ * emit on stdout.
+ *
+ * Honors:
+ *   ASHLR_GENOME_AUTO=0          — env-var kill switch
+ *   ~/.ashlr/config.json         — { "genomeAuto": false } disables
+ */
+
+import { resolve, dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { existsSync } from "fs";
+import { flushHookTimings, recordHookTiming } from "./pretooluse-common";
+
+const hookStartedAt = Date.now();
+let observedTool: string | undefined;
+let outcome: "ok" | "error" = "ok";
+
+async function exit(code: number): Promise<never> {
+  recordHookTiming({
+    hook: "post-tool-use-genome",
+    tool: observedTool,
+    durationMs: Date.now() - hookStartedAt,
+    outcome,
+  });
+  await flushHookTimings();
+  process.exit(code);
+}
+
+if (process.env.ASHLR_GENOME_AUTO === "0") await exit(0);
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT ?? resolve(scriptDir, "..");
+const proposeTs = join(pluginRoot, "scripts", "genome-auto-propose.ts");
+
+if (!existsSync(proposeTs)) await exit(0);
+
+const chunks: Buffer[] = [];
+process.stdin.on("data", (c: Buffer) => chunks.push(c));
+process.stdin.on("end", async () => {
+  const stdin = Buffer.concat(chunks);
+  try {
+    const raw = stdin.toString("utf-8").trim();
+    if (raw) {
+      const p = JSON.parse(raw) as Record<string, unknown>;
+      observedTool = (p.tool_name as string | undefined) || undefined;
+    }
+  } catch {
+    /* best-effort */
+  }
+  try {
+    // Suppress stdout so we don't pollute the hook channel.
+    const proc = Bun.spawn(["bun", "run", proposeTs], {
+      stdin: new Response(stdin),
+      stdout: "ignore",
+      stderr: "ignore",
+    });
+    await proc.exited;
+  } catch {
+    outcome = "error";
+    /* best-effort */
+  }
+  await exit(0);
+});