karajan-code 3.5.0 → 3.6.0

package/README.md

@@ -23,7 +23,7 @@
 
 ---
 
-> **v3.5.0 released** — Quality harness: `kj harden` brings the guardrails Karajan was built with to any repo in one command — idempotent git hooks, lint/format/commit config, CI quality gates and agent guidelines, all stack-aware and behind `kj:managed` markers that never overwrite your content. Native per-language hook commands mean hardening a Go/Python/Java repo never makes Node a commit-time dependency. `kj check` verifies the harness as a CI drift gate, and `kj init` installs it out of the box. Full notes in [CHANGELOG.md](CHANGELOG.md).
+> **v3.6.0 released** — Advisory harden: `kj harden --report` shows what the kj standard would add to an existing repo (per artifact: missing / yours / kj-managed, plus the concrete improvements), and `kj harden --interactive` lets you adopt it piece by piece, default-safe. Plus scope control (`--only`/`--exclude`, demo/fixture dirs ignored), a rounder `kj init` first run (consistent English, glossed terms, clean close), and the `kj-trash` safety net now actually ships to npm installs. Full notes in [CHANGELOG.md](CHANGELOG.md).
 
 You describe what you want to build. Karajan orchestrates multiple AI agents to plan it, implement it, test it, review it with SonarQube, and iterate. No babysitting required.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -26,6 +26,14 @@
   "engines": {
     "node": ">=22.22.1"
   },
+  "kj": {
+    "harden": {
+      "exclude": [
+        "wrappers",
+        "packages"
+      ]
+    }
+  },
   "workspaces": [
     "packages/ai-trash",
     "packages/core",
@@ -46,6 +54,9 @@
     "packages/hu-board/src/",
     "packages/hu-board/public/",
     "packages/hu-board/package.json",
+    "packages/ai-trash/src/",
+    "packages/ai-trash/bin/",
+    "packages/ai-trash/package.json",
     "docs/karajan-code-logo-small.png",
     "docs/README.es.md",
     "LICENSE",
@@ -54,6 +65,7 @@
   "bin": {
     "kj": "bin/kj.js",
     "kj-tail": "bin/kj-tail",
+    "kj-trash": "packages/ai-trash/bin/kj-trash.js",
     "karajan-mcp": "bin/karajan-mcp.js",
     "kj-rag-mcp": "bin/kj-rag-mcp.js"
   },

package/packages/ai-trash/README.md

@@ -0,0 +1,37 @@
+# @karajan/ai-trash
+
+AI-proof trash: intercept destructive operations from an AI-driven shell
+(`rm -rf`, truncation via `>`, `mv` overwriting, destructive `git` ops, …)
+and snapshot the affected paths to a bin the AI cannot reach before the
+command runs.
+
+Status: **skeleton** — see Karajan epic `KJC-PCS-0041` and the planning
+documents in `docs/ai-trash-fase1-report.md` + `docs/ai-trash-fase2-plan.md`
+of the parent repo.
+
+The MVP is being built incrementally (KJC-TSK-0388). This package currently
+only ships the skeleton (`package.json`, `bin/kj-trash.js`, `src/index.js`).
+
+## Why
+
+Any flow where an LLM has shell access (Claude Code hooks, Cursor, Aider,
+OpenCode, Devin, custom LangChain/AutoGen agents …) shares one risk: the
+agent can issue `rm -rf` on a critical path and there is no undo. `ai-trash`
+puts a snapshot in a place the agent cannot read, write, or `empty` —
+restore is one command away; emptying the bin requires a human factor
+(sudo / TTY / external token).
+
+## Roadmap
+
+1. Manifest + trash-store (ULID, TTL, LRU quota) — KJC-TSK-0388 commit 2
+2. Logger append-only + permissions (linux + macOS) — commit 3
+3. File / directory snapshotter (mv + reflink fallback cp) — commit 4
+4. CLI `list / inspect / restore` + `bin/kj-trash` — commit 5
+5. CLI `empty / purge` with TTY guard — commit 6
+6. Destructive git ops (`reset --hard`, `push --force`, …) — KJC-TSK-0389
+7. Claude Code `PreToolUse` adapter — KJC-TSK-0390
+8. Wiring into `kj doctor` — KJC-TSK-0391
+
+## License
+
+AGPL-3.0 — same as Karajan Code.

package/packages/ai-trash/bin/kj-trash.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { runCli } from "../src/cli.js";
+
+runCli(process.argv.slice(2)).then(
+  (code) => process.exit(code ?? 0),
+  (err) => {
+    process.stderr.write(`kj-trash: ${err?.message ?? err}\n`);
+    process.exit(1);
+  }
+);

package/packages/ai-trash/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@karajan/ai-trash",
+  "version": "0.0.0",
+  "description": "AI-proof trash: intercept destructive ops from an AI shell and snapshot them to an unreachable bin before execution",
+  "type": "module",
+  "license": "AGPL-3.0",
+  "author": "Manu Fosela",
+  "homepage": "https://github.com/manufosela/karajan-code/tree/main/packages/ai-trash#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/manufosela/karajan-code.git",
+    "directory": "packages/ai-trash"
+  },
+  "bugs": {
+    "url": "https://github.com/manufosela/karajan-code/issues"
+  },
+  "keywords": [
+    "ai",
+    "trash",
+    "undo",
+    "snapshot",
+    "safety",
+    "claude-code",
+    "cursor",
+    "aider"
+  ],
+  "engines": {
+    "node": ">=22.22.1"
+  },
+  "bin": {
+    "kj-trash": "bin/kj-trash.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "vitest run"
+  },
+  "private": false
+}

