failproofai 0.0.11-beta.1 → 0.0.11-beta.3

package/src/hooks/builtin-policies.ts

@@ -1471,7 +1471,8 @@ function requireCiGreenBeforeStop(ctx: PolicyContext): PolicyResult {
         r.status === "completed" &&
         r.conclusion !== "success" &&
         r.conclusion !== "skipped" &&
-        r.conclusion !== "cancelled",
+        r.conclusion !== "cancelled" &&
+        r.conclusion !== "neutral",
     );
     if (failing.length > 0) {
       const names = failing.map((r) => `"${r.name}"`).join(", ");
@@ -1502,6 +1503,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   {
     name: "sanitize-jwt",
     description: "Stop Claude from reading JWTs in tool responses",
+    displayTitle: "Redacted JWT tokens from tool output",
+    impact: "Stops the agent from echoing auth tokens it saw in command output.",
     fn: sanitizeJwt,
     match: { events: ["PostToolUse"] },
     defaultEnabled: true,
@@ -1510,6 +1513,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   {
     name: "sanitize-api-keys",
     description: "Stop Claude from reading API keys (OpenAI, Anthropic, GitHub, AWS, Stripe, Google) in tool responses",
+    displayTitle: "Redacted API keys from tool output",
+    impact: "Catches OpenAI / Anthropic / GitHub / AWS / Stripe / Google keys before the model sees them.",
     fn: sanitizeApiKeys,
     match: { events: ["PostToolUse"] },
     defaultEnabled: true,
@@ -1525,6 +1530,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   {
     name: "sanitize-connection-strings",
     description: "Stop Claude from reading database connection strings with embedded credentials in tool responses",
+    displayTitle: "Redacted database connection strings from tool output",
+    impact: "Strips embedded DB credentials before they reach the model context.",
     fn: sanitizeConnectionStrings,
     match: { events: ["PostToolUse"] },
     defaultEnabled: true,
@@ -1533,6 +1540,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   {
     name: "sanitize-private-key-content",
     description: "Stop Claude from reading PEM private key content in tool responses",
+    displayTitle: "Redacted PEM private keys from tool output",
+    impact: "Prevents private key bodies from being echoed into chat context.",
     fn: sanitizePrivateKeyContent,
     match: { events: ["PostToolUse"] },
     defaultEnabled: true,
@@ -1540,6 +1549,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   },
   {
     name: "sanitize-bearer-tokens",
+    displayTitle: "Redacted bearer tokens from tool output",
+    impact: "Strips Authorization: Bearer values before they hit the model.",
     description: "Stop Claude from reading Authorization Bearer tokens in tool responses",
     fn: sanitizeBearerTokens,
     match: { events: ["PostToolUse"] },
@@ -1548,6 +1559,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   },
   {
     name: "protect-env-vars",
+    displayTitle: "Tried to dump environment variables to chat",
+    impact: "Env vars often contain secrets; blocking `env` / `printenv` keeps them out of the model context.",
     description: "Prevent commands that read environment variables",
     fn: protectEnvVars,
     match: { events: ["PreToolUse"], toolNames: ["Bash"] },
@@ -1556,6 +1569,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   },
   {
     name: "block-env-files",
+    displayTitle: "Tried to read or write a .env file",
+    impact: "`.env` files routinely contain API keys and DB credentials.",
     description: "Block reading/writing .env files",
     fn: blockEnvFiles,
     match: { events: ["PreToolUse"] },
@@ -1564,6 +1579,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   },
   {
     name: "block-read-outside-cwd",
+    displayTitle: "Tried to read files outside your project directory",
+    impact: "Stops the agent from peeking at neighboring repos or your home directory.",
     description: "Block file reads outside the session working directory",
     fn: blockReadOutsideCwd,
     match: { events: ["PreToolUse"], toolNames: ["Read", "Glob", "Grep", "Bash"] },
@@ -1579,6 +1596,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   },
   {
     name: "block-sudo",
+    displayTitle: "Tried to run a command with sudo",
+    impact: "Sudo gives the agent root — blocked unless explicitly allow-listed.",
     description: "Block sudo commands",
     fn: blockSudo,
     // PermissionRequest is Codex's escalation-approval event; fire the same
@@ -1596,6 +1615,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   },
   {
     name: "block-curl-pipe-sh",
+    displayTitle: "Tried to pipe a downloaded script straight to a shell",
+    impact: "`curl ... | sh` runs unverified remote code on your machine.",
     description: "Block piping downloads to shell",
     fn: blockCurlPipeSh,
     match: { events: ["PreToolUse"], toolNames: ["Bash"] },
@@ -1604,6 +1625,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   },
   {
     name: "block-rm-rf",
+    displayTitle: "Tried to recursively delete a system path",
+    impact: "Catches catastrophic `rm -rf /` and Windows equivalents.",
     description: "Prevent catastrophic deletions",
     fn: blockRmRf,
     match: { events: ["PreToolUse"], toolNames: ["Bash"] },
@@ -1619,6 +1642,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   },
   {
     name: "block-failproofai-commands",
+    displayTitle: "Tried to disable or modify failproofai itself",
+    impact: "Prevents the agent from turning off the policies that protect you.",
     description: "Block failproofai CLI commands and uninstallation",
     fn: blockFailproofaiCommands,
     match: { events: ["PreToolUse"], toolNames: ["Bash"] },
@@ -1627,6 +1652,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   },
   {
     name: "block-kubectl",
+    displayTitle: "Tried to run a Kubernetes command",
+    impact: "kubectl can change live cluster state — gated unless allow-listed.",
     description: "Block kubectl commands (Kubernetes cluster mutations)",
     fn: blockKubectl,
     match: { events: ["PreToolUse"], toolNames: ["Bash"] },
@@ -1642,6 +1669,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   },
   {
     name: "block-terraform",
+    displayTitle: "Tried to run a Terraform/OpenTofu command",
+    impact: "Terraform mutates real infrastructure — gated unless allow-listed.",
     description: "Block terraform and tofu (OpenTofu) commands",
     fn: blockTerraform,
     match: { events: ["PreToolUse"], toolNames: ["Bash"] },
@@ -1657,6 +1686,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   },
   {
     name: "block-aws-cli",
+    displayTitle: "Tried to run an AWS CLI command",
+    impact: "AWS CLI can spend money or break prod — gated.",
     description: "Block aws CLI commands",
     fn: blockAwsCli,
     match: { events: ["PreToolUse"], toolNames: ["Bash"] },
@@ -1672,6 +1703,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   },
   {
     name: "block-gcloud",
+    displayTitle: "Tried to run a Google Cloud command",
+    impact: "gcloud can spend money or break prod — gated.",
     description: "Block gcloud (Google Cloud) CLI commands",
     fn: blockGcloud,
     match: { events: ["PreToolUse"], toolNames: ["Bash"] },
@@ -1687,6 +1720,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   },
   {
     name: "block-az-cli",
+    displayTitle: "Tried to run an Azure CLI command",
+    impact: "az can spend money or break prod — gated.",
     description: "Block az (Azure) CLI commands",
     fn: blockAzCli,
     match: { events: ["PreToolUse"], toolNames: ["Bash"] },
@@ -1702,6 +1737,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   },
   {
     name: "block-helm",
+    displayTitle: "Tried to run a Helm command",
+    impact: "Helm releases mutate cluster state — gated.",
     description: "Block helm commands",
     fn: blockHelm,
     match: { events: ["PreToolUse"], toolNames: ["Bash"] },
@@ -1717,6 +1754,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   },
   {
     name: "block-gh-pipeline",
+    displayTitle: "Tried to run a privileged GitHub CLI pipeline command",
+    impact: "Catches `gh workflow run`, `gh pr merge`, `gh secret set`, etc.",
     description: "Block gh CLI pipeline-trigger subcommands (workflow run, run rerun/cancel, pr merge, release create/delete, cache delete, secret set/delete)",
     fn: blockGhPipeline,
     match: { events: ["PreToolUse"], toolNames: ["Bash"] },
@@ -1732,6 +1771,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   },
   {
     name: "block-secrets-write",
+    displayTitle: "Tried to write a secret-key file",
+    impact: "Stops the agent from creating `.pem`, `id_rsa`, `credentials.json`, etc.",
     description: "Block writing secret key files",
     fn: blockSecretsWrite,
     match: { events: ["PreToolUse"], toolNames: ["Write"] },
@@ -1747,6 +1788,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   },
   {
     name: "block-push-master",
+    displayTitle: "Tried to push directly to main/master",
+    impact: "Direct pushes to a protected branch bypass review.",
     description: "Block pushing to main/master",
     fn: blockPushMaster,
     match: { events: ["PreToolUse"], toolNames: ["Bash"] },
@@ -1762,6 +1805,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   },
   {
     name: "block-force-push",
+    displayTitle: "Tried to force-push",
+    impact: "Force-pushes rewrite history and can clobber teammates' work.",
     description: "Prevent force-pushing to any branch",
     fn: blockForcePush,
     match: { events: ["PreToolUse"], toolNames: ["Bash"] },
@@ -1770,6 +1815,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   },
   {
     name: "block-work-on-main",
+    displayTitle: "Tried to commit or merge on main/master",
+    impact: "Work should land via PR — direct commits skip review.",
     description: "Block git commits and merges on main/master branch",
     fn: blockWorkOnMain,
     match: { events: ["PreToolUse"], toolNames: ["Bash"] },
@@ -1785,6 +1832,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   },
   {
     name: "warn-git-amend",
+    displayTitle: "Used git commit --amend",
+    impact: "Amending after a push rewrites history that others may have pulled.",
     description: "Warns before amending git commits, which rewrites history",
     fn: warnGitAmend,
     match: { events: ["PreToolUse"], toolNames: ["Bash"] },
@@ -1793,6 +1842,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   },
   {
     name: "warn-git-stash-drop",
+    displayTitle: "Tried to drop or clear git stash",
+    impact: "Stash deletions are permanent and silent.",
     description: "Warns before permanently deleting stashed changes",
     fn: warnGitStashDrop,
     match: { events: ["PreToolUse"], toolNames: ["Bash"] },
@@ -1801,6 +1852,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   },
   {
     name: "warn-all-files-staged",
+    displayTitle: "Staged all files with git add -A / .",
+    impact: "Wide stages routinely catch generated files or secrets you didn't intend to commit.",
     description: "Warns before staging all working tree files with git add -A / . / --all",
     fn: warnAllFilesStaged,
     match: { events: ["PreToolUse"], toolNames: ["Bash"] },
@@ -1809,6 +1862,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   },
   {
     name: "warn-destructive-sql",
+    displayTitle: "Ran destructive SQL (DROP / TRUNCATE / DELETE without WHERE)",
+    impact: "Easy way to wipe a table by accident.",
     description: "Warn before executing destructive SQL (DROP/TRUNCATE/DELETE without WHERE) via database clients",
     fn: warnDestructiveSql,
     match: { events: ["PreToolUse"], toolNames: ["Bash"] },
@@ -1817,6 +1872,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   },
   {
     name: "warn-schema-alteration",
+    displayTitle: "Altered a database schema column",
+    impact: "ALTER TABLE operations can lock tables and break readers.",
     description: "Warns before SQL schema changes (ALTER TABLE with column or rename operations)",
     fn: warnSchemaAlteration,
     match: { events: ["PreToolUse"], toolNames: ["Bash"] },
@@ -1825,6 +1882,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   },
   {
     name: "warn-package-publish",
+    displayTitle: "Tried to publish a package",
+    impact: "Publishes are irreversible — `npm publish` / `cargo publish` shouldn't happen without intent.",
     description: "Warn before publishing packages to public registries (npm, PyPI, crates.io, RubyGems, etc.)",
     fn: warnPackagePublish,
     match: { events: ["PreToolUse"], toolNames: ["Bash"] },
@@ -1833,6 +1892,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   },
   {
     name: "warn-global-package-install",
+    displayTitle: "Installed a package globally",
+    impact: "`npm i -g`, `cargo install`, `pip --user` pollute your machine outside the project.",
     description: "Warns before installing packages globally (npm -g, cargo install, etc.)",
     fn: warnGlobalPackageInstall,
     match: { events: ["PreToolUse"], toolNames: ["Bash"] },
@@ -1841,6 +1902,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   },
   {
     name: "prefer-package-manager",
+    displayTitle: "Used a non-preferred package manager",
+    impact: "Mixing package managers creates lockfile churn for your team.",
     description: "Blocks non-preferred package managers and tells Claude to use an allowed one (e.g., uv instead of pip)",
     fn: preferPackageManager,
     match: { events: ["PreToolUse"], toolNames: ["Bash"] },
@@ -1861,6 +1924,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   },
   {
     name: "warn-large-file-write",
+    displayTitle: "Wrote a file larger than the configured threshold",
+    impact: "Catches accidentally large file writes (logs, binaries, model dumps).",
     description: "Warn before writing files larger than 1MB (configurable via thresholdKb param)",
     fn: warnLargeFileWrite,
     match: { events: ["PreToolUse"], toolNames: ["Write"] },
@@ -1876,6 +1941,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   },
   {
     name: "warn-background-process",
+    displayTitle: "Started a long-lived background process",
+    impact: "Catches `nohup` / `&` / `screen` / `tmux` / `disown` patterns that the agent often forgets to clean up.",
     description: "Warns before starting detached or background processes",
     fn: warnBackgroundProcess,
     match: { events: ["PreToolUse"], toolNames: ["Bash"] },
@@ -1884,6 +1951,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   },
   {
     name: "warn-repeated-tool-calls",
+    displayTitle: "Called the same tool 3+ times with identical arguments",
+    impact: "Usually a sign of a stuck loop burning tokens.",
     description: "Warn when the same tool is called 3+ times with identical parameters",
     fn: warnRepeatedToolCalls,
     match: { events: ["PreToolUse"] },
@@ -1892,6 +1961,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   },
   {
     name: "require-commit-before-stop",
+    displayTitle: "Stopped with uncommitted changes",
+    impact: "Work not in a commit is invisible to teammates and easy to lose.",
     description: "Require all changes to be committed before Claude stops",
     fn: requireCommitBeforeStop,
     match: { events: ["Stop"] },
@@ -1900,6 +1971,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   },
   {
     name: "require-push-before-stop",
+    displayTitle: "Stopped with unpushed commits",
+    impact: "Local-only commits won't trigger CI or be reviewable.",
     description: "Require all commits to be pushed to remote before Claude stops",
     fn: requirePushBeforeStop,
     match: { events: ["Stop"] },
@@ -1920,6 +1993,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   },
   {
     name: "require-pr-before-stop",
+    displayTitle: "Stopped without a PR for the branch",
+    impact: "Branches without PRs don't get reviewed.",
     description: "Require a pull request to exist for the current branch before Claude stops",
     fn: requirePrBeforeStop,
     match: { events: ["Stop"] },
@@ -1935,6 +2010,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   },
   {
     name: "require-no-conflicts-before-stop",
+    displayTitle: "Stopped with a branch that conflicts with main",
+    impact: "Conflicting branches can't merge — surface them early.",
     description: "Require the current branch to merge cleanly with the base branch before Claude stops",
     fn: requireNoConflictsBeforeStop,
     match: { events: ["Stop"] },
@@ -1950,6 +2027,8 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
   },
   {
     name: "require-ci-green-before-stop",
+    displayTitle: "Stopped with failing CI",
+    impact: "Failing CI blocks deploy.",
     description: "Require CI checks to pass on the current HEAD commit before Claude stops (ignores stale runs on prior commits)",
     fn: requireCiGreenBeforeStop,
     match: { events: ["Stop"] },

package/src/hooks/custom-hooks-loader.ts

@@ -18,6 +18,8 @@ import { hookLogWarn, hookLogError, hookLogInfo } from "./hook-logger";
 import { getCustomHooks, clearCustomHooks } from "./custom-hooks-registry";
 import { findDistIndex, rewriteFileTree, TMP_SUFFIX, cleanupTmpFiles } from "./loader-utils";
 import { findProjectConfigDir } from "./hooks-config";
+import { trackHookEvent } from "./hook-telemetry";
+import { getInstanceId } from "../../lib/telemetry-id";
 import type { CustomHook } from "./policy-types";
 
 const LOADING_KEY = "__FAILPROOFAI_LOADING_HOOKS__";
@@ -46,7 +48,10 @@ export function discoverPolicyFiles(dir: string): string[] {
  * Load a single policy file into the globalThis custom hooks registry.
  * Does NOT clear the registry — caller is responsible for that.
  */
-async function loadSingleFile(absPath: string, opts?: { strict?: boolean }): Promise<void> {
+async function loadSingleFile(
+  absPath: string,
+  opts?: { strict?: boolean; conventionScope?: "project" | "user" },
+): Promise<void> {
   const g = globalThis as Record<string, unknown>;
   g[LOADING_KEY] = true;
 
@@ -62,6 +67,17 @@ async function loadSingleFile(absPath: string, opts?: { strict?: boolean }): Pro
     await import(/* webpackIgnore: true */ fileUrl);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
+    const errorType = /Cannot find module|MODULE_NOT_FOUND|ENOENT/i.test(msg)
+      ? "module_not_found"
+      : /SyntaxError|Unexpected token/i.test(msg)
+        ? "syntax_error"
+        : "runtime_error";
+    void trackHookEvent(getInstanceId(), "custom_hooks_load_error", {
+      error_type: errorType,
+      is_convention: !!opts?.conventionScope,
+      convention_scope: opts?.conventionScope ?? null,
+      file_basename: basename(absPath),
+    });
     if (opts?.strict) throw new Error(`Failed to load custom hooks from ${absPath}: ${msg}`);
     hookLogError(`failed to load custom hooks from ${absPath}: ${msg}`);
   } finally {
@@ -148,7 +164,7 @@ export async function loadAllCustomHooks(
   const projectFiles = discoverPolicyFiles(projectDir);
   for (const file of projectFiles) {
     const hooksBefore = getCustomHooks().length;
-    await loadSingleFile(file);
+    await loadSingleFile(file, { conventionScope: "project" });
     const newHooks = getCustomHooks().slice(hooksBefore);
     if (newHooks.length > 0) {
       conventionSources.push({
@@ -164,7 +180,7 @@ export async function loadAllCustomHooks(
   const userFiles = discoverPolicyFiles(userDir);
   for (const file of userFiles) {
     const hooksBefore = getCustomHooks().length;
-    await loadSingleFile(file);
+    await loadSingleFile(file, { conventionScope: "user" });
     const newHooks = getCustomHooks().slice(hooksBefore);
     if (newHooks.length > 0) {
       conventionSources.push({

package/src/hooks/first-run-nudge.ts

@@ -0,0 +1,146 @@
+/**
+ * First-run nudge for `failproofai` (no-args invocation).
+ *
+ * Fires when a user runs the bare CLI without having installed any policies on
+ * any detected agent CLI. PostHog data showed only ~10% of npm-installed users
+ * ran `failproofai policies --install`; this prompt closes the awareness gap
+ * by offering to run that install inline.
+ *
+ * The hooks themselves are the sentinel — if any are installed for any
+ * detected CLI, we never prompt again. No separate state file needed.
+ *
+ * Honors `FAILPROOFAI_NO_FIRST_RUN=1` for opt-out, falls back to a short
+ * stderr hint in non-TTY contexts (CI, piped invocations).
+ */
+import * as readline from "node:readline";
+
+import { detectInstalledClis, getIntegration } from "./integrations";
+import { installHooks } from "./manager";
+import { trackHookEvent } from "./hook-telemetry";
+import { getInstanceId } from "../../lib/telemetry-id";
+import type { IntegrationType } from "./types";
+
+type TTYIn = NodeJS.ReadableStream & { isTTY?: boolean };
+type TTYOut = NodeJS.WritableStream & { isTTY?: boolean };
+
+export interface FirstRunNudgeOptions {
+  stdin?: TTYIn;
+  stdout?: TTYOut;
+}
+
+async function emit(event: string, props: Record<string, unknown>): Promise<void> {
+  try {
+    await trackHookEvent(getInstanceId(), event, props);
+  } catch {
+    // Telemetry must never break first-run UX.
+  }
+}
+
+function anyHooksInstalled(detected: IntegrationType[]): boolean {
+  for (const id of detected) {
+    const integration = getIntegration(id);
+    for (const scope of integration.scopes) {
+      try {
+        if (integration.hooksInstalledInSettings(scope)) return true;
+      } catch {
+        // A broken settings file shouldn't suppress the nudge.
+      }
+    }
+  }
+  return false;
+}
+
+function clisLabel(detected: IntegrationType[]): string {
+  return detected.map((id) => getIntegration(id).displayName).join(", ");
+}
+
+async function promptYesNo(
+  stdin: TTYIn,
+  stdout: TTYOut,
+): Promise<"yes" | "no" | "sigint"> {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: stdin, output: stdout });
+    let settled = false;
+    const finish = (answer: "yes" | "no" | "sigint") => {
+      if (settled) return;
+      settled = true;
+      rl.close();
+      resolve(answer);
+    };
+    rl.on("SIGINT", () => finish("sigint"));
+    rl.question("Install policies now? [Y/n] ", (raw) => {
+      const a = (raw ?? "").trim().toLowerCase();
+      if (a === "" || a === "y" || a === "yes") finish("yes");
+      else finish("no");
+    });
+  });
+}
+
+export async function maybeRunFirstRunNudge(opts: FirstRunNudgeOptions = {}): Promise<void> {
+  if (process.env.FAILPROOFAI_NO_FIRST_RUN === "1") return;
+
+  const stdin: TTYIn = opts.stdin ?? process.stdin;
+  const stdout: TTYOut = opts.stdout ?? process.stdout;
+
+  let detected: IntegrationType[];
+  try {
+    detected = detectInstalledClis();
+  } catch {
+    return;
+  }
+  if (detected.length === 0) return;
+
+  if (anyHooksInstalled(detected)) return;
+
+  const detectedProps = { detected_clis: detected, detected_count: detected.length };
+
+  if (!stdin.isTTY || !stdout.isTTY) {
+    stdout.write(
+      `\n[failproofai] No policies are installed. Run \`failproofai policies --install\` to set them up.\n` +
+        `[failproofai] Launching dashboard…\n\n`,
+    );
+    await emit("first_run_nudge_skipped_noninteractive", detectedProps);
+    return;
+  }
+
+  stdout.write(
+    `\n┌─ Failproof AI — first-run setup ────────────────────────────────────\n` +
+      `│  Detected agent CLI(s): ${clisLabel(detected)}\n` +
+      `│  Policies block unsafe actions (sudo, rm -rf /, secret leaks, …)\n` +
+      `│  before your agent runs them. Nothing is installed yet.\n` +
+      `└──────────────────────────────────────────────────────────────────────\n\n` +
+      `  Disable this prompt anytime: FAILPROOFAI_NO_FIRST_RUN=1\n\n`,
+  );
+
+  await emit("first_run_nudge_shown", detectedProps);
+
+  const answer = await promptYesNo(stdin, stdout);
+
+  if (answer === "sigint") {
+    await emit("first_run_nudge_declined", { ...detectedProps, reason: "sigint" });
+    process.exit(130);
+  }
+
+  if (answer === "no") {
+    await emit("first_run_nudge_declined", { ...detectedProps, reason: "user_no" });
+    return;
+  }
+
+  await emit("first_run_nudge_accepted", {
+    ...detectedProps,
+    target_scope: "user",
+    source: "first-run-nudge",
+  });
+
+  await installHooks(
+    undefined,
+    "user",
+    undefined,
+    false,
+    "first-run-nudge",
+    undefined,
+    false,
+    detected,
+  );
+  process.exit(0);
+}