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

# Politiche Built-in

> Tutte le 39 politiche built-in che rilevano i modalità di fallimento comuni degli agent

failproofai viene fornito con 39 politiche built-in che rilevano le modalità di fallimento comuni degli agent. Ogni politica si attiva su un tipo di evento hook specifico e su un nome di strumento. Diciannove politiche accettano parametri che ti permettono di regolarne il comportamento senza scrivere codice. Cinque politiche di workflow impongono una pipeline commit → push → PR → CI prima che Claude si fermi.

***

## Panoramica

Le politiche sono raggruppate in categorie:

| Categoria                                     | Politiche                                                                                                                                    | Tipo di hook |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| [Comandi pericolosi](#comandi-pericolosi)     | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands                                                                      | PreToolUse   |
| [Comandi infra](#comandi-infra)               | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline                                     | PreToolUse   |
| [Secrets (sanitizer)](#secrets-sanitizer)     | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens                           | PostToolUse  |
| [Ambiente](#ambiente)                         | block-env-files, protect-env-vars                                                                                                            | PreToolUse   |
| [Accesso ai file](#accesso-ai-file)           | 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   |
| [Database](#database)                         | warn-destructive-sql, warn-schema-alteration                                                                                                 | PreToolUse   |
| [Avvisi](#avvisi)                             | warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install                                            | PreToolUse   |
| [Gestori di pacchetti](#gestori-di-pacchetti) | 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-`** — ferma l'agent dal procedere.
* **`warn-`** — fornisce all'agent contesto aggiuntivo per l'auto-correzione.
* **`sanitize-`** — rimuove dati sensibili dall'output dello strumento prima che l'agent li veda.

### Spazi dei nomi

Ogni politica risiede in uno slot `<namespace>/<name>`. Le politiche built-in appartengono allo spazio dei nomi **`failproofai/`** — ad esempio, `failproofai/sanitize-jwt`. Lo spazio dei nomi previene collisioni quando carichi anche politiche personalizzate o di terze parti con nomi brevi simili.

Nella tua configurazione puoi fare riferimento a una politica built-in utilizzando sia il suo nome breve che il suo nome qualificato; entrambi i moduli si risolvono nella stessa politica:

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

Se un nome non contiene `/`, failproofai lo tratta come appartenente allo spazio dei nomi predefinito `failproofai`. I nomi che già contengono un `/` (ad es. `myorg/foo`, `custom/my-hook`) vengono mantenuti così come sono.

* **`require-`** — blocca l'evento Stop finché le condizioni non sono soddisfatte.

***

<Tip>
  Ogni politica supporta un campo `hint` opzionale in `policyParams`. L'hint viene aggiunto al messaggio deny o instruct che Claude vede, fornendo una guida concreta senza modificare il codice della politica. Funziona con politiche built-in, personalizzate e di convenzione. Vedi [Configurazione → hint](/it/configuration#hint-cross-cutting) per i dettagli.
</Tip>

***

## Comandi pericolosi

Previeni che gli agent eseguano operazioni difficili da annullare o che potrebbero danneggiare il sistema host.

### `block-sudo`

**Evento:** PreToolUse (Bash)\
**Predefinito:** Nega qualsiasi comando `sudo`.

Blocca le invocazioni che includono la parola chiave `sudo`. La ricerca di modelli viene eseguita sui token di comando analizzati, non sulla stringa grezza, per prevenire bypass tramite iniezione di operatori shell.

**Parametri:**

| Parametro       | Tipo       | Predefinito | Descrizione                                                                                     |
| --------------- | ---------- | ----------- | ----------------------------------------------------------------------------------------------- |
| `allowPatterns` | `string[]` | `[]`        | Prefissi di comando esatti consentiti. Ogni voce viene confrontata con i token argv analizzati. |

**Esempio:**

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

Con questa configurazione, `sudo systemctl status nginx` è consentito, ma `sudo rm /etc/hosts` è negato.

<Note>
  I modelli vengono confrontati con token analizzati, non con la stringa di comando grezza. Questo previene bypass tramite operatori shell aggiunti (ad es. `sudo systemctl status x; rm -rf /` non corrisponde a `sudo systemctl status *`).
</Note>

***

### `block-rm-rf`

**Evento:** PreToolUse (Bash)\
**Predefinito:** Nega `rm -rf`, `rm -fr` e forme di eliminazione ricorsiva simili.

**Parametri:**

| Parametro    | Tipo       | Predefinito | Descrizione                                                   |
| ------------ | ---------- | ----------- | ------------------------------------------------------------- |
| `allowPaths` | `string[]` | `[]`        | Percorsi sicuri per l'eliminazione ricorsiva (ad es. `/tmp`). |

**Esempio:**

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

***

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

**Evento:** PreToolUse (Bash)\
**Predefinito:** Nega `curl <url> | bash`, `curl <url> | sh`, `wget <url> | bash` e modelli simili.

Nessun parametro.

***

### `block-failproofai-commands`

**Evento:** PreToolUse (Bash)\
**Predefinito:** Nega i comandi che disinstallerebbero o disabiliterebbero failproofai stesso (ad es. `npm uninstall failproofai`, `failproofai policies --uninstall`).

Nessun parametro.

***

## Comandi infra

Interrompi gli agent di codifica dall'esecuzione di CLI infrastrutturali o dall'attivazione di pipeline CI/CD. Tutte le politiche in questa categoria sono **opt-in** (`defaultEnabled: false`) — gli agent che legittimamente necessitano di chiamare `kubectl`, `terraform`, ecc. non saranno disturbati a meno che tu non abiliti la politica. Quando abilitata, ogni invocazione della CLI corrispondente è negata a meno che il comando non corrisponda a una voce in `allowPatterns`.

La grammatica del modello è la stessa di [`block-sudo`](#block-sudo): i token vengono confrontati con argv analizzato, `*` è un wildcard per un token e qualsiasi comando contenente un operatore shell autonomo (`&&`, `||`, `|`, `;`) o un token con metacaratteri shell incorporati viene rifiutato prima della ricerca di allowlist per prevenire bypass di iniezione.

### `block-kubectl`

**Evento:** PreToolUse (Bash)\
**Predefinito:** Nega qualsiasi invocazione `kubectl`.

**Parametri:**

| Parametro       | Tipo       | Predefinito | Descrizione                             |
| --------------- | ---------- | ----------- | --------------------------------------- |
| `allowPatterns` | `string[]` | `[]`        | Prefissi di comando kubectl consentiti. |

**Esempio:**

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

Con questa configurazione, `kubectl get pods` è consentito ma `kubectl apply -f deploy.yaml` è negato.

***

### `block-terraform`

**Evento:** PreToolUse (Bash)\
**Predefinito:** Nega qualsiasi invocazione `terraform` o `tofu` (OpenTofu).

**Parametri:**

| Parametro       | Tipo       | Predefinito | Descrizione                                    |
| --------------- | ---------- | ----------- | ---------------------------------------------- |
| `allowPatterns` | `string[]` | `[]`        | Prefissi di comando terraform/tofu consentiti. |

**Esempio:**

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

***

### `block-aws-cli`

**Evento:** PreToolUse (Bash)\
**Predefinito:** Nega qualsiasi invocazione della CLI `aws`.

**Parametri:**

| Parametro       | Tipo       | Predefinito | Descrizione                             |
| --------------- | ---------- | ----------- | --------------------------------------- |
| `allowPatterns` | `string[]` | `[]`        | Prefissi di comando CLI aws consentiti. |

**Esempio:**

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

***

### `block-gcloud`

**Evento:** PreToolUse (Bash)\
**Predefinito:** Nega qualsiasi invocazione della CLI `gcloud` (Google Cloud).

**Parametri:**

| Parametro       | Tipo       | Predefinito | Descrizione                            |
| --------------- | ---------- | ----------- | -------------------------------------- |
| `allowPatterns` | `string[]` | `[]`        | Prefissi di comando gcloud consentiti. |

**Esempio:**

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

***

### `block-az-cli`

**Evento:** PreToolUse (Bash)\
**Predefinito:** Nega qualsiasi invocazione della CLI `az` (Azure).

**Parametri:**

| Parametro       | Tipo       | Predefinito | Descrizione                            |
| --------------- | ---------- | ----------- | -------------------------------------- |
| `allowPatterns` | `string[]` | `[]`        | Prefissi di comando CLI az consentiti. |

**Esempio:**

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

***

### `block-helm`

**Evento:** PreToolUse (Bash)\
**Predefinito:** Nega qualsiasi invocazione `helm`.

**Parametri:**

| Parametro       | Tipo       | Predefinito | Descrizione                          |
| --------------- | ---------- | ----------- | ------------------------------------ |
| `allowPatterns` | `string[]` | `[]`        | Prefissi di comando helm consentiti. |

**Esempio:**

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

***

### `block-gh-pipeline`

**Evento:** PreToolUse (Bash)\
**Predefinito:** Nega i seguenti sottocoman `gh` che mutano lo stato o attivano pipeline:

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

I sottocomandi `gh` di sola lettura come `gh pr view`, `gh pr list`, `gh run list`, `gh release view` e `gh api repos/.../...` **non** vengono corrisposti da questa politica — sono regolarmente necessari per i controlli di workflow (incluso il `require-ci-green-before-stop` di failproofai).

**Parametri:**

| Parametro       | Tipo       | Predefinito | Descrizione                                                                          |
| --------------- | ---------- | ----------- | ------------------------------------------------------------------------------------ |
| `allowPatterns` | `string[]` | `[]`        | Invocazioni scritte specifiche da consentire nonostante sarebbero altrimenti negate. |

**Esempio:**

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

***

## Secrets (sanitizer)

Interrompi gli agent dal leaking di credenziali nel loro contesto o output. Le politiche sanitizer si attivano su eventi **PostToolUse**. Quando Claude esegue un comando Bash, legge un file o chiama qualsiasi strumento, queste politiche ispezionano l'output prima che venga restituito a Claude. Se viene rilevato un modello di secret, la politica restituisce una decisione deny che impedisce all'output di essere passato indietro.

### `sanitize-jwt`

**Evento:** PostToolUse (tutti gli strumenti)\
**Predefinito:** Nasconde i token JWT (tre segmenti base64url separati da `.`).

Nessun parametro.

***

### `sanitize-api-keys`

**Evento:** PostToolUse (tutti gli strumenti)\
**Predefinito:** Nasconde i formati comuni di chiavi API: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), chiavi di accesso AWS (`AKIA`), chiavi Stripe (`sk_live_`, `sk_test_`) e chiavi API Google (`AIza`).

**Parametri:**

| Parametro            | Tipo                                 | Predefinito | Descrizione                                       |
| -------------------- | ------------------------------------ | ----------- | ------------------------------------------------- |
| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]`        | Modelli regex aggiuntivi da trattare come secret. |

**Esempio:**

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

**Evento:** PostToolUse (tutti gli strumenti)\
**Predefinito:** Nasconde le stringhe di connessione al database che contengono credenziali incorporate (ad es. `postgresql://user:password@host/db`).

Nessun parametro.

***

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

**Evento:** PostToolUse (tutti gli strumenti)\
**Predefinito:** Nasconde i blocchi PEM (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, ecc.).

Nessun parametro.

***

### `sanitize-bearer-tokens`

**Evento:** PostToolUse (tutti gli strumenti)\
**Predefinito:** Nasconde le intestazioni `Authorization: Bearer <token>` dove il token è di 20 o più caratteri.

Nessun parametro.

***

## Ambiente

Proteggi la configurazione dell'ambiente sensibile dalla lettura o dall'esposizione da parte degli agent.

### `block-env-files`

**Evento:** PreToolUse (Bash, Read)\
**Predefinito:** Nega la lettura di file `.env` tramite `cat .env`, chiamate dello strumento Read con `.env` come percorso del file, ecc.

Non blocca `.envrc` o altri file adiacenti all'ambiente — solo i file denominati esattamente `.env`.

Nessun parametro.

***

### `protect-env-vars`

**Evento:** PreToolUse (Bash)\
**Predefinito:** Nega i comandi che stampano variabili di ambiente: `printenv`, `env`, `echo $VAR`.

Nessun parametro.

***

## Accesso ai file

Mantieni gli agent che lavorano all'interno dei confini del progetto e lontani da file sensibili.

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

**Evento:** PreToolUse (Read, Bash)\
**Predefinito:** Nega la lettura di file al di fuori della radice del progetto. Il confine è `CLAUDE_PROJECT_DIR` (impostato una volta per sessione da Claude Code), con un fallback alla directory di lavoro corrente della sessione quando quella variabile non è impostata. L'utilizzo della radice del progetto piuttosto che il `cwd` live significa che il confine rimane stabile anche dopo che Claude si sposta in una sottodirectory.

**Parametri:**

| Parametro    | Tipo       | Predefinito | Descrizione                                                                              |
| ------------ | ---------- | ----------- | ---------------------------------------------------------------------------------------- |
| `allowPaths` | `string[]` | `[]`        | Prefissi di percorso assoluto consentiti anche se al di fuori della radice del progetto. |

**Esempio:**

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

***

### `block-secrets-write`

**Evento:** PreToolUse (Write, Edit)\
**Predefinito:** Nega le scritture su file comunemente utilizzati per chiavi private e certificati: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`.

**Parametri:**

| Parametro            | Tipo       | Predefinito | Descrizione                                               |
| -------------------- | ---------- | ----------- | --------------------------------------------------------- |
| `additionalPatterns` | `string[]` | `[]`        | Modelli di nome file aggiuntivi (stile glob) da bloccare. |

**Esempio:**

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

***

## Git

Previeni i push accidentali, force-push e errori di branch difficili da annullare.

### `block-push-master`

**Evento:** PreToolUse (Bash)\
**Predefinito:** Nega `git push origin main` e `git push origin master`.

**Parametri:**

| Parametro           | Tipo       | Predefinito          | Descrizione                                              |
| ------------------- | ---------- | -------------------- | -------------------------------------------------------- |
| `protectedBranches` | `string[]` | `["main", "master"]` | Nomi di branch che non possono essere push direttamente. |

**Esempio:**

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

<Tip>
  Per consentire il push su tutti i branch (disabilitando effettivamente questa politica senza rimuoverla da `enabledPolicies`), imposta `protectedBranches: []`.
</Tip>

***

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

**Evento:** PreToolUse (Bash)\
**Predefinito:** Nega `git commit`, `git merge`, `git rebase` e `git cherry-pick` mentre l'albero di lavoro è su `main` o `master`. La creazione e il cambio di branch (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) non sono interessati.

**Parametri:**

| Parametro           | Tipo       | Predefinito          | Descrizione                                                     |
| ------------------- | ---------- | -------------------- | --------------------------------------------------------------- |
| `protectedBranches` | `string[]` | `["main", "master"]` | Nomi di branch su cui commit/merge/rebase/cherry-pick è negato. |

***

### `block-force-push`

**Evento:** PreToolUse (Bash)\
**Predefinito:** Nega `git push --force` e `git push -f`.

Nessun parametro specifico della politica. Usa il [`hint`](/it/configuration#hint-cross-cutting) trasversale per suggerire alternative:

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

**Evento:** PreToolUse (Bash)\
**Predefinito:** Istruisce Claude a procedere con cautela quando esegue `git commit --amend`. Non blocca il comando.

Nessun parametro.

***

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

**Evento:** PreToolUse (Bash)\
**Predefinito:** Istruisce Claude a confermare prima di eseguire `git stash drop`. Non blocca il comando.

Nessun parametro.

***

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

**Evento:** PreToolUse (Bash)\
**Predefinito:** Istruisce Claude a revisionare quello che sta mettendo in stage quando esegue `git add -A` o `git add .`. Non blocca il comando.

Nessun parametro.

***

## Database

Cattura le operazioni SQL distruttive prima che vengano eseguite sul tuo database.

### `warn-destructive-sql`

**Evento:** PreToolUse (Bash)\
**Predefinito:** Istruisce Claude a confermare prima di eseguire SQL contenente `DROP TABLE`, `DROP DATABASE` o `DELETE` senza una clausola `WHERE`.

Nessun parametro.

***

### `warn-schema-alteration`

**Evento:** PreToolUse (Bash)\
**Predefinito:** Istruisce Claude a confermare prima di eseguire istruzioni `ALTER TABLE`.

Nessun parametro.

***

## Avvisi

Fornisci agli agent contesto aggiuntivo prima di operazioni potenzialmente rischiose ma non distruttive.

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

**Evento:** PreToolUse (Write)\
**Predefinito:** Istruisce Claude a confermare prima di scrivere file più grandi di 1024 KB.

**Parametri:**

| Parametro     | Tipo     | Predefinito | Descrizione                                                                               |
| ------------- | -------- | ----------- | ----------------------------------------------------------------------------------------- |
| `thresholdKb` | `number` | `1024`      | Soglia di dimensione del file in kilobyte al di sopra della quale viene emesso un avviso. |

**Esempio:**

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

<Note>
  Il gestore hook applica un limite stdin di 1 MB sui payload. Per testare questa politica con contenuto piccolo, imposta `thresholdKb` su un valore ben al di sotto di 1024.
</Note>

***

### `warn-package-publish`

**Evento:** PreToolUse (Bash)\
**Predefinito:** Istruisce Claude a confermare prima di eseguire `npm publish`.

Nessun parametro.

***

### `warn-background-process`

**Evento:** PreToolUse (Bash)\
**Predefinito:** Istruisce Claude a stare attento quando avvia processi in background tramite `nohup`, `&`, `disown` o `screen`.

Nessun parametro.

***

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

**Evento:** PreToolUse (Bash)\
**Predefinito:** Istruisce Claude a confermare prima di eseguire `npm install -g`, `yarn global add` o `pip install` senza un ambiente virtuale.

Nessun parametro.

***

## Gestori di pacchetti

Applica quali gestori di pacchetti l'agent è autorizzato a utilizzare.

### `prefer-package-manager`

**Evento:** PreToolUse (Bash)\
**Predefinito:** Disabilitato. Quando abilitato, blocca qualsiasi comando del gestore di pacchetti non nell'elenco `allowed` e dice a Claude di riscrivere il comando utilizzando un gestore consentito.

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

| Parametro | Tipo      | Predefinito | Descrizione                                                                                                                                     |
| --------- | --------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `allowed` | string\[] | `[]`        | Nomi dei gestori di pacchetti consentiti. Qualsiasi gestore rilevato non in questo elenco viene bloccato. Quando vuoto, la politica è un no-op. |
| `blocked` | string\[] | `[]`        | Nomi di gestori aggiuntivi da bloccare al di là dell'elenco integrato (ad es. `['pdm', 'pipx']`).                                               |

L'elenco dei blocchi integrato copre: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Usa `blocked` per aggiungere gestori non in questo elenco.

**Configurazione di esempio:**

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

Con questa configurazione, sia `pip install flask` che `pdm install flask` sono negati con un messaggio che dice a Claude di usare `uv` o `bun` invece. Comandi come `uv pip install flask` sono consentiti perché `uv` è nell'allowlist e viene verificato per primo.

***

## Comportamento dell'IA

Rileva quando gli agent rimangono bloccati o si comportano inaspettatamente.

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

**Evento:** PreToolUse (tutti gli strumenti)\
**Predefinito:** Istruisce Claude a riconsiderare quando lo stesso strumento viene chiamato 3+ volte con parametri identici — un segno comune che l'agent è bloccato in un loop.

Nessun parametro.

***

## Workflow

Applica un workflow disciplinato di fine sessione. Queste politiche si attivano sull'evento **Stop** e negano all'agent di fermarsi finché ogni condizione non è soddisfatta. Seguono una catena di dipendenze naturale: commit → push → PR → CI. Se una politica nega, le politiche successive nella catena vengono saltate (deny short-circuits).

Tutte le politiche di workflow sono **fail-open**: se lo strumento richiesto non è disponibile (ad es. `gh` non installato, nessun remote git), la politica consente con un messaggio informativo che spiega perché il controllo è stato saltato.

### Semantica Stop per CLI

L'applicazione Stop sembra leggermente diversa tra i sette CLI supportati perché ognuno espone un contratto hook di fine agent diverso. Il **risultato** è lo stesso — l'agent non se la cava fermandosi mentre un gate di workflow sta fallendo — ma la **meccanica** differisce. La tabella seguente riassume; solo Pi ha una stranezza visibile all'utente che vale la pena capire prima di abilitare una politica `require-*-before-stop`.

| CLI                      | Quando il gate si attiva               | Cosa vedi                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------------------ | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Claude Code              | Stesso loop dell'agent, immediatamente | Claude continua a lavorare — risolve il problema, quindi tenta di finire di nuovo. Nessuna interruzione visibile per te.                                                                                                                                                                                                                                                                        |
| Codex                    | Stesso loop dell'agent, immediatamente | Uguale a Claude.                                                                                                                                                                                                                                                                                                                                                                                |
| GitHub Copilot CLI       | Stesso loop dell'agent, immediatamente | Uguale a Claude (usa il canale di riprovazione `{decision:"block", reason}` di Copilot — verificato empiricamente su Copilot CLI 1.0.41).                                                                                                                                                                                                                                                       |
| Cursor Agent             | Stesso loop dell'agent, immediatamente | Uguale a Claude (usa il canale `{followup_message}` di Cursor — limitato a `loop_limit`, default 5 riprovazioni).                                                                                                                                                                                                                                                                               |
| Gemini CLI               | Stesso loop dell'agent, immediatamente | Uguale a Claude (usa il canale `{decision:"block", reason}` di Gemini su `AfterAgent`).                                                                                                                                                                                                                                                                                                         |
| OpenCode                 | Stesso loop dell'agent, immediatamente | Uguale a Claude (usa la chiamata SDK `client.session.prompt(...)` di OpenCode instradata attraverso `hookSpecificOutput.additionalContext`).                                                                                                                                                                                                                                                    |
| **Pi (pi-coding-agent)** | **Turno utente successivo**            | **Pi si ferma visibilmente** quando il gate si attiva — il suo loop dell'agent esce e sei restituito al prompt. Il gate si attiva quindi la prossima volta che invii un prompt: failproofai antepone una direttiva `MANDATORY ACTION REQUIRED` al prompt di sistema di quel turno, istruendo l'LLM a completare il passo di workflow (commit, push, ecc.) prima di fare quello che hai chiesto. |

<Note>
  **Limitazione di Pi.** L'evento `AgentEndEvent` di Pi (l'equivalente upstream dell'hook `Stop` di Claude) non ha un tipo Result — nel momento in cui si attiva, il loop dell'agent di Pi è già uscito. Pi non può essere forzato a riprovare lo stesso loop come Claude / Copilot / Cursor / Gemini / OpenCode possono. failproofai sposta il gate all'evento `before_agent_start` di Pi (che si attiva dopo il prossimo prompt utente) in modo che il controllo del workflow si applichi ancora, solo al turno successivo anziché a quello corrente.

  **Cosa significa in pratica:**

  * Dopo che Pi si ferma, il motivo di negazione viene catturato in memoria con chiave id sessione Pi. Il prossimo prompt che invii nello stesso processo Pi lo scarica: l'LLM vede la direttiva `MANDATORY ACTION REQUIRED` in cima al suo prompt di sistema, esegue il commit (o push / apre il PR / attende CI), e solo allora continua con la tua richiesta. Il motivo di negazione catturato è una tantum — una volta scaricato, il gate è libero.
  * Il gate è limitato dalla durata del processo Pi. Se fai `Ctrl+C` Pi o esci tra i turni, la voce in memoria viene eliminata insieme al processo e il gate viene saltato. Claude, Copilot, Cursor, Gemini e OpenCode hanno lo stesso limite (uccidi l'agent e il gate viene saltato) — Pi lo rende solo più visibile perché l'agent esce visibilmente prima che il gate si attivi.
  * Un deny in sospeso viene anche cancellato su `session_shutdown` per qualsiasi motivo (`new` / `resume` / `fork` / `quit`), quindi un gate stantio da una sessione precedente non può trapelare in una sessione nuova avviata nello stesso processo Pi.

  Se hai bisogno di una riprovazione dello stesso loop in stile Claude, esegui le tue politiche `Stop` in uno qualsiasi degli altri sei CLI supportati. Stiamo tracciando Pi upstream per un futuro tipo Result su `AgentEndEvent` che ci permetterebbe di chiudere questa lacuna.
</Note>

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

**Evento:** Stop\
**Predefinito:** Nega l'arresto quando ci sono modifiche non committate (file modificati, staged o non tracciati). Restituisce un messaggio informativo quando la directory di lavoro è pulita.

Nessun parametro.

***

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

**Evento:** Stop\
**Predefinito:** Nega l'arresto quando ci sono commit non push o quando il branch corrente non ha un branch remoto di tracciamento. Suggerisce `git push -u` per creare un branch di tracciamento se necessario. Fallisce open se nessun remote è configurato.

**Parametri:**

| Parametro | Tipo     | Predefinito | Descrizione                      |
| --------- | -------- | ----------- | -------------------------------- |
| `remote`  | `string` | `"origin"`  | Nome remoto su cui fare il push. |

**Esempio:**

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

***

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

**Evento:** Stop\
**Predefinito:** Nega l'arresto quando nessuna pull request esiste per il branch corrente, o quando il PR esistente è chiuso senza essere fuso. Istruisce Claude a creare un PR con `gh pr create`. Quando il PR è **fuso**, la politica consente (il lavoro è stato spedito) e il messaggio suggerisce di uscire dal branch (`git checkout main && git pull`).

Nessun parametro.

<Note>
  Questa politica richiede che [GitHub CLI](https://cli.github.com/) (`gh`) sia installato e autenticato.
  Esegui `gh auth login` con un token di accesso personale che ha scope `repo` per l'accesso in lettura alle
  pull request. Se `gh` non è installato o non autenticato, la politica fallisce open e segnala il motivo a Claude.
</Note>

***

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

**Evento:** Stop\
**Predefinito:** Nega l'arresto quando il branch corrente non può fondersi pulitamente nel branch base. La politica prima conferma che esiste un PR `OPEN` su GitHub per il branch — senza uno, non c'è un target di fusione da applicare, quindi l'intera politica short-circuits per consentire. Una volta confermato un PR `OPEN`, due sonde indipendenti vengono eseguite:

1. **Locale** — `git merge-tree --write-tree --name-only origin/<baseBranch> HEAD`. Su conflitto, il messaggio deny nomina i file in conflitto in modo che Claude sappia esattamente cosa risolvere.
2. **GitHub** — riutilizza il risultato di `gh pr view --json mergeable,state` già recuperato nel precontrollo. Cattura conflitti che un `origin/<baseBranch>` locale stantio perderebbe (ad es. qualcuno ha sbarcato un PR conflittuale su `main` da quando è stato fatto l'ultimo fetch). Un risultato `CONFLICTING` nega. Un risultato `UNKNOWN` nega anche e istruisce Claude ad aspettare \~10 secondi e ri-controllare prima di tentare di fermarsi di nuovo — questo previene falsi negativi mentre GitHub ricalcola.

Salta interamente (consente) quando: `gh` non è installato, nessun PR esiste per il branch, lo stato del PR non è `OPEN` (ad es. `MERGED`, `CLOSED`), o `gh pr view` restituisce output non parsabile. Fallisce anche open quando `origin/<baseBranch>` manca localmente o quando nessun commit è in anticipo di base — quei fall-through del Layer 1 consultano comunque la mergeability PR in cache prima di consentire.

**Parametri:**

| Parametro    | Tipo     | Predefinito | Descrizione                               |
| ------------ | -------- | ----------- | ----------------------------------------- |
| `baseBranch` | `string` | `"main"`    | Branch base da controllare per conflitti. |

<Note>
  GitHub CLI (`gh`) è richiesto per questa politica. La politica usa `gh pr view` per confermare
  che esiste un PR `OPEN` prima di eseguire qualsiasi sonda di conflitto — senza `gh`, la politica
  short-circuits per consentire. Esegui `gh auth login` con un token di accesso personale che ha
  scope `repo` per l'accesso in lettura alle pull request.
</Note>

***

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

**Evento:** Stop\
**Predefinito:** Nega l'arresto quando i controlli CI stanno fallendo o ancora in esecuzione sul branch corrente. Controlla sia le esecuzioni del workflow GitHub Actions che i controlli bot di terze parti (ad es. CodeRabbit, SonarCloud, Codecov). Tratta `skipped`, `cancelled` e `neutral` come non-fallenti (quest'ultimo copre ad es. avvisi di Socket Security su PR di contributori esterni, dove l'app intenzionalmente segnala neutral invece di success/failure). Restituisce un messaggio informativo quando tutti i controlli passano.

Nessun parametro.

<Note>
  Questa politica richiede che [GitHub CLI](https://cli.github.com/) (`gh`) sia installato e autenticato.
  Esegui `gh auth login` con un token di accesso personale che ha scope `repo` per l'accesso in lettura alle
  esecuzioni del workflow Actions e all'API Checks. Se `gh` non è installato o non autenticato, la politica fallisce open e segnala il motivo a Claude.
</Note>

***

***

## Disabilitare singole politiche

Rimuovi una politica specifica da `enabledPolicies` nella tua configurazione, o disabilitala nel tab Policies del dashboard.

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

Le politiche non elencate in `enabledPolicies` non vengono eseguite, anche se esistono voci `policyParams` per loro.