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

# Integrierte Richtlinien

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

failproofai enthält 39 integrierte Richtlinien, die häufige Fehlerquellen von Agenten abfangen. Jede Richtlinie wird bei einem bestimmten Hook-Ereignistyp und Tool-Namen 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  |
| [Infrastrukturbefehle](#infra-commands)        | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline                                     | PreToolUse  |
| [Geheimnisse (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-`** — bereinigt sensible 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 Kollisionen, wenn Sie auch benutzerdefinierte oder Drittanbieter-Richtlinien mit ähnlichen Kurznamen laden.

In Ihrer Konfiguration können Sie auf eine integrierte Richtlinie entweder mit ihrem Kurznamen oder ihrem qualifizierten Namen verweisen; beide Formen lösen sich zur selben Richtlinie auf:

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

Enthält ein Name kein `/`, 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 handlungsorientierte Hinweise, ohne den Richtliniencode zu ändern. Funktioniert mit integrierten, benutzerdefinierten und konventionsbasierten Richtlinien. Siehe [Konfiguration → hint](/de/configuration#hint-cross-cutting) für Details.
</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 `sudo`-Schlüsselwort enthalten. Der Musterabgleich erfolgt auf geparsten Befehls-Tokens, nicht auf dem Rohstring, um Umgehungsversuche durch Shell-Operator-Injection 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 Rohbefehlsstring. Dies verhindert Umgehungsversuche durch angehängte Shell-Operatoren (z. B. `sudo systemctl status x; rm -rf /` entspricht nicht `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.

***

## Infrastrukturbefehle

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 legitim `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, es sei denn, der Befehl entspricht einem Eintrag in `allowPatterns`.

Die Mustergrammatik 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 Injection-Umgehungsversuche 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`-Aufruf (OpenTofu).

**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`-CLI-Aufruf (Google Cloud).

**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`-CLI-Aufruf (Azure).

**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 ä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 failproofais eigenem `require-ci-green-before-stop`).

**Parameter:**

| Parameter       | Typ        | Standard | Beschreibung                                                                                           |
| --------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `allowPatterns` | `string[]` | `[]`     | Bestimmte skriptierte Aufrufe, die erlaubt werden sollen, auch wenn sie andernfalls verweigert würden. |

**Beispiel:**

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

***

## Geheimnisse (Sanitizer)

Verhindert, dass Agenten Anmeldeinformationen in ihren Kontext oder ihre Ausgabe weitergeben. 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 Geheimnis-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-Schlüsselformate: 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 Geheimnisse 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 Datenbankverbindungsstrings, die eingebettete Anmeldeinformationen 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 sensible 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 sensiblen 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` (einmal 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 auch dann stabil bleibt, wenn Claude in ein Unterverzeichnis wechselt.

**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 häufig 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 (was diese Richtlinie effektiv deaktiviert, 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`, während 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 das übergreifende [`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 dem Ausführen 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

Erkennt destruktive SQL-Operationen, bevor sie gegen Ihre Datenbank ausgeführt werden.

### `warn-destructive-sql`

**Ereignis:** PreToolUse (Bash)\
**Standard:** Weist Claude an, zu bestätigen, bevor SQL ausgeführt wird, das `DROP TABLE`, `DROP DATABASE` oder `DELETE` ohne `WHERE`-Klausel enthält.

Keine Parameter.

***

### `warn-schema-alteration`

**Ereignis:** PreToolUse (Bash)\
**Standard:** Weist Claude an, zu bestätigen, bevor `ALTER TABLE`-Anweisungen ausgeführt werden.

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, zu bestätigen, bevor Dateien größer als 1024 KB geschrieben werden.

**Parameter:**

| Parameter     | Typ      | Standard | Beschreibung                                                               |
| ------------- | -------- | -------- | -------------------------------------------------------------------------- |
| `thresholdKb` | `number` | `1024`   | Dateigrößenschwellenwert in Kilobyte, ab dem 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 kleinem Inhalt zu testen, setzen Sie `thresholdKb` auf einen Wert deutlich unterhalb von 1024.
</Note>

***

### `warn-package-publish`

**Ereignis:** PreToolUse (Bash)\
**Standard:** Weist Claude an, zu bestätigen, bevor `npm publish` ausgeführt wird.

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, zu bestätigen, bevor `npm install -g`, `yarn global add` oder `pip install` ohne virtuelle Umgebung ausgeführt wird.

Keine Parameter.

***

## Paketmanager

Legt fest, welche Paketmanager der Agent verwenden darf.

### `prefer-package-manager`

**Ereignis:** PreToolUse (Bash)\
**Standard:** Deaktiviert. Wenn aktiviert, blockiert es jeden Paketmanager-Befehl, der nicht in der `allowed`-Liste steht, und weist Claude an, 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 enthalten 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 Meldung, 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 feststecken oder sich unerwartet verhalten.

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

**Ereignis:** PreToolUse (alle Tools)\
**Standard:** Weist Claude an, neu zu überlegen, wenn dasselbe Tool 3+ Mal mit identischen Parametern aufgerufen wird — ein häufiges Zeichen dafür, dass der Agent in einer Schleife feststeckt.

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 (Kurzschluss bei Verweigerung).

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 den Vorgang mit einer informativen Meldung, die erklärt, warum die Prüfung übersprungen wurde.

### Stop-Semantik je CLI

Die Stop-Durchsetzung sieht bei den sieben unterstützten CLIs etwas unterschiedlich aus, da jede eine andere Vertragsform für den Hook "Agent fertig" bereitstellt. 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 den Benutzer sichtbare Besonderheit, die es wert ist, sie zu verstehen, bevor Sie eine `require-*-before-stop`-Richtlinie aktivieren.

| CLI                      | Wann das Gate ausgelöst wird     | Was Sie sehen                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------------ | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Claude Code              | Dieselbe Agentenschleife, sofort | Claude arbeitet weiter — behebt das Problem und versucht dann erneut zu beenden. Für Sie keine sichtbare Unterbrechung.                                                                                                                                                                                                                                                                                                                                      |
| Codex                    | Dieselbe Agentenschleife, sofort | Wie bei Claude.                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| GitHub Copilot CLI       | Dieselbe Agentenschleife, sofort | Wie bei Claude (verwendet Copilots `{decision:"block", reason}`-Retry-Kanal — empirisch gegen Copilot CLI 1.0.41 verifiziert).                                                                                                                                                                                                                                                                                                                               |
| Cursor Agent             | Dieselbe Agentenschleife, sofort | Wie bei Claude (verwendet Cursors `{followup_message}`-Kanal — begrenzt durch `loop_limit`, Standard 5 Wiederholungen).                                                                                                                                                                                                                                                                                                                                      |
| Gemini CLI               | Dieselbe Agentenschleife, sofort | Wie bei Claude (verwendet Geminis `{decision:"block", reason}`-Kanal bei `AfterAgent`).                                                                                                                                                                                                                                                                                                                                                                      |
| OpenCode                 | Dieselbe Agentenschleife, sofort | Wie bei Claude (verwendet OpenCodes `client.session.prompt(...)`-SDK-Aufruf, weitergeleitet über `hookSpecificOutput.additionalContext`).                                                                                                                                                                                                                                                                                                                    |
| **Pi (pi-coding-agent)** | **Nächste Benutzerrunde**        | **Pi hält sichtbar an**, wenn das Gate ausgelöst wird — seine Agentenschleife wird beendet und Sie kehren zur Eingabeaufforderung zurück. Das Gate wird dann beim nächsten Mal ausgelöst, wenn Sie eine Eingabeaufforderung senden: failproofai stellt eine `MANDATORY ACTION REQUIRED`-Direktive an den Beginn des System-Prompts dieser Runde und weist das LLM an, den Workflow-Schritt (Commit, Push usw.) abzuschließen, bevor es das Angeforderte tut. |

<Note>
  **Pi-Einschränkung.** Pis `AgentEndEvent` (das Upstream-Äquivalent von Claudes `Stop`-Hook) hat keinen Result-Typ — wenn er ausgelöst wird, ist Pis Agentenschleife bereits beendet. Pi kann nicht gezwungen werden, dieselbe Schleife zu wiederholen, wie es Claude / Copilot / Cursor / Gemini / OpenCode können. failproofai verschiebt das Gate auf Pis `before_agent_start`-Ereignis (das nach der nächsten Benutzereingabe ausgelöst wird), damit die Workflow-Prüfung weiterhin erzwungen wird, allerdings erst in der nächsten Runde statt in der aktuellen.

  **Was das in der Praxis bedeutet:**

  * Nachdem Pi anhält, wird der Verweigerungsgrund im Arbeitsspeicher gespeichert, indexiert nach der Pi-Sitzungs-ID. Die nächste Eingabeaufforderung, die Sie in demselben Pi-Prozess senden, leert diesen Speicher: Das LLM sieht die `MANDATORY ACTION REQUIRED`-Direktive am Anfang seines System-Prompts, führt einen Commit durch (oder Push / öffnet den PR / wartet auf CI) und fährt dann erst mit Ihrer Anfrage fort. Der gespeicherte Verweigerungsgrund ist einmalig — sobald er geleert wurde, ist das Gate frei.
  * Das Gate ist an die Lebensdauer des Pi-Prozesses gebunden. Wenn Sie Pi zwischen den Runden mit `Ctrl+C` beenden oder schließen, wird der Speichereintrag zusammen mit dem Prozess verworfen und das Gate wird verpasst. Claude, Copilot, Cursor, Gemini und OpenCode haben dieselbe Einschränkung (Agent beenden und das Gate wird verpasst) — Pi macht es nur sichtbarer, weil der Agent sichtbar beendet wird, bevor das Gate ausgelöst wird.
  * Ein ausstehender Verweigerungsgrund wird auch bei `session_shutdown` aus beliebigem Grund (`new` / `resume` / `fork` / `quit`) gelöscht, sodass ein veraltetes Gate aus einer früheren Sitzung nicht in eine neue Sitzung im selben Pi-Prozess übertragen werden kann.

  Wenn Sie Claude-ähnliche Wiederholungen in derselben Schleife benötigen, führen Sie Ihre `Stop`-Richtlinien unter einer der anderen sechs 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 uncommittete Änderungen vorhanden sind (geänderte, gestagete oder nicht verfolgte Dateien). Gibt eine informative Meldung zurück, wenn das Arbeitsverzeichnis sauber ist.

Keine Parameter.

***

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

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

**Parameter:**

| Parameter | Typ      | Standard   | Beschreibung                              |
| --------- | -------- | ---------- | ----------------------------------------- |
| `remote`  | `string` | `"origin"` | Remote-Name, auf den gepusht werden soll. |

**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** ist, erlaubt die Richtlinie den Vorgang (die Arbeit ist ausgeliefert) und der Hinweis empfiehlt, den Branch zu wechseln (`git checkout main && git pull`).

Keine Parameter.

<Note>
  Diese Richtlinie erfordert, dass [GitHub CLI](https://cli.github.com/) (`gh`) installiert und authentifiziert ist.
  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, schlägt die Richtlinie offen fehl und meldet den Grund an Claude.
</Note>

***

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

**Ereignis:** Stop\
**Standard:** Verweigert das Anhalten, wenn der aktuelle Branch nicht sauber in den Basis-Branch gemergt werden kann. Die Richtlinie prüft zunächst, ob auf GitHub ein `OPEN`-PR für den Branch existiert — ohne einen solchen gibt es kein Merge-Ziel, das erzwungen werden müsste, sodass die gesamte Richtlinie mit allow kurzgeschlossen wird. Sobald ein `OPEN`-PR bestätigt ist, werden zwei unabhängige Prüfungen durchgeführt:

1. **Lokal** — `git merge-tree --write-tree --name-only origin/<baseBranch> HEAD`. Bei einem Konflikt nennt die Verweigerungsmeldung die betroffenen Dateien, damit Claude genau weiß, was aufgelöst werden muss.
2. **GitHub** — verwendet das bereits für die Vorprüfung abgerufene Ergebnis von `gh pr view --json mergeable,state`. Erkennt Konflikte, die ein veraltetes lokales `origin/<baseBranch>` verpasst hätte (z. B. wenn jemand einen konfliktierenden PR auf `main` gemergt hat, seit dem letzten Fetch). 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 weiterer Stoppversuch unternommen wird — dies verhindert falsch-negative Ergebnisse, während GitHub neu berechnet.

Wird vollständig übersprungen (erlaubt), wenn: `gh` nicht installiert ist, kein PR für den Branch existiert, der PR-Status nicht `OPEN` ist (z. B. `MERGED`, `CLOSED`), oder `gh pr view` nicht parsierbare Ausgabe liefert. Schlägt auch offen fehl, wenn `origin/<baseBranch>` lokal fehlt oder wenn keine Commits vor der Basis vorhanden sind — diese Layer-1-Fallbacks konsultieren trotzdem die gecachte PR-Merge-Fähigkeit, 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 existiert, bevor eine Konfliktprüfung durchgeführt wird — ohne `gh` schließt die Richtlinie mit allow kurz. 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 laufen. Prüft sowohl GitHub Actions-Workflow-Runs als auch Drittanbieter-Bot-Prüfungen (z. B. CodeRabbit, SonarCloud, Codecov). Behandelt `skipped`, `cancelled` und `neutral` als nicht fehlgeschlagen (letzteres deckt z. B. Socket Security-Warnungen bei PRs externer Mitwirkender ab, bei denen die App absichtlich neutral statt Erfolg/Fehler meldet). Gibt eine informative Meldung zurück, wenn alle Prüfungen bestanden sind.

Keine Parameter.

<Note>
  Diese Richtlinie erfordert, dass [GitHub CLI](https://cli.github.com/) (`gh`) installiert und authentifiziert ist.
  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, schlägt die Richtlinie offen fehl 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 Richtlinien.

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