package/packages/ai-trash/src/cli.js

@@ -0,0 +1,198 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import process from "node:process";
+import {
+  loadManifest,
+  saveManifest,
+  removeEntry,
+  expireBefore,
+  enforceLruQuota,
+} from "./manifest.js";
+import { restoreSnapshot, purgeSnapshot } from "./snapshot.js";
+import { restoreGitBundle } from "./git-snapshot.js";
+import { ensureSecureDir, assertOwnedByCurrentUser } from "./permissions.js";
+import { runHook } from "./hook.js";
+import { installClaudeCodeHook, DEFAULT_SETTINGS_PATH } from "./install.js";
+
+export const DEFAULT_ROOT = process.env.AI_TRASH_ROOT || join(homedir(), ".ai-trash");
+
+function parseFlags(argv) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const tok = argv[i];
+    if (tok.startsWith("--")) {
+      const eq = tok.indexOf("=");
+      if (eq > -1) flags[tok.slice(2, eq)] = tok.slice(eq + 1);
+      else if (argv[i + 1] && !argv[i + 1].startsWith("--")) flags[tok.slice(2)] = argv[++i];
+      else flags[tok.slice(2)] = true;
+    } else positional.push(tok);
+  }
+  return { positional, flags };
+}
+
+function shortAge(ms) {
+  const sec = Math.max(1, Math.floor(ms / 1000));
+  if (sec < 60) return `${sec}s`;
+  if (sec < 3600) return `${Math.floor(sec / 60)}m`;
+  if (sec < 86400) return `${Math.floor(sec / 3600)}h`;
+  return `${Math.floor(sec / 86400)}d`;
+}
+
+async function ensureRoot(root) {
+  await ensureSecureDir(root);
+  await assertOwnedByCurrentUser(root);
+}
+
+async function cmdList(root, out) {
+  await ensureRoot(root);
+  const m = await loadManifest(root);
+  if (!m.entries.length) {
+    out.write("kj-trash: (empty)\n");
+    return 0;
+  }
+  const now = Date.now();
+  out.write("ID                          AGE   BYTES  SOURCE\n");
+  for (const e of m.entries) {
+    out.write(
+      `${e.id}  ${shortAge(now - e.createdAt).padStart(4)}  ${String(e.sizeBytes).padStart(5)}  ${e.sourcePath}\n`
+    );
+  }
+  return 0;
+}
+
+async function cmdInspect(root, id, out, err) {
+  await ensureRoot(root);
+  const m = await loadManifest(root);
+  const entry = m.entries.find((e) => e.id === id);
+  if (!entry) {
+    err.write(`kj-trash: no entry with id ${id}\n`);
+    return 1;
+  }
+  out.write(`${JSON.stringify(entry, null, 2)}\n`);
+  return 0;
+}
+
+async function cmdRestore(root, id, target, out, err) {
+  await ensureRoot(root);
+  const m = await loadManifest(root);
+  const entry = m.entries.find((e) => e.id === id);
+  if (!entry) {
+    err.write(`kj-trash: no entry with id ${id}\n`);
+    return 1;
+  }
+  if (entry.type === "git-bundle") {
+    const res = await restoreGitBundle(root, entry, target);
+    out.write(
+      `kj-trash: fetched bundle ${id} -> ${res.repo} (${res.refCount} ref(s) at refs/remotes/restore/*)\n`
+    );
+    return 0;
+  }
+  const written = await restoreSnapshot(root, entry, target);
+  removeEntry(m, id);
+  await saveManifest(root, m);
+  out.write(`kj-trash: restored ${id} -> ${written}\n`);
+  return 0;
+}
+
+async function cmdPurge(root, id, out, err) {
+  await ensureRoot(root);
+  const m = await loadManifest(root);
+  const entry = m.entries.find((e) => e.id === id);
+  if (!entry) {
+    err.write(`kj-trash: no entry with id ${id}\n`);
+    return 1;
+  }
+  await purgeSnapshot(root, entry);
+  removeEntry(m, id);
+  await saveManifest(root, m);
+  out.write(`kj-trash: purged ${id}\n`);
+  return 0;
+}
+
+async function cmdEmpty(root, flags, out) {
+  await ensureRoot(root);
+  const m = await loadManifest(root);
+  let dropped = [];
+  if (flags["older-than-days"]) {
+    const days = Number(flags["older-than-days"]);
+    if (!Number.isFinite(days) || days < 0) throw new Error("--older-than-days must be >= 0");
+    dropped = expireBefore(m, Date.now() - days * 86400 * 1000);
+  } else if (flags["max-bytes"]) {
+    const max = Number(flags["max-bytes"]);
+    if (!Number.isFinite(max) || max < 0) throw new Error("--max-bytes must be >= 0");
+    dropped = enforceLruQuota(m, max);
+  } else {
+    dropped = m.entries.slice();
+    m.entries = [];
+  }
+  for (const e of dropped) await purgeSnapshot(root, e);
+  await saveManifest(root, m);
+  out.write(`kj-trash: emptied ${dropped.length} snapshot(s)\n`);
+  return 0;
+}
+
+const HELP =
+  "usage: kj-trash <command> [args]\n" +
+  "  list                       list snapshots oldest-first\n" +
+  "  inspect <id>               print snapshot metadata as JSON\n" +
+  "  restore <id> [--to PATH]   restore a snapshot (default: original path)\n" +
+  "  purge <id>                 delete a single snapshot\n" +
+  "  empty [--older-than-days N | --max-bytes N]\n" +
+  "                             drop all (or filtered) snapshots\n" +
+  "  hook                       Claude Code PreToolUse handler (reads JSON\n" +
+  "                             on stdin, writes decision JSON on stdout)\n" +
+  "  install --claude-code      patch ~/.claude/settings.json (idempotent)\n" +
+  "env: AI_TRASH_ROOT (default ~/.ai-trash)\n";
+
+export async function runCli(argv, io = {}) {
+  const out = io.out ?? process.stdout;
+  const err = io.err ?? process.stderr;
+  const root = io.root ?? DEFAULT_ROOT;
+  const { positional, flags } = parseFlags(argv);
+  const [cmd, arg1] = positional;
+  switch (cmd) {
+    case "list":
+      return cmdList(root, out);
+    case "inspect":
+      if (!arg1) {
+        err.write("kj-trash: inspect requires <id>\n");
+        return 2;
+      }
+      return cmdInspect(root, arg1, out, err);
+    case "restore":
+      if (!arg1) {
+        err.write("kj-trash: restore requires <id>\n");
+        return 2;
+      }
+      return cmdRestore(root, arg1, typeof flags.to === "string" ? flags.to : undefined, out, err);
+    case "purge":
+      if (!arg1) {
+        err.write("kj-trash: purge requires <id>\n");
+        return 2;
+      }
+      return cmdPurge(root, arg1, out, err);
+    case "empty":
+      return cmdEmpty(root, flags, out);
+    case "hook":
+      return runHook({ root, stdin: io.stdin ?? process.stdin, stdout: out });
+    case "install": {
+      if (!flags["claude-code"]) {
+        err.write("kj-trash: install requires --claude-code\n");
+        return 2;
+      }
+      const path = typeof flags.settings === "string" ? flags.settings : DEFAULT_SETTINGS_PATH;
+      const res = await installClaudeCodeHook({ path });
+      out.write(`kj-trash: ${res.mutated ? "installed" : "already installed"} -> ${res.path}\n`);
+      return 0;
+    }
+    case "help":
+    case "--help":
+    case undefined:
+      out.write(HELP);
+      return cmd ? 0 : 2;
+    default:
+      err.write(`kj-trash: unknown command '${cmd}'\n${HELP}`);
+      return 2;
+  }
+}

