> ## Documentation Index
> Fetch the complete documentation index at: https://exosphere-auto-translate-docs-20260624-1149.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Politiques intégrées

> Les 39 politiques intégrées qui interceptent les modes de défaillance courants des agents

failproofai est livré avec 39 politiques intégrées qui interceptent les modes de défaillance courants des agents. Chaque politique se déclenche sur un type d'événement hook et un nom d'outil spécifiques. Dix-neuf politiques acceptent des paramètres permettant d'affiner leur comportement sans écrire de code. Cinq politiques de workflow imposent un pipeline commit → push → PR → CI avant que Claude ne s'arrête.

***

## Vue d'ensemble

Les politiques sont regroupées par catégories :

| Catégorie                                      | Politiques                                                                                                                                   | Type de hook |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| [Commandes dangereuses](#dangerous-commands)   | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands                                                                      | PreToolUse   |
| [Commandes d'infrastructure](#infra-commands)  | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline                                     | PreToolUse   |
| [Secrets (assainisseurs)](#secrets-sanitizers) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens                           | PostToolUse  |
| [Environnement](#environment)                  | block-env-files, protect-env-vars                                                                                                            | PreToolUse   |
| [Accès aux fichiers](#file-access)             | block-read-outside-cwd, block-secrets-write                                                                                                  | PreToolUse   |
| [Git](#git)                                    | block-push-master, block-work-on-main, block-force-push, warn-git-amend, warn-git-stash-drop, warn-all-files-staged                          | PreToolUse   |
| [Base de données](#database)                   | warn-destructive-sql, warn-schema-alteration                                                                                                 | PreToolUse   |
| [Avertissements](#warnings)                    | warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install                                            | PreToolUse   |
| [Gestionnaires de paquets](#package-managers)  | prefer-package-manager                                                                                                                       | PreToolUse   |
| [Workflow](#workflow)                          | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop         |

* **`block-`** — empêche l'agent de poursuivre.
* **`warn-`** — fournit à l'agent un contexte supplémentaire pour qu'il puisse se corriger lui-même.
* **`sanitize-`** — expurge les données sensibles de la sortie de l'outil avant que l'agent ne les voie.

### Espaces de noms

Chaque politique occupe un emplacement `<namespace>/<name>`. Les politiques intégrées appartiennent à l'espace de noms **`failproofai/`** — par exemple, `failproofai/sanitize-jwt`. L'espace de noms évite les collisions lorsque vous chargez également des politiques personnalisées ou tierces avec des noms courts similaires.

Dans votre configuration, vous pouvez faire référence à une politique intégrée par son nom court ou son nom qualifié ; les deux formes correspondent à la même politique :

```json theme={null}
{
  "enabledPolicies": [
    "sanitize-jwt",
    "failproofai/block-rm-rf"
  ]
}
```

Si un nom ne contient pas de `/`, failproofai le considère comme appartenant à l'espace de noms par défaut `failproofai`. Les noms qui contiennent déjà un `/` (ex. `myorg/foo`, `custom/my-hook`) sont conservés tels quels.

* **`require-`** — bloque l'événement Stop jusqu'à ce que les conditions soient remplies.

***

<Tip>
  Toutes les politiques prennent en charge un champ optionnel `hint` dans `policyParams`. Ce conseil est ajouté au message deny ou instruct que voit Claude, fournissant des indications concrètes sans modifier le code de la politique. Fonctionne avec les politiques intégrées, personnalisées et de convention. Voir [Configuration → hint](/fr/configuration#hint-cross-cutting) pour plus de détails.
</Tip>

***

## Commandes dangereuses

Empêche les agents d'exécuter des opérations difficiles à annuler ou pouvant endommager le système hôte.

### `block-sudo`

**Événement :** PreToolUse (Bash)\
**Par défaut :** Refuse toute commande `sudo`.

Bloque les invocations qui incluent le mot-clé `sudo`. La correspondance de motifs est effectuée sur les tokens de commande analysés, et non sur la chaîne brute, pour éviter les contournements par injection d'opérateurs shell.

**Paramètres :**

| Paramètre       | Type       | Défaut | Description                                                                                  |
| --------------- | ---------- | ------ | -------------------------------------------------------------------------------------------- |
| `allowPatterns` | `string[]` | `[]`   | Préfixes de commandes exacts autorisés. Chaque entrée est comparée aux tokens argv analysés. |

**Exemple :**

```json theme={null}
{
  "policyParams": {
    "block-sudo": {
      "allowPatterns": ["sudo systemctl status", "sudo journalctl"]
    }
  }
}
```

Avec cette configuration, `sudo systemctl status nginx` est autorisé, mais `sudo rm /etc/hosts` est refusé.

<Note>
  Les motifs sont comparés aux tokens analysés, et non à la chaîne de commande brute. Cela empêche les contournements via des opérateurs shell ajoutés (ex. `sudo systemctl status x; rm -rf /` ne correspond pas à `sudo systemctl status *`).
</Note>

***

### `block-rm-rf`

**Événement :** PreToolUse (Bash)\
**Par défaut :** Refuse `rm -rf`, `rm -fr` et les formes similaires de suppression récursive.

**Paramètres :**

| Paramètre    | Type       | Défaut | Description                                                       |
| ------------ | ---------- | ------ | ----------------------------------------------------------------- |
| `allowPaths` | `string[]` | `[]`   | Chemins dont la suppression récursive est autorisée (ex. `/tmp`). |

**Exemple :**

```json theme={null}
{
  "policyParams": {
    "block-rm-rf": {
      "allowPaths": ["/tmp", "/var/cache"]
    }
  }
}
```

***

### `block-curl-pipe-sh`

**Événement :** PreToolUse (Bash)\
**Par défaut :** Refuse `curl <url> | bash`, `curl <url> | sh`, `wget <url> | bash` et les motifs similaires.

Aucun paramètre.

***

### `block-failproofai-commands`

**Événement :** PreToolUse (Bash)\
**Par défaut :** Refuse les commandes qui désinstalleraient ou désactiveraient failproofai lui-même (ex. `npm uninstall failproofai`, `failproofai policies --uninstall`).

Aucun paramètre.

***

## Commandes d'infrastructure

Empêche les agents de code d'exécuter des CLI d'infrastructure ou de déclencher des pipelines CI/CD. Toutes les politiques de cette catégorie sont **opt-in** (`defaultEnabled: false`) — les agents ayant légitimement besoin d'appeler `kubectl`, `terraform`, etc. ne seront pas perturbés sauf si vous activez la politique. Une fois activée, toute invocation du CLI correspondant est refusée, sauf si la commande correspond à une entrée dans `allowPatterns`.

La grammaire des motifs est la même que pour [`block-sudo`](#block-sudo) : les tokens sont comparés à l'argv analysé, `*` est un joker pour un token, et toute commande contenant un opérateur shell autonome (`&&`, `||`, `|`, `;`) ou un token avec des métacaractères shell intégrés est rejetée avant la vérification de la liste d'autorisation afin d'éviter les injections.

### `block-kubectl`

**Événement :** PreToolUse (Bash)\
**Par défaut :** Refuse toute invocation de `kubectl`.

**Paramètres :**

| Paramètre       | Type       | Défaut | Description                              |
| --------------- | ---------- | ------ | ---------------------------------------- |
| `allowPatterns` | `string[]` | `[]`   | Préfixes de commandes kubectl autorisés. |

**Exemple :**

```json theme={null}
{
  "policyParams": {
    "block-kubectl": {
      "allowPatterns": ["kubectl get *", "kubectl describe *", "kubectl logs *"]
    }
  }
}
```

Avec cette configuration, `kubectl get pods` est autorisé mais `kubectl apply -f deploy.yaml` est refusé.

***

### `block-terraform`

**Événement :** PreToolUse (Bash)\
**Par défaut :** Refuse toute invocation de `terraform` ou `tofu` (OpenTofu).

**Paramètres :**

| Paramètre       | Type       | Défaut | Description                                     |
| --------------- | ---------- | ------ | ----------------------------------------------- |
| `allowPatterns` | `string[]` | `[]`   | Préfixes de commandes terraform/tofu autorisés. |

**Exemple :**

```json theme={null}
{
  "policyParams": {
    "block-terraform": {
      "allowPatterns": ["terraform plan", "terraform validate", "terraform show *"]
    }
  }
}
```

***

### `block-aws-cli`

**Événement :** PreToolUse (Bash)\
**Par défaut :** Refuse toute invocation du CLI `aws`.

**Paramètres :**

| Paramètre       | Type       | Défaut | Description                                 |
| --------------- | ---------- | ------ | ------------------------------------------- |
| `allowPatterns` | `string[]` | `[]`   | Préfixes de commandes du CLI aws autorisés. |

**Exemple :**

```json theme={null}
{
  "policyParams": {
    "block-aws-cli": {
      "allowPatterns": ["aws s3 ls *", "aws sts get-caller-identity"]
    }
  }
}
```

***

### `block-gcloud`

**Événement :** PreToolUse (Bash)\
**Par défaut :** Refuse toute invocation du CLI `gcloud` (Google Cloud).

**Paramètres :**

| Paramètre       | Type       | Défaut | Description                             |
| --------------- | ---------- | ------ | --------------------------------------- |
| `allowPatterns` | `string[]` | `[]`   | Préfixes de commandes gcloud autorisés. |

**Exemple :**

```json theme={null}
{
  "policyParams": {
    "block-gcloud": {
      "allowPatterns": ["gcloud auth list", "gcloud config list"]
    }
  }
}
```

***

### `block-az-cli`

**Événement :** PreToolUse (Bash)\
**Par défaut :** Refuse toute invocation du CLI `az` (Azure).

**Paramètres :**

| Paramètre       | Type       | Défaut | Description                                |
| --------------- | ---------- | ------ | ------------------------------------------ |
| `allowPatterns` | `string[]` | `[]`   | Préfixes de commandes du CLI az autorisés. |

**Exemple :**

```json theme={null}
{
  "policyParams": {
    "block-az-cli": {
      "allowPatterns": ["az account show", "az group list"]
    }
  }
}
```

***

### `block-helm`

**Événement :** PreToolUse (Bash)\
**Par défaut :** Refuse toute invocation de `helm`.

**Paramètres :**

| Paramètre       | Type       | Défaut | Description                           |
| --------------- | ---------- | ------ | ------------------------------------- |
| `allowPatterns` | `string[]` | `[]`   | Préfixes de commandes helm autorisés. |

**Exemple :**

```json theme={null}
{
  "policyParams": {
    "block-helm": {
      "allowPatterns": ["helm list", "helm status *"]
    }
  }
}
```

***

### `block-gh-pipeline`

**Événement :** PreToolUse (Bash)\
**Par défaut :** Refuse les sous-commandes CLI `gh` suivantes qui modifient l'état ou déclenchent des pipelines :

* `gh workflow run`, `gh workflow enable`, `gh workflow disable`
* `gh run rerun`, `gh run cancel`
* `gh pr merge`
* `gh release create`, `gh release delete`
* `gh cache delete`
* `gh secret set`, `gh secret delete`

Les sous-commandes `gh` en lecture seule telles que `gh pr view`, `gh pr list`, `gh run list`, `gh release view` et `gh api repos/.../...` **ne sont pas** couvertes par cette politique — elles sont couramment nécessaires pour les vérifications de workflow (y compris le `require-ci-green-before-stop` de failproofai).

**Paramètres :**

| Paramètre       | Type       | Défaut | Description                                                                                |
| --------------- | ---------- | ------ | ------------------------------------------------------------------------------------------ |
| `allowPatterns` | `string[]` | `[]`   | Invocations scriptées spécifiques à autoriser même si elles seraient normalement refusées. |

**Exemple :**

```json theme={null}
{
  "policyParams": {
    "block-gh-pipeline": {
      "allowPatterns": ["gh run rerun *"]
    }
  }
}
```

***

## Secrets (assainisseurs)

Empêche les agents de laisser fuiter des identifiants dans leur contexte ou leur sortie. Les politiques d'assainissement se déclenchent sur les événements **PostToolUse**. Lorsque Claude exécute une commande Bash, lit un fichier ou appelle un outil, ces politiques inspectent la sortie avant qu'elle ne soit retournée à Claude. Si un motif de secret est détecté, la politique retourne une décision deny qui empêche la sortie d'être renvoyée.

### `sanitize-jwt`

**Événement :** PostToolUse (tous les outils)\
**Par défaut :** Masque les tokens JWT (trois segments base64url séparés par `.`).

Aucun paramètre.

***

### `sanitize-api-keys`

**Événement :** PostToolUse (tous les outils)\
**Par défaut :** Masque les formats de clés API courants : Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), clés d'accès AWS (`AKIA`), clés Stripe (`sk_live_`, `sk_test_`), et clés API Google (`AIza`).

**Paramètres :**

| Paramètre            | Type                                 | Défaut | Description                                               |
| -------------------- | ------------------------------------ | ------ | --------------------------------------------------------- |
| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]`   | Motifs regex supplémentaires à traiter comme des secrets. |

**Exemple :**

```json theme={null}
{
  "policyParams": {
    "sanitize-api-keys": {
      "additionalPatterns": [
        { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo internal API key" },
        { "regex": "pat_[0-9a-f]{40}", "label": "Internal PAT" }
      ]
    }
  }
}
```

***

### `sanitize-connection-strings`

**Événement :** PostToolUse (tous les outils)\
**Par défaut :** Masque les chaînes de connexion de bases de données contenant des identifiants intégrés (ex. `postgresql://user:password@host/db`).

Aucun paramètre.

***

### `sanitize-private-key-content`

**Événement :** PostToolUse (tous les outils)\
**Par défaut :** Masque les blocs PEM (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, etc.).

Aucun paramètre.

***

### `sanitize-bearer-tokens`

**Événement :** PostToolUse (tous les outils)\
**Par défaut :** Masque les en-têtes `Authorization: Bearer <token>` dont le token fait 20 caractères ou plus.

Aucun paramètre.

***

## Environnement

Protège la configuration d'environnement sensible contre la lecture ou l'exposition par les agents.

### `block-env-files`

**Événement :** PreToolUse (Bash, Read)\
**Par défaut :** Refuse la lecture des fichiers `.env` via `cat .env`, les appels à l'outil `Read` avec `.env` comme chemin de fichier, etc.

Ne bloque pas `.envrc` ni les autres fichiers liés à l'environnement — uniquement les fichiers nommés exactement `.env`.

Aucun paramètre.

***

### `protect-env-vars`

**Événement :** PreToolUse (Bash)\
**Par défaut :** Refuse les commandes qui affichent les variables d'environnement : `printenv`, `env`, `echo $VAR`.

Aucun paramètre.

***

## Accès aux fichiers

Maintient les agents dans les limites du projet et à l'écart des fichiers sensibles.

### `block-read-outside-cwd`

**Événement :** PreToolUse (Read, Bash)\
**Par défaut :** Refuse la lecture de fichiers en dehors de la racine du projet. La limite est `CLAUDE_PROJECT_DIR` (définie une fois par session par Claude Code), avec un repli sur le répertoire de travail courant de la session si cette variable n'est pas définie. L'utilisation de la racine du projet plutôt que du `cwd` actif garantit que la limite reste stable même après qu'un `cd` de Claude vers un sous-répertoire.

**Paramètres :**

| Paramètre    | Type       | Défaut | Description                                                                                    |
| ------------ | ---------- | ------ | ---------------------------------------------------------------------------------------------- |
| `allowPaths` | `string[]` | `[]`   | Préfixes de chemins absolus autorisés même s'ils se trouvent en dehors de la racine du projet. |

**Exemple :**

```json theme={null}
{
  "policyParams": {
    "block-read-outside-cwd": {
      "allowPaths": ["/shared/data", "/opt/company/config"]
    }
  }
}
```

***

### `block-secrets-write`

**Événement :** PreToolUse (Write, Edit)\
**Par défaut :** Refuse les écritures dans les fichiers couramment utilisés pour les clés privées et les certificats : `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`.

**Paramètres :**

| Paramètre            | Type       | Défaut | Description                                                        |
| -------------------- | ---------- | ------ | ------------------------------------------------------------------ |
| `additionalPatterns` | `string[]` | `[]`   | Motifs de noms de fichiers supplémentaires (style glob) à bloquer. |

**Exemple :**

```json theme={null}
{
  "policyParams": {
    "block-secrets-write": {
      "additionalPatterns": [".token", ".secret"]
    }
  }
}
```

***

## Git

Évite les pushs accidentels, les force-pushs et les erreurs de branche difficiles à annuler.

### `block-push-master`

**Événement :** PreToolUse (Bash)\
**Par défaut :** Refuse `git push origin main` et `git push origin master`.

**Paramètres :**

| Paramètre           | Type       | Défaut               | Description                                                  |
| ------------------- | ---------- | -------------------- | ------------------------------------------------------------ |
| `protectedBranches` | `string[]` | `["main", "master"]` | Noms de branches sur lesquelles le push direct est interdit. |

**Exemple :**

```json theme={null}
{
  "policyParams": {
    "block-push-master": {
      "protectedBranches": ["main", "master", "release", "prod"]
    }
  }
}
```

<Tip>
  Pour autoriser le push vers toutes les branches (ce qui désactive effectivement cette politique sans la retirer de `enabledPolicies`), définissez `protectedBranches: []`.
</Tip>

***

### `block-work-on-main`

**Événement :** PreToolUse (Bash)\
**Par défaut :** Refuse `git commit`, `git merge`, `git rebase` et `git cherry-pick` lorsque l'arbre de travail est sur `main` ou `master`. La création et le changement de branche (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) ne sont pas affectés.

**Paramètres :**

| Paramètre           | Type       | Défaut               | Description                                                                 |
| ------------------- | ---------- | -------------------- | --------------------------------------------------------------------------- |
| `protectedBranches` | `string[]` | `["main", "master"]` | Noms de branches sur lesquelles commit/merge/rebase/cherry-pick est refusé. |

***

### `block-force-push`

**Événement :** PreToolUse (Bash)\
**Par défaut :** Refuse `git push --force` et `git push -f`.

Aucun paramètre spécifique à cette politique. Utilisez le [`hint`](/fr/configuration#hint-cross-cutting) transversal pour suggérer des alternatives :

```json theme={null}
{
  "policyParams": {
    "block-force-push": {
      "hint": "Create a new branch from your current HEAD (e.g. `git checkout -b <new-branch>`) and push that instead."
    }
  }
}
```

***

### `warn-git-amend`

**Événement :** PreToolUse (Bash)\
**Par défaut :** Demande à Claude de procéder avec précaution lors de l'exécution de `git commit --amend`. Ne bloque pas la commande.

Aucun paramètre.

***

### `warn-git-stash-drop`

**Événement :** PreToolUse (Bash)\
**Par défaut :** Demande à Claude de confirmer avant d'exécuter `git stash drop`. Ne bloque pas la commande.

Aucun paramètre.

***

### `warn-all-files-staged`

**Événement :** PreToolUse (Bash)\
**Par défaut :** Demande à Claude de vérifier ce qu'il indexe lorsqu'il exécute `git add -A` ou `git add .`. Ne bloque pas la commande.

Aucun paramètre.

***

## Base de données

Détecte les opérations SQL destructives avant qu'elles ne s'exécutent sur votre base de données.

### `warn-destructive-sql`

**Événement :** PreToolUse (Bash)\
**Par défaut :** Demande à Claude de confirmer avant d'exécuter du SQL contenant `DROP TABLE`, `DROP DATABASE` ou `DELETE` sans clause `WHERE`.

Aucun paramètre.

***

### `warn-schema-alteration`

**Événement :** PreToolUse (Bash)\
**Par défaut :** Demande à Claude de confirmer avant d'exécuter des instructions `ALTER TABLE`.

Aucun paramètre.

***

## Avertissements

Fournit aux agents un contexte supplémentaire avant des opérations potentiellement risquées mais non destructives.

### `warn-large-file-write`

**Événement :** PreToolUse (Write)\
**Par défaut :** Demande à Claude de confirmer avant d'écrire des fichiers de plus de 1024 Ko.

**Paramètres :**

| Paramètre     | Type     | Défaut | Description                                                                         |
| ------------- | -------- | ------ | ----------------------------------------------------------------------------------- |
| `thresholdKb` | `number` | `1024` | Seuil de taille de fichier en kilo-octets au-delà duquel un avertissement est émis. |

**Exemple :**

```json theme={null}
{
  "policyParams": {
    "warn-large-file-write": {
      "thresholdKb": 256
    }
  }
}
```

<Note>
  Le gestionnaire de hook impose une limite de 1 Mo sur les charges utiles stdin. Pour tester cette politique avec un contenu de petite taille, définissez `thresholdKb` à une valeur bien inférieure à 1024.
</Note>

***

### `warn-package-publish`

**Événement :** PreToolUse (Bash)\
**Par défaut :** Demande à Claude de confirmer avant d'exécuter `npm publish`.

Aucun paramètre.

***

### `warn-background-process`

**Événement :** PreToolUse (Bash)\
**Par défaut :** Demande à Claude d'être prudent lors du lancement de processus en arrière-plan via `nohup`, `&`, `disown` ou `screen`.

Aucun paramètre.

***

### `warn-global-package-install`

**Événement :** PreToolUse (Bash)\
**Par défaut :** Demande à Claude de confirmer avant d'exécuter `npm install -g`, `yarn global add` ou `pip install` sans environnement virtuel.

Aucun paramètre.

***

## Gestionnaires de paquets

Impose les gestionnaires de paquets que l'agent est autorisé à utiliser.

### `prefer-package-manager`

**Événement :** PreToolUse (Bash)\
**Par défaut :** Désactivé. Lorsqu'activé, bloque toute commande de gestionnaire de paquets absent de la liste `allowed` et demande à Claude de réécrire la commande en utilisant un gestionnaire autorisé.

Détecte : pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo.

| Paramètre | Type      | Défaut | Description                                                                                                                                   |
| --------- | --------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `allowed` | string\[] | `[]`   | Noms de gestionnaires de paquets autorisés. Tout gestionnaire détecté absent de cette liste est bloqué. Si vide, la politique est sans effet. |
| `blocked` | string\[] | `[]`   | Noms de gestionnaires supplémentaires à bloquer en plus de la liste intégrée (ex. `['pdm', 'pipx']`).                                         |

La liste de blocage intégrée couvre : pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Utilisez `blocked` pour ajouter des gestionnaires absents de cette liste.

**Exemple de configuration :**

```json theme={null}
{
  "enabledPolicies": ["prefer-package-manager"],
  "policyParams": {
    "prefer-package-manager": {
      "allowed": ["uv", "bun"],
      "blocked": ["pdm", "pipx"]
    }
  }
}
```

Avec cette configuration, `pip install flask` et `pdm install flask` sont tous deux refusés avec un message indiquant à Claude d'utiliser `uv` ou `bun` à la place. Les commandes comme `uv pip install flask` sont autorisées car `uv` est dans la liste d'autorisation et est vérifié en premier.

***

## Comportement de l'IA

Détecte quand les agents sont bloqués ou se comportent de manière inattendue.

### `warn-repeated-tool-calls`

**Événement :** PreToolUse (tous les outils)\
**Par défaut :** Demande à Claude de reconsidérer lorsque le même outil est appelé 3 fois ou plus avec des paramètres identiques — signe courant que l'agent est coincé dans une boucle.

Aucun paramètre.

***

## Workflow

Impose un workflow de fin de session discipliné. Ces politiques se déclenchent sur l'événement **Stop** et empêchent l'agent de s'arrêter jusqu'à ce que chaque condition soit remplie. Elles suivent une chaîne de dépendances naturelle : commit → push → PR → CI. Si une politique refuse, les politiques suivantes dans la chaîne sont ignorées (court-circuit sur deny).

Toutes les politiques de workflow sont **fail-open** : si l'outil requis n'est pas disponible (ex. `gh` non installé, pas de remote git), la politique autorise avec un message informatif expliquant pourquoi la vérification a été ignorée.

### Sémantique Stop par CLI

L'application du Stop se présente légèrement différemment selon les sept CLI supportés, car chacun expose un contrat de hook différent pour signaler que l'agent a terminé. Le **résultat** est le même — l'agent ne peut pas s'arrêter tant qu'une barrière de workflow est en échec — mais les **mécanismes** diffèrent. Le tableau ci-dessous résume la situation ; seul Pi présente un comportement visible par l'utilisateur qui mérite d'être compris avant d'activer une politique `require-*-before-stop`.

| CLI                      | Moment du déclenchement            | Ce que vous voyez                                                                                                                                                                                                                                                                                                                                                                                                         |
| ------------------------ | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Claude Code              | Même boucle d'agent, immédiatement | Claude continue de travailler — corrige le problème, puis tente de terminer à nouveau. Aucune interruption visible pour vous.                                                                                                                                                                                                                                                                                             |
| Codex                    | Même boucle d'agent, immédiatement | Identique à Claude.                                                                                                                                                                                                                                                                                                                                                                                                       |
| GitHub Copilot CLI       | Même boucle d'agent, immédiatement | Identique à Claude (utilise le canal de relance `{decision:"block", reason}` de Copilot — vérifié empiriquement avec Copilot CLI 1.0.41).                                                                                                                                                                                                                                                                                 |
| Cursor Agent             | Même boucle d'agent, immédiatement | Identique à Claude (utilise le canal `{followup_message}` de Cursor — limité par `loop_limit`, 5 relances par défaut).                                                                                                                                                                                                                                                                                                    |
| Gemini CLI               | Même boucle d'agent, immédiatement | Identique à Claude (utilise le canal `{decision:"block", reason}` de Gemini sur `AfterAgent`).                                                                                                                                                                                                                                                                                                                            |
| OpenCode                 | Même boucle d'agent, immédiatement | Identique à Claude (utilise l'appel SDK `client.session.prompt(...)` d'OpenCode routé via `hookSpecificOutput.additionalContext`).                                                                                                                                                                                                                                                                                        |
| **Pi (pi-coding-agent)** | **Tour utilisateur suivant**       | **Pi s'arrête visiblement** lorsque la barrière se déclenche — sa boucle d'agent se termine et vous revenez au prompt. La barrière se déclenche alors la prochaine fois que vous soumettez un prompt : failproofai ajoute en tête une directive `MANDATORY ACTION REQUIRED` au prompt système de ce tour, demandant au LLM de compléter l'étape de workflow (commit, push, etc.) avant de faire ce que vous avez demandé. |

<Note>
  **Limitation de Pi.** L'`AgentEndEvent` de Pi (l'équivalent en amont du hook `Stop` de Claude) n'a pas de type Result — au moment où il se déclenche, la boucle d'agent de Pi a déjà quitté. Pi ne peut pas être forcé à réessayer la même boucle comme Claude / Copilot / Cursor / Gemini / OpenCode. failproofai déplace la barrière vers l'événement `before_agent_start` de Pi (qui se déclenche après le prochain prompt utilisateur) afin que la vérification du workflow soit toujours appliquée, mais au tour suivant plutôt qu'au tour courant.

  **Ce que cela signifie en pratique :**

  * Après l'arrêt de Pi, la raison du refus est capturée en mémoire, indexée par l'identifiant de session Pi. Le prochain prompt que vous soumettez dans le même processus Pi la consomme : le LLM voit la directive `MANDATORY ACTION REQUIRED` en tête de son prompt système, effectue le commit (ou le push / ouvre la PR / attend le CI), et ne continue avec votre demande qu'ensuite. La raison de refus capturée est à usage unique — une fois consommée, la barrière est levée.
  * La barrière est liée à la durée de vie du processus Pi. Si vous faites `Ctrl+C` sur Pi ou quittez entre les tours, l'entrée en mémoire est supprimée avec le processus et la barrière est manquée. Claude, Copilot, Cursor, Gemini et OpenCode ont la même contrainte (tuer l'agent fait manquer la barrière) — Pi le rend simplement plus visible car l'agent quitte visiblement avant que la barrière ne se déclenche.
  * Un refus en attente est également effacé lors d'un `session_shutdown` pour toute raison (`new` / `resume` / `fork` / `quit`), de sorte qu'une barrière obsolète d'une session précédente ne peut pas contaminer une nouvelle session démarrée dans le même processus Pi.

  Si vous avez besoin d'une relance dans la même boucle comme avec Claude, exécutez vos politiques `Stop` avec l'un des six autres CLI supportés. Nous suivons l'évolution de Pi en amont pour un futur type Result sur `AgentEndEvent` qui permettrait de combler cet écart.
</Note>

### `require-commit-before-stop`

**Événement :** Stop\
**Par défaut :** Refuse l'arrêt lorsqu'il y a des modifications non commitées (fichiers modifiés, indexés ou non suivis). Retourne un message informatif lorsque le répertoire de travail est propre.

Aucun paramètre.

***

### `require-push-before-stop`

**Événement :** Stop\
**Par défaut :** Refuse l'arrêt lorsqu'il y a des commits non pushés ou lorsque la branche courante n'a pas de branche de suivi distante. Suggère `git push -u` pour créer une branche de suivi si nécessaire. Fail-open si aucun remote n'est configuré.

**Paramètres :**

| Paramètre | Type     | Défaut     | Description                       |
| --------- | -------- | ---------- | --------------------------------- |
| `remote`  | `string` | `"origin"` | Nom du remote vers lequel pusher. |

**Exemple :**

```json theme={null}
{
  "policyParams": {
    "require-push-before-stop": {
      "remote": "upstream"
    }
  }
}
```

***

### `require-pr-before-stop`

**Événement :** Stop\
**Par défaut :** Refuse l'arrêt lorsqu'aucune pull request n'existe pour la branche courante, ou lorsque la PR existante est fermée sans avoir été fusionnée. Demande à Claude de créer une PR avec `gh pr create`. Lorsque la PR est **fusionnée**, la politique autorise (le travail a été livré) et le message suggère de quitter la branche (`git checkout main && git pull`).

Aucun paramètre.

<Note>
  Cette politique nécessite que le [GitHub CLI](https://cli.github.com/) (`gh`) soit installé et authentifié.
  Exécutez `gh auth login` avec un personal access token disposant de la portée `repo` pour accéder en lecture aux pull requests. Si `gh` n'est pas installé ou non authentifié, la politique est fail-open et en informe Claude.
</Note>

***

### `require-no-conflicts-before-stop`

**Événement :** Stop\
**Par défaut :** Refuse l'arrêt lorsque la branche courante ne peut pas fusionner proprement dans la branche de base. La politique confirme d'abord qu'il existe une PR `OPEN` sur GitHub pour la branche — sans PR, il n'y a pas de cible de fusion à appliquer, et la politique court-circuite vers allow. Une fois une PR `OPEN` confirmée, deux sondes indépendantes s'exécutent :

1. **Locale** — `git merge-tree --write-tree --name-only origin/<baseBranch> HEAD`. En cas de conflit, le message de refus liste les fichiers en conflit pour que Claude sache exactement quoi résoudre.
2. **GitHub** — réutilise le résultat de `gh pr view --json mergeable,state` déjà récupéré lors de la vérification préalable. Détecte les conflits qu'un `origin/<baseBranch>` local périmé pourrait manquer (ex. une PR conflictuelle mergée sur `main` depuis le dernier fetch). Un résultat `CONFLICTING` entraîne un refus. Un résultat `UNKNOWN` entraîne également un refus et demande à Claude d'attendre environ 10 secondes et de revérifier avant de tenter de s'arrêter — cela évite les faux négatifs pendant que GitHub recalcule.

Ignore entièrement (autorise) dans les cas suivants : `gh` non installé, aucune PR pour la branche, l'état de la PR n'est pas `OPEN` (ex. `MERGED`, `CLOSED`), ou `gh pr view` retourne une sortie non analysable. Également fail-open lorsque `origin/<baseBranch>` est absent localement ou lorsqu'aucun commit n'est en avance sur la base — ces cas de repli de niveau 1 consultent tout de même la fusionnabilité de la PR en cache avant d'autoriser.

**Paramètres :**

| Paramètre    | Type     | Défaut   | Description                                            |
| ------------ | -------- | -------- | ------------------------------------------------------ |
| `baseBranch` | `string` | `"main"` | Branche de base contre laquelle vérifier les conflits. |

<Note>
  Le GitHub CLI (`gh`) est requis pour cette politique. La politique utilise `gh pr view` pour confirmer l'existence d'une PR `OPEN` avant d'exécuter toute sonde de conflit — sans `gh`, la politique court-circuite vers allow. Exécutez `gh auth login` avec un personal access token disposant de la portée `repo` pour accéder en lecture aux pull requests.
</Note>

***

### `require-ci-green-before-stop`

**Événement :** Stop\
**Par défaut :** Refuse l'arrêt lorsque les vérifications CI sont en échec ou toujours en cours sur la branche courante. Vérifie à la fois les workflows GitHub Actions et les vérifications de bots tiers (ex. CodeRabbit, SonarCloud, Codecov). Considère les conclusions `skipped`, `cancelled` et `neutral` comme non-échouées (cette dernière couvre par exemple les alertes Socket Security sur les PRs de contributeurs externes, où l'application signale intentionnellement neutral plutôt que success/failure). Retourne un message informatif lorsque toutes les vérifications réussissent.

Aucun paramètre.

<Note>
  Cette politique nécessite que le [GitHub CLI](https://cli.github.com/) (`gh`) soit installé et authentifié.
  Exécutez `gh auth login` avec un personal access token disposant de la portée `repo` pour accéder en lecture aux workflows GitHub Actions et à l'API Checks. Si `gh` n'est pas installé ou non authentifié, la politique est fail-open et en informe Claude.
</Note>

***

***

## Désactiver des politiques individuelles

Retirez une politique spécifique de `enabledPolicies` dans votre configuration, ou désactivez-la dans l'onglet Policies du tableau de bord.

```json theme={null}
{
  "enabledPolicies": [
    "block-rm-rf",
    "sanitize-api-keys"
  ]
}
```

Les politiques absentes de `enabledPolicies` ne s'exécutent pas, même si des entrées `policyParams` existent pour elles.