failproofai 1.0.1-beta.0 → 1.0.1

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

@@ -0,0 +1,271 @@
+---
+title: Configuration
+description: "Format de fichier de configuration, système à trois niveaux et règles de fusion"
+icon: gear
+---
+
+failproofai utilise des fichiers de configuration JSON pour contrôler quelles politiques sont actives, comment elles se comportent, et où les politiques personnalisées sont chargées. La configuration est conçue pour être facilement partageable avec votre équipe — commitez-la dans votre dépôt et chaque développeur bénéficie du même filet de sécurité pour l'agent.
+
+---
+
+## Niveaux de configuration
+
+Il existe trois niveaux de configuration, évalués par ordre de priorité :
+
+| Niveau | Chemin du fichier | Objectif |
+|--------|-------------------|---------|
+| **project** | `.failproofai/policies-config.json` | Paramètres par dépôt, commités dans le contrôle de version |
+| **local** | `.failproofai/policies-config.local.json` | Remplacements personnels par dépôt, ignorés par git |
+| **global** | `~/.failproofai/policies-config.json` | Valeurs par défaut au niveau utilisateur pour tous les projets |
+
+Lorsque failproofai reçoit un événement de hook, il charge et fusionne les trois fichiers qui existent pour le répertoire de travail courant.
+
+### Règles de fusion
+
+**`enabledPolicies`** — union des trois niveaux. Une politique activée à n'importe quel niveau est active.
+
+```text
+project:  ["block-sudo"]
+local:    ["block-rm-rf"]
+global:   ["block-sudo", "sanitize-api-keys"]
+
+resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← union dédoublonnée
+```
+
+**`policyParams`** — le premier niveau qui définit des paramètres pour une politique donnée l'emporte entièrement. Il n'y a pas de fusion profonde des valeurs au sein des paramètres d'une politique.
+
+```text
+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é
+```
+
+```text
+project:  (aucune entrée block-sudo)
+local:    (aucune entrée block-sudo)
+global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
+
+resolved: { allowPatterns: ["sudo systemctl status"] }  ← remonte jusqu'au global
+```
+
+**`customPoliciesPaths` / `customPoliciesPath`** — le premier niveau qui définit l'une ou l'autre forme l'emporte.
+
+**`disabledCustomPolicies`** — union entre tous les niveaux. Le tableau de bord écrit un
+identifiant qualifié par la source ici lorsque vous désactivez une politique individuelle depuis
+un fichier de politiques explicite ou de convention. Les politiques non listées restent activées par
+défaut ; les identifiants incluent le fichier source afin que les politiques de même nom dans plusieurs fichiers
+puissent être contrôlées indépendamment.
+
+**`llm`** — le premier niveau qui le définit l'emporte.
+
+---
+
+## Format du fichier de configuration
+
+```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"
+}
+```
+
+---
+
+## Référence des champs
+
+### `enabledPolicies`
+
+Type : `string[]`
+
+Liste des noms de politiques à activer. Les noms doivent correspondre exactement aux identifiants de politique affichés par `failproofai policies`. Consultez [Politiques intégrées](/fr/built-in-policies) pour la liste complète.
+
+Les politiques absentes de `enabledPolicies` sont inactives, même si elles ont des entrées dans `policyParams`.
+
+### `policyParams`
+
+Type : `Record<string, Record<string, unknown>>`
+
+Remplacements de paramètres par politique. La clé externe est le nom de la politique ; les clés internes sont spécifiques à chaque politique. Chaque politique documente ses paramètres disponibles dans [Politiques intégrées](/fr/built-in-policies).
+
+Si une politique possède des paramètres mais que vous ne les spécifiez pas, les valeurs par défaut intégrées de la politique sont utilisées. Les utilisateurs qui ne configurent pas du tout `policyParams` obtiennent un comportement identique aux versions précédentes.
+
+Les clés inconnues dans le bloc de paramètres d'une politique sont silencieusement ignorées au moment du déclenchement du hook, mais signalées comme avertissements lors de l'exécution de `failproofai policies`.
+
+#### `hint` (transversal)
+
+Type : `string` (optionnel)
+
+Un message ajouté à la raison lorsqu'une politique retourne `deny` ou `instruct`. Utilisez-le pour donner à Claude des instructions exploitables sans modifier la politique elle-même.
+
+Fonctionne avec n'importe quel type de politique — intégrée, personnalisée (`custom/`), convention de projet (`.failproofai-project/`) ou convention utilisateur (`.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."
+    }
+  }
+}
+```
+
+Lorsque `block-force-push` refuse, Claude voit : *« Les push forcés sont bloqués. Try creating a fresh branch instead. »*
+
+Les valeurs non-chaînes et les chaînes vides sont silencieusement ignorées. Si `hint` n'est pas défini, le comportement est inchangé (rétrocompatible).
+
+### `customPoliciesPath`
+
+Type : `string` (chemin absolu)
+
+Chemin vers un fichier JavaScript contenant des politiques de hook personnalisées. Ce champ est défini automatiquement par `failproofai policies --install --custom <path>` (le chemin est résolu en chemin absolu avant d'être enregistré).
+
+Le fichier est rechargé à chaque événement de hook — il n'y a pas de mise en cache. Consultez [Politiques personnalisées](/fr/custom-policies) pour les détails de création.
+
+### Politiques basées sur les conventions
+
+En plus du `customPoliciesPath` explicite, failproofai découvre et charge automatiquement les fichiers de politiques depuis les répertoires `.failproofai/policies/` :
+
+| Niveau | Répertoire | Portée |
+|--------|------------|--------|
+| Projet | `.failproofai/policies/` | Partagé avec l'équipe via le contrôle de version |
+| Utilisateur | `~/.failproofai/policies/custom-policies/` | Personnel, s'applique à tous les projets |
+
+<Note>
+  Le répertoire de niveau utilisateur a été déplacé d'un niveau dans la
+  réorganisation du répertoire personnel. Les fichiers laissés à l'ancien emplacement `~/.failproofai/policies/` sont déplacés
+  automatiquement dans `custom-policies/` la première fois que vous exécutez une commande `failproofai`
+  après la mise à niveau, et la commande vous indique les fichiers déplacés.
+</Note>
+
+**Correspondance de fichiers :** Seuls les fichiers correspondant à `*policies.{js,mjs,ts}` sont chargés (ex. : `security-policies.mjs`, `workflow-policies.js`). Les autres fichiers du répertoire sont ignorés.
+
+**Aucune configuration requise :** Les politiques de convention ne nécessitent aucune entrée dans `policies-config.json`. Déposez simplement des fichiers dans le répertoire et ils seront pris en compte au prochain événement de hook.
+
+**Chargement par union :** Les répertoires de convention du projet et de l'utilisateur sont tous deux analysés. Tous les fichiers correspondants des deux niveaux sont chargés (contrairement à `customPoliciesPath` qui utilise le premier niveau gagnant).
+
+Consultez [Politiques personnalisées](/fr/custom-policies) pour plus de détails et d'exemples.
+
+### `llm`
+
+Type : `object` (optionnel)
+
+Configuration du client LLM pour les politiques qui effectuent des appels IA. Non requis pour la plupart des configurations.
+
+```json
+{
+  "llm": {
+    "model": "claude-sonnet-4-6",
+    "apiKey": "sk-ant-..."
+  }
+}
+```
+
+---
+
+## Gestion de la configuration depuis la CLI
+
+Les commandes `policies --install` et `policies --uninstall` écrivent dans le fichier de paramètres de hooks de votre CLI d'agent (les points d'entrée du hook), tandis que `policies-config.json` est le fichier que vous gérez directement. Les deux sont distincts :
+
+- **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` à clé OS de Copilot avec `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. **VS Code Copilot Chat en mode agent (Prévisualisation)** lit les configurations de hooks depuis `.github/hooks/*.json`, `~/.copilot/hooks/*.json` et `~/.claude/settings.json` (régi par le paramètre `chat.hookFilesLocations`) en utilisant le même contrat Claude `{hookSpecificOutput:{permissionDecision:"deny",…}}` — exactement les chemins que cette intégration `copilot` et l'intégration `claude` (`~/.claude/settings.json`) écrivent déjà, donc `failproofai policies --install --cli copilot` (ou `--cli claude`) **applique déjà les politiques en mode agent VS Code** sans intégration `vscode` séparée (confirmé en direct depuis les journaux de découverte VS Code).
+  - **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énement en camelCase (`preToolUse`, `beforeSubmitPrompt`, …) dans un tableau plat selon le [schéma de hooks](https://cursor.com/docs/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 transcription 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 cinq autres CLIs, OpenCode **n'a pas de système de hooks par commande externe** : il charge des plugins JS/TS en cours de processus 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 — le seul canal de forçage de relance puisque `session.idle` est en lecture seule et que lever une exception depuis celui-ci est un no-op), et no-op pour allow. Le shim canonicalise à la fois 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, afin que les politiques intégrées de vérification de chemin 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 vivent dans la base de données 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 entre les versions et contre davantage de sessions réelles. Consultez la [documentation des plugins OpenCode](https://opencode.ai/docs/plugins/).
+  - **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/` intégré. 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` dans un shell ; 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` (les outils Read / Write / Edit de Pi fournissent `path` plutôt que `file_path` ; mapper la clé de niveau supérieur permet à `block-env-files` et `block-secrets-write` de se déclencher — `block-read-outside-cwd` avait déjà un fallback `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.
+  - **Hermes (hermes-agent)** : `~/.hermes/config.yaml` (**portée utilisateur uniquement** — Hermes n'a pas de configuration projet/local). Hermes est une **passerelle** Slack/Telegram, donc une seule installation intercepte les appels d'outils de chaque plateforme (Slack/Telegram/cli/cron) **et** les sous-agents internes. Les entrées de hook sont une paire `{command, timeout}` (timeout en **secondes**) sous une map `hooks:` à clé par les événements snake_case de Hermes (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`) ; le gestionnaire canonicalise les événements via `HERMES_EVENT_MAP` et les noms d'outils via `HERMES_TOOL_MAP` afin que les politiques intégrées se déclenchent sans modification. La configuration est modifiée via un aller-retour YAML `Document` préservant les commentaires afin que les autres paramètres de l'opérateur survivent, et l'installation définit `hooks_auto_accept: true` afin que la passerelle sans tête (pas de TTY) exécute les hooks sans invite de consentement. L'évaluateur émet le contrat stdout `{"decision":"block","reason"}` de Hermes (Hermes ignore les codes de sortie). **Limitations :** Hermes n'a pas d'événement `Stop` de fin de tour, donc les politiques intégrées `require-*-before-stop` ne se déclenchent jamais pour lui (non applicable, pas cassé) ; `instruct` se dégrade en allow-avec-note-journalisée (pas de canal de contexte supplémentaire) ; et la suppression des secrets en sortie (`sanitize-*`) ne peut pas réécrire la sortie d'outil via le contrat de hook shell. Hermes est **également** une source d'**audit** hors ligne — le tableau de bord lit ses sessions de passerelle directement depuis `~/.hermes/state.db`.
+  - **OpenClaw (passerelle openclaw)** : `~/.openclaw/openclaw.json` (**portée utilisateur uniquement** — OpenClaw n'a pas de configuration projet/local). Comme Hermes, OpenClaw est une **passerelle** multi-canal auto-hébergée, donc une seule installation intercepte les appels d'outils de chaque canal et ses sous-agents internes. L'application des politiques passe par les **hooks de plugin en cours de processus** d'OpenClaw (ses hooks internes basés sur des fichiers sont en observation uniquement et ne peuvent pas bloquer), donc — comme OpenCode/Pi — failproofai livre un package `openclaw-plugin/` statique qui lance le binaire failproofai de manière asynchrone et traduit le verdict. L'installation enregistre le répertoire du plugin livré dans `plugins.load.paths[]` de `openclaw.json` et l'active sous `plugins.entries.failproofai` (avec `hooks.allowConversationAccess: true`, requis pour les hooks de conversation brute). L'évaluateur émet un verdict plat `{permission, reason}` et le shim le mappe à la forme de retour native de chaque hook : `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**), et `before_agent_finalize → {action:"revise", reason}` (**Stop** — une vraie porte de fin de tour, donc les politiques intégrées `require-*-before-stop` **s'appliquent** sur OpenClaw, contrairement à Hermes). Les événements et les noms d'outils se canonicalisent côté binaire via `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` (`exec→Bash`, `read→Read`, …) afin que les politiques intégrées se déclenchent sans modification ; le shim échoue ouvert en cas d'erreur de spawn/parse/timeout. OpenClaw est **également** une source d'**audit** hors ligne — le tableau de bord lit ses sessions JSONL à `~/.openclaw/agents/<agentId>/sessions/<uuid>.jsonl`.
+  - **Factory Droid (`droid`)** : `~/.factory/hooks.json` (utilisateur), `<cwd>/.factory/hooks.json` (projet) — Factory n'a pas de portée `local`. droid livre un système de hook par commande externe de style Claude, mais avec deux particularités vérifiées en direct contre droid v0.171.0 : (1) les noms d'événements se trouvent au **niveau supérieur** de `hooks.json` — il n'y a **pas d'enveloppe `"hooks"`** (droid la rejette) ; les événements d'outil (`PreToolUse`/`PostToolUse`) portent `"matcher": "*"`, les événements non-outil l'omettent. (2) Le refus est piloté par le **code de sortie 2 + stderr** du hook, pas par une décision JSON — la branche `factory` de l'évaluateur retourne le code de sortie 2 pour les événements d'outil/prompt et `{decision:"block", reason}` uniquement sur l'événement de fin de tour `Stop` (le seul canal de forçage de relance de droid). Les événements sont déjà en PascalCase (pas de map d'événements) et le payload est en snake_case Claude ; seuls les noms d'outils sont canonicalisés via `FACTORY_TOOL_MAP` (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …). Factory est **également** une source d'**audit** hors ligne — le tableau de bord lit ses sessions JSONL sur disque à `~/.factory/sessions/<encoded-cwd>/<sessionId>.jsonl`.
+  - **Devin CLI (`devin`, Cognition)** : `~/.config/devin/config.json` (utilisateur), `<cwd>/.devin/config.json` (projet) — Devin n'a pas de portée `local`. Devin est un **clone pur de Claude** vérifié en direct contre devin v3000.1.27 : il utilise le schéma standard Claude avec enveloppe `"hooks"` (les écritures préservent la fusion afin que les autres clés du fichier de configuration — `org_id`, `theme_mode`, … — survivent), des noms d'événements déjà en PascalCase (pas de map d'événements, pas de branche de gestionnaire), et un payload stdin snake_case Claude (pas de normalisation). La branche `devin` de l'évaluateur refuse avec `{"decision":"block","reason"}` JSON sur stdout au code de sortie 0 pour **chaque** événement (vérifié — le bloc a surchargé `--permission-mode dangerous`) ; sur l'événement de fin de tour `Stop`, la raison porte le libellé de forçage de relance MANDATORY-ACTION afin que les politiques intégrées `require-*-before-stop` s'appliquent. Seuls les noms d'outils sont canonicalisés via `DEVIN_TOOL_MAP` (`exec→Bash` ; `tool_input.command` est déjà canonique). Devin est **également** une source d'**audit** hors ligne — le tableau de bord lit ses sessions SQLite à `~/.local/share/devin/cli/sessions.db` (chaque ligne `sessions` porte un vrai `working_directory`, donc les sessions se regroupent par cwd de projet comme Claude).
+  - **Antigravity CLI (`agy`)** : `~/.gemini/config/hooks.json` (utilisateur), `<cwd>/.agents/hooks.json` (projet) — Antigravity n'a pas de portée `local`. Contrairement à Factory/Devin, Antigravity a son **propre** contrat (pas un clone de Claude), vérifié en direct contre agy v1.1.2. `hooks.json` utilise un schéma de **hook nommé** : la clé de niveau supérieur est un *nom* de hook (`"failproofai"`) dont la valeur est une map événement→gestionnaires — les événements d'outil (`PreToolUse`/`PostToolUse`) enveloppent les gestionnaires dans `{matcher:"*", hooks:[…]}`, tandis que `PreInvocation`/`Stop` sont des **tableaux plats** de gestionnaires (les autres hooks nommés sont préservés). Le payload stdin est du **protojson en camelCase** (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) — failproofai le normalise en snake_case avant l'exécution des politiques, et mappe les args PascalCase de `run_command` (`CommandLine`/`Cwd`) via `ANTIGRAVITY_TOOL_INPUT_MAP`. La branche `antigravity` de l'évaluateur utilise les **propres** formes de réponse d'Antigravity : `{decision:"deny", reason}` bloque un outil/prompt (code de sortie 0), `{decision:"continue", reason}` sur l'événement de fin de tour `Stop` relance la boucle (donc les politiques intégrées `require-*-before-stop` s'appliquent), et `{injectSteps:[{ephemeralMessage}]}` injecte une instruction sur `PreInvocation` (→ `UserPromptSubmit`). Les noms d'outils se canonicalisent via `ANTIGRAVITY_TOOL_MAP` (`run_command→Bash`, `view_file→Read`, …). Antigravity est **également** une source d'**audit** hors ligne — le tableau de bord lit ses transcriptions JSONL brutes à `~/.gemini/antigravity-cli/brain/<conversationId>/.system_generated/logs/transcript_full.jsonl` (index de conversation dans `conversation_summaries.db`).
+  - **Goose (nom de code goose, Block)** : `~/.agents/plugins/failproofai/hooks/hooks.json` (utilisateur), `<cwd>/.agents/plugins/failproofai/hooks/hooks.json` (projet) — Goose n'a pas de portée `local`. L'application des politiques utilise le système de **hooks** de Goose, la spécification **Open Plugins** multi-agents : l'installateur dépose simplement le répertoire du plugin `failproofai` et Goose le découvre automatiquement au démarrage (en l'auto-enregistrant dans `~/.config/goose/config.yaml`). Le `hooks.json` utilise un schéma Open Plugins **avec** une enveloppe `"hooks"` au niveau supérieur, et le matcher est **omis** sur chaque événement — un `"*"` nu est une regex invalide qui ne correspond à rien (vérifié en direct contre goose v1.43.0). Les noms d'événements sont déjà en PascalCase (pas de map d'événements) ; le payload stdin utilise `event`/`working_dir`, que le gestionnaire normalise en `hook_event_name`/`cwd`. La branche `goose` de l'évaluateur refuse avec `{"decision":"block","reason"}` JSON sur stdout au code de sortie 0, honoré sur l'événement **`PreToolUse`** uniquement (livré dans goose ≥ v1.37.0) — qui se déclenche pour l'outil shell **et à l'intérieur des sous-agents délégués**, en faisant le seul point de refus suffisant ; toute autre erreur de hook échoue **ouvert**. Goose **n'a pas d'événement `Stop`**, donc les politiques intégrées `require-*-before-stop` ne s'appliquent pas (comme avec Hermes). Les noms d'outils se canonicalisent via `GOOSE_TOOL_MAP` (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) et les clés de chemin via `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`). Goose est **également** une source d'**audit** hors ligne — le tableau de bord lit ses sessions SQLite à `~/.local/share/goose/sessions/sessions.db` (chaque ligne `sessions` porte un vrai `working_dir`, donc les sessions se regroupent par cwd de projet comme Devin ; les exécutions scratch `--no-session` sont filtrées).
+- **`policies-config.json`** — indique à failproofai quelles politiques évaluer et avec quels paramètres (partagé entre toutes les CLIs d'agent)
+
+Passez `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` pour cibler un agent spécifique (séparé par des espaces ou répété pour tout sous-ensemble) :
+
+```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
+```
+
+Lorsque `--cli` est omis, `failproofai` détecte les CLIs d'agent installées (`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`) :
+
+- **Une CLI détectée** — sélectionne automatiquement cette CLI sans demande de confirmation.
+- **Plusieurs CLIs détectées** dans un terminal interactif — affiche une invite de sélection unique par flèches groupé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 toutes les CLIs prises en charge non détectées comme option d'installation anticipée (↑↓ 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 demande de confirmation.
+- **Aucune détectée** — revient à `claude`, avec un avertissement qu'aucun binaire d'agent n'a été trouvé dans PATH ; la commande de hook est quand même écrite afin qu'elle s'active dès que vous en installez une.
+
+Vous pouvez modifier `policies-config.json` directement à tout moment ; les modifications prennent effet immédiatement au prochain événement de hook, sans redémarrage nécessaire.
+
+---
+
+## Exemple : configuration au niveau projet avec des valeurs par défaut d'équipe
+
+Commitez `.failproofai/policies-config.json` dans votre dépôt :
+
+```json
+{
+  "enabledPolicies": [
+    "block-sudo",
+    "block-rm-rf",
+    "block-push-master",
+    "sanitize-api-keys",
+    "block-env-files"
+  ],
+  "policyParams": {
+    "block-push-master": {
+      "protectedBranches": ["main", "release", "hotfix"]
+    }
+  }
+}
+```
+
+Chaque développeur peut ensuite créer `.failproofai/policies-config.local.json` (ignoré par git) pour ses remplacements personnels sans affecter ses coéquipiers.

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

@@ -0,0 +1,358 @@
+---
+title: Politiques personnalisées
+description: "Écrivez vos propres politiques en JavaScript - appliquez des conventions, prévenez la dérive, détectez les échecs, intégrez des systèmes externes"
+icon: code
+---
+
+Les politiques personnalisées vous permettent d'écrire des règles pour n'importe quel comportement d'agent : appliquer des conventions de projet, prévenir la dérive, bloquer les opérations destructives, détecter les agents bloqués, ou intégrer Slack, des workflows d'approbation, et plus encore. Elles utilisent le même système d'événements de hook et les mêmes décisions `allow`, `deny`, `instruct` que les politiques intégrées.
+
+---
+
+## Exemple rapide
+
+```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();
+  },
+});
+```
+
+Installez-la :
+
+```bash
+failproofai policies --install --custom ./my-policies.js
+```
+
+---
+
+## Deux façons de charger des politiques personnalisées
+
+### Option 1 : Basée sur les conventions (recommandée)
+
+Déposez des fichiers `*policies.{js,mjs,ts}` dans `.failproofai/policies/` et ils sont automatiquement chargés — aucun indicateur ni modification de configuration nécessaire. Cela fonctionne comme les hooks git : déposez un fichier, ça marche tout de suite.
+
+```
+# Niveau projet — commité dans git, partagé avec l'équipe
+.failproofai/policies/security-policies.mjs
+.failproofai/policies/workflow-policies.mjs
+
+# Niveau utilisateur — personnel, s'applique à tous les projets
+~/.failproofai/policies/my-policies.mjs
+```
+
+**Comment ça fonctionne :**
+- Les répertoires projet et utilisateur sont tous les deux analysés (union — pas de priorité par portée)
+- Les fichiers sont chargés par ordre alphabétique dans chaque répertoire. Préfixez avec `01-`, `02-` pour contrôler l'ordre
+- Seuls les fichiers correspondant à `*policies.{js,mjs,ts}` sont chargés ; les autres fichiers sont ignorés
+- Chaque fichier est chargé indépendamment (fail-open par fichier)
+- Fonctionne avec les options explicites `--custom` et les politiques intégrées
+
+<Tip>
+Les politiques basées sur les conventions sont le moyen le plus simple d'établir un standard de qualité pour votre organisation. Commitez `.failproofai/policies/` dans git et chaque membre de l'équipe obtient automatiquement les mêmes règles — aucune configuration par développeur requise. Au fil de la découverte de nouveaux modes d'échec, ajoutez une politique et poussez. Ces politiques deviennent progressivement un standard de qualité vivant qui s'améliore à chaque contribution.
+</Tip>
+
+### Option 2 : Chemin de fichier explicite
+
+```bash
+# Installer avec un fichier de politiques personnalisées
+failproofai policies --install --custom ./my-policies.js
+
+# Remplacer les chemins de politiques personnalisées
+failproofai policies --install --custom ./new-policies.js
+
+# Configurer plusieurs fichiers explicites (chargés dans l'ordre des indicateurs)
+failproofai policies --install --custom ./security.js --custom ./workflow.js
+
+# Supprimer tous les chemins de politiques personnalisées explicites de la configuration
+failproofai policies --uninstall --custom
+```
+
+Les chemins absolus résolus sont stockés dans `policies-config.json` sous `customPoliciesPaths`. Répétez `--custom` pour configurer plusieurs fichiers. Les configurations existantes utilisant le champ hérité `customPoliciesPath` continuent de fonctionner. Les fichiers sont rechargés à chaque événement de hook - il n'y a pas de mise en cache entre les événements.
+
+Chaque politique enregistrée apparaît avec son propre bouton de bascule dans le tableau de bord. Désactiver une politique enregistre son ID qualifié par la source dans `disabledCustomPolicies` ; le fichier et ses autres politiques continuent de se charger, tandis que la politique désactivée est exclue avant la correspondance d'événement. Les noms de politiques dupliqués entre fichiers ont des boutons de bascule indépendants.
+
+### Utiliser les deux ensemble
+
+Les politiques basées sur les conventions et les fichiers `--custom` explicites peuvent coexister. Ordre de chargement :
+
+1. Fichiers `customPoliciesPaths` explicites (dans l'ordre configuré)
+2. Fichiers de convention du projet (`{cwd}/.failproofai/policies/`, ordre alphabétique)
+3. Fichiers de convention utilisateur (`~/.failproofai/policies/`, ordre alphabétique)
+
+---
+
+## API
+
+### Import
+
+```js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+```
+
+### `customPolicies.add(hook)`
+
+Enregistre une politique. Appelez cette fonction autant de fois que nécessaire pour plusieurs politiques dans le même fichier.
+
+```ts
+customPolicies.add({
+  name: string;                         // requis - identifiant unique
+  description?: string;                 // affiché dans la sortie de `failproofai policies`
+  match?: { events?: HookEventType[] }; // filtrer par type d'événement ; omettez pour tout correspondre
+  fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
+});
+```
+
+### Fonctions d'aide aux décisions
+
+| Fonction | Effet | Utiliser quand |
+|----------|--------|----------|
+| `allow()` | Autorise l'opération silencieusement | L'action est sûre, aucun message nécessaire |
+| `deny(message)` | Bloque l'opération | L'agent ne devrait pas effectuer cette action |
+| `instruct(message)` | Ajoute du contexte sans bloquer | Donner à l'agent un contexte supplémentaire pour rester sur la bonne voie |
+
+`deny(message)` - le message apparaît à Claude préfixé par `"Blocked by failproofai:"`. Un seul `deny` court-circuite toute évaluation ultérieure.
+
+`instruct(message)` - le message est ajouté au contexte de Claude pour l'appel d'outil en cours. Tous les messages `instruct` sont accumulés et délivrés ensemble.
+
+<Tip>
+Vous pouvez ajouter des indications supplémentaires à n'importe quel message `deny` ou `instruct` en ajoutant un champ `hint` dans `policyParams` — aucune modification de code nécessaire. Cela fonctionne également pour les politiques personnalisées (`custom/`), les conventions de projet (`.failproofai-project/`) et les conventions utilisateur (`.failproofai-user/`). Consultez [Configuration → hint](/fr/configuration#hint-cross-cutting) pour plus de détails.
+</Tip>
+
+### Messages d'autorisation informatifs
+
+`allow(message)` autorise l'opération **et** envoie un message informatif à Claude. Le message est délivré sous forme de `additionalContext` dans la réponse stdout du gestionnaire de hook — le même mécanisme utilisé par `instruct`, mais sémantiquement différent : c'est une mise à jour de statut, pas un avertissement.
+
+| Fonction | Effet | Utiliser quand |
+|----------|--------|----------|
+| `allow(message)` | Autorise et envoie du contexte à Claude | Confirmer qu'une vérification a réussi, ou expliquer pourquoi une vérification a été ignorée |
+
+Cas d'utilisation :
+- **Confirmations de statut :** `allow("All CI checks passed.")` — indique à Claude que tout est en ordre
+- **Explications fail-open :** `allow("GitHub CLI not installed, skipping CI check.")` — indique à Claude pourquoi une vérification a été ignorée afin qu'il dispose du contexte complet
+- **Accumulation de messages :** si plusieurs politiques retournent chacune `allow(message)`, tous les messages sont joints avec des sauts de ligne et délivrés ensemble
+
+```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.");
+  },
+});
+```
+
+### Champs de `PolicyContext`
+
+| Champ | Type | Description |
+|-------|------|-------------|
+| `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` |
+| `toolName` | `string \| undefined` | L'outil appelé (ex. `"Bash"`, `"Write"`, `"Read"`) |
+| `toolInput` | `Record<string, unknown> \| undefined` | Les paramètres d'entrée de l'outil |
+| `payload` | `Record<string, unknown>` | Charge utile brute complète de l'événement provenant de Claude Code |
+| `session` | `SessionMetadata \| undefined` | Contexte de session (voir ci-dessous) |
+
+### Champs de `SessionMetadata`
+
+| Champ | Type | Description |
+|-------|------|-------------|
+| `sessionId` | `string` | Identifiant de session Claude Code |
+| `cwd` | `string` | Répertoire de travail de la session Claude Code |
+| `transcriptPath` | `string` | Chemin vers le fichier de transcription JSONL de la session |
+
+### Types d'événements
+
+| Événement | Quand il se déclenche | Contenu de `toolInput` |
+|-------|--------------|----------------------|
+| `PreToolUse` | Avant que Claude exécute un outil | L'entrée de l'outil (ex. `{ command: "..." }` pour Bash) |
+| `PostToolUse` | Après la fin d'un outil | L'entrée de l'outil + `tool_result` (la sortie) |
+| `Notification` | Quand Claude envoie une notification | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - les hooks doivent toujours retourner `allow()`, ils ne peuvent pas bloquer les notifications |
+| `Stop` | Quand la session Claude se termine | Vide |
+
+---
+
+## Ordre d'évaluation
+
+Les politiques sont évaluées dans cet ordre :
+
+1. Politiques intégrées (dans l'ordre de définition)
+2. Politiques personnalisées explicites de `customPoliciesPath` (dans l'ordre `.add()`)
+3. Politiques de convention du projet `.failproofai/policies/` (fichiers par ordre alphabétique, ordre `.add()` à l'intérieur)
+4. Politiques de convention utilisateur `~/.failproofai/policies/` (fichiers par ordre alphabétique, ordre `.add()` à l'intérieur)
+
+<Note>
+Le premier `deny` court-circuite toutes les politiques suivantes. Tous les messages `instruct` sont accumulés et délivrés ensemble.
+</Note>
+
+---
+
+## Imports transitifs
+
+Les fichiers de politiques personnalisées peuvent importer des modules locaux en utilisant des chemins relatifs :
+
+```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");
+  },
+});
+```
+
+Tous les imports relatifs accessibles depuis le fichier d'entrée sont résolus. Ceci est implémenté en réécrivant les imports `from "failproofai"` vers le chemin dist réel et en créant des fichiers `.mjs` temporaires pour assurer la compatibilité ESM.
+
+---
+
+## Filtrage par type d'événement
+
+Utilisez `match.events` pour limiter quand une politique se déclenche :
+
+```js
+customPolicies.add({
+  name: "require-summary-on-stop",
+  match: { events: ["Stop"] },
+  fn: async (ctx) => {
+    // Se déclenche uniquement quand la session se termine
+    // ctx.session.transcriptPath contient le journal complet de la session
+    return allow();
+  },
+});
+```
+
+Omettez `match` entièrement pour se déclencher sur chaque type d'événement.
+
+---
+
+## Gestion des erreurs et modes d'échec
+
+Les politiques personnalisées sont **fail-open** : les erreurs ne bloquent jamais les politiques intégrées ni ne font planter le gestionnaire de hook.
+
+| Échec | Comportement |
+|---------|----------|
+| `customPoliciesPath` non défini | Aucune politique personnalisée explicite ne s'exécute ; les politiques de convention et les intégrées continuent normalement |
+| Fichier introuvable | Avertissement journalisé dans `~/.failproofai/hook.log` ; les politiques intégrées continuent |
+| Erreur de syntaxe/import (explicite) | Erreur journalisée dans `~/.failproofai/hook.log` ; politiques personnalisées explicites ignorées |
+| Erreur de syntaxe/import (convention) | Erreur journalisée ; ce fichier ignoré, les autres fichiers de convention se chargent quand même |
+| `fn` lève une erreur à l'exécution | Erreur journalisée ; ce hook traité comme `allow` ; les autres hooks continuent |
+| `fn` prend plus de 10 secondes | Délai d'expiration journalisé ; traité comme `allow` |
+| Répertoire de convention manquant | Aucune politique de convention ne s'exécute ; aucune erreur |
+
+<Tip>
+Pour déboguer les erreurs de politiques personnalisées, surveillez le fichier journal :
+
+```bash
+tail -f ~/.failproofai/hook.log
+```
+</Tip>
+
+---
+
+## Exemple complet : plusieurs politiques
+
+```js
+// my-policies.js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+
+// Empêcher l'agent d'écrire dans le répertoire secrets/
+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();
+  },
+});
+
+// Garder l'agent sur la bonne voie : vérifier les tests avant de commiter
+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();
+  },
+});
+
+// Empêcher les changements de dépendances non planifiés pendant le gel
+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 };
+```
+
+---
+
+## Exemples
+
+Le répertoire `examples/` contient des fichiers de politiques prêts à l'emploi :
+
+| Fichier | Contenu |
+|------|----------|
+| `examples/policies-basic.js` | Cinq politiques de démarrage couvrant les modes d'échec d'agent courants |
+| `examples/policies-advanced/index.js` | Modèles avancés : imports transitifs, appels asynchrones, nettoyage de sortie et hooks de fin de session |
+| `examples/convention-policies/security-policies.mjs` | Politiques de sécurité basées sur les conventions (bloquer les écritures .env, empêcher la réécriture de l'historique git) |
+| `examples/convention-policies/workflow-policies.mjs` | Politiques de workflow basées sur les conventions (rappels de tests, journalisation des écritures de fichiers) |
+
+### Utiliser les exemples de fichiers explicites
+
+```bash
+failproofai policies --install --custom ./examples/policies-basic.js
+```
+
+### Utiliser les exemples basés sur les conventions
+
+```bash
+# Copier au niveau du projet
+mkdir -p .failproofai/policies
+cp examples/convention-policies/*.mjs .failproofai/policies/
+
+# Ou copier au niveau utilisateur
+mkdir -p ~/.failproofai/policies
+cp examples/convention-policies/*.mjs ~/.failproofai/policies/
+```
+
+Aucune commande d'installation requise — les fichiers sont automatiquement pris en compte lors du prochain événement de hook.