failproofai 1.0.1-beta.0 → 1.0.1

package/.next/standalone/docs-old/de/getting-started.mdx

@@ -0,0 +1,199 @@
+---
+title: Erste Schritte
+description: "Installiere failproofai, aktiviere Richtlinien und lass deine Agenten zuverlässig laufen"
+icon: rocket
+---
+
+## Voraussetzungen
+
+- **Node.js** >= 20.9.0
+- **Bun** >= 1.3.0 (optional – nur für den Build aus dem Quellcode erforderlich)
+
+---
+
+## Installation
+
+<CodeGroup>
+
+```bash npm
+npm install -g failproofai
+```
+
+```bash bun
+bun add -g failproofai
+```
+
+</CodeGroup>
+
+---
+
+## Schnellstart
+
+<Steps>
+  <Step title="Richtlinien aktivieren">
+    Richtlinien sind Regeln, die vor und nach jedem Tool-Aufruf eines Agenten ausgeführt werden. Sie erkennen destruktive Befehle, das Durchsickern von Geheimnissen und andere Fehlerquellen, bevor sie Schaden anrichten.
+
+    ```bash
+    failproofai policies --install
+    ```
+
+    Dies schreibt Hook-Einträge in die installierten Agenten-CLIs (Claude Code's `~/.claude/settings.json`, OpenAI Codex's `~/.codex/hooks.json`, GitHub Copilot CLI's `~/.copilot/hooks/failproofai.json`, Cursor Agent's `~/.cursor/hooks.json`, OpenCode's generiertes Plugin-Shim unter `~/.config/opencode/plugins/failproofai.mjs` plus einen Registrierungseintrag im `plugin`-Array von `~/.config/opencode/opencode.json`, Pi's `~/.pi/agent/settings.json`, Hermes's `~/.hermes/config.yaml`, OpenClaw's `~/.openclaw/openclaw.json`, Factory Droid's `~/.factory/hooks.json`, Devin CLI's `~/.config/devin/config.json`, Antigravity CLI's `~/.gemini/config/hooks.json` oder Goose's automatisch erkanntes Plugin-Verzeichnis unter `~/.agents/plugins/failproofai/hooks/hooks.json`). Wenn mehr als eine CLI vorhanden ist, wird eine Abfrage angezeigt; übergib `--cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose` (beliebige Teilmenge), um die Abfrage zu überspringen.
+
+    GitHub Copilot CLI, Cursor Agent, OpenCode und Pi-Unterstützung sind **Beta** – installiere mit `--cli copilot`, `--cli cursor`, `--cli opencode` oder `--cli pi`. Hermes (hermes-agent, ein Slack/Telegram-Gateway) wird im User-Scope mit `--cli hermes` installiert und ist **außerdem** eine Offline-Audit-Quelle. OpenClaw (openclaw-Gateway, ein selbst gehosteter Multi-Channel-Assistent) wird im User-Scope mit `--cli openclaw` installiert – die Durchsetzung erfolgt über seine In-Process-Plugin-Hooks (`before_agent_finalize` ist ein echter Turn-End-Gate, sodass die eingebauten `require-*-before-stop`-Richtlinien greifen) – und ist **außerdem** eine Offline-Audit-Quelle. Factory Droid (`droid`) wird mit `--cli factory` (User- und Projekt-Scope) installiert und ist **außerdem** eine Offline-Audit-Quelle. Devin CLI (`devin`, Cognition) wird mit `--cli devin` (User- und Projekt-Scope) installiert und ist **außerdem** eine Offline-Audit-Quelle. Antigravity CLI (`agy`) wird mit `--cli antigravity` (User- und Projekt-Scope) installiert und ist **außerdem** eine Offline-Audit-Quelle. Goose (Codename goose, Block) wird mit `--cli goose` (User- und Projekt-Scope) installiert – der Installer legt ein Plugin-Verzeichnis unter `~/.agents/plugins/failproofai/` an, das Goose automatisch erkennt, und ist **außerdem** eine Offline-Audit-Quelle.
+
+    ```bash
+    failproofai policies --install --scope project
+    failproofai policies --install --cli codex --scope project
+    failproofai policies --install --cli copilot --scope project
+    failproofai policies --install --cli cursor --scope project
+    failproofai policies --install --cli opencode --scope project
+    failproofai policies --install --cli pi --scope project
+    failproofai policies --install --cli hermes --scope user
+    failproofai policies --install --cli openclaw --scope user
+    failproofai policies --install --cli factory --scope project
+    failproofai policies --install --cli devin --scope project
+    failproofai policies --install --cli antigravity --scope project
+    failproofai policies --install --cli goose --scope project
+    failproofai policies --install block-sudo block-rm-rf sanitize-api-keys
+    ```
+  </Step>
+  <Step title="Überprüfen">
+    ```bash
+    failproofai policies
+    ```
+
+    Zeigt jede Richtlinie an, ob sie aktiviert ist und welche Parameter konfiguriert sind.
+  </Step>
+  <Step title="Dashboard starten">
+    ```bash
+    failproofai
+    ```
+
+    Öffnet ein lokales Dashboard unter `http://localhost:8020`, in dem du Sitzungen durchsuchen, Tool-Aufrufe untersuchen und Richtlinien verwalten kannst.
+  </Step>
+  <Step title="Agenten starten">
+    Starte Claude Code wie gewohnt. Wenn der Agent etwas Riskantes versucht, greift failproofai automatisch ein. Lass ihn unbeaufsichtigt laufen und überprüfe im Dashboard, was passiert ist.
+  </Step>
+</Steps>
+
+---
+
+## Wie Richtlinien funktionieren
+
+Jedes Mal, wenn ein Agent ein Tool ausführt, ruft Claude Code failproofai als Unterprozess auf:
+
+```text
+Claude Code  →  failproofai --hook PreToolUse  →  reads stdin JSON
+                                                 evaluates policies
+                                                 writes decision to stdout
+```
+
+Jede Richtlinie gibt eine von drei Entscheidungen zurück:
+
+- **allow** – der Agent fährt normal fort
+- **deny** – die Aktion wird blockiert und der Agent wird über den Grund informiert
+- **instruct** – dem Prompt des Agenten wird zusätzlicher Kontext hinzugefügt
+
+<Note>
+Richtlinien werden in deinem lokalen Prozess ausgeführt. Es werden keine Daten an einen Remote-Dienst gesendet.
+</Note>
+
+---
+
+## Team-Richtlinien mit konventionsbasierten Richtlinien einrichten
+
+Der schnellste Weg, Qualitätsstandards im gesamten Team zu etablieren, ist die `.failproofai/policies/`-Konvention. Lege Richtliniendateien in dieses Verzeichnis und sie werden automatisch geladen – keine Flags, keine Konfigurationsänderungen, keine Install-Befehle.
+
+<Steps>
+  <Step title="Richtlinienverzeichnis erstellen">
+    ```bash
+    mkdir -p .failproofai/policies
+    ```
+  </Step>
+  <Step title="Richtliniendateien hinzufügen">
+    Kopiere die Startbeispiele oder schreibe eigene:
+
+    ```bash
+    cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/
+    ```
+
+    Oder erstelle eine neue:
+
+    ```js
+    // .failproofai/policies/team-policies.mjs
+    import { customPolicies, allow, deny, instruct } from "failproofai";
+
+    customPolicies.add({
+      name: "test-before-commit",
+      match: { events: ["PreToolUse"] },
+      fn: async (ctx) => {
+        if (ctx.toolName !== "Bash") return allow();
+        if (/git\s+commit/.test(ctx.toolInput?.command ?? "")) {
+          return instruct("Run tests before committing.");
+        }
+        return allow();
+      },
+    });
+    ```
+  </Step>
+  <Step title="In Git einchecken">
+    ```bash
+    git add .failproofai/policies/
+    git commit -m "Add team quality policies"
+    ```
+
+    Jedes Teammitglied, das failproofai installiert hat, übernimmt diese Richtlinien automatisch. Kein Setup pro Entwickler erforderlich.
+  </Step>
+</Steps>
+
+<Tip>
+Checke `.failproofai/policies/` in dein Repository ein, damit das gesamte Team dieselben Standards teilt. Wenn dein Team neue Fehlerquellen entdeckt, füge Richtlinien hinzu und pushe – alle erhalten das Update beim nächsten `git pull`. Mit der Zeit werden diese Richtlinien zu einem lebendigen Qualitätsstandard, der sich kontinuierlich verbessert.
+</Tip>
+
+---
+
+## Datenspeicherung
+
+Alle Konfigurationen und Protokolle verbleiben auf deinem Rechner:
+
+| Pfad | Was gespeichert wird |
+|------|----------------------|
+| `~/.failproofai/policies/local-policies/policies-config.json` | Globale Richtlinienkonfiguration |
+| `~/.failproofai/hook-activity/` | Hook-Ausführungsverlauf (seitenweise JSONL) |
+| `~/.failproofai/logs/` | Debug-Protokolle für benutzerdefinierte Hook-Fehler |
+| `.failproofai/policies-config.json` | Projektbezogene Konfiguration (eingecheckt) |
+| `.failproofai/policies-config.local.json` | Persönliche Überschreibungen (gitignored) |
+
+---
+
+## Deinstallation
+
+```bash
+failproofai policies --uninstall
+```
+
+Entfernt Hook-Einträge aus `~/.claude/settings.json`. Konfigurationsdateien in `~/.failproofai/` bleiben erhalten.
+
+---
+
+## Nächste Schritte
+
+<CardGroup cols={2}>
+
+<Card title="Konfiguration" icon="gear" href="/de/configuration">
+  Scopes und Konfigurationsdateiformat
+</Card>
+
+<Card title="Integrierte Richtlinien" icon="shield" href="/de/built-in-policies">
+  Alle 26 Richtlinien mit Parametern
+</Card>
+
+<Card title="Benutzerdefinierte Richtlinien" icon="code" href="/de/custom-policies">
+  Schreibe eigene Richtlinien in JavaScript
+</Card>
+
+<Card title="Agenten-Monitor" icon="chart-line" href="/de/dashboard">
+  Sitzungen überwachen und Richtlinienaktivitäten überprüfen
+</Card>
+
+</CardGroup>

