failproofai 0.0.10 → 0.0.11-beta.10

package/src/audit/cli-adapters/shared.ts

@@ -0,0 +1,85 @@
+/**
+ * Shared helpers used by every per-CLI adapter.
+ *
+ * The lib/<cli>-sessions.ts parsers all produce the same `LogEntry[]` shape
+ * (defined in lib/log-entries.ts), so the conversion from LogEntry[] to
+ * NormalizedToolEvent[] is uniform across CLIs. The only per-CLI difference is
+ * the canonicalization function, which we delegate to
+ * `src/hooks/tool-name-canonicalize.ts`.
+ */
+import type { LogEntry } from "../../../lib/log-entries";
+import type { IntegrationType } from "../../hooks/types";
+import {
+  canonicalizeToolName,
+  canonicalizeToolInput,
+} from "../../hooks/tool-name-canonicalize";
+import {
+  AUDIT_TOOL_RESULT_MAX_BYTES,
+  type NormalizedToolEvent,
+} from "../types";
+
+/** Truncate a string to at most `maxBytes` UTF-8 bytes, preserving valid
+ *  encoding (never splits a multi-byte sequence). `String.prototype.length`
+ *  counts UTF-16 code units, not bytes — using it to "cap memory" would let
+ *  through up to 4× the intended byte budget for non-ASCII text. */
+function truncateToUtf8Bytes(s: string, maxBytes: number): string {
+  const buf = Buffer.from(s, "utf-8");
+  if (buf.byteLength <= maxBytes) return s;
+  // Walk back at most 3 bytes to land on a UTF-8 boundary (a leading byte is
+  // 0xxxxxxx or 11xxxxxx; continuation bytes are 10xxxxxx).
+  let end = maxBytes;
+  while (end > 0 && (buf[end] & 0xc0) === 0x80) end--;
+  return buf.subarray(0, end).toString("utf-8");
+}
+
+export interface ConvertContext {
+  cli: IntegrationType;
+  sessionId: string;
+  transcriptPath: string;
+  /** Cwd resolved by the per-CLI parser. May be empty if the transcript had no
+   *  session-start record. The audit falls back to the decoded project name. */
+  cwd: string;
+}
+
+/** Walks the LogEntry[] in timestamp order and yields one NormalizedToolEvent
+ *  per `tool_use` content block, with the matching `tool_result.content` text
+ *  attached (truncated). Returns events in chronological order. */
+export function logEntriesToEvents(
+  entries: LogEntry[],
+  ctx: ConvertContext,
+): NormalizedToolEvent[] {
+  const events: NormalizedToolEvent[] = [];
+
+  for (const entry of entries) {
+    if (entry.type !== "assistant") continue;
+    for (const block of entry.message.content) {
+      if (block.type !== "tool_use") continue;
+      const rawName = block.name;
+      const canonicalName = canonicalizeToolName(rawName, ctx.cli) ?? rawName;
+      const canonicalInput = canonicalizeToolInput(
+        canonicalName,
+        block.input,
+        ctx.cli,
+      ) as Record<string, unknown>;
+
+      let toolResultText: string | undefined;
+      if (block.result?.content) {
+        toolResultText = truncateToUtf8Bytes(block.result.content, AUDIT_TOOL_RESULT_MAX_BYTES);
+      }
+
+      events.push({
+        cli: ctx.cli,
+        sessionId: ctx.sessionId,
+        transcriptPath: ctx.transcriptPath,
+        cwd: ctx.cwd,
+        timestamp: entry.timestamp,
+        toolName: canonicalName,
+        rawToolName: rawName,
+        toolInput: canonicalInput ?? {},
+        toolResultText,
+      });
+    }
+  }
+
+  return events;
+}

package/src/audit/cli.ts

