> ## Documentation Index
> Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrierte Richtlinien

> Alle 39 integrierten Richtlinien, die häufige Fehlerszenarien von Agenten abfangen

failproofai enthält 39 integrierte Richtlinien, die häufige Fehlerszenarien von Agenten abfangen. Jede Richtlinie wird für einen bestimmten Hook-Ereignistyp und Toolnamen ausgelöst. Neunzehn Richtlinien akzeptieren Parameter, mit denen Sie ihr Verhalten anpassen können, ohne Code zu schreiben. Fünf Workflow-Richtlinien erzwingen eine Commit → Push → PR → CI-Pipeline, bevor Claude anhält.

***

## Übersicht

Richtlinien sind in Kategorien gruppiert:

| Kategorie                                  | Richtlinien                                                                                                                                  | Hook-Typ    |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| [Gefährliche Befehle](#dangerous-commands) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands                                                                      | PreToolUse  |
| [Infra-Befehle](#infra-commands)           | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline                                     | PreToolUse  |
| [Secrets (Sanitizer)](#secrets-sanitizers) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens                           | PostToolUse |
| [Umgebung](#environment)                   | block-env-files, protect-env-vars                                                                                                            | PreToolUse  |
| [Dateizugriff](#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  |
| [Datenbank](#database)                     | warn-destructive-sql, warn-schema-alteration                                                                                                 | PreToolUse  |
| [Warnungen](#warnings)                     | warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install                                            | PreToolUse  |
| [Paketmanager](#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-`** — verhindert, dass der Agent fortfährt.
* **`warn-`** — gibt dem Agenten zusätzlichen Kontext, damit er sich selbst korrigieren kann.
* **`sanitize-`** — entfernt vertrauliche Daten aus der Tool-Ausgabe, bevor der Agent sie sieht.

### Namespaces

Jede Richtlinie befindet sich in einem `<namespace>/<name>`-Slot. Integrierte Richtlinien gehören zum **`failproofai/`**-Namespace — zum Beispiel `failproofai/sanitize-jwt`. Der Namespace verhindert Konflikte, wenn Sie auch benutzerdefinierte oder Drittanbieter-Richtlinien mit ähnlichen Kurznamen laden.

In Ihrer Konfiguration können Sie eine integrierte Richtlinie entweder über ihren Kurznamen oder ihren qualifizierten Namen referenzieren; beide Formen lösen sich zur gleichen Richtlinie auf:

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

Wenn ein Name kein `/` enthält, behandelt failproofai ihn als zum Standard-Namespace `failproofai` gehörend. Namen, die bereits ein `/` enthalten (z.B. `myorg/foo`, `custom/my-hook`), werden unverändert übernommen.

* **`require-`** — blockiert das Stop-Ereignis, bis die Bedingungen erfüllt sind.

***

<Tip>
  Jede Richtlinie unterstützt ein optionales `hint`-Feld in `policyParams`. Der Hinweis wird an die deny- oder instruct-Nachricht angehängt, die Claude sieht, und gibt umsetzbare Anweisungen, ohne den Richtliniencode zu ändern. Funktioniert mit integrierten, benutzerdefinierten und konventionsbasierten Richtlinien. Weitere Informationen finden Sie unter [Konfiguration → hint](/de/configuration#hint-cross-cutting).
</Tip>

***

## Gefährliche Befehle

Verhindert, dass Agenten Operationen ausführen, die schwer rückgängig zu machen sind oder das Hostsystem beschädigen könnten.

### `block-sudo`

**Ereignis:** PreToolUse (Bash)\
**Standard:** Verweigert jeden `sudo`-Befehl.

Blockiert Aufrufe, die das Schlüsselwort `sudo` enthalten. Der Musterabgleich erfolgt auf geparsten Befehls-Tokens, nicht auf dem rohen String, um Umgehungsversuche über Shell-Operator-Injektion zu verhindern.

**Parameter:**

| Parameter       | Typ        | Standard | Beschreibung                                                                                             |
| --------------- | ---------- | -------- | -------------------------------------------------------------------------------------------------------- |
| `allowPatterns` | `string[]` | `[]`     | Exakte Befehlspräfixe, die erlaubt sind. Jeder Eintrag wird gegen die geparsten argv-Tokens abgeglichen. |

**Beispiel:**

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

Mit dieser Konfiguration ist `sudo systemctl status nginx` erlaubt, aber `sudo rm /etc/hosts` wird verweigert.

<Note>
  Muster werden gegen geparste Tokens abgeglichen, nicht gegen den rohen Befehlsstring. Dies verhindert Umgehungsversuche über angehängte Shell-Operatoren (z.B. führt `sudo systemctl status x; rm -rf /` nicht zu einer Übereinstimmung mit `sudo systemctl status *`).
</Note>

***

### `block-rm-rf`

**Ereignis:** PreToolUse (Bash)\
**Standard:** Verweigert `rm -rf`, `rm -fr` und ähnliche rekursive Löschformen.

**Parameter:**

| Parameter    | Typ        | Standard | Beschreibung                                                     |
| ------------ | ---------- | -------- | ---------------------------------------------------------------- |
| `allowPaths` | `string[]` | `[]`     | Pfade, die sicher rekursiv gelöscht werden dürfen (z.B. `/tmp`). |

**Beispiel:**

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

***

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

**Ereignis:** PreToolUse (Bash)\
**Standard:** Verweigert `curl <url> | bash`, `curl <url> | sh`, `wget <url> | bash` und ähnliche Muster.

Keine Parameter.

***

### `block-failproofai-commands`

**Ereignis:** PreToolUse (Bash)\
**Standard:** Verweigert Befehle, die failproofai selbst deinstallieren oder deaktivieren würden (z.B. `npm uninstall failproofai`, `failproofai policies --uninstall`).

Keine Parameter.

***

## Infra-Befehle

Verhindert, dass Coding-Agenten Infrastruktur-CLIs ausführen oder CI/CD-Pipelines auslösen. Alle Richtlinien in dieser Kategorie sind **opt-in** (`defaultEnabled: false`) — Agenten, die legitimerweise `kubectl`, `terraform` usw. aufrufen müssen, werden nicht beeinträchtigt, es sei denn, Sie aktivieren die Richtlinie. Wenn aktiviert, wird jeder Aufruf der entsprechenden CLI verweigert, sofern der Befehl nicht einem Eintrag in `allowPatterns` entspricht.

Die Muster-Grammatik ist dieselbe wie bei [`block-sudo`](#block-sudo): Tokens werden gegen geparste argv abgeglichen, `*` ist ein Platzhalter für ein Token, und jeder Befehl, der einen eigenständigen Shell-Operator (`&&`, `||`, `|`, `;`) oder ein Token mit eingebetteten Shell-Metazeichen enthält, wird vor dem Allowlist-Abgleich abgelehnt, um Injektionsumgehungen zu verhindern.

### `block-kubectl`

**Ereignis:** PreToolUse (Bash)\
**Standard:** Verweigert jeden `kubectl`-Aufruf.

**Parameter:**

| Parameter       | Typ        | Standard | Beschreibung                              |
| --------------- | ---------- | -------- | ----------------------------------------- |
| `allowPatterns` | `string[]` | `[]`     | kubectl-Befehlspräfixe, die erlaubt sind. |

**Beispiel:**

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

Mit dieser Konfiguration ist `kubectl get pods` erlaubt, aber `kubectl apply -f deploy.yaml` wird verweigert.

***

### `block-terraform`

**Ereignis:** PreToolUse (Bash)\
**Standard:** Verweigert jeden `terraform`- oder `tofu`-(OpenTofu-)Aufruf.

**Parameter:**

| Parameter       | Typ        | Standard | Beschreibung                                     |
| --------------- | ---------- | -------- | ------------------------------------------------ |
| `allowPatterns` | `string[]` | `[]`     | terraform/tofu-Befehlspräfixe, die erlaubt sind. |

**Beispiel:**

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

***

### `block-aws-cli`

**Ereignis:** PreToolUse (Bash)\
**Standard:** Verweigert jeden `aws`-CLI-Aufruf.

**Parameter:**

| Parameter       | Typ        | Standard | Beschreibung                              |
| --------------- | ---------- | -------- | ----------------------------------------- |
| `allowPatterns` | `string[]` | `[]`     | aws-CLI-Befehlspräfixe, die erlaubt sind. |

**Beispiel:**

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

***

### `block-gcloud`

**Ereignis:** PreToolUse (Bash)\
**Standard:** Verweigert jeden `gcloud`-(Google Cloud-)CLI-Aufruf.

**Parameter:**

| Parameter       | Typ        | Standard | Beschreibung                             |
| --------------- | ---------- | -------- | ---------------------------------------- |
| `allowPatterns` | `string[]` | `[]`     | gcloud-Befehlspräfixe, die erlaubt sind. |

**Beispiel:**

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

***

### `block-az-cli`

**Ereignis:** PreToolUse (Bash)\
**Standard:** Verweigert jeden `az`-(Azure-)CLI-Aufruf.

**Parameter:**

| Parameter       | Typ        | Standard | Beschreibung                             |
| --------------- | ---------- | -------- | ---------------------------------------- |
| `allowPatterns` | `string[]` | `[]`     | az-CLI-Befehlspräfixe, die erlaubt sind. |

**Beispiel:**

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

***

### `block-helm`

**Ereignis:** PreToolUse (Bash)\
**Standard:** Verweigert jeden `helm`-Aufruf.

**Parameter:**

| Parameter       | Typ        | Standard | Beschreibung                           |
| --------------- | ---------- | -------- | -------------------------------------- |
| `allowPatterns` | `string[]` | `[]`     | helm-Befehlspräfixe, die erlaubt sind. |

**Beispiel:**

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

***

### `block-gh-pipeline`

**Ereignis:** PreToolUse (Bash)\
**Standard:** Verweigert die folgenden `gh`-CLI-Unterbefehle, die den Zustand verändern oder Pipelines auslösen:

* `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`

Schreibgeschützte `gh`-Unterbefehle wie `gh pr view`, `gh pr list`, `gh run list`, `gh release view` und `gh api repos/.../...` werden von dieser Richtlinie **nicht** erfasst — sie werden routinemäßig für Workflow-Prüfungen benötigt (einschließlich failproofai's eigenem `require-ci-green-before-stop`).

**Parameter:**

| Parameter       | Typ        | Standard | Beschreibung                                                                                       |
| --------------- | ---------- | -------- | -------------------------------------------------------------------------------------------------- |
| `allowPatterns` | `string[]` | `[]`     | Bestimmte skriptgesteuerte Aufrufe, die erlaubt werden sollen, obwohl sie sonst verweigert würden. |

**Beispiel:**

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

***

## Secrets (Sanitizer)

Verhindert, dass Agenten Zugangsdaten in ihren Kontext oder ihre Ausgabe einschleusen. Sanitizer-Richtlinien werden bei **PostToolUse**-Ereignissen ausgelöst. Wenn Claude einen Bash-Befehl ausführt, eine Datei liest oder ein Tool aufruft, prüfen diese Richtlinien die Ausgabe, bevor sie an Claude zurückgegeben wird. Wenn ein Secret-Muster erkannt wird, gibt die Richtlinie eine Verweigerungsentscheidung zurück, die verhindert, dass die Ausgabe weitergeleitet wird.

### `sanitize-jwt`

**Ereignis:** PostToolUse (alle Tools)\
**Standard:** Schwärzt JWT-Tokens (drei base64url-Segmente, getrennt durch `.`).

Keine Parameter.

***

### `sanitize-api-keys`

**Ereignis:** PostToolUse (alle Tools)\
**Standard:** Schwärzt gängige API-Key-Formate: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), AWS-Zugriffsschlüssel (`AKIA`), Stripe-Schlüssel (`sk_live_`, `sk_test_`) und Google API-Schlüssel (`AIza`).

**Parameter:**

| Parameter            | Typ                                  | Standard | Beschreibung                                                       |
| -------------------- | ------------------------------------ | -------- | ------------------------------------------------------------------ |
| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]`     | Zusätzliche Regex-Muster, die als Secrets behandelt werden sollen. |

**Beispiel:**

```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`

**Ereignis:** PostToolUse (alle Tools)\
**Standard:** Schwärzt Datenbankverbindungszeichenfolgen, die eingebettete Zugangsdaten enthalten (z.B. `postgresql://user:password@host/db`).

Keine Parameter.

***

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

**Ereignis:** PostToolUse (alle Tools)\
**Standard:** Schwärzt PEM-Blöcke (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----` usw.).

Keine Parameter.

***

### `sanitize-bearer-tokens`

**Ereignis:** PostToolUse (alle Tools)\
**Standard:** Schwärzt `Authorization: Bearer <token>`-Header, bei denen das Token 20 oder mehr Zeichen lang ist.

Keine Parameter.

***

## Umgebung

Schützt vertrauliche Umgebungskonfigurationen davor, von Agenten gelesen oder offengelegt zu werden.

### `block-env-files`

**Ereignis:** PreToolUse (Bash, Read)\
**Standard:** Verweigert das Lesen von `.env`-Dateien über `cat .env`, `Read`-Tool-Aufrufe mit `.env` als Dateipfad usw.

Blockiert nicht `.envrc` oder andere umgebungsnahe Dateien — nur Dateien, die exakt `.env` heißen.

Keine Parameter.

***

### `protect-env-vars`

**Ereignis:** PreToolUse (Bash)\
**Standard:** Verweigert Befehle, die Umgebungsvariablen ausgeben: `printenv`, `env`, `echo $VAR`.

Keine Parameter.

***

## Dateizugriff

Hält Agenten innerhalb der Projektgrenzen und fernab von vertraulichen Dateien.

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

**Ereignis:** PreToolUse (Read, Bash)\
**Standard:** Verweigert das Lesen von Dateien außerhalb des Projektstamms. Die Grenze ist `CLAUDE_PROJECT_DIR` (einmalig pro Sitzung von Claude Code gesetzt), mit einem Fallback auf das aktuelle Arbeitsverzeichnis der Sitzung, wenn diese Variable nicht gesetzt ist. Die Verwendung des Projektstamms anstelle des Live-`cwd` bedeutet, dass die Grenze stabil bleibt, auch nachdem Claude in ein Unterverzeichnis gewechselt hat.

**Parameter:**

| Parameter    | Typ        | Standard | Beschreibung                                                             |
| ------------ | ---------- | -------- | ------------------------------------------------------------------------ |
| `allowPaths` | `string[]` | `[]`     | Absolute Pfadpräfixe, die auch außerhalb des Projektstamms erlaubt sind. |

**Beispiel:**

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

***

### `block-secrets-write`

**Ereignis:** PreToolUse (Write, Edit)\
**Standard:** Verweigert Schreibvorgänge in Dateien, die üblicherweise für private Schlüssel und Zertifikate verwendet werden: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`.

**Parameter:**

| Parameter            | Typ        | Standard | Beschreibung                                                           |
| -------------------- | ---------- | -------- | ---------------------------------------------------------------------- |
| `additionalPatterns` | `string[]` | `[]`     | Zusätzliche Dateinamenmuster (Glob-Stil), die blockiert werden sollen. |

**Beispiel:**

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

***

## Git

Verhindert versehentliche Pushes, Force-Pushes und Branch-Fehler, die schwer rückgängig zu machen sind.

### `block-push-master`

**Ereignis:** PreToolUse (Bash)\
**Standard:** Verweigert `git push origin main` und `git push origin master`.

**Parameter:**

| Parameter           | Typ        | Standard             | Beschreibung                                            |
| ------------------- | ---------- | -------------------- | ------------------------------------------------------- |
| `protectedBranches` | `string[]` | `["main", "master"]` | Branch-Namen, auf die nicht direkt gepusht werden darf. |

**Beispiel:**

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

<Tip>
  Um das Pushen auf alle Branches zu erlauben (wodurch diese Richtlinie effektiv deaktiviert wird, ohne sie aus `enabledPolicies` zu entfernen), setzen Sie `protectedBranches: []`.
</Tip>

***

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

**Ereignis:** PreToolUse (Bash)\
**Standard:** Verweigert `git commit`, `git merge`, `git rebase` und `git cherry-pick`, wenn sich der Working Tree auf `main` oder `master` befindet. Branch-Erstellung und -Wechsel (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) sind nicht betroffen.

**Parameter:**

| Parameter           | Typ        | Standard             | Beschreibung                                                             |
| ------------------- | ---------- | -------------------- | ------------------------------------------------------------------------ |
| `protectedBranches` | `string[]` | `["main", "master"]` | Branch-Namen, auf denen commit/merge/rebase/cherry-pick verweigert wird. |

***

### `block-force-push`

**Ereignis:** PreToolUse (Bash)\
**Standard:** Verweigert `git push --force` und `git push -f`.

Keine richtlinienspezifischen Parameter. Verwenden Sie den übergreifenden [`hint`](/de/configuration#hint-cross-cutting), um Alternativen vorzuschlagen:

```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`

**Ereignis:** PreToolUse (Bash)\
**Standard:** Weist Claude an, vorsichtig vorzugehen, wenn `git commit --amend` ausgeführt wird. Blockiert den Befehl nicht.

Keine Parameter.

***

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

**Ereignis:** PreToolUse (Bash)\
**Standard:** Weist Claude an, vor der Ausführung von `git stash drop` zu bestätigen. Blockiert den Befehl nicht.

Keine Parameter.

***

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

**Ereignis:** PreToolUse (Bash)\
**Standard:** Weist Claude an, zu überprüfen, was es staged, wenn es `git add -A` oder `git add .` ausführt. Blockiert den Befehl nicht.

Keine Parameter.

***

## Datenbank

Fängt destruktive SQL-Operationen ab, bevor sie gegen Ihre Datenbank ausgeführt werden.

### `warn-destructive-sql`

**Ereignis:** PreToolUse (Bash)\
**Standard:** Weist Claude an, vor der Ausführung von SQL mit `DROP TABLE`, `DROP DATABASE` oder `DELETE` ohne `WHERE`-Klausel zu bestätigen.

Keine Parameter.

***

### `warn-schema-alteration`

**Ereignis:** PreToolUse (Bash)\
**Standard:** Weist Claude an, vor der Ausführung von `ALTER TABLE`-Anweisungen zu bestätigen.

Keine Parameter.

***

## Warnungen

Gibt Agenten zusätzlichen Kontext vor potenziell riskanten, aber nicht destruktiven Operationen.

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

**Ereignis:** PreToolUse (Write)\
**Standard:** Weist Claude an, vor dem Schreiben von Dateien größer als 1024 KB zu bestätigen.

**Parameter:**

| Parameter     | Typ      | Standard | Beschreibung                                                 |
| ------------- | -------- | -------- | ------------------------------------------------------------ |
| `thresholdKb` | `number` | `1024`   | Dateigröße in Kilobyte, ab der eine Warnung ausgegeben wird. |

**Beispiel:**

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

<Note>
  Der Hook-Handler erzwingt ein stdin-Limit von 1 MB für Payloads. Um diese Richtlinie mit kleinen Inhalten zu testen, setzen Sie `thresholdKb` auf einen Wert deutlich unter 1024.
</Note>

***

### `warn-package-publish`

**Ereignis:** PreToolUse (Bash)\
**Standard:** Weist Claude an, vor der Ausführung von `npm publish` zu bestätigen.

Keine Parameter.

***

### `warn-background-process`

**Ereignis:** PreToolUse (Bash)\
**Standard:** Weist Claude an, vorsichtig zu sein, wenn Hintergrundprozesse über `nohup`, `&`, `disown` oder `screen` gestartet werden.

Keine Parameter.

***

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

**Ereignis:** PreToolUse (Bash)\
**Standard:** Weist Claude an, vor der Ausführung von `npm install -g`, `yarn global add` oder `pip install` ohne virtuelle Umgebung zu bestätigen.

Keine Parameter.

***

## Paketmanager

Legt fest, welche Paketmanager der Agent verwenden darf.

### `prefer-package-manager`

**Ereignis:** PreToolUse (Bash)\
**Standard:** Deaktiviert. Wenn aktiviert, blockiert alle Paketmanager-Befehle, die nicht in der `allowed`-Liste stehen, und teilt Claude mit, den Befehl mit einem erlaubten Manager umzuschreiben.

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

| Parameter | Typ       | Standard | Beschreibung                                                                                                                                     |
| --------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `allowed` | string\[] | `[]`     | Erlaubte Paketmanager-Namen. Jeder erkannte Manager, der nicht in dieser Liste steht, wird blockiert. Wenn leer, ist die Richtlinie wirkungslos. |
| `blocked` | string\[] | `[]`     | Zusätzliche Manager-Namen, die über die integrierte Liste hinaus blockiert werden sollen (z.B. `['pdm', 'pipx']`).                               |

Die integrierte Blockliste umfasst: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Verwenden Sie `blocked`, um Manager hinzuzufügen, die nicht in dieser Liste sind.

**Beispielkonfiguration:**

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

Mit dieser Konfiguration werden `pip install flask` und `pdm install flask` beide verweigert, mit einer Nachricht, die Claude auffordert, stattdessen `uv` oder `bun` zu verwenden. Befehle wie `uv pip install flask` sind erlaubt, da `uv` in der Allowlist steht und zuerst geprüft wird.

***

## KI-Verhalten

Erkennt, wenn Agenten stecken bleiben oder sich unerwartet verhalten.

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

**Ereignis:** PreToolUse (alle Tools)\
**Standard:** Weist Claude an, seine Vorgehensweise zu überdenken, wenn dasselbe Tool drei oder mehr Mal mit identischen Parametern aufgerufen wird — ein häufiges Zeichen dafür, dass der Agent in einer Schleife steckt.

Keine Parameter.

***

## Workflow

Erzwingt einen disziplinierten Workflow am Sitzungsende. Diese Richtlinien werden beim **Stop**-Ereignis ausgelöst und verhindern, dass der Agent anhält, bis jede Bedingung erfüllt ist. Sie folgen einer natürlichen Abhängigkeitskette: Commit → Push → PR → CI. Wenn eine Richtlinie verweigert, werden spätere Richtlinien in der Kette übersprungen (Deny bricht ab).

Alle Workflow-Richtlinien sind **fail-open**: Wenn das erforderliche Tool nicht verfügbar ist (z.B. `gh` nicht installiert, kein git-Remote), erlaubt die Richtlinie mit einer informativen Nachricht, die erklärt, warum die Prüfung übersprungen wurde.

### Stop-Semantik je CLI

Die Stop-Durchsetzung sieht bei den sechs unterstützten CLIs etwas unterschiedlich aus, da jede eine andere Vertragsgestaltung für den Hook „Agent fertig" bietet. Das **Ergebnis** ist dasselbe — der Agent kommt nicht damit durch, anzuhalten, während ein Workflow-Gate fehlschlägt — aber die **Mechanik** unterscheidet sich. Die folgende Tabelle fasst dies zusammen; nur Pi hat eine für Benutzer sichtbare Besonderheit, die Sie verstehen sollten, bevor Sie eine `require-*-before-stop`-Richtlinie aktivieren.

| CLI                      | Wann das Gate auslöst           | Was Sie sehen                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------ | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Claude Code              | Gleiche Agentenschleife, sofort | Claude arbeitet weiter — behebt das Problem, versucht dann erneut zu beenden. Für Sie keine sichtbare Unterbrechung.                                                                                                                                                                                                                                                                                             |
| Codex                    | Gleiche Agentenschleife, sofort | Wie Claude.                                                                                                                                                                                                                                                                                                                                                                                                      |
| GitHub Copilot CLI       | Gleiche Agentenschleife, sofort | Wie Claude (verwendet Copilots `{decision:"block", reason}`-Wiederholungskanal — empirisch verifiziert gegen Copilot CLI 1.0.41).                                                                                                                                                                                                                                                                                |
| Cursor Agent             | Gleiche Agentenschleife, sofort | Wie Claude (verwendet Cursors `{followup_message}`-Kanal — begrenzt auf `loop_limit`, standardmäßig 5 Wiederholungen).                                                                                                                                                                                                                                                                                           |
| OpenCode                 | Gleiche Agentenschleife, sofort | Wie Claude (verwendet OpenCodes `client.session.prompt(...)`-SDK-Aufruf, der über `hookSpecificOutput.additionalContext` geleitet wird).                                                                                                                                                                                                                                                                         |
| **Pi (pi-coding-agent)** | **Nächster Benutzerturn**       | **Pi hält sichtbar an**, wenn das Gate auslöst — seine Agentenschleife beendet sich und Sie gelangen zurück zur Eingabeaufforderung. Das Gate löst dann beim nächsten Absenden einer Eingabe aus: failproofai stellt eine `MANDATORY ACTION REQUIRED`-Direktive an den Systempromt dieses Turns voran und weist das LLM an, den Workflow-Schritt (Commit, Push usw.) abzuschließen, bevor es das Gewünschte tut. |

<Note>
  **Pi-Einschränkung.** Pis `AgentEndEvent` (das Upstream-Äquivalent zu Claudes `Stop`-Hook) hat keinen Result-Typ — wenn er auslöst, hat Pis Agentenschleife bereits beendet. Pi kann nicht dazu gezwungen werden, dieselbe Schleife zu wiederholen, wie es Claude / Copilot / Cursor / OpenCode können. failproofai verlagert das Gate auf Pis `before_agent_start`-Ereignis (das nach der nächsten Benutzereingabe auslöst), sodass die Workflow-Prüfung trotzdem greift, nur beim nächsten Turn statt beim aktuellen.

  **Was das in der Praxis bedeutet:**

  * Nachdem Pi anhält, wird der Ablehnungsgrund im Speicher gespeichert, indexiert nach Pi-Sitzungs-ID. Die nächste Eingabe, die Sie im selben Pi-Prozess absenden, entleert ihn: Das LLM sieht die `MANDATORY ACTION REQUIRED`-Direktive am Anfang seines Systemprompts, führt einen Commit durch (oder Push / öffnet den PR / wartet auf CI) und fährt erst dann mit Ihrer Anfrage fort. Der gespeicherte Ablehnungsgrund ist einmalig — sobald entleert, ist das Gate frei.
  * Das Gate ist durch die Prozesslebensdauer von Pi begrenzt. Wenn Sie Pi zwischen den Turns mit `Ctrl+C` beenden oder schließen, wird der In-Memory-Eintrag zusammen mit dem Prozess gelöscht und das Gate wird verfehlt. Claude, Copilot, Cursor und OpenCode haben dieselbe Einschränkung (Agent beenden und das Gate wird verfehlt) — bei Pi ist es nur sichtbarer, weil der Agent sichtbar beendet wird, bevor das Gate auslöst.
  * Ein ausstehender Deny wird auch bei `session_shutdown` aus beliebigem Grund (`new` / `resume` / `fork` / `quit`) gelöscht, sodass ein veraltetes Gate einer vorherigen Sitzung nicht in eine neue Sitzung überlaufen kann, die im selben Pi-Prozess gestartet wurde.

  Wenn Sie das Claude-ähnliche Wiederholen in derselben Schleife benötigen, führen Sie Ihre `Stop`-Richtlinien unter einer der anderen fünf unterstützten CLIs aus. Wir verfolgen Pi upstream auf einen zukünftigen Result-Typ bei `AgentEndEvent`, der es uns ermöglichen würde, diese Lücke zu schließen.
</Note>

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

**Ereignis:** Stop\
**Standard:** Verweigert das Anhalten, wenn nicht committete Änderungen vorhanden sind (geänderte, gestagete oder nicht verfolgte Dateien). Gibt eine informative Nachricht zurück, wenn das Arbeitsverzeichnis sauber ist.

Keine Parameter.

***

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

**Ereignis:** Stop\
**Standard:** Verweigert das Anhalten, wenn nicht gepushte Commits vorhanden sind oder wenn der aktuelle Branch keinen Remote-Tracking-Branch hat. Schlägt bei Bedarf `git push -u` vor, um einen Tracking-Branch zu erstellen. Fail-open, wenn kein Remote konfiguriert ist.

**Parameter:**

| Parameter | Typ      | Standard   | Beschreibung                      |
| --------- | -------- | ---------- | --------------------------------- |
| `remote`  | `string` | `"origin"` | Remote-Name, zu dem gepusht wird. |

**Beispiel:**

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

***

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

**Ereignis:** Stop\
**Standard:** Verweigert das Anhalten, wenn kein Pull Request für den aktuellen Branch existiert oder wenn der vorhandene PR ohne Merge geschlossen wurde. Weist Claude an, einen PR mit `gh pr create` zu erstellen. Wenn der PR **gemergt** wurde, erlaubt die Richtlinie (die Arbeit ist ausgeliefert) und die Nachricht gibt den Hinweis, den Branch zu wechseln (`git checkout main && git pull`).

Keine Parameter.

<Note>
  Diese Richtlinie erfordert die Installation und Authentifizierung von [GitHub CLI](https://cli.github.com/) (`gh`).
  Führen Sie `gh auth login` mit einem persönlichen Zugriffstoken aus, das den `repo`-Scope für Lesezugriff auf
  Pull Requests hat. Wenn `gh` nicht installiert oder nicht authentifiziert ist, ist die Richtlinie fail-open und meldet den Grund an Claude.
</Note>

***

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

**Ereignis:** Stop\
**Standard:** Verweigert das Anhalten, wenn der aktuelle Branch nicht konfliktfrei in den Basis-Branch gemergt werden kann. Die Richtlinie bestätigt zunächst, dass für den Branch ein `OPEN`-PR auf GitHub vorhanden ist — ohne einen solchen gibt es kein Merge-Ziel zum Erzwingen, sodass die gesamte Richtlinie allow zurückgibt. Sobald ein `OPEN`-PR bestätigt wurde, laufen zwei unabhängige Prüfungen:

1. **Lokal** — `git merge-tree --write-tree --name-only origin/<baseBranch> HEAD`. Bei einem Konflikt nennt die Deny-Nachricht die konfliktbehafteten Dateien, damit Claude genau weiß, was zu lösen ist.
2. **GitHub** — verwendet das bereits beim Vorcheck abgerufene `gh pr view --json mergeable,state`-Ergebnis erneut. Fängt Konflikte ab, die ein veraltetes lokales `origin/<baseBranch>` übersehen würde (z.B. wenn jemand einen konfliktbehafteten PR auf `main` seit dem letzten Fetch gemergt hat). Ein `CONFLICTING`-Ergebnis verweigert. Ein `UNKNOWN`-Ergebnis verweigert ebenfalls und weist Claude an, etwa 10 Sekunden zu warten und erneut zu prüfen, bevor ein erneuter Stoppversuch unternommen wird — dies verhindert falsche Negative, während GitHub neu berechnet.

Überspringt vollständig (erlaubt), wenn: `gh` nicht installiert ist, kein PR für den Branch vorhanden ist, der PR-Status nicht `OPEN` ist (z.B. `MERGED`, `CLOSED`), oder `gh pr view` nicht parsbare Ausgabe liefert. Fail-open auch wenn `origin/<baseBranch>` lokal fehlt oder wenn keine Commits vor dem Basis-Branch vorhanden sind — diese Layer-1-Durchfälle konsultieren trotzdem die zwischengespeicherte PR-Zusammenführbarkeit, bevor sie erlauben.

**Parameter:**

| Parameter    | Typ      | Standard | Beschreibung                                        |
| ------------ | -------- | -------- | --------------------------------------------------- |
| `baseBranch` | `string` | `"main"` | Basis-Branch, gegen den auf Konflikte geprüft wird. |

<Note>
  GitHub CLI (`gh`) ist für diese Richtlinie erforderlich. Die Richtlinie verwendet `gh pr view`, um zu bestätigen,
  dass ein `OPEN`-PR vorhanden ist, bevor eine Konfliktprüfung durchgeführt wird — ohne `gh` gibt die Richtlinie
  allow zurück. Führen Sie `gh auth login` mit einem persönlichen Zugriffstoken aus, das den `repo`-Scope für Lesezugriff auf Pull Requests hat.
</Note>

***

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

**Ereignis:** Stop\
**Standard:** Verweigert das Anhalten, wenn CI-Prüfungen fehlschlagen oder auf dem aktuellen Branch noch ausgeführt werden. Prüft sowohl GitHub Actions-Workflow-Runs als auch Drittanbieter-Bot-Prüfungen (z.B. CodeRabbit, SonarCloud, Codecov). Behandelt `skipped`-, `cancelled`- und `neutral`-Abschlüsse als nicht fehlerhaft (letzteres deckt z.B. Socket Security-Meldungen bei PRs externer Mitwirkender ab, bei denen die App absichtlich neutral statt success/failure meldet). Gibt eine informative Nachricht zurück, wenn alle Prüfungen bestanden sind.

Keine Parameter.

<Note>
  Diese Richtlinie erfordert die Installation und Authentifizierung von [GitHub CLI](https://cli.github.com/) (`gh`).
  Führen Sie `gh auth login` mit einem persönlichen Zugriffstoken aus, das den `repo`-Scope für Lesezugriff auf
  Actions-Workflow-Runs und die Checks API hat. Wenn `gh` nicht installiert oder nicht authentifiziert ist, ist die Richtlinie fail-open und meldet den Grund an Claude.
</Note>

***

***

## Einzelne Richtlinien deaktivieren

Entfernen Sie eine bestimmte Richtlinie aus `enabledPolicies` in Ihrer Konfiguration, oder deaktivieren Sie sie im Dashboard-Tab „Policies".

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

Richtlinien, die nicht in `enabledPolicies` aufgeführt sind, werden nicht ausgeführt, auch wenn `policyParams`-Einträge für sie vorhanden sind.