package/.next/standalone/docs-old/de/introduction.mdx

@@ -0,0 +1,57 @@
+---
+title: "Failproof AI"
+description: "FailproofAI gibt KI-Agenten 39 integrierte Fehlerrichtlinien, die Schleifen, Secret-Leaks, destruktive Tool-Aufrufe und mehr mit einer einzigen Installation abfangen."
+---
+
+[![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai)
+
+Hooks und Richtlinien für **KI-Fehlerbehandlung**, **Fehlerwiederherstellung** und **LLM-Zuverlässigkeit**. Halten Sie Ihre KI-Agenten zuverlässig und autonom am Laufen – für **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Hermes**, **OpenClaw**, **Factory Droid**, **Devin CLI**, **Antigravity CLI** und das **Agents SDK**.
+
+KI-Agenten scheitern auf vorhersehbare Weise. Sie führen destruktive Befehle aus, leaken Secrets, driften vom Kurs ab, stecken in Schleifen fest oder pushen direkt auf main. Werden diese Fehler nicht abgefangen, können kleine Probleme zu Ausfällen, geleakten Zugangsdaten und verlorener Arbeit eskalieren.
+
+FailproofAI löst das mit **Richtlinien**. Diese Regeln greifen in jeden Agent-Tool-Aufruf ein, um **Fehler zu erkennen**, **sie zu beheben** (blockieren, anweisen, bereinigen) und **Sie zu benachrichtigen**, wenn etwas Aufmerksamkeit erfordert. Ein lokales Dashboard ermöglicht es Ihnen, anschließend jeden Tool-Aufruf, jeden Agentenfehler und jede Wiederherstellungsaktion nachzuvollziehen.
+
+Transkripte und Richtlinienauswertungen verbleiben auf Ihrem Rechner. Daten werden nur übertragen, wenn Sie explizit eine Online-Funktion nutzen, z. B. authentifizierte Audit-Erinnerungen oder Einladungen.
+
+## Erste Schritte
+
+<CardGroup cols={2}>
+
+<Card title="39 integrierte Richtlinien" icon="shield" href="/de/built-in-policies">
+  Destruktive Befehle blockieren, Secret-Leaks verhindern, Agenten innerhalb der Projektgrenzen halten und vieles mehr. Alles sofort einsatzbereit.
+</Card>
+
+<Card title="Benutzerdefinierte Richtlinien" icon="code" href="/de/custom-policies">
+  Schreiben Sie eigene Regeln in JavaScript mit einer einfachen allow / deny / instruct API.
+</Card>
+
+<Card title="Agenten-Monitor" icon="chart-line" href="/de/dashboard">
+  Sehen Sie, was Ihre Agenten in Ihrer Abwesenheit getan haben. Sitzungen durchsuchen, Tool-Aufrufe prüfen, nachverfolgen, wo Richtlinien ausgelöst wurden.
+</Card>
+
+<Card title="Einfache Konfiguration" icon="gear" href="/de/configuration">
+  Jede Richtlinie ohne Code anpassen. Allowlists, geschützte Branches oder Schwellenwerte pro Projekt oder global festlegen.
+</Card>
+
+</CardGroup>
+
+## Schnellstart
+
+<CodeGroup>
+
+```bash npm
+npm install -g failproofai
+```
+
+```bash bun
+bun add -g failproofai
+```
+
+</CodeGroup>
+
+```bash
+failproofai policies --install   # enable policies (or skip — `failproofai` will offer to set them up on first run)
+failproofai                      # launch the dashboard
+```
+
+Die vollständige Anleitung finden Sie im [Erste-Schritte-Leitfaden](/de/getting-started).

package/.next/standalone/docs-old/de/package-aliases.mdx

@@ -0,0 +1,82 @@
+---
+title: Package-Aliasse
+description: "Registrierte Aliasse zur Typosquatting-Prävention und wie sie funktionieren"
+icon: copy
+---
+
+## Offizielles Paket
+
+Das kanonische npm-Paket ist **`failproofai`**:
+
+```bash
+npm install -g failproofai
+# or
+bun add -g failproofai
+```
+
+---
+
+## Warum wir die Aliasnamen besitzen
+
+Typosquatting ist ein verbreiteter Supply-Chain-Angriff, bei dem ein böswilliger Akteur einen Paketnamen registriert, der sich nur um einen Tastendruck vom Namen eines verbreiteten Pakets unterscheidet. Ahnungslose Nutzer, die den Installationsbefehl vertippen, führen dadurch angreifer-kontrollierten Code mit vollem Systemzugriff aus – genau die Art von Bedrohung, gegen die Failproof AI schützen soll.
+
+Um diese Angriffsfläche zu eliminieren, **registrieren wir vorbeugend alle gängigen Schreibfehler und Formatierungsvarianten** von `failproofai` auf npm. Keiner dieser Namen kann von Dritten registriert werden. Jeder ist ein schlanker Proxy, der das echte `failproofai`-Paket installiert und an dieses delegiert.
+
+---
+
+## Registrierte Aliasse
+
+**Formatierungsvarianten** – verschiedene Schreibweisen von „failproof ai":
+
+| Paket | Status |
+|-------|--------|
+| `failproof` | ✅ Veröffentlicht |
+| `failproof-ai` | ⏳ Ausstehend (npm-Freigabe) |
+| `fail-proof-ai` | ⏳ Ausstehend (npm-Freigabe) |
+| `failproof_ai` | ⏳ Ausstehend (npm-Freigabe) |
+| `fail_proof_ai` | ⏳ Ausstehend (npm-Freigabe) |
+| `fail-proofai` | ⏳ Ausstehend (npm-Freigabe) |
+
+**`failprof*`-Tippfehler** – fehlendes „o" in „proof":
+
+| Paket | Status |
+|-------|--------|
+| `failprof` | ✅ Veröffentlicht |
+| `failprof-ai` | ✅ Veröffentlicht |
+| `failprofai` | ⏳ Ausstehend (npm-Freigabe) |
+| `fail-prof-ai` | ⏳ Ausstehend (npm-Freigabe) |
+| `failprof_ai` | ⏳ Ausstehend (npm-Freigabe) |
+
+**`faliproof*`-Tippfehler** – vertauschtes „a" und „i":
+
+| Paket | Status |
+|-------|--------|
+| `faliproof` | ✅ Veröffentlicht |
+| `faliproof-ai` | ✅ Veröffentlicht |
+| `faliproofai` | ⏳ Ausstehend (npm-Freigabe) |
+
+> **Warum ausstehend?** Die Spam-Prävention von npm blockiert Namen, die nach dem Entfernen von Satzzeichen und dem Ausführen von Ähnlichkeitsprüfungen auf denselben String wie ein bestehendes Paket normalisiert werden. Wir haben den npm-Support kontaktiert, um diese Namen für Anti-Squatting-Zwecke zu reservieren. Sie werden nach der Genehmigung aktiviert.
+
+Sie können prüfen, ob ein veröffentlichter Alias uns gehört:
+
+```bash
+npm info failproof
+# Look for: "ExosphereHost Inc." in the maintainers field
+```
+
+---
+
+## Wie die Aliasse funktionieren
+
+Jedes Alias-Paket:
+
+1. Listet `failproofai` als Abhängigkeit auf – damit wird das eigentliche Paket installiert und sein Binary verfügbar
+2. Stellt ein Binary bereit, das dem eigenen Namen entspricht (z. B. `failprof-ai`) und alle Argumente an das `failproofai`-Binary weiterleitet
+
+Der Proxy ist ein zweizeiliges Node-Skript; es enthält keine Logik, keine Netzwerkaufrufe und keine Datenerfassung über das hinaus, was `failproofai` selbst tut.
+
+---
+
+## Falls Sie einen fehlenden Namen entdecken
+
+Erstellen Sie ein Issue unter [failproofai/failproofai](https://github.com/failproofai/failproofai/issues), und wir werden ihn registrieren.

package/.next/standalone/docs-old/de/testing.mdx

@@ -0,0 +1,260 @@
+---
+title: Testing
+description: "Unit-Tests, E2E-Tests und Test-Hilfsfunktionen"
+icon: flask-vial
+---
+
+failproofai verfügt über zwei Test-Suiten: **Unit-Tests** (schnell, mit Mocks) und **End-to-End-Tests** (echte Subprocess-Aufrufe).
+
+---
+
+## Tests ausführen
+
+```bash
+# Alle Unit-Tests einmalig ausführen
+bun run test:run
+
+# Unit-Tests im Watch-Modus ausführen
+bun run test
+
+# E2E-Tests ausführen (erfordert Setup – siehe unten)
+bun run test:e2e
+
+# Typprüfung ohne Build
+bunx tsc --noEmit
+
+# Linting
+bun run lint
+```
+
+---
+
+## Unit-Tests
+
+Unit-Tests befinden sich in `__tests__/` und verwenden [Vitest](https://vitest.dev) mit `jsdom`.
+
+```text
+__tests__/
+  hooks/
+    builtin-policies.test.ts      # Policy-Logik für jede eingebaute Policy
+    hooks-config.test.ts          # Konfigurationsladen und Scope-Zusammenführung
+    policy-evaluator.test.ts      # Param-Injektion und Auswertungsreihenfolge
+    custom-hooks-registry.test.ts # globalThis-Registry add/get/clear
+    custom-hooks-loader.test.ts   # ESM-Loader, transitive Imports, Fehlerbehandlung
+    manager.test.ts               # install/remove/list-Operationen
+  components/
+    sessions-list.test.tsx        # Session-Listen-Komponente
+    project-list.test.tsx         # Projektlisten-Komponente
+    ...
+  lib/
+    logger.test.ts
+    paths.test.ts
+    date-filters.test.ts
+    telemetry.test.ts
+    ...
+  actions/
+    get-hooks-config.test.ts
+    get-hook-activity.test.ts
+    ...
+  contexts/
+    ThemeContext.test.tsx
+    AutoRefreshContext.test.tsx
+```
+
+### Einen Policy-Unit-Test schreiben
+
+```typescript
+import { describe, it, expect, beforeEach } from "vitest";
+import { getBuiltinPolicies } from "../../src/hooks/builtin-policies";
+import { allow, deny } from "../../src/hooks/policy-types";
+
+describe("block-sudo", () => {
+  const policy = getBuiltinPolicies().find((p) => p.name === "block-sudo")!;
+
+  it("denies sudo commands", () => {
+    const ctx = {
+      eventType: "PreToolUse" as const,
+      payload: {},
+      toolName: "Bash",
+      toolInput: { command: "sudo apt install nodejs" },
+      params: { allowPatterns: [] },
+    };
+    expect(policy.fn(ctx)).toEqual(deny("sudo command blocked by failproofai"));
+  });
+
+  it("allows non-sudo commands", () => {
+    const ctx = {
+      eventType: "PreToolUse" as const,
+      payload: {},
+      toolName: "Bash",
+      toolInput: { command: "ls -la" },
+      params: { allowPatterns: [] },
+    };
+    expect(policy.fn(ctx)).toEqual(allow());
+  });
+
+  it("allows patterns in allowPatterns", () => {
+    const ctx = {
+      eventType: "PreToolUse" as const,
+      payload: {},
+      toolName: "Bash",
+      toolInput: { command: "sudo systemctl status nginx" },
+      params: { allowPatterns: ["sudo systemctl status"] },
+    };
+    expect(policy.fn(ctx)).toEqual(allow());
+  });
+});
+```
+
+---
+
+## End-to-End-Tests
+
+E2E-Tests rufen das echte `failproofai`-Binary als Subprocess auf, leiten eine JSON-Payload an stdin weiter und prüfen die stdout-Ausgabe sowie den Exit-Code. Damit wird der vollständige Integrationspfad getestet, den Claude Code verwendet.
+
+### Setup
+
+E2E-Tests führen das Binary direkt aus dem Repo-Quellcode aus. Vor dem ersten Durchlauf muss das CJS-Bundle gebaut werden, das Custom-Hook-Dateien beim Import von `'failproofai'` verwenden:
+
+```bash
+bun build src/index.ts --outdir dist --target node --format cjs
+```
+
+Anschließend die Tests ausführen:
+
+```bash
+bun run test:e2e
+```
+
+`dist/` muss neu gebaut werden, wenn die öffentliche Hook-API geändert wird (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts` oder `src/hooks/policy-types.ts`).
+
+### E2E-Teststruktur
+
+```text
+__tests__/e2e/
+  helpers/
+    hook-runner.ts      # Binary starten, Payload-JSON weiterleiten, Exit-Code + stdout + stderr erfassen
+    fixture-env.ts      # Pro Test isolierte temporäre Verzeichnisse mit Konfigurationsdateien
+    payloads.ts         # Claude-konforme Payload-Factories für jeden Event-Typ
+  hooks/
+    builtin-policies.e2e.test.ts   # Jede eingebaute Policy mit echtem Subprocess
+    custom-hooks.e2e.test.ts       # Laden und Auswerten von Custom Hooks
+    config-scopes.e2e.test.ts      # Konfigurationszusammenführung über project/local/global
+    policy-params.e2e.test.ts      # Parameter-Injektion für jede parametrisierte Policy
+```
+
+### Die E2E-Hilfsfunktionen verwenden
+
+**`FixtureEnv`** – isolierte Umgebung pro Test:
+
+```typescript
+import { createFixtureEnv } from "../helpers/fixture-env";
+
+const env = createFixtureEnv();
+// env.cwd    - temporäres Verzeichnis; als payload.cwd übergeben, um .failproofai/policies-config.json einzulesen
+// env.home   - isoliertes Home-Verzeichnis; kein echtes ~/.failproofai wird eingelesen
+
+env.writeConfig({
+  enabledPolicies: ["block-sudo"],
+  policyParams: {
+    "block-sudo": { allowPatterns: ["sudo systemctl status"] },
+  },
+});
+```
+
+`createFixtureEnv()` registriert `afterEach`-Cleanup automatisch.
+
+**`runHook`** – das Binary aufrufen:
+
+```typescript
+import { runHook } from "../helpers/hook-runner";
+import { Payloads } from "../helpers/payloads";
+
+const result = await runHook(
+  "PreToolUse",
+  Payloads.preToolUse.bash("sudo apt install nodejs", env.cwd),
+  { homeDir: env.home }
+);
+
+expect(result.exitCode).toBe(0);
+expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny");
+```
+
+**`Payloads`** – fertige Payload-Factories:
+
+```typescript
+Payloads.preToolUse.bash(command, cwd)
+Payloads.preToolUse.write(filePath, content, cwd)
+Payloads.preToolUse.read(filePath, cwd)
+Payloads.postToolUse.bash(command, output, cwd)
+Payloads.postToolUse.read(filePath, content, cwd)
+Payloads.notification(message, cwd)
+Payloads.stop(cwd)
+```
+
+### Einen E2E-Test schreiben
+
+```typescript
+import { describe, it, expect } from "vitest";
+import { createFixtureEnv } from "../helpers/fixture-env";
+import { runHook } from "../helpers/hook-runner";
+import { Payloads } from "../helpers/payloads";
+
+describe("block-rm-rf (E2E)", () => {
+  it("denies rm -rf", async () => {
+    const env = createFixtureEnv();
+    env.writeConfig({ enabledPolicies: ["block-rm-rf"] });
+
+    const result = await runHook(
+      "PreToolUse",
+      Payloads.preToolUse.bash("rm -rf /", env.cwd),
+      { homeDir: env.home }
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny");
+  });
+
+  it("allows non-recursive rm", async () => {
+    const env = createFixtureEnv();
+    env.writeConfig({ enabledPolicies: ["block-rm-rf"] });
+
+    const result = await runHook(
+      "PreToolUse",
+      Payloads.preToolUse.bash("rm /tmp/file.txt", env.cwd),
+      { homeDir: env.home }
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toBe("");  // allow → leerer stdout
+  });
+});
+```
+
+### E2E-Antwortformate
+
+| Entscheidung | Exit-Code | stdout |
+|----------|-----------|--------|
+| `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` |
+| `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` |
+| Instruct (kein Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` |
+| Stop instruct | `2` | leerer stdout; Grund in stderr |
+| Allow | `0` | leerer String |
+
+### Vitest-Konfiguration
+
+E2E-Tests verwenden `vitest.config.e2e.mts` mit:
+
+- `environment: "node"` – keine Browser-Globals erforderlich
+- `pool: "forks"` – echte Prozessisolierung (Tests starten Subprozesse)
+- `testTimeout: 20_000` – 20 Sekunden pro Test (Binary-Start + Hook-Auswertung)
+
+Der `forks`-Pool ist wichtig: Thread-basierte Worker teilen `globalThis`, was Subprozess-startende Tests beeinträchtigen kann. Prozessbasierte Forks vermeiden dieses Problem.
+
+---
+
+## CI
+
+Der vollständige CI-Durchlauf (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) muss erfolgreich sein, bevor ein Merge durchgeführt werden kann. Die E2E-Suite wird als separater CI-Job parallel ausgeführt.
+
+Die vollständige Checkliste vor dem Merge ist unter [Contributing](../CONTRIBUTING.md) zu finden.