@@ -0,0 +1,319 @@
+/**
+ * `failproofai audit` — run a local audit of your agent-CLI history, then open
+ * the dashboard to view it.
+ *
+ *   failproofai audit          Scan, then launch the dashboard at /audit.
+ *   failproofai audit --help   Show usage.
+ *
+ * `runAudit()` is a pure local function (no network, no account). We run it,
+ * render the same four progress stages the dashboard's RunProgress shows,
+ * pre-warm the dashboard cache (~/.failproofai/audit-dashboard.json), then start
+ * the bundled dashboard server and open the browser to /audit — which renders
+ * instantly from that cache.
+ *
+ * No arguments yet — a bare `failproofai audit` does a full scan (all CLIs, all
+ * history). Flags (--since, --cli, --project, --port, --no-open) are easy
+ * follow-ups against `RunAuditOptions`.
+ */
+import { runAudit } from "./index";
+import { writeDashboardCache } from "./dashboard-cache";
+import type { AuditResult, RunAuditOptions } from "./types";
+import { trackHookEvent } from "../hooks/hook-telemetry";
+import { getInstanceId } from "../../lib/telemetry-id";
+import { openWhenReady } from "./open-browser";
+
+/** Port the bundled dashboard binds to. Matches `scripts/launch.ts`'s default
+ *  for `start` mode, which `failproofai` (bare) already uses. */
+const DASHBOARD_PORT = 8020;
+
+/**
+ * Mirror of `app/audit/_components/run-progress.tsx`'s `STAGES`. Kept identical
+ * so the CLI and the dashboard's in-progress view tell the same story — the
+ * dashboard even renders a mock `$ failproofai audit` terminal, and this is the
+ * real thing. `audit-cli.test.ts` guards against drift between the two.
+ */
+export const AUDIT_STAGES: ReadonlyArray<{ label: string; detail: string }> = [
+  { label: "discovering transcripts", detail: "walking ~/.claude, ~/.codex, ~/.cursor, …" },
+  { label: "parsing session logs", detail: "reading JSONL + sqlite session stores" },
+  { label: "running policy checks", detail: "replaying through 30 builtin policies" },
+  { label: "aggregating results", detail: "counting hits, ranking by frequency" },
+];
+
+const HELP = `
+failproofai audit — audit your AI agent's behavior, then open the dashboard
+
+USAGE
+  failproofai audit          Scan your agent-CLI session history for risky and
+                             wasteful patterns, then open the audit dashboard.
+  failproofai audit --help   Show this help.
+
+WHAT IT DOES
+  1. Scans past sessions from every installed agent CLI (Claude, Codex, Cursor,
+     Copilot, OpenCode, Pi, Gemini) — entirely on your machine.
+  2. Starts the local dashboard and opens
+     http://localhost:${DASHBOARD_PORT}/audit with your results.
+
+  Runs fully offline — no account or network required. Press Ctrl+C to stop the
+  dashboard server when you're done.
+`.trimStart();
+
+// ── ANSI helpers ────────────────────────────────────────────────────────────
+const RESET = "\x1b[0m";
+const DIM = "\x1b[2m";
+const BOLD = "\x1b[1m";
+const PINK = "\x1b[38;5;204m";
+const GREEN = "\x1b[38;5;120m";
+const CYAN = "\x1b[38;5;81m";
+const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+function colorOn(): boolean {
+  if (process.env.NO_COLOR && process.env.NO_COLOR !== "") return false;
+  if (process.env.FORCE_COLOR === "0") return false;
+  if (process.env.FORCE_COLOR) return true;
+  return !!process.stdout.isTTY;
+}
+
+/** Wrap `s` in an ANSI code when color is enabled, else return it bare. */
+function c(code: string, s: string): string {
+  return colorOn() ? `${code}${s}${RESET}` : s;
+}
+
+function num(n: number): string {
+  return n.toLocaleString("en-US");
+}
+
+/**
+ * Print an error and exit 1. We exit directly rather than throwing a `CliError`
+ * because, in the shipped single-file bundle (`dist/cli.mjs`), the entrypoint's
+ * dynamically-imported `CliError` is a different class instance than the one
+ * bundled here, so `err instanceof CliError` fails and the message degrades to
+ * "Unexpected error" + exit 2. Exiting here keeps the audit command's failures
+ * clean in both source and bundled runs.
+ */
+function die(message: string): never {
+  process.stderr.write(`Error: ${message}\n`);
+  process.exit(1);
+}
+
+// ── Progress animation ───────────────────────────────────────────────────────
+
+interface Progress {
+  /** Mark every stage done and stop the timers. */
+  finish(): void;
+  /** Stop the timers without marking done (used on error). */
+  fail(): void;
+}
+
+/**
+ * Render the four audit stages with a live spinner, redrawing in place. Like the
+ * dashboard's RunProgress, the stages are time-driven (runAudit emits no phase
+ * events) and the last stage is *held* until `finish()` is called, so it never
+ * claims "done" before the real work resolves. TTY-only — the caller picks the
+ * plain-text path when stdout isn't a terminal.
+ */
+function startProgress(): Progress {
+  const n = AUDIT_STAGES.length;
+  let stage = 0;
+  let tick = 0;
+  let done = false;
+  let printed = false;
+
+  const lineFor = (i: number): string => {
+    const s = AUDIT_STAGES[i];
+    if (done || i < stage) return `  ${c(GREEN, "✓")} ${c(DIM, s.label)}`;
+    if (i === stage) {
+      return `  ${c(PINK, SPINNER[tick % SPINNER.length])} ${s.label}  ${c(DIM, s.detail)}`;
+    }
+    return `  ${c(DIM, "○")} ${c(DIM, s.label)}`;
+  };
+
+  const render = (): void => {
+    const lines = Array.from({ length: n }, (_, i) => lineFor(i));
+    // Move the cursor back up over the previously-drawn block, then clear and
+    // rewrite each line in place.
+    if (printed) process.stdout.write(`\x1b[${n}A`);
+    process.stdout.write(lines.map((l) => `\x1b[2K${l}`).join("\n") + "\n");
+    printed = true;
+  };
+
+  render();
+  const spinTimer = setInterval(() => {
+    tick++;
+    render();
+  }, 90);
+  // Advance through stages on a fixed cadence, holding on the last one until
+  // finish() flips `done`.
+  const stageTimer = setInterval(() => {
+    if (stage < n - 1) {
+      stage++;
+      render();
+    }
+  }, 1100);
+
+  const stop = (): void => {
+    clearInterval(spinTimer);
+    clearInterval(stageTimer);
+  };
+
+  return {
+    finish() {
+      stop();
+      done = true;
+      render();
+    },
+    fail() {
+      stop();
+      process.stdout.write("\n");
+    },
+  };
+}
+
+/** Run the audit, showing animated progress on a TTY or a single line elsewhere. */
+async function runWithProgress(opts: RunAuditOptions): Promise<AuditResult> {
+  if (!process.stdout.isTTY) {
+    process.stdout.write("  scanning your agent session history — this can take a moment…\n");
+    return runAudit(opts);
+  }
+  const progress = startProgress();
+  try {
+    const result = await runAudit(opts);
+    progress.finish();
+    return result;
+  } catch (err) {
+    progress.fail();
+    throw err;
+  }
+}
+
+// ── Output ───────────────────────────────────────────────────────────────────
+
+function printHeader(): void {
+  process.stdout.write(`\n  ${c(PINK, "🛡  failproofai audit")}  ${c(DIM, "· beta")}\n\n`);
+  process.stdout.write(`  ${c(DIM, "starting audit…")}\n\n`);
+}
+
+/**
+ * The post-run summary lines (no leading indent, no trailing newlines). Pure so
+ * it's unit-testable; `printSummary` handles the indentation + stdout.
+ */
+export function buildSummary(result: AuditResult): string[] {
+  const sessions = result.transcripts.scanned;
+  const events = result.eventsScanned;
+  const projects = result.projectsScanned.length;
+  const enabledRows = result.results.filter((r) => r.source === "builtin" && r.enabledInConfig);
+  const slippingRows = result.results.filter((r) => !(r.source === "builtin" && r.enabledInConfig));
+
+  const lines: string[] = [];
+  lines.push(
+    `${c(GREEN, "✓ audit complete")}  ${c(DIM, "·")}  ` +
+      `${c(BOLD, num(events))} tool call${events === 1 ? "" : "s"} across ` +
+      `${num(sessions)} session${sessions === 1 ? "" : "s"}` +
+      (projects > 0 ? ` ${c(DIM, "·")} ${num(projects)} project${projects === 1 ? "" : "s"}` : ""),
+  );
+
+  if (result.totals.hits === 0) {
+    // Only call it a "clean run" when we actually scanned something — for zero
+    // events the caller prints "no agent sessions found yet" guidance instead.
+    if (events > 0) lines.push(c(DIM, "clean run — nothing flagged. nice."));
+    return lines;
+  }
+
+  const parts: string[] = [];
+  if (slippingRows.length > 0) {
+    parts.push(
+      `${c(PINK, String(slippingRows.length))} ${slippingRows.length === 1 ? "pattern" : "patterns"} slipping through`,
+    );
+  }
+  if (enabledRows.length > 0) {
+    parts.push(`${c(GREEN, String(enabledRows.length))} already blocked by your policies`);
+  }
+  if (parts.length > 0) lines.push(parts.join(`  ${c(DIM, "·")}  `));
+  return lines;
+}
+
+function printSummary(result: AuditResult): void {
+  process.stdout.write("\n");
+  for (const line of buildSummary(result)) process.stdout.write(`  ${line}\n`);
+}
+
+// ── Entry point ──────────────────────────────────────────────────────────────
+
+export async function runAuditCli(args: string[]): Promise<void> {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(HELP);
+    process.exit(0);
+  }
+  // No arguments supported yet — reject typos rather than silently doing a bare
+  // audit, so a future `failproofai audit --since 7d` doesn't quietly no-op.
+  const stray = args.find((a) => a !== "--help" && a !== "-h");
+  if (stray) {
+    die(
+      `\`audit\` takes no arguments yet (got: ${stray}).\n` +
+        `Run \`failproofai audit\` to scan your history and open the dashboard.`,
+    );
+  }
+
+  const instanceId = getInstanceId();
+  void trackHookEvent(instanceId, "cli_audit_started", { source: "cli" });
+
+  printHeader();
+
+  // Full scan: all CLIs, all history, per-transcript cache on.
+  const opts: RunAuditOptions = {};
+
+  let result: AuditResult;
+  try {
+    result = await runWithProgress(opts);
+  } catch (err) {
+    void trackHookEvent(instanceId, "cli_audit_failed", {
+      source: "cli",
+      error_type: err instanceof Error ? err.name : "unknown",
+    });
+    die(`Audit failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  printSummary(result);
+
+  void trackHookEvent(instanceId, "cli_audit_completed", {
+    source: "cli",
+    events_scanned: result.eventsScanned,
+    sessions_scanned: result.transcripts.scanned,
+    total_hits: result.totals.hits,
+    findings: result.results.length,
+  });
+
+  // No sessions on disk — guide the user instead of opening an empty dashboard.
+  if (result.eventsScanned === 0) {
+    process.stdout.write(
+      `\n  ${c(DIM, "no agent sessions found yet.")}\n` +
+        `  install hooks with ${c(CYAN, "failproofai policies --install")} ` +
+        `${c(DIM, "and come back after using your agent.")}\n\n`,
+    );
+    process.exit(0);
+  }
+
+  // Pre-warm the dashboard cache — the /audit page reads this file directly, so
+  // the page renders our result instantly with no in-browser re-run.
+  const persisted = writeDashboardCache(opts, result);
+  if (!persisted) {
+    process.stdout.write(
+      `\n  ${c(PINK, "!")} ${c(DIM, "couldn't save the audit cache; the dashboard may show an empty state.")}\n`,
+    );
+  }
+
+  const url = `http://localhost:${DASHBOARD_PORT}/audit`;
+  process.stdout.write(
+    `\n  ${c(DIM, "starting the dashboard…")}\n` +
+      `  ${c(PINK, "✦")} ${c(BOLD, "here's your audit")}  ${c(DIM, "→")}  ${c(CYAN, url)}\n` +
+      `  ${c(DIM, "(opening in your browser — press Ctrl+C to stop the server)")}\n\n`,
+  );
+
+  // Open the page once the server answers (best-effort, detached), then start
+  // the server. `launch("start")` blocks-by-keeping-alive — it spawns the
+  // bundled standalone dashboard and the process stays up serving it.
+  openWhenReady(DASHBOARD_PORT, "/audit");
+  const { launch } = await import("../../scripts/launch");
+  launch("start");
+  // Intentionally no process.exit(): launch() keeps this process alive running
+  // the dashboard until the user stops it.
+}

package/src/audit/dashboard-cache.ts

@@ -0,0 +1,158 @@
+/**
+ * Whole-result cache for the Next.js dashboard's `/audit` page.
+ *
+ * Stored at `~/.failproofai/audit-dashboard.json` with mode 0600. Single
+ * slot — a new run with different params overwrites the previous entry.
+ * Read by `app/actions/get-audit-result.ts` (server action) and written by
+ * `app/api/audit/run/route.ts` on successful run completion.
+ *
+ * Separate from the per-transcript cache at `~/.failproofai/cache/audit/`
+ * (see `src/audit/cache.ts`): that one makes re-running fast; this one
+ * makes navigating back to /audit instant without re-running.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { writeJsonAtomically } from "../../lib/atomic-write";
+import type { AuditResult, RunAuditOptions } from "./types";
+
+const DEFAULT_MAX_AGE_MINUTES = 30;
+
+/** Hard expiry: the dashboard cache is rejected on read once it's this old.
+ *  Matches the per-transcript TTL in `cache.ts` so the whole audit surface
+ *  has a consistent 7-day freshness window — past that, `/audit` falls
+ *  through to its empty state and nudges the user to re-audit. */
+const DASHBOARD_CACHE_TTL_MINUTES = 7 * 24 * 60;
+
+/**
+ * Bump whenever the on-disk shape of a cached entry changes in a way the
+ * reader can't tolerate (added required field, renamed key, swapped result
+ * version). Entries written with a different `schemaVersion` are rejected
+ * — better an empty state than rendering against the wrong shape.
+ *
+ * v2: AuditResult.version bumped 1→2 (added `projectsScanned`,
+ * `eventsScanned`, `enabledBuiltinNames`). Renderers defaulted missing
+ * fields silently, which masked a stale cache as "0 tool calls scanned"
+ * instead of triggering the empty-state recovery. Rejecting v1 entries
+ * forces a re-run.
+ */
+export const DASHBOARD_CACHE_SCHEMA_VERSION = 2;
+
+export interface DashboardCacheEntry {
+  /** Bumped whenever the cache shape changes incompatibly. */
+  schemaVersion: number;
+  /** ISO timestamp the cache was written at. */
+  cachedAt: string;
+  /** The exact RunAuditOptions the cached result was produced with. */
+  params: RunAuditOptions;
+  /** The full `AuditResult` from `runAudit()`. */
+  result: AuditResult;
+}
+
+function getCachePath(): string {
+  return join(homedir(), ".failproofai", "audit-dashboard.json");
+}
+
+/** Read the cache file. Returns null on missing/corrupt/unreadable file —
+ *  callers treat "no cache" as the empty state. */
+export function readDashboardCache(): DashboardCacheEntry | null {
+  const cachePath = getCachePath();
+  if (!existsSync(cachePath)) return null;
+  try {
+    const raw = readFileSync(cachePath, "utf-8");
+    const entry = JSON.parse(raw) as DashboardCacheEntry;
+    // `typeof null === "object"`, so explicit null checks are required for
+    // params and result — otherwise a corrupt cache like `{"params": null}`
+    // would slip through and crash downstream readers.
+    if (
+      !entry
+      || typeof entry !== "object"
+      || typeof entry.cachedAt !== "string"
+      || !entry.params
+      || typeof entry.params !== "object"
+      || !entry.result
+      || typeof entry.result !== "object"
+    ) {
+      return null;
+    }
+    // Reject anything written by an older code version with a different
+    // shape. The dashboard treats null as the "no cached result" empty
+    // state, which is the safer fallback when we can't trust the bytes.
+    if (entry.schemaVersion !== DASHBOARD_CACHE_SCHEMA_VERSION) {
+      return null;
+    }
+    if (isCacheStale(entry.cachedAt, DASHBOARD_CACHE_TTL_MINUTES)) {
+      return null;
+    }
+    return entry;
+  } catch {
+    return null;
+  }
+}
+
+/** Write the cache file atomically via the shared `writeJsonAtomically`
+ *  helper. Returns `true` on success and `false` if the write threw (disk
+ *  full, permissions, …) — never throwing into the run path. The temp-file
+ *  dance protects concurrent readers (e.g. the 1s status poll firing while a
+ *  fresh run writes a multi-hundred-KB AuditResult) from observing a torn JSON
+ *  file. The fire-and-forget run route relies on this boolean to surface a
+ *  persistence failure: the cache is the only channel by which a detached
+ *  run's result reaches the dashboard, so a silently dropped write would
+ *  otherwise look like a successful run that serves stale data. */
+export function writeDashboardCache(params: RunAuditOptions, result: AuditResult): boolean {
+  try {
+    const entry: DashboardCacheEntry = {
+      schemaVersion: DASHBOARD_CACHE_SCHEMA_VERSION,
+      cachedAt: new Date().toISOString(),
+      params,
+      result,
+    };
+    writeJsonAtomically(getCachePath(), entry);
+    return true;
+  } catch {
+    // Best-effort: never throw into the run path. The caller decides how to
+    // treat a failed persist (the run route reports it as a run error).
+    return false;
+  }
+}
+
+/** True when the cache is older than `maxAgeMinutes` (default 30). The
+ *  dashboard doesn't auto-refresh on stale cache — staleness only drives
+ *  the "Re-run" affordance hint. */
+export function isCacheStale(cachedAt: string, maxAgeMinutes: number = DEFAULT_MAX_AGE_MINUTES): boolean {
+  const cachedMs = new Date(cachedAt).getTime();
+  if (Number.isNaN(cachedMs)) return true;
+  const ageMs = Date.now() - cachedMs;
+  return ageMs > maxAgeMinutes * 60_000;
+}
+
+/**
+ * Read just the `cachedAt` timestamp from the dashboard cache file,
+ * **bypassing** the TTL check. Used by the empty-state path to tell apart
+ * "no audit has ever run" from "your last audit aged out". A non-null
+ * return whose age exceeds `DASHBOARD_CACHE_TTL_MINUTES` means the cache
+ * was rejected by `readDashboardCache()` for being expired (rather than
+ * missing or schema-incompatible).
+ */
+export function readDashboardCacheMeta(): { cachedAt: string } | null {
+  const cachePath = getCachePath();
+  if (!existsSync(cachePath)) return null;
+  try {
+    const raw = readFileSync(cachePath, "utf-8");
+    const entry = JSON.parse(raw) as Partial<DashboardCacheEntry>;
+    // Require schema-version match + a parseable ISO timestamp before
+    // surfacing the entry as "this user's audit aged out". A
+    // schema-incompatible entry is structurally indistinguishable from
+    // "no audit has ever run", so it should fall through to the
+    // first-run empty copy, not the expired banner.
+    if (
+      !entry
+      || entry.schemaVersion !== DASHBOARD_CACHE_SCHEMA_VERSION
+      || typeof entry.cachedAt !== "string"
+      || Number.isNaN(new Date(entry.cachedAt).getTime())
+    ) return null;
+    return { cachedAt: entry.cachedAt };
+  } catch {
+    return null;
+  }
+}

package/src/audit/detectors/find-from-root.ts

@@ -0,0 +1,27 @@
+import type { Detector } from "../types";
+
+const RISKY_ROOTS = ["/", "/home", "/usr", "/etc", "/var", "/opt", "/Users"];
+
+/** Bash `find` invoked against the filesystem root or another high-level
+ *  directory — tends to exhaust resources and rarely returns useful results. */
+export const findFromRoot: Detector = {
+  name: "find-from-root",
+  description: "Bash `find` against `/`, `/home`, `/usr`, etc. — scope to cwd instead.",
+  category: "Risky",
+  severity: "warn",
+  displayTitle: "Ran find from /, /home, /usr, etc.",
+  impact: "Filesystem-wide finds exhaust resources and rarely return useful results.",
+  detect(event) {
+    if (event.toolName !== "Bash") return null;
+    const command = (event.toolInput as { command?: unknown }).command;
+    if (typeof command !== "string") return null;
+    const cmd = command.trim();
+    // find / OR find /home OR find "/etc" …  — first non-flag arg
+    const match = /(?:^|[\s;|&])find\s+(?:-\S+\s+)*("[^"]+"|'[^']+'|\S+)/.exec(cmd);
+    if (!match) return null;
+    const raw = match[1].replace(/^["']|["']$/g, "");
+    const stripped = raw.replace(/\/+$/, "") || "/";
+    if (!RISKY_ROOTS.includes(stripped)) return null;
+    return { example: cmd.slice(0, 160) };
+  },
+};

package/src/audit/detectors/git-commit-no-verify.ts

@@ -0,0 +1,22 @@
+import type { Detector } from "../types";
+
+/** `git commit ... --no-verify` (or short `-n`) — skipping pre-commit hooks. */
+export const gitCommitNoVerify: Detector = {
+  name: "git-commit-no-verify",
+  description: "git commit invoked with --no-verify / -n, skipping hooks.",
+  category: "Risky",
+  severity: "warn",
+  displayTitle: "Committed with --no-verify",
+  impact: "Skips pre-commit hooks that exist to catch broken or unsafe code.",
+  detect(event) {
+    if (event.toolName !== "Bash") return null;
+    const command = (event.toolInput as { command?: unknown }).command;
+    if (typeof command !== "string") return null;
+    const cmd = command;
+    if (!/\bgit\s+commit\b/.test(cmd)) return null;
+    if (/\s--no-verify\b/.test(cmd) || /\s-n\b/.test(cmd)) {
+      return { example: cmd.replace(/\s+/g, " ").trim().slice(0, 160) };
+    }
+    return null;
+  },
+};

package/src/audit/detectors/index.ts

@@ -0,0 +1,33 @@
+/**
+ * Registry of audit-only detectors.
+ *
+ * Detectors are pure functions over a NormalizedToolEvent (plus optional
+ * per-session state). They detect "stupid behaviors" not currently covered by
+ * the runtime builtin policies, with no real-time enforcement — counting only.
+ *
+ * Add a new detector by writing a sibling file and registering it here.
+ */
+import type { Detector } from "../types";
+import { redundantCdCwd } from "./redundant-cd-cwd";
+import { preferEditOverReadCat } from "./prefer-edit-over-read-cat";
+import { preferEditOverSedAwk } from "./prefer-edit-over-sed-awk";
+import { preferWriteOverHeredoc } from "./prefer-write-over-heredoc";
+import { sleepPollingLoop } from "./sleep-polling-loop";
+import { findFromRoot } from "./find-from-root";
+import { gitCommitNoVerify } from "./git-commit-no-verify";
+import { rereadAfterEdit } from "./reread-after-edit";
+
+export const AUDIT_DETECTORS: Detector[] = [
+  redundantCdCwd,
+  preferEditOverReadCat,
+  preferEditOverSedAwk,
+  preferWriteOverHeredoc,
+  sleepPollingLoop,
+  findFromRoot,
+  gitCommitNoVerify,
+  rereadAfterEdit,
+];
+
+export function getDetectorByName(name: string): Detector | undefined {
+  return AUDIT_DETECTORS.find((d) => d.name === name);
+}

package/src/audit/detectors/prefer-edit-over-read-cat.ts

@@ -0,0 +1,31 @@
+import type { Detector } from "../types";
+
+const SOURCE_EXT_RE = /\.(?:ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|swift|rb|php|c|h|cc|cpp|hpp|cs|scala|sh|bash|zsh|json|yaml|yml|toml|md|txt|sql|html|css|scss|sass)$/i;
+
+/** `cat | head | tail | less | more` invoked on a single source file with no
+ *  shell pipeline / redirection. The Read tool is the right answer. .env files
+ *  are intentionally excluded (covered by `block-env-files`). */
+export const preferEditOverReadCat: Detector = {
+  name: "prefer-edit-over-read-cat",
+  description: "Bash `cat`/`head`/`tail`/`less`/`more` on a single source file — use Read.",
+  category: "Wasteful",
+  severity: "info",
+  displayTitle: "Used `cat`/`head`/`tail` on a source file",
+  impact: "Burns tokens; the Read tool returns content directly without going through Bash output.",
+  detect(event) {
+    if (event.toolName !== "Bash") return null;
+    const command = (event.toolInput as { command?: unknown }).command;
+    if (typeof command !== "string") return null;
+    const cmd = command.trim();
+    // Reject any shell pipeline, redirection, command chaining or substitution.
+    if (/[|<>;&`$()]/.test(cmd)) return null;
+    const match = /^(cat|head|tail|less|more)\s+(?:-\S+\s+)*(?:"([^"]+)"|'([^']+)'|(\S+))\s*$/.exec(cmd);
+    if (!match) return null;
+    const path = match[2] ?? match[3] ?? match[4] ?? "";
+    if (!path) return null;
+    // .env is covered by block-env-files; skip to avoid double-counting.
+    if (/(?:^|\/)\.env(?:\..+)?$/.test(path)) return null;
+    if (!SOURCE_EXT_RE.test(path)) return null;
+    return { example: cmd };
+  },
+};