Konfiguration

​

Konfigurationsbereiche

​

Merge-Regeln

project:  ["block-sudo"]
local:    ["block-rm-rf"]
global:   ["block-sudo", "sanitize-api-keys"]

resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← deduplizierte Vereinigung

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

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

​

Konfigurationsdateiformat

{
  "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

​

policyParams

​

hint (übergreifend)

{
  "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."
    }
  }
}

​

customPoliciesPath

​

Konventionsbasierte Richtlinien

​

llm

{
  "llm": {
    "model": "claude-sonnet-4-6",
    "apiKey": "sk-ant-..."
  }
}

​

Konfiguration über die CLI verwalten

• Agenten-CLI-Einstellungen — weist den Agenten an, bei jeder Werkzeugnutzung 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-Bereich
  • GitHub Copilot CLI (beta): ~/.copilot/hooks/failproofai.json (Benutzer), <cwd>/.github/hooks/failproofai.json (Projekt) — Copilot hat keinen local-Bereich. Hook-Einträge verwenden die betriebssystemabhängigen bash/powershell-Befehlsfelder von Copilot 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-Aufzeichnungsschema (das in den öffentlichen Docs nicht spezifiziert ist) anhand weiterer realer Sitzungen verifizieren.
  • Cursor Agent (beta): ~/.cursor/hooks.json (Benutzer), <cwd>/.cursor/hooks.json (Projekt) — Cursor hat keinen local-Bereich. Hook-Einträge verwenden die Claude-ähnliche Form {type, command, timeout} (keine bash/powershell-Aufteilung), werden aber unter camelCase-Ereignisschlüsseln (preToolUse, beforeSubmitPrompt, …) in einem flachen Array gemäß Cursors Hooks-Schema gespeichert; die Datei trägt einen version: 1-Marker auf oberster Ebene. Der Handler kanonisiert camelCase → PascalCase über CURSOR_EVENT_MAP, sodass bestehende eingebaute Richtlinien unverändert ausgelöst werden. Die Unterstützung für Cursor Agent ist beta, während wir Cursors On-Disk-Transkriptformat (in den öffentlichen Docs nicht spezifiziert) anhand weiterer realer 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-Bereich. Im Gegensatz zu den anderen sechs CLIs verfügt OpenCode über kein externes Befehlshook-System: Es lädt In-Process-JS/TS-Plugins, die explizit über das plugin: []-Array in opencode.json registriert werden (Auto-Discovery aus .opencode/plugins/ ist nicht der Weg, wie Plugins in opencode v1.14.33 geladen werden). Die Installation legt einen kleinen generierten Plugin-Shim ab, der die failproofai-Binärdatei als Subprocess aufruft und die Claude-ähnliche JSON-Antwort der Binärdatei zurück in Plugin-Semantik übersetzt: throw new Error() für Tool-Event-deny (bricht den Tool-Aufruf ab), client.session.prompt(...) für instruct UND für Stop/SubagentStop-deny (sendet den Ablehnungsgrund als nächste Benutzernachricht – der einzige Force-Retry-Kanal, da session.idle nur benachrichtigend 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 Tool-Input-Argumentschlüssel (camelCase → snake_case über OPENCODE_TOOL_INPUT_MAP für Read/Write/Edit, z. B. filePath → file_path, oldString → old_string), bevor es an die Binärdatei weitergeleitet wird, sodass pfadprüfende Builtins wie block-read-outside-cwd, block-env-files und block-secrets-write bei OpenCode-Tool-Aufrufen unverändert ausgelöst werden. Sitzungen werden in OpenCodes SQLite-Datenbank unter ~/.local/share/opencode/opencode.db gespeichert; 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 verschiedene Versionen und mehr reale Sitzungen hinweg verifizieren. Siehe die OpenCode-Plugins-Dokumentation.
  • Pi (beta): ~/.pi/agent/settings.json (Benutzer), <cwd>/.pi/settings.json (Projekt) — Pi hat keinen local-Bereich. 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 verweist. Die Erweiterung abonniert intern Pis tool_call/user_bash/input/session_start-Ereignisse und ruft failproofai --hook <Event> --cli pi als Shell-Prozess auf; der Handler kanonisiert underscore_lower_snake_case → PascalCase über PI_EVENT_MAP, sodass bestehende eingebaute Richtlinien unverändert ausgelöst werden. Tool-Input-Argumente werden ebenfalls über PI_TOOL_INPUT_MAP kanonisiert (Pis Read/Write/Edit liefern path statt file_path; die Abbildung des Top-Level-Schlüssels lässt block-env-files und block-secrets-write auslösen – block-read-outside-cwd hatte bereits einen path-Fallback). Die Pi-Unterstützung ist beta, während sich Pis Erweiterungs-API und das Sitzungsprotokoll-Layout stabilisieren.
  • Gemini CLI (beta): ~/.gemini/settings.json (Benutzer), <cwd>/.gemini/settings.json (Projekt) — Gemini hat keinen local-Bereich (es dokumentiert einen system-Bereich unter /etc/gemini-cli/settings.json, den failproofai nicht bereitstellt). Hook-Einträge verwenden Claudes {type, command, timeout}-Form, eingebettet in Geminis {matcher, hooks: [...]}-Matcher-Schema mit standardmäßig matcher: "*". Ereignisse sind PascalCase (SessionStart, BeforeAgent, AfterAgent, BeforeModel, AfterModel, BeforeToolSelection, BeforeTool, AfterTool, PreCompress, Notification, SessionEnd); der Handler bildet sie über GEMINI_EVENT_MAP auf kanonische Claude-Namen ab. Werkzeugnamen sind snake_case (run_shell_command, read_file, write_file, replace, …) – der Handler kanonisiert über GEMINI_TOOL_MAP, sodass bestehende eingebaute Richtlinien unverändert ausgelöst werden. Der Richtlinienauswerter gibt Geminis flache {decision: "deny", reason}-Form aus (bevorzugt gemäß Geminis „Golden Rule” exit-0-Vertrag), {hookSpecificOutput: {hookEventName, additionalContext}} für Kontexteinschleusung bei BeforeAgent/AfterTool/SessionStart, und {decision: "block", reason} bei AfterAgent für Force-Retry-Semantik. Die Unterstützung für Gemini CLI ist beta, während wir die reale Abdeckung ausweiten. Siehe die Gemini CLI Hooks-Dokumentation.
• policies-config.json — teilt failproofai mit, welche Richtlinien ausgewertet werden sollen und mit welchen Parametern (gilt für alle Agenten-CLIs)

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 gemini --scope project
failproofai policies --install --cli claude codex copilot cursor opencode pi gemini

• Eine CLI erkannt — wählt diese CLI automatisch ohne Nachfrage aus.
• Mehrere CLIs erkannt in einem interaktiven Terminal — zeigt eine Pfeilauswahl-Eingabeaufforderung an, gruppiert 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 aufführt (↑↓ zum Bewegen, Enter zum Auswählen, ^C zum Beenden). Der Deinstallationsablauf zeigt nur den Abschnitt „Erkannt”.
• 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 keine Agenten-Binärdatei im PATH gefunden wurde; der Hook-Befehl wird dennoch geschrieben, sodass er aktiviert wird, sobald Sie eine installieren.

​

Beispiel: Konfiguration auf Projektebene mit Team-Standardwerten

{
  "enabledPolicies": [
    "block-sudo",
    "block-rm-rf",
    "block-push-master",
    "sanitize-api-keys",
    "block-env-files"
  ],
  "policyParams": {
    "block-push-master": {
      "protectedBranches": ["main", "release", "hotfix"]
    }
  }
}