package/packages/ai-trash/src/destructive-parser.js

@@ -0,0 +1,74 @@
+// Pure classifier for shell commands the PreToolUse hook receives.
+// Recognises the destructive ops ai-trash will snapshot before they run.
+// Conservative: anything unknown is left as safe, but every destructive
+// shape returns kind+paths so the hook can snapshot before letting it run.
+
+function tokenise(command) {
+  if (Array.isArray(command)) return command.filter((t) => typeof t === "string");
+  if (typeof command !== "string") return [];
+  const out = [];
+  let buf = "", quote = null;
+  for (const ch of command) {
+    if (quote) { if (ch === quote) quote = null; else buf += ch; continue; }
+    if (ch === "'" || ch === '"') { quote = ch; continue; }
+    if (ch === " " || ch === "\t" || ch === "\n") { if (buf) { out.push(buf); buf = ""; } continue; }
+    buf += ch;
+  }
+  if (buf) out.push(buf);
+  return out;
+}
+
+function rmFlags(tokens) {
+  const flags = tokens.filter((t) => t.startsWith("-")).join("");
+  return { recursive: flags.includes("r"), force: flags.includes("f") };
+}
+
+function classifyRm(tokens) {
+  const positional = tokens.slice(1).filter((t) => !t.startsWith("-"));
+  const { recursive, force } = rmFlags(tokens.slice(1));
+  return { destructive: true, kind: "rm", recursive, force, paths: positional, reason: "rm removes files" };
+}
+
+function classifyMv(tokens) {
+  const positional = tokens.slice(1).filter((t) => !t.startsWith("-"));
+  if (positional.length < 2) return { destructive: false, kind: "mv-noop", paths: [], reason: "mv without source/target" };
+  return { destructive: true, kind: "mv-overwrite", paths: positional.slice(-1), reason: "mv may overwrite destination" };
+}
+
+function classifyGit(tokens) {
+  const sub = tokens[1];
+  const has = (...flags) => flags.some((f) => tokens.includes(f));
+  if (sub === "reset" && has("--hard")) return { destructive: true, kind: "git-reset-hard", paths: [], reason: "git reset --hard drops working tree" };
+  if (sub === "clean" && has("-f", "-fd", "-xdf")) return { destructive: true, kind: "git-clean", paths: [], reason: "git clean -f removes untracked files" };
+  if (sub === "branch" && has("-D")) return { destructive: true, kind: "git-branch-D", paths: [], reason: "git branch -D drops unmerged branch" };
+  if (sub === "push" && has("--force", "-f", "--force-with-lease")) return { destructive: true, kind: "git-push-force", paths: [], reason: "git push --force rewrites remote history" };
+  if (sub === "checkout" && has("--", ".")) return { destructive: true, kind: "git-checkout-discard", paths: [], reason: "git checkout -- discards local edits" };
+  return { destructive: false, kind: "git-safe", paths: [], reason: "git op without destructive flags" };
+}
+
+function classifyRedirect(tokens) {
+  for (let i = 0; i < tokens.length; i += 1) {
+    if ((tokens[i] === ">" || tokens[i] === ">|") && tokens[i + 1]) {
+      return { destructive: true, kind: "redirect-clobber", paths: [tokens[i + 1]], reason: "> truncates the target file" };
+    }
+  }
+  return null;
+}
+
+export function classifyCommand(command) {
+  const tokens = tokenise(command);
+  if (!tokens.length) return { destructive: false, kind: "empty", paths: [], reason: "no command" };
+  const redirect = classifyRedirect(tokens);
+  if (redirect) return redirect;
+  const head = tokens[0];
+  if (head === "rm") return classifyRm(tokens);
+  if (head === "truncate") {
+    const paths = tokens.slice(1).filter((t) => !t.startsWith("-") && !/^\d+$/.test(t));
+    return { destructive: true, kind: "truncate", paths, reason: "truncate rewrites file size" };
+  }
+  if (head === "mv" || head === "cp") return classifyMv(tokens);
+  if (head === "git") return classifyGit(tokens);
+  return { destructive: false, kind: "safe", paths: [], reason: `head '${head}' not in destructive list` };
+}
+
+export { tokenise };

