failproofai 1.0.1-beta.0 → 1.0.1

package/.next/standalone/docs-old/it/built-in-policies.mdx

@@ -0,0 +1,853 @@
+---
+title: Politiche integrate
+description: "Tutte le 39 politiche integrate che individuano le modalità di errore comuni degli agenti"
+icon: shield
+---
+
+failproofai include 39 politiche integrate che individuano le modalità di errore comuni degli agenti. Ogni politica si attiva su un tipo di evento hook specifico e su un nome di strumento. Diciannove politiche accettano parametri che consentono di regolarne il comportamento senza scrivere codice. Cinque politiche di flusso di lavoro applicano un 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, block-self-pause | PreToolUse |
+| [Comandi infrastrutturali](#comandi-infrastrutturali) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse |
+| [Segreti (sanitizzatori)](#segreti-sanitizzatori) | 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 pacchetti](#gestori-pacchetti) | prefer-package-manager | PreToolUse |
+| [Flusso di lavoro](#flusso-di-lavoro) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop |
+
+- **`block-`** — interrompe l'agente dal procedere.
+- **`warn-`** — fornisce all'agente contesto aggiuntivo in modo che possa correggersi autonomamente.
+- **`sanitize-`** — rimuove i dati sensibili dall'output dello strumento prima che l'agente li veda.
+
+### Spazi dei nomi
+
+Ogni politica si trova in uno slot `<namespace>/<name>`. Le politiche integrate 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 integrata utilizzando il suo nome breve o il suo nome qualificato; entrambe le forme si risolvono nella stessa politica:
+
+```json
+{
+  "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 contengono già `/` (ad es. `myorg/foo`, `custom/my-hook`) vengono mantenuti così come sono.
+- **`require-`** — blocca l'evento Stop fino al verificarsi delle condizioni.
+
+---
+
+<Tip>
+Ogni politica supporta un campo `hint` facoltativo in `policyParams`. L'hint viene aggiunto al messaggio di deny o instruct che Claude vede, fornendo indicazioni pratiche senza modificare il codice della politica. Funziona con politiche integrate, personalizzate e per convenzione. Consulta [Configurazione → hint](/it/configuration#hint-cross-cutting) per i dettagli.
+</Tip>
+
+---
+
+## Comandi pericolosi
+
+Impedisci agli agenti di eseguire operazioni difficili da annullare o che potrebbero danneggiare il sistema host.
+
+### `block-sudo`
+
+**Evento:** PreToolUse (Bash)  
+**Predefinito:** Nega qualsiasi comando `sudo` o `doas`.
+
+Blocca un comando che esegue un binario di elevazione **in posizione di comando**. La corrispondenza è strutturale piuttosto che testuale: il comando viene suddiviso in segmenti come farebbe una shell, gli assegnamenti di prefisso (`FOO=bar`), i reindirizzamenti e i runner con i loro flag (`env`, `nohup`, `timeout`, `xargs`, `sh -c`, …) vengono rimossi, e il binario risultante viene confrontato per **basename**. Quindi `/usr/bin/sudo`, `env sudo`, `timeout 5 sudo`, `"sudo"`, `\sudo` e `bash -c "sudo …"` sono tutti negati, e `doas` viene trattato come la stessa capacità con un nome diverso.
+
+Poiché si ancora sulla posizione del comando piuttosto che sulla parola che appare da qualsiasi parte, **non** si attiva su comandi che la menzionano semplicemente — `grep -r sudo /etc`, `cat /etc/sudoers`, `git commit -m "fix sudo handling"`, o un'alternazione `grep` contenente la parola vengono eseguiti normalmente.
+
+<Warning>
+Questo ferma il tentativo ovvio; non chiude la classe. Un agente che può eseguire shell arbitrarie può comunque raggiungere l'elevazione indirettamente — attraverso una variabile (`S=sudo; $S …`), una pipe decodificata base64, o uno script wrapper su disco — perché nessuna ispezione di una singola stringa di comando può seguirle. Tratta questo come una protezione contro gli errori e l'escalation casuale, non come un confine di sicurezza contro un agente determinato. Un confine reale deve essere applicato sotto la shell.
+</Warning>
+
+**Parametri:**
+
+| Parametro | Tipo | Predefinito | Descrizione |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | Prefissi di comando esatti che sono consentiti. Ogni voce viene confrontata con i token argv analizzati. |
+
+**Esempio:**
+
+```json
+{
+  "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 pattern vengono confrontati con i token analizzati, non con la stringa di comando grezza. Questo previene il 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 altre forme di eliminazione ricorsiva simili.
+
+**Parametri:**
+
+| Parametro | Tipo | Predefinito | Descrizione |
+|-------|------|---------|-------------|
+| `allowPaths` | `string[]` | `[]` | Percorsi che sono sicuri da eliminare ricorsivamente (ad es. `/tmp`). |
+
+**Esempio:**
+
+```json
+{
+  "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 pattern simili.
+
+Nessun parametro.
+
+---
+
+### `block-failproofai-commands`
+
+**Evento:** PreToolUse (Bash)  
+**Predefinito:** Nega comandi che disinstallerebbero o disabiliterebbero failproofai stesso (ad es. `npm uninstall failproofai`, `failproofai policies --uninstall`).
+
+Nessun parametro.
+
+---
+
+### `block-self-pause`
+
+**Evento:** PreToolUse (Bash)  
+**Predefinito:** Nega `failproofai config --pause`, che sospende l'applicazione per una sessione. La pausa è una decisione umana — un agente in grado di eseguirla potrebbe disattivare tutte le altre politiche con un singolo comando.
+
+Più ristretto di [`block-failproofai-commands`](#block-failproofai-commands) di proposito, e non coperto da esso: quella politica si ancora su un confine di comando, quindi `npx -y failproofai config --pause` non corrisponde ad esso, ed essendo ampio è spesso disattivato in modo che gli agenti possono eseguire `failproofai audit`. `--resume` e `--status` sono consentiti — nessuno rimuove l'applicazione.
+
+Questo ferma il tentativo diretto, non l'intera classe: un agente può comunque raggiungere lo stesso stato attraverso un alias o uno script wrapper. Chiuderlo completamente richiede che la pausa sia irraggiungibile da una chiamata di strumento.
+
+Nessun parametro.
+
+---
+
+## Comandi infrastrutturali
+
+Ferma gli agenti di codifica dall'eseguire CLI infrastrutturali o dall'attivare pipeline CI/CD. Tutte le politiche in questa categoria sono **opt-in** (`defaultEnabled: false`) — gli agenti che hanno legittimamente bisogno di chiamare `kubectl`, `terraform`, ecc. non verranno disturbati a meno che non abiliti la politica. Se abilitata, ogni invocazione della CLI corrispondente è negata a meno che il comando corrisponda a una voce in `allowPatterns`.
+
+La grammatica del pattern è la stessa di [`block-sudo`](#block-sudo): i token vengono confrontati con argv analizzati, `*` è un wildcard per un token, e qualsiasi comando contenente un operatore shell autonomo (`&&`, `||`, `|`, `;`) o un token con metarcatteri shell incorporati viene rifiutato prima della corrispondenza della lista di consentiti per prevenire bypass di iniezione.
+
+### `block-kubectl`
+
+**Evento:** PreToolUse (Bash)  
+**Predefinito:** Nega qualsiasi invocazione di `kubectl`.
+
+**Parametri:**
+
+| Parametro | Tipo | Predefinito | Descrizione |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | Prefissi di comando kubectl consentiti. |
+
+**Esempio:**
+
+```json
+{
+  "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 di `terraform` o `tofu` (OpenTofu).
+
+**Parametri:**
+
+| Parametro | Tipo | Predefinito | Descrizione |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | Prefissi di comando terraform/tofu consentiti. |
+
+**Esempio:**
+
+```json
+{
+  "policyParams": {
+    "block-terraform": {
+      "allowPatterns": ["terraform plan", "terraform validate", "terraform show *"]
+    }
+  }
+}
+```
+
+---
+
+### `block-aws-cli`
+
+**Evento:** PreToolUse (Bash)  
+**Predefinito:** Nega qualsiasi invocazione di CLI `aws`.
+
+**Parametri:**
+
+| Parametro | Tipo | Predefinito | Descrizione |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | Prefissi di comando aws CLI consentiti. |
+
+**Esempio:**
+
+```json
+{
+  "policyParams": {
+    "block-aws-cli": {
+      "allowPatterns": ["aws s3 ls *", "aws sts get-caller-identity"]
+    }
+  }
+}
+```
+
+---
+
+### `block-gcloud`
+
+**Evento:** PreToolUse (Bash)  
+**Predefinito:** Nega qualsiasi invocazione di CLI `gcloud` (Google Cloud).
+
+**Parametri:**
+
+| Parametro | Tipo | Predefinito | Descrizione |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | Prefissi di comando gcloud consentiti. |
+
+**Esempio:**
+
+```json
+{
+  "policyParams": {
+    "block-gcloud": {
+      "allowPatterns": ["gcloud auth list", "gcloud config list"]
+    }
+  }
+}
+```
+
+---
+
+### `block-az-cli`
+
+**Evento:** PreToolUse (Bash)  
+**Predefinito:** Nega qualsiasi invocazione di CLI `az` (Azure).
+
+**Parametri:**
+
+| Parametro | Tipo | Predefinito | Descrizione |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | Prefissi di comando az CLI consentiti. |
+
+**Esempio:**
+
+```json
+{
+  "policyParams": {
+    "block-az-cli": {
+      "allowPatterns": ["az account show", "az group list"]
+    }
+  }
+}
+```
+
+---
+
+### `block-helm`
+
+**Evento:** PreToolUse (Bash)  
+**Predefinito:** Nega qualsiasi invocazione di `helm`.
+
+**Parametri:**
+
+| Parametro | Tipo | Predefinito | Descrizione |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | Prefissi di comando helm consentiti. |
+
+**Esempio:**
+
+```json
+{
+  "policyParams": {
+    "block-helm": {
+      "allowPatterns": ["helm list", "helm status *"]
+    }
+  }
+}
+```
+
+---
+
+### `block-gh-pipeline`
+
+**Evento:** PreToolUse (Bash)  
+**Predefinito:** Nega i seguenti sottocomandi `gh` CLI 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** sono abbinati da questa politica — vengono regolarmente necessari per i controlli del flusso di lavoro (incluso il proprio `require-ci-green-before-stop` di failproofai).
+
+**Parametri:**
+
+| Parametro | Tipo | Predefinito | Descrizione |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | Invocazioni scriptate specifiche da consentire anche se verrebbero negate. |
+
+**Esempio:**
+
+```json
+{
+  "policyParams": {
+    "block-gh-pipeline": {
+      "allowPatterns": ["gh run rerun *"]
+    }
+  }
+}
+```
+
+---
+
+## Segreti (sanitizzatori)
+
+Ferma gli agenti dal divulgare credenziali nel loro contesto o output. Le politiche di sanitizzazione 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 pattern di segreto, la politica restituisce una decisione di negazione che impedisce al output di essere restituito.
+
+### `sanitize-jwt`
+
+**Evento:** PostToolUse (tutti gli strumenti)  
+**Predefinito:** Redige i token JWT (tre segmenti base64url separati da `.`).
+
+Nessun parametro.
+
+---
+
+### `sanitize-api-keys`
+
+**Evento:** PostToolUse (tutti gli strumenti)  
+**Predefinito:** Redige i formati di chiave API comuni: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PAT (`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 }[]` | `[]` | Pattern regex aggiuntivi da trattare come segreti. |
+
+**Esempio:**
+
+```json
+{
+  "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:** Redige 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:** Redige i blocchi PEM (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, ecc.).
+
+Nessun parametro.
+
+---
+
+### `sanitize-bearer-tokens`
+
+**Evento:** PostToolUse (tutti gli strumenti)  
+**Predefinito:** Redige le intestazioni `Authorization: Bearer <token>` dove il token è 20 o più caratteri.
+
+Nessun parametro.
+
+---
+
+## Ambiente
+
+Proteggi la configurazione dell'ambiente sensibile dalla lettura o dall'esposizione da parte degli agenti.
+
+### `block-env-files`
+
+**Evento:** PreToolUse (Bash, Read)  
+**Predefinito:** Nega la lettura di file `.env` tramite `cat .env`, chiamate di strumento Read con `.env` come percorso del file, ecc.
+
+Non blocca `.envrc` o altri file correlati all'ambiente — solo i file denominati esattamente `.env`.
+
+Nessun parametro.
+
+---
+
+### `protect-env-vars`
+
+**Evento:** PreToolUse (Bash)  
+**Predefinito:** Nega comandi che stampano le variabili di ambiente: `printenv`, `env`, `echo $VAR`.
+
+Nessun parametro.
+
+---
+
+## Accesso ai file
+
+Mantieni gli agenti che lavorano entro i confini del progetto e lontano dai 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 anziché della `cwd` dal vivo significa che il confine rimane stabile anche dopo che Claude esegue `cd` 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
+{
+  "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 usati per chiavi private e certificati: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`.
+
+**Parametri:**
+
+| Parametro | Tipo | Predefinito | Descrizione |
+|-------|------|---------|-------------|
+| `additionalPatterns` | `string[]` | `[]` | Pattern di nome file aggiuntivi (stile glob) da bloccare. |
+
+**Esempio:**
+
+```json
+{
+  "policyParams": {
+    "block-secrets-write": {
+      "additionalPatterns": [".token", ".secret"]
+    }
+  }
+}
+```
+
+---
+
+## Git
+
+Previeni 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 pushati direttamente. |
+
+**Esempio:**
+
+```json
+{
+  "policyParams": {
+    "block-push-master": {
+      "protectedBranches": ["main", "master", "release", "prod"]
+    }
+  }
+}
+```
+
+<Tip>
+Per consentire il push su tutti i branch (disabilitando efficacemente 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
+{
+  "policyParams": {
+    "block-force-push": {
+      "hint": "Crea un nuovo branch dal tuo HEAD corrente (ad es. `git checkout -b <new-branch>`) e pusha quello invece."
+    }
+  }
+}
+```
+
+---
+
+### `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 rivedere ciò che sta stage quando esegue `git add -A` o `git add .`. Non blocca il comando.
+
+Nessun parametro.
+
+---
+
+## Database
+
+Individua le operazioni SQL distruttive prima che si eseguano contro il 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 le istruzioni `ALTER TABLE`.
+
+Nessun parametro.
+
+---
+
+## Avvisi
+
+Fornisci agli agenti contesto extra prima di operazioni potenzialmente rischiose ma non distruttive.
+
+### `warn-large-file-write`
+
+**Evento:** PreToolUse (Write)  
+**Predefinito:** Istruisce Claude a confermare prima di scrivere file di dimensioni superiori a 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
+{
+  "policyParams": {
+    "warn-large-file-write": {
+      "thresholdKb": 256
+    }
+  }
+}
+```
+
+<Note>
+Il gestore di hook applica un limite stdin di 1 MB sui payload. Per testare questa politica con contenuti piccoli, imposta `thresholdKb` a 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 lancia 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 pacchetti
+
+Applica quale gestore di pacchetti è consentito all'agente di utilizzare.
+
+### `prefer-package-manager`
+
+**Evento:** PreToolUse (Bash)  
+**Predefinito:** Disabilitato. Se abilitato, blocca qualsiasi comando del gestore di pacchetti non nella lista `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 questa lista è bloccato. Se vuoto, la politica è no-op. |
+| `blocked` | string[] | `[]` | Nomi di gestori aggiuntivi da bloccare oltre la lista integrata (ad es. `['pdm', 'pipx']`). |
+
+La lista di blocco integrata include: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Usa `blocked` per aggiungere gestori non in questa lista.
+
+**Configurazione di esempio:**
+
+```json
+{
+  "enabledPolicies": ["prefer-package-manager"],
+  "policyParams": {
+    "prefer-package-manager": {
+      "allowed": ["uv", "bun"],
+      "blocked": ["pdm", "pipx"]
+    }
+  }
+}
+```
+
+Con questa configurazione, `pip install flask` e `pdm install flask` sono entrambi negati con un messaggio che dice a Claude di utilizzare `uv` o `bun` invece. I comandi come `uv pip install flask` sono consentiti perché `uv` è nella lista di consentiti e viene verificato per primo.
+
+---
+
+## Comportamento dell'IA
+
+Rileva quando gli agenti 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'agente è bloccato in un ciclo.
+
+Nessun parametro.
+
+---
+
+## Flusso di lavoro
+
+Applica un flusso di lavoro di fine sessione disciplinato. Queste politiche si attivano sull'evento **Stop** e negano all'agente il diritto di fermarsi fino al verificarsi di ogni condizione. Seguono una catena di dipendenza naturale: commit → push → PR → CI. Se una politica nega, le politiche successive nella catena vengono saltate (deny cortocircuita).
+
+Tutte le politiche di flusso di lavoro sono **fail-open**: se lo strumento richiesto non è disponibile (ad es. `gh` non installato, nessun git remote), la politica consente con un messaggio informativo che spiega perché il controllo è stato saltato.
+
+### Semantica Stop per CLI
+
+L'applicazione dello Stop sembra leggermente diversa tra i sei CLI supportati perché ognuno espone un contratto hook "agente terminato" diverso. L'**risultato** è lo stesso — l'agente non scappa fermarsi mentre un gate del flusso di lavoro sta fallendo — ma i **meccanismi** differiscono. 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 ciclo agente, immediatamente | Claude continua a lavorare — corregge il problema, quindi tenta di terminare di nuovo. Nessuna interruzione visibile per te. |
+| Codex | Stesso ciclo agente, immediatamente | Uguale a Claude. |
+| GitHub Copilot CLI | Stesso ciclo agente, immediatamente | Uguale a Claude (utilizza il canale di ripetizione `{decision:"block", reason}` di Copilot — verificato empiricamente contro Copilot CLI 1.0.41). |
+| Cursor Agent | Stesso ciclo agente, immediatamente | Uguale a Claude (utilizza il canale `{followup_message}` di Cursor — limitato a `loop_limit`, predefinito 5 tentativi). |
+| OpenCode | Stesso ciclo agente, immediatamente | Uguale a Claude (utilizza la chiamata SDK `client.session.prompt(...)` di OpenCode instradato attraverso `hookSpecificOutput.additionalContext`). |
+| **Pi (pi-coding-agent)** | **Turno utente successivo** | **Pi si ferma visibilmente** quando il gate si attiva — il suo ciclo agente esce e vieni 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 del flusso di lavoro (commit, push, ecc.) prima di fare quello che hai chiesto. |
+
+<Note>
+**Limitazione Pi.** L'`AgentEndEvent` di Pi (l'equivalente a monte dell'hook `Stop` di Claude) non ha un tipo Result — nel momento in cui si attiva, il ciclo agente di Pi è già uscito. Pi non può essere forzato a ritentare lo stesso ciclo come Claude / Copilot / Cursor / OpenCode possono. failproofai sposta il gate all'evento `before_agent_start` di Pi (che si attiva dopo il prossimo prompt dell'utente) in modo che il controllo del flusso di lavoro si applichi ancora, solo al turno successivo anziché a quello corrente.
+
+**Cosa significa in pratica:**
+
+- Dopo che Pi si ferma, la ragione del deny viene acquisita in memoria con chiave dall'id della sessione Pi. Il prossimo prompt che invii nella stessa sessione Pi lo scarica: l'LLM vede la direttiva `MANDATORY ACTION REQUIRED` in cima al suo prompt di sistema, esegue il commit (o push / apre la PR / attende CI), e solo allora continua con la tua richiesta. La ragione del deny acquisita è one-shot — una volta scaricata, il gate è chiaro.
+- Il gate è vincolato dalla durata del processo Pi. Se esegui `Ctrl+C` Pi o esci tra i turni, la voce in memoria viene eliminata insieme al processo e il gate viene mancato. Claude, Copilot, Cursor e OpenCode hanno lo stesso vincolo (uccidi l'agente e il gate viene mancato) — Pi lo rende solo più visibile perché l'agente 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ò fuoriuscire in una nuova sessione avviata nello stesso processo Pi.
+
+Se hai bisogno di un retry nello stesso ciclo in stile Claude, esegui le tue politiche `Stop` sotto uno qualsiasi degli altri cinque CLI supportati. Stiamo tracciando Pi a monte per un futuro tipo Result su `AgentEndEvent` che ci permetterebbe di colmare questo gap.
+</Note>
+
+### `require-commit-before-stop`
+
+**Evento:** Stop  
+**Predefinito:** Nega la fermata quando ci sono modifiche non impegnate (file modificati, stage o non tracciati). Restituisce un messaggio informativo quando la directory di lavoro è pulita.
+
+Nessun parametro.
+
+---
+
+### `require-push-before-stop`
+
+**Evento:** Stop  
+**Predefinito:** Nega la fermata quando ci sono commit non pushati o quando il branch corrente non ha un branch di tracciamento remoto. 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 del remote a cui pushare. |
+
+**Esempio:**
+
+```json
+{
+  "policyParams": {
+    "require-push-before-stop": {
+      "remote": "upstream"
+    }
+  }
+}
+```
+
+---
+
+### `require-pr-before-stop`
+
+**Evento:** Stop  
+**Predefinito:** Nega la fermata quando non esiste una pull request per il branch corrente, o quando la PR esistente è chiusa senza essere merge. Istruisce Claude a creare una PR con `gh pr create`. Quando la PR viene **merge**, la politica consente (il lavoro è stato spedito) e il messaggio suggerisce di disattivare il 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 l'ambito `repo` per l'accesso in lettura alle
+pull request. Se `gh` non è installato o non autenticato, la politica fallisce open e riporta il motivo a Claude.
+</Note>
+
+---
+
+### `require-no-conflicts-before-stop`
+
+**Evento:** Stop  
+**Predefinito:** Nega la fermata quando il branch corrente non può eseguire il merge in modo pulito nel branch di base. La politica prima conferma che c'è una PR `OPEN` su GitHub per il branch — senza una, non c'è un target di merge da applicare, quindi l'intera politica cortocircuita a consentire. Una volta che una PR `OPEN` è confermata, due sonde indipendenti vengono eseguite:
+
+1. **Locale** — `git merge-tree --write-tree --name-only origin/<baseBranch> HEAD`. In caso di conflitto, il messaggio di deny nomina i file in conflitto in modo che Claude sappia esattamente cosa risolvere.
+2. **GitHub** — riutilizza il risultato `gh pr view --json mergeable,state` già recuperato nella verifica preliminare. Individua i conflitti che un `origin/<baseBranch>` locale stantio avrebbe mancato (ad es. qualcuno ha fatto il land di una PR in conflitto su `main` dall'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, non esiste una PR per il branch, lo stato della PR non è `OPEN` (ad es. `MERGED`, `CLOSED`), o `gh pr view` restituisce output non analizzabile. Fallisce anche open quando `origin/<baseBranch>` è mancante localmente o quando nessun commit è in anticipo sulla base — quelle fall-through di Strato 1 consultano comunque la mergeability della PR memorizzata nella cache prima di consentire.
+
+**Parametri:**
+
+| Parametro | Tipo | Predefinito | Descrizione |
+|-------|------|---------|-------------|
+| `baseBranch` | `string` | `"main"` | Branch di base su cui verificare i conflitti. |
+
+<Note>
+GitHub CLI (`gh`) è richiesto per questa politica. La politica utilizza `gh pr view` per confermare
+che esiste una PR `OPEN` prima di eseguire qualsiasi sonda di conflitto — senza `gh`, la politica
+cortocircuita a consentire. Esegui `gh auth login` con un token di accesso personale che ha
+l'ambito `repo` per l'accesso in lettura alle pull request.
+</Note>
+
+---
+
+### `require-ci-green-before-stop`
+
+**Evento:** Stop  
+**Predefinito:** Nega la fermata quando i controlli CI stanno fallendo o sono ancora in esecuzione sul branch corrente. Controlla sia le esecuzioni del flusso di lavoro GitHub Actions che i controlli di bot di terze parti (ad es. CodeRabbit, SonarCloud, Codecov). Tratta conclusioni `skipped`, `cancelled` e `neutral` come non fallimentari (quest'ultima copre ad es. avvisi di Socket Security su PR di contributori esterni, dove l'app intenzionalmente riporta neutral anziché 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 l'ambito `repo` per l'accesso in lettura alle
+esecuzioni del flusso di lavoro Actions e all'API Checks. Se `gh` non è installato o non autenticato, la politica fallisce open e riporta il motivo a Claude.
+</Note>
+
+---
+
+---
+
+## Disabilitazione di politiche individuali
+
+Rimuovi una politica specifica da `enabledPolicies` nella tua configurazione, o disattivarla nella scheda Politiche del dashboard.
+
+```json
+{
+  "enabledPolicies": [
+    "block-rm-rf",
+    "sanitize-api-keys"
+  ]
+}
+```
+
+Le politiche non elencate in `enabledPolicies` non vengono eseguite, anche se le voci `policyParams` esistono per loro.