Configuration

​

Portées de configuration

​

Règles de fusion

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

resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← union dédupliquée

project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }

resolved: { allowPatterns: ["sudo apt-get update"] }   ← project l'emporte, global ignoré

project:  (pas d'entrée block-sudo)
local:    (pas d'entrée block-sudo)
global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }

resolved: { allowPatterns: ["sudo systemctl status"] }  ← remonte jusqu'au global

​

Format du fichier de configuration

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

​

Référence des champs

​

enabledPolicies

​

policyParams

​

hint (transversal)

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

​

Politiques basées sur des conventions

​

llm

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

​

Gestion de la configuration depuis la CLI

• Paramètres de la CLI d’agent — indique à l’agent d’appeler failproofai --hook <event> à chaque utilisation d’outil :
  • Claude Code : ~/.claude/settings.json (utilisateur), <cwd>/.claude/settings.json (projet), <cwd>/.claude/settings.local.json (local)
  • OpenAI Codex : ~/.codex/hooks.json (utilisateur), <cwd>/.codex/hooks.json (projet) — Codex n’a pas de portée local
  • GitHub Copilot CLI (bêta) : ~/.copilot/hooks/failproofai.json (utilisateur), <cwd>/.github/hooks/failproofai.json (projet) — Copilot n’a pas de portée local. Les entrées de hook utilisent les champs de commande bash/powershell avec clé OS de Copilot et timeoutSec ; le fichier porte un marqueur version: 1 au niveau supérieur. La prise en charge de Copilot CLI est en bêta pendant que nous vérifions le schéma d’enregistrement events.jsonl (non spécifié dans la documentation publique) contre davantage de sessions réelles.
  • Cursor Agent (bêta) : ~/.cursor/hooks.json (utilisateur), <cwd>/.cursor/hooks.json (projet) — Cursor n’a pas de portée local. Les entrées de hook utilisent la forme Claude {type, command, timeout} (sans séparation bash/powershell), mais stockées sous des clés d’événements en camelCase (preToolUse, beforeSubmitPrompt, …) dans un tableau plat selon le schéma de hooks de Cursor ; le fichier porte un marqueur version: 1 au niveau supérieur. Le gestionnaire canonicalise camelCase → PascalCase via CURSOR_EVENT_MAP afin que les politiques intégrées existantes se déclenchent sans modification. La prise en charge de Cursor Agent est en bêta pendant que nous vérifions le format de transcript sur disque de Cursor (non spécifié dans la documentation publique) contre davantage d’installations réelles.
  • OpenCode (bêta) : ~/.config/opencode/opencode.json + ~/.config/opencode/plugins/failproofai.mjs (utilisateur), <cwd>/.opencode/opencode.json + <cwd>/.opencode/plugins/failproofai.mjs (projet) — OpenCode n’a pas de portée local. Contrairement aux six autres CLIs, OpenCode n’a pas de système de hook par commande externe : il charge des plugins JS/TS in-process explicitement enregistrés via le tableau plugin: [] dans opencode.json (la découverte automatique depuis .opencode/plugins/ n’est pas la façon dont les plugins se chargent sur opencode v1.14.33). L’installation dépose un petit shim de plugin généré qui appelle le binaire failproofai en sous-processus et traduit la réponse JSON de forme Claude du binaire en sémantique de plugin : throw new Error() pour le refus d’événement d’outil (annule l’appel d’outil), client.session.prompt(...) pour instruct ET pour le refus Stop / SubagentStop (soumet la raison du refus comme prochain message utilisateur — seul canal de force-retry puisque session.idle est notification uniquement et que lever une exception depuis celui-ci est un no-op), et no-op pour allow. Le shim canonicalise les noms d’outils (minuscules → PascalCase via OPENCODE_TOOL_MAP) et les clés d’arguments d’entrée d’outil (camelCase → snake_case via OPENCODE_TOOL_INPUT_MAP pour Read / Write / Edit, ex. filePath → file_path, oldString → old_string) avant de transmettre au binaire, de sorte que les politiques intégrées vérifiant les chemins comme block-read-outside-cwd, block-env-files et block-secrets-write se déclenchent sans modification sur les appels d’outils OpenCode. Les sessions résident dans la base SQLite d’opencode à ~/.local/share/opencode/opencode.db ; le visualiseur de sessions du tableau de bord les lit via opencode db --format json et opencode export <id>. La prise en charge d’OpenCode est en bêta pendant que nous vérifions le comportement sur différentes versions et contre davantage de sessions réelles. Consultez la documentation des plugins OpenCode.
  • Pi (bêta) : ~/.pi/agent/settings.json (utilisateur), <cwd>/.pi/settings.json (projet) — Pi n’a pas de portée local. Pi charge des packages d’extension TypeScript au démarrage ; le fichier de paramètres est un tableau de chaînes plat {"packages": ["./relative/path", …]}. failproofai écrit une seule entrée dans le tableau packages pointant vers son répertoire pi-extension/ fourni. L’extension s’abonne en interne aux événements tool_call / user_bash / input / session_start de Pi et exécute failproofai --hook <Event> --cli pi en sous-processus ; le gestionnaire canonicalise underscore_lower_snake_case → PascalCase via PI_EVENT_MAP afin que les politiques intégrées existantes se déclenchent sans modification. Les arguments d’entrée d’outil sont également canonicalisés via PI_TOOL_INPUT_MAP (Read / Write / Edit de Pi utilisent path plutôt que file_path ; mapper la clé de premier niveau permet à block-env-files et block-secrets-write de se déclencher — block-read-outside-cwd avait déjà un repli sur path). La prise en charge de Pi est en bêta pendant que l’API d’extension de Pi et la disposition des journaux de session se stabilisent.
  • Gemini CLI (bêta) : ~/.gemini/settings.json (utilisateur), <cwd>/.gemini/settings.json (projet) — Gemini n’a pas de portée local (il documente une portée system à /etc/gemini-cli/settings.json que failproofai n’expose pas). Les entrées de hook utilisent la forme Claude {type, command, timeout} encapsulée dans le schéma de correspondance Gemini {matcher, hooks: [...]} avec matcher: "*" par défaut. Les événements sont en PascalCase (SessionStart, BeforeAgent, AfterAgent, BeforeModel, AfterModel, BeforeToolSelection, BeforeTool, AfterTool, PreCompress, Notification, SessionEnd) ; le gestionnaire les mappe vers les noms canoniques Claude via GEMINI_EVENT_MAP. Les noms d’outils sont en snake_case (run_shell_command, read_file, write_file, replace, …) — le gestionnaire canonicalise via GEMINI_TOOL_MAP afin que les politiques intégrées existantes se déclenchent sans modification. L’évaluateur de politique émet la forme plate Gemini {decision: "deny", reason} (privilégiée selon la règle d’or exit-0 de Gemini), {hookSpecificOutput: {hookEventName, additionalContext}} pour l’injection de contexte sur BeforeAgent / AfterTool / SessionStart, et {decision: "block", reason} sur AfterAgent pour la sémantique de force-retry. La prise en charge de Gemini CLI est en bêta pendant que nous élargissons la couverture réelle. Consultez la documentation des hooks Gemini CLI.
• policies-config.json — indique à failproofai quelles politiques évaluer et avec quels paramètres (partagé entre toutes les CLIs d’agent)

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

• Une seule CLI détectée — la sélectionne automatiquement sans invite.
• Plusieurs CLIs détectées dans un terminal interactif — affiche une invite de sélection unique par touches fléchées regroupée en une section Detected (N) (avec une ligne agrégée Install for all N detected + chaque CLI détectée individuellement) et une section Not installed (M) · install hooks ahead of time listant chaque CLI prise en charge non détectée comme option d’installation préventive (↑↓ pour déplacer, Entrée pour sélectionner, ^C pour quitter). Le flux de désinstallation n’affiche que la section Detected.
• Plusieurs CLIs détectées lors d’une exécution non interactive (CI, pas de TTY) — installe pour toutes les CLIs détectées sans invite.
• Aucune détectée — repli sur claude, avec un avertissement qu’aucun binaire d’agent n’a été trouvé dans PATH ; la commande de hook est tout de même écrite pour s’activer dès que vous en installez une.

​

Exemple : configuration au niveau projet avec des valeurs par défaut d’équipe

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