failproofai 1.0.1-beta.0 → 1.0.1

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

@@ -0,0 +1,272 @@
+---
+title: Konfiguration
+description: "Konfigurationsdateiformat, Drei-Ebenen-System und Zusammenführungsregeln"
+icon: gear
+---
+
+failproofai verwendet JSON-Konfigurationsdateien, um zu steuern, welche Richtlinien aktiv sind, wie sie sich verhalten und woher benutzerdefinierte Richtlinien geladen werden. Die Konfiguration ist so gestaltet, dass sie sich leicht im Team teilen lässt – committen Sie sie in Ihr Repository und jeder Entwickler erhält dasselbe Sicherheitsnetz für den Agenten.
+
+---
+
+## Konfigurationsebenen
+
+Es gibt drei Konfigurationsebenen, die in Prioritätsreihenfolge ausgewertet werden:
+
+| Ebene | Dateipfad | Zweck |
+|-------|-----------|-------|
+| **project** | `.failproofai/policies-config.json` | Repository-spezifische Einstellungen, in die Versionskontrolle eingecheckt |
+| **local** | `.failproofai/policies-config.local.json` | Persönliche Überschreibungen pro Repository, per gitignore ausgeschlossen |
+| **global** | `~/.failproofai/policies-config.json` | Benutzerweite Standardwerte für alle Projekte |
+
+Wenn failproofai ein Hook-Ereignis empfängt, lädt und zusammenführt es alle drei Dateien, die für das aktuelle Arbeitsverzeichnis existieren.
+
+### Zusammenführungsregeln
+
+**`enabledPolicies`** – die Vereinigung aller drei Ebenen. Eine Richtlinie, die auf einer beliebigen Ebene aktiviert ist, ist aktiv.
+
+```text
+project:  ["block-sudo"]
+local:    ["block-rm-rf"]
+global:   ["block-sudo", "sanitize-api-keys"]
+
+resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← deduplizierte Vereinigung
+```
+
+**`policyParams`** – die erste Ebene, die Parameter für eine bestimmte Richtlinie definiert, gewinnt vollständig. Es findet keine tiefe Zusammenführung von Werten innerhalb der Parameter einer Richtlinie statt.
+
+```text
+project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
+global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
+
+resolved: { allowPatterns: ["sudo apt-get update"] }   ← project gewinnt, global wird ignoriert
+```
+
+```text
+project:  (kein block-sudo-Eintrag)
+local:    (kein block-sudo-Eintrag)
+global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
+
+resolved: { allowPatterns: ["sudo systemctl status"] }  ← fällt auf global zurück
+```
+
+**`customPoliciesPaths` / `customPoliciesPath`** – die erste Ebene, die eine der beiden Formen definiert, gewinnt.
+
+**`disabledCustomPolicies`** – Vereinigung über alle Ebenen. Das Dashboard schreibt hier eine
+quellenqualifizierte ID, wenn Sie eine einzelne Richtlinie aus einer expliziten oder konventionsbasierten
+Richtliniendatei deaktivieren. Nicht aufgeführte Richtlinien bleiben standardmäßig aktiviert;
+IDs enthalten die Quelldatei, sodass gleichnamige Richtlinien in mehreren Dateien
+unabhängig voneinander gesteuert werden können.
+
+**`llm`** – die erste Ebene, die es definiert, gewinnt.
+
+---
+
+## Konfigurationsdateiformat
+
+```json
+{
+  "enabledPolicies": [
+    "block-sudo",
+    "block-rm-rf",
+    "block-push-master",
+    "sanitize-api-keys",
+    "sanitize-jwt",
+    "block-env-files",
+    "block-read-outside-cwd"
+  ],
+  "policyParams": {
+    "block-sudo": {
+      "allowPatterns": ["sudo systemctl status", "sudo journalctl"]
+    },
+    "block-push-master": {
+      "protectedBranches": ["main", "release", "prod"]
+    },
+    "block-rm-rf": {
+      "allowPaths": ["/tmp"]
+    },
+    "block-read-outside-cwd": {
+      "allowPaths": ["/shared/data", "/opt/company"]
+    },
+    "sanitize-api-keys": {
+      "additionalPatterns": [
+        { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo API key" }
+      ]
+    },
+    "warn-large-file-write": {
+      "thresholdKb": 512
+    }
+  },
+  "customPoliciesPath": "/home/alice/myproject/my-policies.js"
+}
+```
+
+---
+
+## Feldreferenz
+
+### `enabledPolicies`
+
+Typ: `string[]`
+
+Liste der zu aktivierenden Richtliniennamen. Die Namen müssen exakt mit den Richtlinienkennungen übereinstimmen, die `failproofai policies` anzeigt. Die vollständige Liste finden Sie unter [Integrierte Richtlinien](/de/built-in-policies).
+
+Richtlinien, die nicht in `enabledPolicies` aufgeführt sind, sind inaktiv, auch wenn sie Einträge in `policyParams` haben.
+
+### `policyParams`
+
+Typ: `Record<string, Record<string, unknown>>`
+
+Parameterüberschreibungen pro Richtlinie. Der äußere Schlüssel ist der Richtlinienname; die inneren Schlüssel sind richtlinienspezifisch. Jede Richtlinie dokumentiert ihre verfügbaren Parameter unter [Integrierte Richtlinien](/de/built-in-policies).
+
+Wenn eine Richtlinie Parameter hat, Sie diese aber nicht angeben, werden die integrierten Standardwerte der Richtlinie verwendet. Benutzer, die `policyParams` gar nicht konfigurieren, erhalten ein identisches Verhalten wie in früheren Versionen.
+
+Unbekannte Schlüssel innerhalb des Parameterblocks einer Richtlinie werden zur Hook-Ausführungszeit stillschweigend ignoriert, aber als Warnungen ausgegeben, wenn Sie `failproofai policies` ausführen.
+
+#### `hint` (übergreifend)
+
+Typ: `string` (optional)
+
+Eine Meldung, die an die Begründung angehängt wird, wenn eine Richtlinie `deny` oder `instruct` zurückgibt. Verwenden Sie dieses Feld, um Claude handlungsrelevante Hinweise zu geben, ohne die Richtlinie selbst zu ändern.
+
+Funktioniert mit jedem Richtlinientyp – integriert, benutzerdefiniert (`custom/`), Projektkonfiguration (`.failproofai-project/`) oder Benutzerkonfiguration (`.failproofai-user/`).
+
+```json
+{
+  "policyParams": {
+    "block-force-push": {
+      "hint": "Try creating a fresh branch instead."
+    },
+    "block-sudo": {
+      "allowPatterns": ["sudo apt-get"],
+      "hint": "Use apt-get directly without sudo."
+    },
+    "custom/my-policy": {
+      "hint": "Ask the user for approval first."
+    }
+  }
+}
+```
+
+Wenn `block-force-push` ablehnt, sieht Claude: *„Force-Pushing ist blockiert. Try creating a fresh branch instead."*
+
+Nicht-String-Werte und leere Zeichenketten werden stillschweigend ignoriert. Wenn `hint` nicht gesetzt ist, bleibt das Verhalten unverändert (abwärtskompatibel).
+
+### `customPoliciesPath`
+
+Typ: `string` (absoluter Pfad)
+
+Pfad zu einer JavaScript-Datei mit benutzerdefinierten Hook-Richtlinien. Dieser wird automatisch durch `failproofai policies --install --custom <path>` gesetzt (der Pfad wird vor der Speicherung in einen absoluten Pfad aufgelöst).
+
+Die Datei wird bei jedem Hook-Ereignis neu geladen – es gibt kein Caching. Details zur Erstellung finden Sie unter [Benutzerdefinierte Richtlinien](/de/custom-policies).
+
+### Konventionsbasierte Richtlinien
+
+Zusätzlich zum expliziten `customPoliciesPath` erkennt und lädt failproofai automatisch Richtliniendateien aus `.failproofai/policies/`-Verzeichnissen:
+
+| Ebene | Verzeichnis | Geltungsbereich |
+|-------|-------------|-----------------|
+| Projekt | `.failproofai/policies/` | Gemeinsam mit dem Team über die Versionskontrolle |
+| Benutzer | `~/.failproofai/policies/custom-policies/` | Persönlich, gilt für alle Projekte |
+
+<Note>
+  Das Verzeichnis auf Benutzerebene wurde im Rahmen der Umstrukturierung des
+  Home-Verzeichnisses eine Ebene tiefer verschoben. Dateien, die noch am alten
+  Speicherort `~/.failproofai/policies/` liegen, werden beim ersten Ausführen
+  eines `failproofai`-Befehls nach dem Upgrade automatisch in `custom-policies/`
+  verschoben, und der Befehl zeigt Ihnen an, welche Dateien verschoben wurden.
+</Note>
+
+**Dateiabgleich:** Es werden nur Dateien geladen, die dem Muster `*policies.{js,mjs,ts}` entsprechen (z. B. `security-policies.mjs`, `workflow-policies.js`). Andere Dateien im Verzeichnis werden ignoriert.
+
+**Keine Konfiguration erforderlich:** Konventionsbasierte Richtlinien benötigen keine Einträge in `policies-config.json`. Legen Sie die Dateien einfach im Verzeichnis ab und sie werden beim nächsten Hook-Ereignis aufgegriffen.
+
+**Gemeinsames Laden:** Sowohl Projekt- als auch Benutzer-Konventionsverzeichnisse werden durchsucht. Alle übereinstimmenden Dateien aus beiden Ebenen werden geladen (im Gegensatz zu `customPoliciesPath`, das die Regel „erste Ebene gewinnt" verwendet).
+
+Weitere Details und Beispiele finden Sie unter [Benutzerdefinierte Richtlinien](/de/custom-policies).
+
+### `llm`
+
+Typ: `object` (optional)
+
+LLM-Client-Konfiguration für Richtlinien, die KI-Aufrufe durchführen. Für die meisten Setups nicht erforderlich.
+
+```json
+{
+  "llm": {
+    "model": "claude-sonnet-4-6",
+    "apiKey": "sk-ant-..."
+  }
+}
+```
+
+---
+
+## Konfiguration über die CLI verwalten
+
+Die Befehle `policies --install` und `policies --uninstall` schreiben in die Hook-Einstellungsdatei Ihrer Agenten-CLI (die Hook-Einstiegspunkte), während `policies-config.json` die Datei ist, die Sie direkt verwalten. Beides ist getrennt:
+
+- **Agenten-CLI-Einstellungen** – weist den Agenten an, bei jeder Werkzeugverwendung `failproofai --hook <event>` aufzurufen:
+  - **Claude Code**: `~/.claude/settings.json` (Benutzer), `<cwd>/.claude/settings.json` (Projekt), `<cwd>/.claude/settings.local.json` (lokal)
+  - **OpenAI Codex**: `~/.codex/hooks.json` (Benutzer), `<cwd>/.codex/hooks.json` (Projekt) – Codex hat keinen `local`-Geltungsbereich
+  - **GitHub Copilot CLI _(Beta)_**: `~/.copilot/hooks/failproofai.json` (Benutzer), `<cwd>/.github/hooks/failproofai.json` (Projekt) – Copilot hat keinen `local`-Geltungsbereich. Hook-Einträge verwenden Copilots betriebssystemspezifische `bash`/`powershell`-Befehlsfelder mit `timeoutSec`; die Datei enthält einen `version: 1`-Marker auf oberster Ebene. Die Unterstützung für Copilot CLI ist **Beta**, während wir das `events.jsonl`-Datensatzschema (das in der öffentlichen Dokumentation nicht spezifiziert ist) gegen mehr reale Sitzungen verifizieren. **VS Code Copilot Chat Agent-Modus (Vorschau)** liest Hook-Konfigurationen aus `.github/hooks/*.json`, `~/.copilot/hooks/*.json` und `~/.claude/settings.json` (gesteuert durch die Einstellung `chat.hookFilesLocations`) unter Verwendung desselben Claude-förmigen `{hookSpecificOutput:{permissionDecision:"deny",…}}`-Vertrags – genau die Pfade, in die diese `copilot`-Integration und die `claude`-Integration (`~/.claude/settings.json`) bereits schreiben, sodass `failproofai policies --install --cli copilot` (oder `--cli claude`) **bereits im VS Code Agent-Modus durchgesetzt wird**, ohne eine separate `vscode`-Integration zu benötigen (bestätigt anhand der VS Code-Erkennungsprotokolle).
+  - **Cursor Agent _(Beta)_**: `~/.cursor/hooks.json` (Benutzer), `<cwd>/.cursor/hooks.json` (Projekt) – Cursor hat keinen `local`-Geltungsbereich. Hook-Einträge verwenden die Claude-förmige Form `{type, command, timeout}` (keine `bash`/`powershell`-Aufteilung), werden aber unter camelCase-Ereignisschlüsseln (`preToolUse`, `beforeSubmitPrompt`, …) in einem flachen Array gemäß Cursors [Hook-Schema](https://cursor.com/docs/hooks) gespeichert; die Datei enthält einen `version: 1`-Marker auf oberster Ebene. Der Handler kanonisiert camelCase → PascalCase über `CURSOR_EVENT_MAP`, sodass bestehende integrierte Richtlinien unverändert ausgelöst werden. Die Unterstützung für Cursor Agent ist **Beta**, während wir Cursors Transcript-Festplattenformat (in der öffentlichen Dokumentation nicht spezifiziert) gegen mehr reale Installationen verifizieren.
+  - **OpenCode _(Beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (Benutzer), `<cwd>/.opencode/opencode.json` + `<cwd>/.opencode/plugins/failproofai.mjs` (Projekt) – OpenCode hat keinen `local`-Geltungsbereich. Im Gegensatz zu den anderen fünf CLIs verfügt OpenCode über **kein externes Befehlshook-System**: Es lädt prozessinterne JS/TS-Plugins, die explizit über das `plugin: []`-Array in `opencode.json` registriert sind (die automatische Erkennung aus `.opencode/plugins/` ist **nicht** die Art, wie Plugins in opencode v1.14.33 geladen werden). Die Installation legt einen kleinen generierten Plugin-Shim ab, der das failproofai-Binary als Unterprozess aufruft und die Claude-förmige JSON-Antwort des Binärprogramms zurück in Plugin-Semantik übersetzt: `throw new Error()` für Werkzeugereigenis-Deny (bricht den Werkzeugaufruf ab), `client.session.prompt(...)` für instruct UND für `Stop` / `SubagentStop`-Deny (sendet den Ablehnungsgrund als nächste Benutzermeldung – der einzige Force-Retry-Kanal, da `session.idle` nur für Benachrichtigungen ist und ein Throw daraus ein No-op ist), und No-op für allow. Der Shim kanonisiert sowohl Werkzeugnamen (Kleinbuchstaben → PascalCase über `OPENCODE_TOOL_MAP`) als auch Werkzeugeingabe-Argumentschlüssel (camelCase → snake_case über `OPENCODE_TOOL_INPUT_MAP` für `Read` / `Write` / `Edit`, z. B. `filePath` → `file_path`, `oldString` → `old_string`), bevor er an das Binary weiterleitet, sodass pfadprüfende integrierte Richtlinien wie `block-read-outside-cwd`, `block-env-files` und `block-secrets-write` bei OpenCode-Werkzeugaufrufen unverändert ausgelöst werden. Sitzungen leben in OpenCodes SQLite-Datenbank unter `~/.local/share/opencode/opencode.db`; der Sitzungs-Viewer des Dashboards liest sie über `opencode db --format json` und `opencode export <id>`. Die Unterstützung für OpenCode ist **Beta**, während wir das Verhalten über Versionen hinweg und gegen mehr reale Sitzungen verifizieren. Siehe die [OpenCode-Plugins-Dokumentation](https://opencode.ai/docs/plugins/).
+  - **Pi _(Beta)_**: `~/.pi/agent/settings.json` (Benutzer), `<cwd>/.pi/settings.json` (Projekt) – Pi hat keinen `local`-Geltungsbereich. Pi lädt TypeScript-Erweiterungspakete beim Start; die Einstellungsdatei ist ein flaches String-Array `{"packages": ["./relative/path", …]}`. failproofai schreibt einen einzelnen Packages-Array-Eintrag, der auf sein gebündeltes `pi-extension/`-Verzeichnis zeigt. Die Erweiterung abonniert intern Pis `tool_call` / `user_bash` / `input` / `session_start`-Ereignisse und ruft `failproofai --hook <Event> --cli pi` auf; der Handler kanonisiert underscore_lower_snake_case → PascalCase über `PI_EVENT_MAP`, sodass bestehende integrierte Richtlinien unverändert ausgelöst werden. Werkzeugeingabeargumente werden ebenfalls über `PI_TOOL_INPUT_MAP` kanonisiert (Pis Read / Write / Edit liefern `path` statt `file_path`; die Zuordnung des Top-Level-Schlüssels ermöglicht das Auslösen von `block-env-files` und `block-secrets-write` – `block-read-outside-cwd` hatte bereits einen `path`-Fallback). Die Unterstützung für Pi ist **Beta**, während Pis Erweiterungs-API und Sitzungsprotokoll-Layout sich stabilisieren.
+  - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**nur Benutzerebene** – Hermes hat keine Projekt-/lokale Konfiguration). Hermes ist ein Slack/Telegram-**Gateway**, sodass eine Installation Werkzeugaufrufe von jeder Plattform (Slack/Telegram/cli/cron) **und** internen Subagenten abfängt. Hook-Einträge sind ein `{command, timeout}`-Paar (Timeout in **Sekunden**) unter einer `hooks:`-Map, die durch Hermes' snake_case-Ereignisse (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`) als Schlüssel indexiert ist; der Handler kanonisiert Ereignisse über `HERMES_EVENT_MAP` und Werkzeugnamen über `HERMES_TOOL_MAP`, sodass integrierte Richtlinien unverändert ausgelöst werden. Die Konfiguration wird durch einen kommentarerhaltenden YAML-`Document`-Round-Trip bearbeitet, sodass die anderen Einstellungen des Operators erhalten bleiben, und die Installation setzt `hooks_auto_accept: true`, damit das kopflose Gateway (kein TTY) die Hooks ohne Zustimmungsaufforderung ausführt. Der Evaluator gibt Hermes' `{"decision":"block","reason"}`-stdout-Vertrag aus (Hermes ignoriert Exit-Codes). **Einschränkungen:** Hermes hat kein Turn-End-`Stop`-Ereignis, sodass die `require-*-before-stop`-Integrierten nie dafür ausgelöst werden (nicht anwendbar, nicht kaputt); `instruct` degradiert zu allow-with-logged-note (kein Zusatzkontext-Kanal); und die Ausgabe-Geheimnis-Redaktion (`sanitize-*`) kann Werkzeugausgaben über den Shell-Hook-Vertrag nicht neu schreiben. Hermes ist **auch** eine Offline-**Audit**-Quelle – das Dashboard liest seine Gateway-Sitzungen direkt aus `~/.hermes/state.db`.
+  - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json` (**nur Benutzerebene** – OpenClaw hat keine Projekt-/lokale Konfiguration). Wie Hermes ist OpenClaw ein selbst gehostetes Multi-Channel-**Gateway**, sodass eine Installation Werkzeugaufrufe von jedem Kanal und seinen internen Subagenten abfängt. Die Durchsetzung erfolgt über OpenClaws **prozessinterne Plugin-Hooks** (seine dateibasierten internen Hooks sind nur zur Beobachtung und können nicht blockieren), sodass – wie OpenCode/Pi – failproofai ein statisches `openclaw-plugin/`-Paket liefert, das das failproofai-Binary asynchron startet und das Urteil übersetzt. Die Installation registriert das mitgelieferte Plugin-Verzeichnis in `openclaw.json`'s `plugins.load.paths[]` und aktiviert es unter `plugins.entries.failproofai` (mit `hooks.allowConversationAccess: true`, erforderlich für die Raw-Conversation-Hooks). Der Evaluator gibt ein flaches `{permission, reason}`-Urteil aus und der Shim ordnet es der nativen Rückgabeform jedes Hooks zu: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**) und `before_agent_finalize → {action:"revise", reason}` (**Stop** – ein echter Turn-End-Gate, sodass die `require-*-before-stop`-Integrierten bei OpenClaw **durchgesetzt werden**, anders als bei Hermes). Ereignisse und Werkzeugnamen kanonisieren binärseitig über `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` (`exec→Bash`, `read→Read`, …), sodass integrierte Richtlinien unverändert ausgelöst werden; der Shim schlägt bei Spawn-/Parse-/Timeout-Fehlern offen fehl. OpenClaw ist **auch** eine Offline-**Audit**-Quelle – das Dashboard liest seine JSONL-Sitzungen unter `~/.openclaw/agents/<agentId>/sessions/<uuid>.jsonl`.
+  - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (Benutzer), `<cwd>/.factory/hooks.json` (Projekt) – Factory hat keinen `local`-Geltungsbereich. droid liefert ein Claude-ähnliches externes Befehlshook-System, jedoch mit zwei live gegen droid v0.171.0 verifizierten Besonderheiten: (1) Ereignisnamen befinden sich auf der **obersten Ebene** von `hooks.json` – es gibt **keinen `"hooks"`-Wrapper** (droid lehnt einen ab); Werkzeugereignisse (`PreToolUse`/`PostToolUse`) tragen `"matcher": "*"`, Nicht-Werkzeugereignisse lassen es weg. (2) Deny wird durch **Exit-Code 2 + stderr** gesteuert, nicht durch eine JSON-Entscheidung – der `factory`-Zweig des Evaluators gibt Exit 2 für Werkzeug-/Prompt-Ereignisse zurück und `{decision:"block", reason}` nur beim Turn-End-`Stop`-Ereignis (dem einzigen Force-Retry-Kanal von droid). Ereignisse sind bereits in PascalCase (keine Ereigniszuordnung) und die Payload ist Claude snake_case; nur Werkzeugnamen werden über `FACTORY_TOOL_MAP` kanonisiert (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …). Factory ist **auch** eine Offline-**Audit**-Quelle – das Dashboard liest seine JSONL-Sitzungen unter `~/.factory/sessions/<encoded-cwd>/<sessionId>.jsonl`.
+  - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (Benutzer), `<cwd>/.devin/config.json` (Projekt) – Devin hat keinen `local`-Geltungsbereich. Devin ist ein **reiner Claude-Klon**, live gegen devin v3000.1.27 verifiziert: Es verwendet das Standard-Claude-`"hooks"`-Wrapper-Schema (Schreibvorgänge sind merge-erhaltend, sodass die anderen Schlüssel der Konfigurationsdatei – `org_id`, `theme_mode`, … – erhalten bleiben), bereits PascalCase-Ereignisnamen (keine Ereigniszuordnung, kein Handler-Zweig) und eine Claude-snake_case-stdin-Payload (keine Normalisierung). Der `devin`-Zweig des Evaluators lehnt bei **jedem** Ereignis mit `{"decision":"block","reason"}` JSON auf stdout bei Exit 0 ab (verifiziert – der Block überschrieb `--permission-mode dangerous`); beim Turn-End-`Stop`-Ereignis enthält der Grund den MANDATORY-ACTION-Force-Retry-Wortlaut, sodass die `require-*-before-stop`-Integrierten durchgesetzt werden. Nur Werkzeugnamen werden über `DEVIN_TOOL_MAP` kanonisiert (`exec→Bash`; `tool_input.command` ist bereits kanonisch). Devin ist **auch** eine Offline-**Audit**-Quelle – das Dashboard liest seine SQLite-Sitzungen unter `~/.local/share/devin/cli/sessions.db` (jede `sessions`-Zeile enthält ein echtes `working_directory`, sodass Sitzungen wie bei Claude nach Projekt-cwd gruppiert werden).
+  - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (Benutzer), `<cwd>/.agents/hooks.json` (Projekt) – Antigravity hat keinen `local`-Geltungsbereich. Anders als Factory/Devin hat Antigravity seinen **eigenen** Vertrag (kein Claude-Klon), live gegen agy v1.1.2 verifiziert. `hooks.json` verwendet ein **benanntes-Hook**-Schema: Der Top-Level-Schlüssel ist ein Hook-*Name* (`"failproofai"`), dessen Wert eine Ereignis→Handler-Map ist – Werkzeugereignisse (`PreToolUse`/`PostToolUse`) wickeln Handler in `{matcher:"*", hooks:[…]}` ein, während `PreInvocation`/`Stop` **flache** Handler-Arrays sind (andere benannte Hooks bleiben erhalten). Die stdin-Payload ist **camelCase-Protojson** (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) – failproofai normalisiert sie vor der Richtlinienausführung zu snake_case und ordnet die PascalCase-Argumente von `run_command` (`CommandLine`/`Cwd`) über `ANTIGRAVITY_TOOL_INPUT_MAP` zu. Der `antigravity`-Zweig des Evaluators verwendet Antigravitys **eigene** Antwortformen: `{decision:"deny", reason}` blockiert ein Werkzeug/Prompt (Exit 0), `{decision:"continue", reason}` beim Turn-End-`Stop` betritt die Schleife erneut (sodass die `require-*-before-stop`-Integrierten durchgesetzt werden) und `{injectSteps:[{ephemeralMessage}]}` fügt eine Anweisung bei `PreInvocation` (→ `UserPromptSubmit`) ein. Werkzeugnamen kanonisieren über `ANTIGRAVITY_TOOL_MAP` (`run_command→Bash`, `view_file→Read`, …). Antigravity ist **auch** eine Offline-**Audit**-Quelle – das Dashboard liest seine Plain-JSONL-Transkripte unter `~/.gemini/antigravity-cli/brain/<conversationId>/.system_generated/logs/transcript_full.jsonl` (Gesprächsindex in `conversation_summaries.db`).
+  - **Goose (Codename goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (Benutzer), `<cwd>/.agents/plugins/failproofai/hooks/hooks.json` (Projekt) – Goose hat keinen `local`-Geltungsbereich. Die Durchsetzung verwendet Gooses **Hooks**-System, die agentenübergreifende **Open Plugins**-Spezifikation: Der Installer legt einfach das `failproofai`-Plugin-Verzeichnis ab und Goose erkennt es beim Start automatisch (und registriert es selbst in `~/.config/goose/config.yaml`). Die `hooks.json` verwendet ein Open-Plugins-Schema **mit** einem `"hooks"`-Wrapper auf oberster Ebene, und der Matcher wird bei jedem Ereignis **weggelassen** – ein bloßes `"*"` ist ein ungültiger Regex, der nichts übereinstimmt (live gegen goose v1.43.0 verifiziert). Ereignisnamen sind bereits in PascalCase (keine Ereigniszuordnung); die stdin-Payload verwendet `event`/`working_dir`, was der Handler zu `hook_event_name`/`cwd` normalisiert. Der `goose`-Zweig des Evaluators lehnt mit `{"decision":"block","reason"}` JSON auf stdout bei Exit 0 ab, was nur beim **`PreToolUse`**-Ereignis berücksichtigt wird (ab goose ≥ v1.37.0 ausgeliefert) – das sowohl für das Shell-Tool **als auch innerhalb delegierter Subagenten** ausgelöst wird und damit der einzige ausreichende Deny-Punkt ist; jeder andere Hook-Fehler schlägt **offen** fehl. Goose hat **kein `Stop`-Ereignis**, sodass die `require-*-before-stop`-Integrierten nicht anwendbar sind (wie bei Hermes). Werkzeugnamen kanonisieren über `GOOSE_TOOL_MAP` (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) und Pfadschlüssel über `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`). Goose ist **auch** eine Offline-**Audit**-Quelle – das Dashboard liest seine SQLite-Sitzungen unter `~/.local/share/goose/sessions/sessions.db` (jede `sessions`-Zeile enthält ein echtes `working_dir`, sodass Sitzungen wie bei Devin nach Projekt-cwd gruppiert werden; `--no-session`-Scratch-Runs werden herausgefiltert).
+- **`policies-config.json`** – teilt failproofai mit, welche Richtlinien ausgewertet werden sollen und mit welchen Parametern (wird von allen Agenten-CLIs gemeinsam genutzt)
+
+Übergeben Sie `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`, um einen bestimmten Agenten anzusteuern (durch Leerzeichen getrennt oder wiederholt für eine beliebige Teilmenge):
+
+```bash
+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 --cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose
+```
+
+Wenn `--cli` weggelassen wird, erkennt `failproofai` automatisch, welche Agenten-CLIs installiert sind (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`):
+
+- **Eine CLI erkannt** – wählt diese CLI automatisch aus, ohne nachzufragen.
+- **Mehrere CLIs erkannt** in einem interaktiven Terminal – zeigt eine Einzelauswahl-Eingabeaufforderung mit Pfeiltastennavigation an, gegliedert in einen Abschnitt `Erkannt (N)` (mit einer aggregierten Zeile `Für alle N erkannten installieren` + jede erkannte CLI einzeln) und einen Abschnitt `Nicht installiert (M) · Hooks vorab installieren`, der jede nicht erkannte unterstützte CLI als Vorab-Installationsoption auflistet (↑↓ zum Bewegen, Eingabe zum Auswählen, ^C zum Beenden). Der Deinstallationsablauf zeigt nur den Erkannt-Abschnitt.
+- **Mehrere CLIs erkannt** in einer nicht-interaktiven Ausführung (CI, kein TTY) – installiert für alle erkannten CLIs ohne Nachfrage.
+- **Keine erkannt** – fällt auf `claude` zurück, mit einer Warnung, dass kein Agenten-Binary im PATH gefunden wurde; der Hook-Befehl wird trotzdem geschrieben, sodass er aktiviert wird, sobald Sie einen installieren.
+
+Sie können `policies-config.json` jederzeit direkt bearbeiten; Änderungen werden sofort beim nächsten Hook-Ereignis wirksam, ohne dass ein Neustart erforderlich ist.
+
+---
+
+## Beispiel: Konfiguration auf Projektebene mit Team-Standardwerten
+
+Committen Sie `.failproofai/policies-config.json` in Ihr Repository:
+
+```json
+{
+  "enabledPolicies": [
+    "block-sudo",
+    "block-rm-rf",
+    "block-push-master",
+    "sanitize-api-keys",
+    "block-env-files"
+  ],
+  "policyParams": {
+    "block-push-master": {
+      "protectedBranches": ["main", "release", "hotfix"]
+    }
+  }
+}
+```
+
+Jeder Entwickler kann dann `.failproofai/policies-config.local.json` (per gitignore ausgeschlossen) für persönliche Überschreibungen erstellen, ohne die Teamkollegen zu beeinflussen.

package/.next/standalone/docs-old/de/custom-policies.mdx

@@ -0,0 +1,358 @@
+---
+title: Benutzerdefinierte Richtlinien
+description: "Schreiben Sie eigene Richtlinien in JavaScript – Konventionen durchsetzen, Drift verhindern, Fehler erkennen, externe Systeme integrieren"
+icon: code
+---
+
+Benutzerdefinierte Richtlinien ermöglichen es Ihnen, Regeln für beliebige Agentverhalten zu schreiben: Projektkonventionen durchsetzen, Drift verhindern, destruktive Operationen absichern, feststeckende Agenten erkennen oder Integrationen mit Slack, Genehmigungsworkflows und mehr umsetzen. Sie nutzen dasselbe Hook-Event-System und dieselben `allow`-, `deny`- und `instruct`-Entscheidungen wie die integrierten Richtlinien.
+
+---
+
+## Schnellbeispiel
+
+```js
+// my-policies.js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+
+customPolicies.add({
+  name: "no-production-writes",
+  description: "Block writes to paths containing 'production'",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Write" && ctx.toolName !== "Edit") return allow();
+    const path = ctx.toolInput?.file_path ?? "";
+    if (path.includes("production")) {
+      return deny("Writes to production paths are blocked");
+    }
+    return allow();
+  },
+});
+```
+
+Installieren:
+
+```bash
+failproofai policies --install --custom ./my-policies.js
+```
+
+---
+
+## Zwei Möglichkeiten, benutzerdefinierte Richtlinien zu laden
+
+### Option 1: Konventionsbasiert (empfohlen)
+
+Legen Sie `*policies.{js,mjs,ts}`-Dateien im Verzeichnis `.failproofai/policies/` ab – sie werden automatisch geladen, ohne Flags oder Konfigurationsänderungen. Dies funktioniert wie Git-Hooks: Datei ablegen, fertig.
+
+```
+# Projektebene — in Git eingecheckt, mit dem Team geteilt
+.failproofai/policies/security-policies.mjs
+.failproofai/policies/workflow-policies.mjs
+
+# Benutzerebene — persönlich, gilt für alle Projekte
+~/.failproofai/policies/my-policies.mjs
+```
+
+**So funktioniert es:**
+- Sowohl das Projekt- als auch das Benutzerverzeichnis werden durchsucht (Vereinigungsmenge – kein Erster-gewinnt-nach-Scope)
+- Dateien werden alphabetisch innerhalb jedes Verzeichnisses geladen. Mit `01-`, `02-` als Präfix können Sie die Reihenfolge steuern
+- Nur Dateien, die `*policies.{js,mjs,ts}` entsprechen, werden geladen; andere Dateien werden ignoriert
+- Jede Datei wird unabhängig geladen (Fail-open pro Datei)
+- Funktioniert zusammen mit explizitem `--custom` und integrierten Richtlinien
+
+<Tip>
+Konventionsrichtlinien sind der einfachste Weg, einen Qualitätsstandard für Ihre Organisation aufzubauen. Checken Sie `.failproofai/policies/` in Git ein, und jedes Teammitglied erhält automatisch dieselben Regeln – kein Setup pro Entwickler erforderlich. Wenn Ihr Team neue Fehlermuster entdeckt, fügen Sie eine Richtlinie hinzu und pushen Sie. Mit der Zeit werden diese zu einem lebendigen Qualitätsstandard, der sich mit jedem Beitrag weiterentwickelt.
+</Tip>
+
+### Option 2: Expliziter Dateipfad
+
+```bash
+# Installation mit einer benutzerdefinierten Richtliniendatei
+failproofai policies --install --custom ./my-policies.js
+
+# Benutzerdefinierte Richtlinienpfade ersetzen
+failproofai policies --install --custom ./new-policies.js
+
+# Mehrere explizite Dateien konfigurieren (in Flag-Reihenfolge geladen)
+failproofai policies --install --custom ./security.js --custom ./workflow.js
+
+# Alle expliziten benutzerdefinierten Richtlinienpfade aus der Konfiguration entfernen
+failproofai policies --uninstall --custom
+```
+
+Aufgelöste absolute Pfade werden in `policies-config.json` als `customPoliciesPaths` gespeichert. Wiederholen Sie `--custom`, um mehrere Dateien zu konfigurieren. Bestehende Konfigurationen mit dem veralteten Feld `customPoliciesPath` funktionieren weiterhin. Dateien werden bei jedem Hook-Event neu geladen – es gibt kein Caching zwischen Events.
+
+Jede registrierte Richtlinie erscheint mit einem eigenen Umschalter im Dashboard. Das Deaktivieren einer Richtlinie speichert ihre quellenqualifizierte ID in `disabledCustomPolicies`; die Datei und ihre anderen Richtlinien werden weiterhin geladen, während die deaktivierte Richtlinie vor dem Event-Matching ausgeschlossen wird. Richtliniennamen, die über mehrere Dateien hinweg doppelt vorkommen, haben unabhängige Umschalter.
+
+### Beide Methoden kombinieren
+
+Konventionsrichtlinien und explizite `--custom`-Dateien können nebeneinander existieren. Ladereihenfolge:
+
+1. Explizite `customPoliciesPaths`-Dateien (in konfigurierter Reihenfolge)
+2. Projektkonventionsdateien (`{cwd}/.failproofai/policies/`, alphabetisch)
+3. Benutzerkonventionsdateien (`~/.failproofai/policies/`, alphabetisch)
+
+---
+
+## API
+
+### Import
+
+```js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+```
+
+### `customPolicies.add(hook)`
+
+Registriert eine Richtlinie. Rufen Sie diese Methode beliebig oft auf, um mehrere Richtlinien in derselben Datei zu definieren.
+
+```ts
+customPolicies.add({
+  name: string;                         // erforderlich – eindeutige Kennung
+  description?: string;                 // wird in der Ausgabe von `failproofai policies` angezeigt
+  match?: { events?: HookEventType[] }; // nach Eventtyp filtern; weglassen, um alle zu erfassen
+  fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
+});
+```
+
+### Entscheidungs-Hilfsfunktionen
+
+| Funktion | Wirkung | Wann verwenden |
+|----------|--------|----------|
+| `allow()` | Operation stillschweigend erlauben | Die Aktion ist sicher, keine Meldung erforderlich |
+| `deny(message)` | Operation blockieren | Der Agent sollte diese Aktion nicht ausführen |
+| `instruct(message)` | Kontext hinzufügen, ohne zu blockieren | Dem Agenten zusätzlichen Kontext geben, um ihn auf Kurs zu halten |
+
+`deny(message)` – die Nachricht erscheint für Claude mit dem Präfix `"Blocked by failproofai:"`. Ein einzelnes `deny` bricht alle weiteren Auswertungen ab.
+
+`instruct(message)` – die Nachricht wird dem Kontext von Claude für den aktuellen Tool-Aufruf hinzugefügt. Alle `instruct`-Nachrichten werden gesammelt und gemeinsam übermittelt.
+
+<Tip>
+Sie können jedem `deny`- oder `instruct`-Message zusätzliche Hinweise anfügen, indem Sie ein `hint`-Feld in `policyParams` angeben – ohne Codeänderungen. Dies funktioniert auch für benutzerdefinierte (`custom/`), Projektkonventions- (`.failproofai-project/`) und Benutzerkonventionsrichtlinien (`.failproofai-user/`). Weitere Details finden Sie unter [Konfiguration → hint](/de/configuration#hint-cross-cutting).
+</Tip>
+
+### Informative Allow-Nachrichten
+
+`allow(message)` erlaubt die Operation **und** sendet eine informative Nachricht an Claude. Die Nachricht wird als `additionalContext` in der stdout-Antwort des Hook-Handlers übermittelt – derselbe Mechanismus wie bei `instruct`, aber semantisch anders: Es handelt sich um ein Statusupdate, nicht um eine Warnung.
+
+| Funktion | Wirkung | Wann verwenden |
+|----------|--------|----------|
+| `allow(message)` | Erlauben und Kontext an Claude senden | Bestätigen, dass eine Prüfung erfolgreich war, oder erklären, warum eine Prüfung übersprungen wurde |
+
+Anwendungsfälle:
+- **Statusbestätigungen:** `allow("All CI checks passed.")` – teilt Claude mit, dass alles in Ordnung ist
+- **Fail-open-Erklärungen:** `allow("GitHub CLI not installed, skipping CI check.")` – erklärt Claude, warum eine Prüfung übersprungen wurde, damit es den vollen Kontext hat
+- **Mehrere Nachrichten werden gesammelt:** Wenn mehrere Richtlinien jeweils `allow(message)` zurückgeben, werden alle Nachrichten mit Zeilenumbrüchen verbunden und gemeinsam übermittelt
+
+```js
+customPolicies.add({
+  name: "confirm-branch-status",
+  match: { events: ["Stop"] },
+  fn: async (ctx) => {
+    const cwd = ctx.session?.cwd;
+    if (!cwd) return allow("No working directory, skipping branch check.");
+
+    // ... check branch status ...
+    if (allPushed) {
+      return allow("Branch is up to date with remote.");
+    }
+    return deny("Unpushed changes detected.");
+  },
+});
+```
+
+### `PolicyContext`-Felder
+
+| Feld | Typ | Beschreibung |
+|-------|------|-------------|
+| `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` |
+| `toolName` | `string \| undefined` | Das aufgerufene Tool (z. B. `"Bash"`, `"Write"`, `"Read"`) |
+| `toolInput` | `Record<string, unknown> \| undefined` | Die Eingabeparameter des Tools |
+| `payload` | `Record<string, unknown>` | Vollständige rohe Event-Nutzlast von Claude Code |
+| `session` | `SessionMetadata \| undefined` | Sitzungskontext (siehe unten) |
+
+### `SessionMetadata`-Felder
+
+| Feld | Typ | Beschreibung |
+|-------|------|-------------|
+| `sessionId` | `string` | Claude Code-Sitzungskennung |
+| `cwd` | `string` | Arbeitsverzeichnis der Claude Code-Sitzung |
+| `transcriptPath` | `string` | Pfad zur JSONL-Transkriptdatei der Sitzung |
+
+### Eventtypen
+
+| Event | Wann es ausgelöst wird | `toolInput`-Inhalt |
+|-------|--------------|----------------------|
+| `PreToolUse` | Bevor Claude ein Tool ausführt | Die Eingabe des Tools (z. B. `{ command: "..." }` für Bash) |
+| `PostToolUse` | Nachdem ein Tool abgeschlossen wurde | Die Eingabe des Tools + `tool_result` (die Ausgabe) |
+| `Notification` | Wenn Claude eine Benachrichtigung sendet | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` – Hooks müssen immer `allow()` zurückgeben, sie können Benachrichtigungen nicht blockieren |
+| `Stop` | Wenn die Claude-Sitzung endet | Leer |
+
+---
+
+## Auswertungsreihenfolge
+
+Richtlinien werden in dieser Reihenfolge ausgewertet:
+
+1. Integrierte Richtlinien (in Definitionsreihenfolge)
+2. Explizite benutzerdefinierte Richtlinien aus `customPoliciesPath` (in `.add()`-Reihenfolge)
+3. Konventionsrichtlinien aus dem Projekt `.failproofai/policies/` (Dateien alphabetisch, `.add()`-Reihenfolge innerhalb)
+4. Konventionsrichtlinien aus dem Benutzerverzeichnis `~/.failproofai/policies/` (Dateien alphabetisch, `.add()`-Reihenfolge innerhalb)
+
+<Note>
+Das erste `deny` bricht alle nachfolgenden Richtlinien ab. Alle `instruct`-Nachrichten werden gesammelt und gemeinsam übermittelt.
+</Note>
+
+---
+
+## Transitive Imports
+
+Benutzerdefinierte Richtliniendateien können lokale Module über relative Pfade importieren:
+
+```js
+// my-policies.js
+import { isBlockedPath } from "./utils.js";
+import { checkApproval } from "./approval-client.js";
+
+customPolicies.add({
+  name: "approval-gate",
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const approved = await checkApproval(ctx.toolInput?.command, ctx.session?.sessionId);
+    return approved ? allow() : deny("Approval required for this command");
+  },
+});
+```
+
+Alle relativen Imports, die von der Einstiegsdatei aus erreichbar sind, werden aufgelöst. Dies wird implementiert, indem `from "failproofai"`-Imports auf den tatsächlichen dist-Pfad umgeschrieben und temporäre `.mjs`-Dateien erstellt werden, um ESM-Kompatibilität sicherzustellen.
+
+---
+
+## Eventtyp-Filterung
+
+Verwenden Sie `match.events`, um einzuschränken, wann eine Richtlinie ausgelöst wird:
+
+```js
+customPolicies.add({
+  name: "require-summary-on-stop",
+  match: { events: ["Stop"] },
+  fn: async (ctx) => {
+    // Wird nur ausgelöst, wenn die Sitzung endet
+    // ctx.session.transcriptPath enthält das vollständige Sitzungsprotokoll
+    return allow();
+  },
+});
+```
+
+Lassen Sie `match` vollständig weg, um bei jedem Eventtyp ausgelöst zu werden.
+
+---
+
+## Fehlerbehandlung und Fehlermodi
+
+Benutzerdefinierte Richtlinien sind **fail-open**: Fehler blockieren niemals integrierte Richtlinien oder bringen den Hook-Handler zum Absturz.
+
+| Fehler | Verhalten |
+|---------|----------|
+| `customPoliciesPath` nicht gesetzt | Keine expliziten benutzerdefinierten Richtlinien werden ausgeführt; Konventionsrichtlinien und integrierte Richtlinien laufen normal weiter |
+| Datei nicht gefunden | Warnung in `~/.failproofai/hook.log` protokolliert; integrierte Richtlinien laufen weiter |
+| Syntax-/Importfehler (explizit) | Fehler in `~/.failproofai/hook.log` protokolliert; explizite benutzerdefinierte Richtlinien werden übersprungen |
+| Syntax-/Importfehler (Konvention) | Fehler protokolliert; diese Datei wird übersprungen, andere Konventionsdateien werden weiterhin geladen |
+| `fn` wirft zur Laufzeit | Fehler protokolliert; dieser Hook wird als `allow` behandelt; andere Hooks laufen weiter |
+| `fn` dauert länger als 10 Sekunden | Timeout protokolliert; wird als `allow` behandelt |
+| Konventionsverzeichnis fehlt | Keine Konventionsrichtlinien werden ausgeführt; kein Fehler |
+
+<Tip>
+Um Fehler in benutzerdefinierten Richtlinien zu debuggen, beobachten Sie die Logdatei:
+
+```bash
+tail -f ~/.failproofai/hook.log
+```
+</Tip>
+
+---
+
+## Vollständiges Beispiel: Mehrere Richtlinien
+
+```js
+// my-policies.js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+
+// Prevent agent from writing to secrets/ directory
+customPolicies.add({
+  name: "block-secrets-dir",
+  description: "Prevent agent from writing to secrets/ directory",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow();
+    const path = ctx.toolInput?.file_path ?? "";
+    if (path.includes("secrets/")) return deny("Writing to secrets/ is not permitted");
+    return allow();
+  },
+});
+
+// Keep the agent on track: verify tests before committing
+customPolicies.add({
+  name: "remind-test-before-commit",
+  description: "Keep the agent on track: verify tests pass before committing",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = ctx.toolInput?.command ?? "";
+    if (/git\s+commit/.test(cmd)) {
+      return instruct("Verify all tests pass before committing. Run `bun test` if you haven't already.");
+    }
+    return allow();
+  },
+});
+
+// Prevent unplanned dependency changes during freeze
+customPolicies.add({
+  name: "dependency-freeze",
+  description: "Prevent unplanned dependency changes during freeze period",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = ctx.toolInput?.command ?? "";
+    const isInstall = /^(npm install|yarn add|bun add|pnpm add)\s+\S/.test(cmd);
+    if (isInstall && process.env.DEPENDENCY_FREEZE === "1") {
+      return deny("Package installs are frozen. Unset DEPENDENCY_FREEZE to allow.");
+    }
+    return allow();
+  },
+});
+
+export { customPolicies };
+```
+
+---
+
+## Beispiele
+
+Das Verzeichnis `examples/` enthält sofort ausführbare Richtliniendateien:
+
+| Datei | Inhalt |
+|------|----------|
+| `examples/policies-basic.js` | Fünf Einstiegsrichtlinien für häufige Agentfehlermodi |
+| `examples/policies-advanced/index.js` | Fortgeschrittene Muster: transitive Imports, asynchrone Aufrufe, Output-Bereinigung und Sitzungsende-Hooks |
+| `examples/convention-policies/security-policies.mjs` | Konventionsbasierte Sicherheitsrichtlinien (Block .env-Schreibvorgänge, Git-Historienschreiben verhindern) |
+| `examples/convention-policies/workflow-policies.mjs` | Konventionsbasierte Workflow-Richtlinien (Testeinstufungen, Audit-Dateischreibvorgänge) |
+
+### Explizite Dateibeispiele verwenden
+
+```bash
+failproofai policies --install --custom ./examples/policies-basic.js
+```
+
+### Konventionsbasierte Beispiele verwenden
+
+```bash
+# Auf Projektebene kopieren
+mkdir -p .failproofai/policies
+cp examples/convention-policies/*.mjs .failproofai/policies/
+
+# Oder auf Benutzerebene kopieren
+mkdir -p ~/.failproofai/policies
+cp examples/convention-policies/*.mjs ~/.failproofai/policies/
+```
+
+Kein Installationsbefehl erforderlich – die Dateien werden beim nächsten Hook-Event automatisch erkannt.