package/packages/ai-trash/src/git-snapshot.js

@@ -0,0 +1,128 @@
+// Git snapshot primitive (KJC-TSK-0389 commit 1). Captures the full repo
+// state via `git bundle create --all` before a destructive git op runs so
+// the hook can restore lost commits/refs afterwards. The bundle includes
+// every reachable commit + every ref (branches + tags), letting
+// `git fetch --all <bundle>` rebuild HEAD + ref tips even after a
+// `reset --hard`, `branch -D`, or `push --force`.
+
+import { promises as fs } from "node:fs";
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+import { ulid } from "./ulid.js";
+import { ensureSecureDir, lockdownFile } from "./permissions.js";
+import { appendLogEntry } from "./logger.js";
+
+function runGit(args, cwd) {
+  return new Promise((resolve, reject) => {
+    const child = spawn("git", args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (b) => (stdout += b.toString("utf8")));
+    child.stderr.on("data", (b) => (stderr += b.toString("utf8")));
+    child.on("error", reject);
+    child.on("close", (code) => resolve({ code, stdout, stderr }));
+  });
+}
+
+async function captureRefs(repoDir) {
+  const res = await runGit(["show-ref", "--head"], repoDir);
+  if (res.code !== 0) return [];
+  return res.stdout
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      const [sha, ref] = line.split(/\s+/, 2);
+      return { sha, ref };
+    });
+}
+
+/**
+ * Snapshot the full state of a git repository as a `.bundle` file so the
+ * pre-op refs can be restored after a destructive op. Returns a manifest
+ * entry shaped like `snapshotFile`'s output so the manifest layer can
+ * store both file and git snapshots side by side.
+ *
+ * @param {string} rootDir - ai-trash root (`<root>/store/<id>/repo.bundle`).
+ * @param {string} repoDir - target git repository.
+ * @param {{command?: string, origin?: string, label?: string}} [options]
+ * @returns {Promise<object>} manifest entry with type=`git-bundle`.
+ */
+export async function snapshotGitBundle(rootDir, repoDir, options = {}) {
+  const insideRepo = await runGit(["rev-parse", "--is-inside-work-tree"], repoDir);
+  if (insideRepo.code !== 0 || insideRepo.stdout.trim() !== "true") {
+    throw new Error(`ai-trash: not a git repo: ${repoDir}`);
+  }
+  const id = ulid();
+  const storeDir = join(rootDir, "store", id);
+  await ensureSecureDir(storeDir);
+  const bundlePath = join(storeDir, "repo.bundle");
+  const bundle = await runGit(["bundle", "create", bundlePath, "--all"], repoDir);
+  if (bundle.code !== 0) {
+    throw new Error(`ai-trash: git bundle failed: ${bundle.stderr.trim()}`);
+  }
+  await lockdownFile(bundlePath);
+  const refs = await captureRefs(repoDir);
+  const stat = await fs.stat(bundlePath);
+  const entry = {
+    id,
+    type: "git-bundle",
+    createdAt: Date.now(),
+    sourcePath: repoDir,
+    snapshotPath: bundlePath,
+    sizeBytes: stat.size,
+    refs,
+    command: options.command ?? null,
+    origin: options.origin ?? "unknown",
+    label: options.label ?? null,
+  };
+  await appendLogEntry(rootDir, "snapshot.git-bundle", {
+    id,
+    repoDir,
+    bundlePath,
+    sizeBytes: stat.size,
+    refCount: refs.length,
+  });
+  return entry;
+}
+
+/**
+ * Replay a `git-bundle` snapshot into a target repository. Runs
+ * `git fetch <bundlePath> +refs/heads/*:refs/remotes/restore/*` so the
+ * pre-op refs land under `restore/*` and can be inspected, checked out,
+ * or `reset --hard`-ed back without clobbering anything in the current
+ * working tree. Leaves the manifest entry intact so repeated fetches
+ * remain possible (the bundle is not deleted).
+ *
+ * @param {string} rootDir - ai-trash root (for audit).
+ * @param {object} entry - manifest entry with type `git-bundle`.
+ * @param {string} [targetRepo] - destination repo (default: entry.sourcePath).
+ * @returns {Promise<{ repo: string, refspec: string, refCount: number }>}
+ */
+export async function restoreGitBundle(rootDir, entry, targetRepo) {
+  if (entry?.type !== "git-bundle") {
+    throw new Error(`ai-trash: not a git-bundle entry: ${entry?.id ?? "<missing>"}`);
+  }
+  const repo = targetRepo ?? entry.sourcePath;
+  const insideRepo = await runGit(["rev-parse", "--is-inside-work-tree"], repo);
+  if (insideRepo.code !== 0 || insideRepo.stdout.trim() !== "true") {
+    throw new Error(`ai-trash: restore target is not a git repo: ${repo}`);
+  }
+  try {
+    await fs.stat(entry.snapshotPath);
+  } catch {
+    throw new Error(`ai-trash: bundle missing on disk: ${entry.snapshotPath}`);
+  }
+  const refspec = "+refs/heads/*:refs/remotes/restore/*";
+  const fetched = await runGit(["fetch", entry.snapshotPath, refspec], repo);
+  if (fetched.code !== 0) {
+    throw new Error(`ai-trash: git fetch failed: ${fetched.stderr.trim()}`);
+  }
+  await appendLogEntry(rootDir, "snapshot.restore-bundle", {
+    id: entry.id,
+    bundlePath: entry.snapshotPath,
+    targetRepo: repo,
+    refCount: entry.refs?.length ?? 0,
+  });
+  return { repo, refspec, refCount: entry.refs?.length ?? 0 };
+}

