Konfiguration

​

Konfigurationsscopes

​

Zusammenführungsregeln

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 Toolnutzung 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-Scope
  • GitHub Copilot CLI (beta): ~/.copilot/hooks/failproofai.json (Benutzer), <cwd>/.github/hooks/failproofai.json (Projekt) – Copilot hat keinen local-Scope. 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 von Copilot CLI ist beta, während wir das events.jsonl-Aufzeichnungsschema (das in der öffentlichen Dokumentation nicht spezifiziert ist) anhand weiterer realer Sitzungen überprüfen.
  • Cursor Agent (beta): ~/.cursor/hooks.json (Benutzer), <cwd>/.cursor/hooks.json (Projekt) – Cursor hat keinen local-Scope. Hook-Einträge verwenden die Claude-ähnliche {type, command, timeout}-Form (ohne bash/powershell-Aufteilung), werden aber unter camelCase-Ereignisschlüsseln (preToolUse, beforeSubmitPrompt, …) in einem flachen Array gemäß Cursors Hooks-Schema 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 von Cursor Agent ist beta, während wir Cursors On-Disk-Transkriptformat (in der öffentlichen Dokumentation nicht spezifiziert) anhand weiterer realer Installationen überprüfen.
  • 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-Scope. Im Gegensatz zu den anderen fünf CLIs verfügt OpenCode über kein externes Befehls-Hook-System: Es lädt In-Process-JS/TS-Plugins, die explizit über das plugin: []-Array in opencode.json registriert werden (automatische Erkennung aus .opencode/plugins/ ist nicht die Art, wie Plugins in opencode v1.14.33 geladen werden). Die Installation legt ein kleines generiertes Plugin-Shim ab, das den failproofai-Binary als Subprozess aufruft und die JSON-Antwort im Claude-Format des Binaries 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 (reicht den Ablehnungsgrund als nächste Benutzernachricht ein – der einzige Force-Retry-Kanal, da session.idle nur eine Benachrichtigung ist und das Werfen einer Exception dort ein No-op ist), und No-op für allow. Das Shim kanonisiert sowohl Tool-Namen (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 das Binary weiterleitet, 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 Session-Viewer des Dashboards liest sie über opencode db --format json und opencode export <id>. Die OpenCode-Unterstützung ist beta, während wir das Verhalten versionsübergreifend und anhand weiterer realer Sitzungen überprüfen. Siehe die OpenCode-Plugin-Dokumentation.
  • Pi (beta): ~/.pi/agent/settings.json (Benutzer), <cwd>/.pi/settings.json (Projekt) – Pi hat keinen local-Scope. 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 als Shell-Befehl auf; der Handler kanonisiert Ereignisse über PI_EVENT_MAP von underscore_lower_snake_case → PascalCase, sodass bestehende integrierte 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 Zuordnung des obersten 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 Sitzungslog-Layout stabilisieren.
  • Hermes (hermes-agent): ~/.hermes/config.yaml (nur Benutzer-Scope – Hermes hat keine Projekt-/lokale Konfiguration). Hermes ist ein Slack/Telegram-Gateway, daher fängt eine Installation Tool-Aufrufe von jeder Plattform (Slack/Telegram/cli/cron) und internen Subagenten ab. Hook-Einträge sind ein {command, timeout}-Paar (Timeout in Sekunden) unter einem hooks:-Map, der nach Hermes’ snake_case-Ereignissen (pre_tool_call / post_tool_call / on_session_start / on_session_end / subagent_stop) geordnet ist; der Handler kanonisiert Ereignisse über HERMES_EVENT_MAP und Tool-Namen ü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 Betreibers erhalten bleiben, und die Installation setzt hooks_auto_accept: true, sodass das kopflose Gateway (kein TTY) die Hooks ohne Zustimmungsaufforderung ausführt. Der Auswerter gibt Hermes’ stdout-Vertrag {"decision":"block","reason"} aus (Hermes ignoriert Exit-Codes). Einschränkungen: Hermes hat kein turn-end-Stop-Ereignis, daher werden die require-*-before-stop-Builtins für Hermes nie ausgelöst (nicht anwendbar, nicht defekt); instruct wird zu allow-with-logged-note herabgestuft (kein additional-context-Kanal); und Output-Secret-Redaktion (sanitize-*) kann Tool-Output über den Shell-Hook-Vertrag nicht umschreiben. Hermes ist auch eine Offline-Audit-Quelle – das Dashboard liest seine Gateway-Sitzungen direkt aus ~/.hermes/state.db.
• policies-config.json – teilt failproofai mit, welche Richtlinien ausgewertet werden sollen und mit welchen Parametern (geteilt über 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 hermes --scope user
failproofai policies --install --cli claude codex copilot cursor opencode pi

• Eine CLI erkannt – wählt diese CLI automatisch ohne Rückfrage aus.
• Mehrere CLIs erkannt in einem interaktiven Terminal – zeigt eine Einzelauswahl-Eingabeaufforderung mit Pfeiltasten an, die in einen Abschnitt Erkannt (N) (mit einer Für alle N erkannten installieren-Sammelzeile + jeder erkannten CLI einzeln) und einen Abschnitt Nicht installiert (M) · Hooks vorab installieren unterteilt ist, der alle nicht erkannten unterstützten CLIs als Vorwärts-Installationsoption auflistet (↑↓ zum Bewegen, Enter zum Auswählen, ^C zum Beenden). Der Deinstallationsablauf zeigt nur den Abschnitt „Erkannt” an.
• Mehrere CLIs erkannt in einem nicht-interaktiven Lauf (CI, kein TTY) – installiert für alle erkannten CLIs ohne Rückfrage.
• 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.

​

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"]
    }
  }
}