package/packages/ai-trash/src/hook.js

@@ -0,0 +1,137 @@
+// Claude Code PreToolUse hook (KJC-TSK-0390 commit 2). Reads the JSON
+// payload from stdin, classifies the Bash command, snapshots target
+// paths, prints the decision JSON on stdout. Fail-closed: if snapshot
+// throws, deny the op so Claude never destroys without a recovery copy.
+
+import { promises as fs } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import process from "node:process";
+import { classifyCommand } from "./destructive-parser.js";
+import { loadManifest, saveManifest } from "./manifest.js";
+import { snapshotFile } from "./snapshot.js";
+import { snapshotGitBundle } from "./git-snapshot.js";
+import { ensureSecureDir, assertOwnedByCurrentUser } from "./permissions.js";
+import { appendLogEntry } from "./logger.js";
+
+function reply(decision, reason) {
+  return {
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: decision,
+      permissionDecisionReason: reason,
+    },
+  };
+}
+
+async function readJsonStdin(stdin) {
+  let raw = "";
+  for await (const chunk of stdin) raw += chunk;
+  if (!raw.trim()) return null;
+  return JSON.parse(raw);
+}
+
+async function snapshotExistingPaths(root, paths, cwd, command) {
+  const snapshots = [];
+  for (const p of paths) {
+    const abs = isAbsolute(p) ? p : resolve(cwd ?? process.cwd(), p);
+    try {
+      const stat = await fs.lstat(abs);
+      if (stat.isDirectory()) continue;
+      const entry = await snapshotFile(root, abs, { command, origin: "claude-code" });
+      snapshots.push(entry);
+    } catch (err) {
+      if (err.code === "ENOENT") continue;
+      throw err;
+    }
+  }
+  return snapshots;
+}
+
+async function snapshotGitRepo(root, cwd, command, kind) {
+  if (!cwd) return { snapshots: [], skipped: "no cwd" };
+  try {
+    const entry = await snapshotGitBundle(root, cwd, {
+      command,
+      origin: "claude-code",
+      label: kind,
+    });
+    return { snapshots: [entry], skipped: null };
+  } catch (err) {
+    if (/not a git repo/.test(err.message)) {
+      return { snapshots: [], skipped: "cwd is not a git repo" };
+    }
+    throw err;
+  }
+}
+
+export async function handleHookPayload(payload, { root, stdin }) {
+  const data = payload ?? (await readJsonStdin(stdin));
+  if (!data) return reply("allow", "ai-trash: empty payload, deferring");
+  if (data.hook_event_name !== "PreToolUse") {
+    return reply("allow", `ai-trash: not PreToolUse (${data.hook_event_name})`);
+  }
+  if (data.tool_name !== "Bash")
+    return reply("allow", `ai-trash: tool '${data.tool_name}' not handled`);
+
+  const command = data.tool_input?.command;
+  if (typeof command !== "string" || !command.trim()) {
+    return reply("allow", "ai-trash: empty Bash command");
+  }
+
+  const verdict = classifyCommand(command);
+  if (!verdict.destructive) return reply("allow", `ai-trash: ${verdict.kind} (${verdict.reason})`);
+
+  try {
+    await ensureSecureDir(root);
+    await assertOwnedByCurrentUser(root);
+    let snapshots = [];
+    let skipped = null;
+    if (verdict.kind.startsWith("git-")) {
+      ({ snapshots, skipped } = await snapshotGitRepo(root, data.cwd, command, verdict.kind));
+    } else {
+      snapshots = await snapshotExistingPaths(root, verdict.paths, data.cwd, command);
+    }
+    if (snapshots.length) {
+      const m = await loadManifest(root);
+      for (const s of snapshots) m.entries.push(s);
+      await saveManifest(root, m);
+    }
+    await appendLogEntry(root, "hook.allow", {
+      kind: verdict.kind,
+      command,
+      cwd: data.cwd ?? null,
+      snapshotCount: snapshots.length,
+      sessionId: data.session_id ?? null,
+    });
+    if (snapshots.length) {
+      return reply(
+        "allow",
+        `ai-trash: snapshotted ${snapshots.length} ${verdict.kind.startsWith("git-") ? "git bundle" : "path(s)"} before ${verdict.kind}`
+      );
+    }
+    return reply(
+      "allow",
+      skipped
+        ? `ai-trash: ${verdict.kind} (${skipped})`
+        : `ai-trash: ${verdict.kind} (no existing paths to snapshot)`
+    );
+  } catch (err) {
+    try {
+      await appendLogEntry(root, "hook.deny", {
+        kind: verdict.kind,
+        command,
+        error: err.message,
+        sessionId: data.session_id ?? null,
+      });
+    } catch {
+      /* root unwritable; deny is still the right answer */
+    }
+    return reply("deny", `ai-trash: snapshot failed (${err.message}); blocking ${verdict.kind}`);
+  }
+}
+
+export async function runHook({ root, stdin = process.stdin, stdout = process.stdout }) {
+  const response = await handleHookPayload(null, { root, stdin, stdout });
+  stdout.write(JSON.stringify(response) + "\n");
+  return 0;
+}