failproofai 1.0.1-beta.0 → 1.0.1

package/.next/standalone/docs-old/it/configuration.mdx

@@ -0,0 +1,269 @@
+---
+---
+title: Configurazione
+description: "Formato del file di configurazione, sistema a tre scope e regole di unione"
+icon: gear
+---
+
+failproofai utilizza file di configurazione JSON per controllare quali politiche sono attive, come si comportano e da dove vengono caricate le politiche personalizzate. La configurazione è progettata per essere facile da condividere con il tuo team - commitla nel tuo repo e ogni sviluppatore ottiene la stessa rete di sicurezza per gli agent.
+
+---
+
+## Ambiti di configurazione
+
+Esistono tre ambiti di configurazione, valutati in ordine di priorità:
+
+| Ambito | Percorso file | Scopo |
+|-------|-----------|---------|
+| **project** | `.failproofai/policies-config.json` | Impostazioni per-repo, commitmate nel controllo versione |
+| **local** | `.failproofai/policies-config.local.json` | Override personali per-repo, gitignored |
+| **global** | `~/.failproofai/policies-config.json` | Impostazioni predefinite a livello utente per tutti i progetti |
+
+Quando failproofai riceve un evento hook, carica e unisce tutti e tre i file che esistono per la directory di lavoro corrente.
+
+### Regole di unione
+
+**`enabledPolicies`** - l'unione di tutti e tre gli ambiti. Una politica abilitata a qualsiasi livello è attiva.
+
+```text
+project:  ["block-sudo"]
+local:    ["block-rm-rf"]
+global:   ["block-sudo", "sanitize-api-keys"]
+
+resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← unione con deduplica
+```
+
+**`policyParams`** - il primo ambito che definisce i parametri per una determinata politica vince completamente. Non c'è fusione profonda dei valori all'interno dei parametri di una politica.
+
+```text
+project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
+global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
+
+resolved: { allowPatterns: ["sudo apt-get update"] }   ← project vince, global ignorato
+```
+
+```text
+project:  (nessuna voce block-sudo)
+local:    (nessuna voce block-sudo)
+global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
+
+resolved: { allowPatterns: ["sudo systemctl status"] }  ← ricade su global
+```
+
+**`customPoliciesPaths` / `customPoliciesPath`** - il primo ambito che definisce una delle due forme vince.
+
+**`disabledCustomPolicies`** - unione tra tutti gli ambiti. Il dashboard scrive un ID qualificato di origine qui quando disattivi una politica individuale da un file di politiche esplicite o per convenzione. Le politiche non elencate rimangono abilitate per impostazione predefinita; gli ID includono il file di origine in modo che politiche con lo stesso nome in più file possano essere controllate indipendentemente.
+
+**`llm`** - il primo ambito che lo definisce vince.
+
+---
+
+## Formato del file di configurazione
+
+```json
+{
+  "enabledPolicies": [
+    "block-sudo",
+    "block-rm-rf",
+    "block-push-master",
+    "sanitize-api-keys",
+    "sanitize-jwt",
+    "block-env-files",
+    "block-read-outside-cwd"
+  ],
+  "policyParams": {
+    "block-sudo": {
+      "allowPatterns": ["sudo systemctl status", "sudo journalctl"]
+    },
+    "block-push-master": {
+      "protectedBranches": ["main", "release", "prod"]
+    },
+    "block-rm-rf": {
+      "allowPaths": ["/tmp"]
+    },
+    "block-read-outside-cwd": {
+      "allowPaths": ["/shared/data", "/opt/company"]
+    },
+    "sanitize-api-keys": {
+      "additionalPatterns": [
+        { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo API key" }
+      ]
+    },
+    "warn-large-file-write": {
+      "thresholdKb": 512
+    }
+  },
+  "customPoliciesPath": "/home/alice/myproject/my-policies.js"
+}
+```
+
+---
+
+## Riferimento dei campi
+
+### `enabledPolicies`
+
+Tipo: `string[]`
+
+Elenco dei nomi delle politiche da abilitare. I nomi devono corrispondere esattamente agli identificatori delle politiche mostrati da `failproofai policies`. Vedi [Built-in Policies](/it/built-in-policies) per l'elenco completo.
+
+Le politiche non in `enabledPolicies` sono inattive, anche se hanno voci in `policyParams`.
+
+### `policyParams`
+
+Tipo: `Record<string, Record<string, unknown>>`
+
+Override dei parametri per-politica. La chiave esterna è il nome della politica; le chiavi interne sono specifiche della politica. Ogni politica documenta i suoi parametri disponibili in [Built-in Policies](/it/built-in-policies).
+
+Se una politica ha parametri ma non li specifichi, vengono utilizzati i valori predefiniti incorporati della politica. Gli utenti che non configurano affatto `policyParams` ottengono un comportamento identico alle versioni precedenti.
+
+Le chiavi sconosciute all'interno del blocco dei parametri di una politica vengono silenziosamente ignorate al momento dell'attivazione dell'hook, ma segnalate come avvisi quando esegui `failproofai policies`.
+
+#### `hint` (trasversale)
+
+Tipo: `string` (opzionale)
+
+Un messaggio aggiunto al motivo quando una politica restituisce `deny` o `instruct`. Usalo per dare a Claude una guida attuabile senza modificare la politica stessa.
+
+Funziona con qualsiasi tipo di politica — incorporata, personalizzata (`custom/`), convenzione di progetto (`.failproofai-project/`), o convenzione utente (`.failproofai-user/`).
+
+```json
+{
+  "policyParams": {
+    "block-force-push": {
+      "hint": "Prova a creare un nuovo branch."
+    },
+    "block-sudo": {
+      "allowPatterns": ["sudo apt-get"],
+      "hint": "Usa apt-get direttamente senza sudo."
+    },
+    "custom/my-policy": {
+      "hint": "Chiedi l'approvazione dell'utente per primo."
+    }
+  }
+}
+```
+
+Quando `block-force-push` nega, Claude vede: *"Il force-push è bloccato. Prova a creare un nuovo branch."*
+
+I valori non stringa e le stringhe vuote vengono silenziosamente ignorate. Se `hint` non è impostato, il comportamento è invariato (retrocompatibile).
+
+### `customPoliciesPath`
+
+Tipo: `string` (percorso assoluto)
+
+Percorso di un file JavaScript contenente politiche di hook personalizzate. Questo viene impostato automaticamente da `failproofai policies --install --custom <path>` (il percorso viene risolto in assoluto prima di essere archiviato).
+
+Il file viene caricato di nuovo su ogni evento hook - non c'è caching. Vedi [Custom Policies](/it/custom-policies) per i dettagli di creazione.
+
+### Politiche basate su convenzione
+
+Oltre a `customPoliciesPath` esplicito, failproofai scopre e carica automaticamente file di politiche dalle directory `.failproofai/policies/`:
+
+| Livello | Directory | Ambito |
+|-------|-----------|-------|
+| Progetto | `.failproofai/policies/` | Condiviso con il team tramite controllo versione |
+| Utente | `~/.failproofai/policies/custom-policies/` | Personale, si applica a tutti i progetti |
+
+<Note>
+  La directory a livello utente si è spostata di un livello nella riorganizzazione
+  della home-directory. I file lasciati nel vecchio percorso `~/.failproofai/policies/`
+  vengono spostati automaticamente in `custom-policies/` la prima volta che esegui
+  un comando `failproofai` dopo l'aggiornamento, e il comando ti dice quali file
+  sono stati spostati.
+</Note>
+
+**Corrispondenza file:** Solo i file che corrispondono a `*policies.{js,mjs,ts}` vengono caricati (ad es. `security-policies.mjs`, `workflow-policies.js`). Gli altri file nella directory vengono ignorati.
+
+**Nessuna configurazione necessaria:** Le politiche per convenzione non richiedono voci in `policies-config.json`. Basta rilasciare file nella directory e verranno ripresi sul prossimo evento hook.
+
+**Caricamento unione:** Entrambe le directory di convenzione di progetto e utente vengono scansionate. Tutti i file corrispondenti da entrambi i livelli vengono caricati (a differenza di `customPoliciesPath` che utilizza il primo ambito che vince).
+
+Vedi [Custom Policies](/it/custom-policies) per ulteriori dettagli ed esempi.
+
+### `llm`
+
+Tipo: `object` (opzionale)
+
+Configurazione del client LLM per le politiche che effettuano chiamate AI. Non richiesto per la maggior parte delle configurazioni.
+
+```json
+{
+  "llm": {
+    "model": "claude-sonnet-4-6",
+    "apiKey": "sk-ant-..."
+  }
+}
+```
+
+---
+
+## Gestione della configurazione dalla CLI
+
+I comandi `policies --install` e `policies --uninstall` scrivono nel file delle impostazioni hook della tua CLI agent (i punti di ingresso dell'hook), mentre `policies-config.json` è il file che gestisci direttamente. I due sono separati:
+
+- **Impostazioni CLI Agent** — dice all'agent di chiamare `failproofai --hook <event>` su ogni uso dello strumento:
+  - **Claude Code**: `~/.claude/settings.json` (utente), `<cwd>/.claude/settings.json` (progetto), `<cwd>/.claude/settings.local.json` (locale)
+  - **OpenAI Codex**: `~/.codex/hooks.json` (utente), `<cwd>/.codex/hooks.json` (progetto) — Codex non ha un ambito `local`
+  - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (utente), `<cwd>/.github/hooks/failproofai.json` (progetto) — Copilot non ha un ambito `local`. Le voci dell'hook utilizzano i campi di comando keyed da SO di Copilot `bash`/`powershell` con `timeoutSec`; il file contiene un marcatore `version: 1` di livello superiore. Il supporto di Copilot CLI è **beta** mentre verifichiamo lo schema del record `events.jsonl` (che i documenti pubblici non specificano) rispetto a più sessioni del mondo reale. **VS Code Copilot Chat agent mode (Preview)** legge le configurazioni dell'hook da `.github/hooks/*.json`, `~/.copilot/hooks/*.json`, e `~/.claude/settings.json` (governato dall'impostazione `chat.hookFilesLocations`) utilizzando lo stesso contratto Claude-shaped `{hookSpecificOutput:{permissionDecision:"deny",…}}` — i percorsi esatti che questa integrazione `copilot` e l'integrazione `claude` (`~/.claude/settings.json`) già scrivono, quindi `failproofai policies --install --cli copilot` (o `--cli claude`) **già applica in VS Code agent mode** senza bisogno di un'integrazione `vscode` separata (confermato in diretta dai log di discovery di VS Code).
+  - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (utente), `<cwd>/.cursor/hooks.json` (progetto) — Cursor non ha un ambito `local`. Le voci dell'hook utilizzano il modulo Claude-shaped `{type, command, timeout}` (nessuna divisione `bash`/`powershell`), ma archiviate sotto chiavi di evento camelCase (`preToolUse`, `beforeSubmitPrompt`, …) in un array piatto per lo schema degli hook di Cursor; il file contiene un marcatore `version: 1` di livello superiore. Il gestore canonicalizza camelCase → PascalCase tramite `CURSOR_EVENT_MAP` in modo che le politiche incorporate esistenti si attivino invariate. Il supporto di Cursor Agent è **beta** mentre verifichiamo il trascritto su disco di Cursor (non specificato nei documenti pubblici) rispetto a più installazioni del mondo reale.
+  - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (utente), `<cwd>/.opencode/opencode.json` + `<cwd>/.opencode/plugins/failproofai.mjs` (progetto) — OpenCode non ha un ambito `local`. A differenza degli altri cinque CLI, OpenCode **non ha un sistema di hook con comando esterno**: carica plugin JS/TS in-process esplicitamente registrati tramite l'array `plugin: []` in `opencode.json` (l'auto-discovery da `.opencode/plugins/` **non** è il modo in cui i plugin si caricano su opencode v1.14.33). L'installazione rilascia un piccolo shim di plugin generato che chiama il binario failproofai in subprocess e traduce la risposta JSON di shape Claude del binario di nuovo in semantica di plugin: `throw new Error()` per la negazione di evento di strumento (annulla la chiamata dello strumento), `client.session.prompt(...)` per `instruct` E per `Stop` / `SubagentStop` negazione (invia il motivo della negazione come prossimo messaggio utente — l'unico canale di ritentatività forzata poiché `session.idle` è solo notifica e lanciare da esso è un no-op), e no-op per allow. Lo shim canonicalizza sia i nomi degli strumenti (minuscolo → PascalCase tramite `OPENCODE_TOOL_MAP`) che le chiavi degli argomenti di input dello strumento (camelCase → snake_case tramite `OPENCODE_TOOL_INPUT_MAP` per `Read` / `Write` / `Edit`, ad es. `filePath` → `file_path`, `oldString` → `old_string`) prima di inoltrarsi al binario, così i builtin di controllo del percorso come `block-read-outside-cwd`, `block-env-files`, e `block-secrets-write` si attivano invariati su chiamate di strumento OpenCode. Le sessioni vivono nel DB SQLite di opencode in `~/.local/share/opencode/opencode.db`; il visualizzatore di sessioni del dashboard le legge tramite `opencode db --format json` e `opencode export <id>`. Il supporto di OpenCode è **beta** mentre verifichiamo il comportamento tra versioni e rispetto a più sessioni del mondo reale. Vedi la [documentazione dei plugin OpenCode](https://opencode.ai/docs/plugins/).
+  - **Pi _(beta)_**: `~/.pi/agent/settings.json` (utente), `<cwd>/.pi/settings.json` (progetto) — Pi non ha un ambito `local`. Pi carica pacchetti di estensione TypeScript all'avvio; il file delle impostazioni è un array di stringhe piatto `{"packages": ["./relative/path", …]}`. failproofai scrive una singola voce di array di pacchetti che punta alla directory `pi-extension/` in bundle. L'estensione internamente si sottoscrive agli eventi `tool_call` / `user_bash` / `input` / `session_start` di Pi e chiama il shell a `failproofai --hook <Event> --cli pi`; il gestore canonicalizza underscore_lower_snake_case → PascalCase tramite `PI_EVENT_MAP` in modo che le politiche incorporate esistenti si attivino invariate. Gli argomenti di input dello strumento vengono anche canonicalizzati tramite `PI_TOOL_INPUT_MAP` (Pi's Read / Write / Edit forniscono `path` piuttosto che `file_path`; mappare la chiave di livello superiore consente a `block-env-files` e `block-secrets-write` di attivarsi — `block-read-outside-cwd` già aveva un fallback `path`). Il supporto di Pi è **beta** mentre l'API di estensione di Pi e il layout del log di sessione si stabilizzano.
+  - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**solo ambito utente** — Hermes non ha configurazione di progetto/locale). Hermes è un **gateway** Slack/Telegram, quindi un'installazione intercetta le chiamate agli strumenti da ogni piattaforma (Slack/Telegram/cli/cron) **e** subagent interni. Le voci dell'hook sono una coppia `{command, timeout}` (timeout in **secondi**) sotto una mappa `hooks:` keyed da eventi snake_case di Hermes (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`); il gestore canonicalizza gli eventi tramite `HERMES_EVENT_MAP` e i nomi degli strumenti tramite `HERMES_TOOL_MAP` in modo che le politiche incorporate si attivino invariate. La configurazione viene modificata tramite un roundtrip YAML `Document` che preserva i commenti in modo che le altre impostazioni dell'operatore sopravvivano, e l'installazione imposta `hooks_auto_accept: true` in modo che il gateway headless (nessun TTY) esegua gli hook senza una richiesta di consenso. L'evaluatore emette il contratto stdout di Hermes `{"decision":"block","reason"}` (Hermes ignora i codici di uscita). **Limitazioni:** Hermes non ha un evento di fine turno `Stop`, quindi i builtin `require-*-before-stop` mai si attivano per esso (inapplicabile, non rotto); `instruct` si degrada a allow-with-logged-note (nessun canale di contesto aggiuntivo); e la redazione di output-secret (`sanitize-*`) non può riscrivere l'output dello strumento sul contratto shell-hook. Hermes è **anche** una fonte di audit **offline** — il dashboard legge le sue sessioni di gateway direttamente da `~/.hermes/state.db`.
+  - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json` (**solo ambito utente** — OpenClaw non ha configurazione di progetto/locale). Come Hermes, OpenClaw è un **gateway** multi-canale auto-hosted, quindi un'installazione intercetta le chiamate agli strumenti da ogni canale e dai suoi subagent interni. L'applicazione viene eseguita tramite gli **hook di plugin in-process** di OpenClaw (i suoi hook basati su file interni sono solo osservativi e non possono bloccare), quindi — come OpenCode/Pi — failproofai spedisce un pacchetto `openclaw-plugin/` statico che spawn async il binario failproofai e traduce il verdetto. L'installazione registra la directory del plugin fornito in `openclaw.json`'s `plugins.load.paths[]` e lo abilita sotto `plugins.entries.failproofai` (con `hooks.allowConversationAccess: true`, richiesto per gli hook di conversazione grezzi). L'evaluatore emette un verdetto piatto `{permission, reason}` e lo shim lo mappa alla forma di ritorno nativa di ogni hook: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**), e `before_agent_finalize → {action:"revise", reason}` (**Stop** — un vero gate di fine turno, quindi i builtin `require-*-before-stop` **appliano** su OpenClaw, a differenza di Hermes). Gli eventi e i nomi degli strumenti canonicalizzano il lato binario tramite `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` (`exec→Bash`, `read→Read`, …) in modo che le politiche incorporate si attivino invariate; lo shim fallisce open su qualsiasi errore di spawn/parse/timeout. OpenClaw è **anche** una fonte di audit **offline** — il dashboard legge le sue sessioni JSONL in `~/.openclaw/agents/<agentId>/sessions/<uuid>.jsonl`.
+  - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (utente), `<cwd>/.factory/hooks.json` (progetto) — Factory non ha un ambito `local`. droid spedisce un sistema di hook con comando esterno di stile Claude, ma con due stranezze verificate in diretta rispetto a droid v0.171.0: (1) i nomi degli eventi vivono al **livello superiore** di `hooks.json` — non c'è **nessun wrapper `"hooks"`** (droid lo rifiuta); gli eventi dello strumento (`PreToolUse`/`PostToolUse`) trasportano `"matcher": "*"`, gli eventi non-strumento lo omettono. (2) Deny è guidato dal codice di uscita dell'hook **2 + stderr**, non da una decisione JSON — il ramo `factory` dell'evaluatore restituisce uscita 2 per eventi di strumento/prompt e `{decision:"block", reason}` solo sull'evento di fine turno `Stop` (l'unico canale di ritentatività forzata di droid). Gli eventi sono già PascalCase (nessuna mappa di eventi) e il payload è snake_case di Claude; solo i nomi degli strumenti vengono canonicalizzati tramite `FACTORY_TOOL_MAP` (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …). Factory è **anche** una fonte di audit **offline** — il dashboard legge le sue sessioni JSONL su disco in `~/.factory/sessions/<encoded-cwd>/<sessionId>.jsonl`.
+  - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (utente), `<cwd>/.devin/config.json` (progetto) — Devin non ha un ambito `local`. Devin è un **clone puro di Claude** verificato in diretta rispetto a devin v3000.1.27: utilizza lo schema dello schema Claude standard `"hooks"` (i write preservano la fusione in modo che le altre chiavi del file di configurazione — `org_id`, `theme_mode`, … — sopravvivano), nomi di eventi già PascalCase (nessuna mappa di eventi, nessun ramo di gestore), e un payload stdin snake_case di Claude (nessuna normalizzazione). Il ramo `devin` dell'evaluatore nega con JSON `{"decision":"block","reason"}` su stdout all'uscita 0 per **ogni** evento (verificato — il blocco ha ignorato `--permission-mode dangerous`); sull'evento di fine turno `Stop` il motivo trasporta il wording di ritentatività forzata OBBLIGATORIO in modo che i builtin `require-*-before-stop` applino. Solo i nomi degli strumenti vengono canonicalizzati tramite `DEVIN_TOOL_MAP` (`exec→Bash`; `tool_input.command` è già canonico). Devin è **anche** una fonte di audit **offline** — il dashboard legge le sue sessioni SQLite in `~/.local/share/devin/cli/sessions.db` (ogni riga `sessions` trasporta una vera `working_directory`, quindi le sessioni si raggruppano per progetto cwd come Claude).
+  - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (utente), `<cwd>/.agents/hooks.json` (progetto) — Antigravity non ha un ambito `local`. A differenza di Factory/Devin, Antigravity ha il **suo** contratto (non un clone di Claude), verificato in diretta rispetto a agy v1.1.2. `hooks.json` utilizza uno schema **named-hook**: la chiave di livello superiore è un nome di hook (*"failproofai"*) il cui valore è una mappa evento→gestori — gli eventi dello strumento (`PreToolUse`/`PostToolUse`) avvolgono i gestori in `{matcher:"*", hooks:[…]}`, mentre `PreInvocation`/`Stop` sono array di gestori **piatti** (altri hook nominati vengono preservati). Il payload stdin è **camelCase protojson** (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) — failproofai lo normalizza a snake_case prima che le politiche si eseguano, e mappa gli argomenti PascalCase di `run_command` (`CommandLine`/`Cwd`) tramite `ANTIGRAVITY_TOOL_INPUT_MAP`. Il ramo `antigravity` dell'evaluatore utilizza le forme di risposta **proprie** di Antigravity: `{decision:"deny", reason}` blocca uno strumento/prompt (uscita 0), `{decision:"continue", reason}` sull'evento di fine turno `Stop` rientra nel loop (quindi i builtin `require-*-before-stop` applino), e `{injectSteps:[{ephemeralMessage}]}` inietta un'istruzione su `PreInvocation` (→ `UserPromptSubmit`). I nomi degli strumenti canonicalizzano tramite `ANTIGRAVITY_TOOL_MAP` (`run_command→Bash`, `view_file→Read`, …). Antigravity è **anche** una fonte di audit **offline** — il dashboard legge i suoi trascritti plain-JSONL in `~/.gemini/antigravity-cli/brain/<conversationId>/.system_generated/logs/transcript_full.jsonl` (indice di conversazione in `conversation_summaries.db`).
+  - **Goose (codename goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (utente), `<cwd>/.agents/plugins/failproofai/hooks/hooks.json` (progetto) — Goose non ha un ambito `local`. L'applicazione utilizza il sistema **hooks** di Goose, la specifica **Open Plugins** tra agent: l'installatore basta rilascia la directory del plugin `failproofai` e Goose lo auto-scopre all'avvio (auto-registrandolo in `~/.config/goose/config.yaml`). `hooks.json` utilizza uno schema Open Plugins **con** un wrapper `"hooks"` di livello superiore, e il matcher è **omesso** su ogni evento — un `"*"` nudo è un regex non valido che non corrisponde a nulla (verificato in diretta rispetto a goose v1.43.0). I nomi degli eventi sono già PascalCase (nessuna mappa di eventi); il payload stdin utilizza `event`/`working_dir`, che il gestore normalizza in `hook_event_name`/`cwd`. Il ramo `goose` dell'evaluatore nega con JSON `{"decision":"block","reason"}` su stdout all'uscita 0, onorato sull'evento **`PreToolUse`** solo (spedito in goose ≥ v1.37.0) — che si attiva per lo strumento shell **e all'interno dei subagent delegati**, quindi è il singolo punto di negazione sufficiente; qualsiasi altro errore di hook fallisce **open**. Goose non ha un evento **`Stop`**, quindi i builtin `require-*-before-stop` non si applicano (come con Hermes). I nomi degli strumenti canonicalizzano tramite `GOOSE_TOOL_MAP` (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) e le chiavi del percorso tramite `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`). Goose è **anche** una fonte di audit **offline** — il dashboard legge le sue sessioni SQLite in `~/.local/share/goose/sessions/sessions.db` (ogni riga `sessions` trasporta una vera `working_dir`, quindi le sessioni si raggruppano per progetto cwd come Devin; le esecuzioni `--no-session` scratch vengono filtrate).
+- **`policies-config.json`** — dice a failproofai quali politiche valutare e con quali parametri (condiviso tra tutti i CLI agent)
+
+Passa `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` per indirizzare un agent specifico (separati da spazio o ripetuti per qualsiasi sottoinsieme):
+
+```bash
+failproofai policies --install --cli codex --scope project
+failproofai policies --install --cli copilot --scope project
+failproofai policies --install --cli cursor --scope project
+failproofai policies --install --cli opencode --scope project
+failproofai policies --install --cli pi --scope project
+failproofai policies --install --cli hermes --scope user
+failproofai policies --install --cli openclaw --scope user
+failproofai policies --install --cli factory --scope project
+failproofai policies --install --cli devin --scope project
+failproofai policies --install --cli antigravity --scope project
+failproofai policies --install --cli goose --scope project
+failproofai policies --install --cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose
+```
+
+Quando `--cli` viene omesso, `failproofai` rileva quali CLI agent sono installati (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`):
+
+- **Un CLI rilevato** — seleziona automaticamente quel CLI senza chiedere.
+- **Più CLI rilevati** in un terminale interattivo — mostra un prompt di selezione singola con tasti freccia raggruppato in una sezione `Detected (N)` (con una riga aggregata `Install for all N detected` + ogni CLI rilevato individualmente) e una sezione `Not installed (M) · install hooks ahead of time` che elenca ogni CLI non rilevato supportato come opzione di installazione anticipata (↑↓ per spostare, Invio per selezionare, ^C per uscire). Il flusso di disinstallazione mostra solo la sezione Rilevato.
+- **Più CLI rilevati** in un'esecuzione non interattiva (CI, nessun TTY) — installa per tutti i CLI rilevati senza chiedere.
+- **Nessuno rilevato** — ricade su `claude`, con un avviso che nessun binario agent è stato trovato in PATH; il comando dell'hook viene comunque scritto in modo che si attivi non appena installi uno.
+
+Puoi modificare `policies-config.json` direttamente in qualsiasi momento; le modifiche hanno effetto immediato sul prossimo evento hook senza bisogno di riavvio.
+
+---
+
+## Esempio: configurazione a livello di progetto con impostazioni predefinite del team
+
+Committa `.failproofai/policies-config.json` nel tuo repo:
+
+```json
+{
+  "enabledPolicies": [
+    "block-sudo",
+    "block-rm-rf",
+    "block-push-master",
+    "sanitize-api-keys",
+    "block-env-files"
+  ],
+  "policyParams": {
+    "block-push-master": {
+      "protectedBranches": ["main", "release", "hotfix"]
+    }
+  }
+}
+```
+
+Ogni sviluppatore può quindi creare `.failproofai/policies-config.local.json` (gitignored) per override personali senza influenzare i compagni di squadra.

package/.next/standalone/docs-old/it/custom-policies.mdx

@@ -0,0 +1,359 @@
+---
+---
+title: Politiche Personalizzate
+description: "Scrivi le tue regole in JavaScript - applica convenzioni, previeni derive, rileva errori, integrati con sistemi esterni"
+icon: code
+---
+
+Le politiche personalizzate ti permettono di scrivere regole per qualsiasi comportamento dell'agente: applica convenzioni di progetto, previeni derive, blocca operazioni distruttive, rileva agenti bloccati, o integrati con Slack, flussi di approvazione e altro ancora. Utilizzano lo stesso sistema di hook event e le decisioni `allow`, `deny`, `instruct` delle politiche incorporate.
+
+---
+
+## Esempio rapido
+
+```js
+// my-policies.js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+
+customPolicies.add({
+  name: "no-production-writes",
+  description: "Block writes to paths containing 'production'",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Write" && ctx.toolName !== "Edit") return allow();
+    const path = ctx.toolInput?.file_path ?? "";
+    if (path.includes("production")) {
+      return deny("Writes to production paths are blocked");
+    }
+    return allow();
+  },
+});
+```
+
+Installala:
+
+```bash
+failproofai policies --install --custom ./my-policies.js
+```
+
+---
+
+## Due modi per caricare le politiche personalizzate
+
+### Opzione 1: Basata su convenzione (consigliata)
+
+Inserisci i file `*policies.{js,mjs,ts}` in `.failproofai/policies/` e verranno caricati automaticamente — nessun flag o modifica di configurazione necessaria. Funziona come i git hook: inserisci un file e basta.
+
+```
+# Livello di progetto — salvato in git, condiviso con il team
+.failproofai/policies/security-policies.mjs
+.failproofai/policies/workflow-policies.mjs
+
+# Livello utente — personale, si applica a tutti i progetti
+~/.failproofai/policies/my-policies.mjs
+```
+
+**Come funziona:**
+- Entrambe le directory di progetto e utente vengono scansionate (unione — non first-scope-wins)
+- I file vengono caricati alfabeticamente all'interno di ogni directory. Prefissi con `01-`, `02-` per controllare l'ordine
+- Solo i file che corrispondono a `*policies.{js,mjs,ts}` vengono caricati; gli altri file vengono ignorati
+- Ogni file viene caricato indipendentemente (fail-open per file)
+- Funziona insieme alle politiche esplicite `--custom` e incorporate
+
+<Tip>
+Le politiche di convenzione sono il modo più semplice per costruire uno standard di qualità per la tua organizzazione. Salva `.failproofai/policies/` in git e ogni membro del team ottiene automaticamente le stesse regole — nessuna configurazione per sviluppatore necessaria. Man mano che il tuo team scopre nuove modalità di errore, aggiungi una politica e fai il push. Nel tempo questi diventano uno standard di qualità dinamico che continua a migliorare con ogni contributo.
+</Tip>
+
+### Opzione 2: Percorso file esplicito
+
+```bash
+# Installa con un file di politiche personalizzate
+failproofai policies --install --custom ./my-policies.js
+
+# Sostituisci i percorsi della politica personalizzata
+failproofai policies --install --custom ./new-policies.js
+
+# Configura più file espliciti (caricati nell'ordine del flag)
+failproofai policies --install --custom ./security.js --custom ./workflow.js
+
+# Rimuovi tutti i percorsi della politica personalizzata esplicita dalla configurazione
+failproofai policies --uninstall --custom
+```
+
+I percorsi assoluti risolti vengono archiviati in `policies-config.json` come `customPoliciesPaths`. Ripeti `--custom` per configurare più file. Le configurazioni esistenti che utilizzano il campo legacy `customPoliciesPath` continuano a funzionare. I file vengono caricati di nuovo a ogni evento hook — non c'è caching tra gli eventi.
+
+Ogni politica registrata appare con il proprio interruttore nel dashboard. Lo spegnimento di una politica registra il suo ID qualificato con la fonte in `disabledCustomPolicies`; il file e le altre sue politiche continuano a caricarsi, mentre la politica disabilitata viene esclusa prima della corrispondenza degli eventi. I nomi di politica duplicati tra i file hanno interruttori indipendenti.
+
+### Usarli insieme
+
+Le politiche di convenzione e i file espliciti `--custom` possono coesistere. Ordine di caricamento:
+
+1. File `customPoliciesPaths` espliciti (nell'ordine configurato)
+2. File di convenzione di progetto (`{cwd}/.failproofai/policies/`, alfabetici)
+3. File di convenzione utente (`~/.failproofai/policies/`, alfabetici)
+
+---
+
+## API
+
+### Importazione
+
+```js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+```
+
+### `customPolicies.add(hook)`
+
+Registra una politica. Chiama questo quanto necessario per più politiche nello stesso file.
+
+```ts
+customPolicies.add({
+  name: string;                         // richiesto - identificatore univoco
+  description?: string;                 // mostrato nell'output di `failproofai policies`
+  match?: { events?: HookEventType[] }; // filtra per tipo di evento; ometti per abbinare tutti
+  fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
+});
+```
+
+### Aiutanti per le decisioni
+
+| Funzione | Effetto | Usa quando |
+|----------|--------|----------|
+| `allow()` | Consenti l'operazione silenziosamente | L'azione è sicura, nessun messaggio necessario |
+| `deny(message)` | Blocca l'operazione | L'agente non dovrebbe eseguire questa azione |
+| `instruct(message)` | Aggiungi contesto senza bloccare | Dai all'agente contesto extra per rimanere in traccia |
+
+`deny(message)` - il messaggio appare a Claude con prefisso `"Blocked by failproofai:"`. Un singolo `deny` interrompe tutta la valutazione successiva.
+
+`instruct(message)` - il messaggio viene aggiunto al contesto di Claude per la chiamata dello strumento corrente. Tutti i messaggi `instruct` vengono accumulati e consegnati insieme.
+
+<Tip>
+Puoi aggiungere indicazioni aggiuntive a qualsiasi messaggio `deny` o `instruct` aggiungendo un campo `hint` in `policyParams` — nessuna modifica del codice necessaria. Questo funziona anche per le politiche personalizzate (`custom/`), di convenzione di progetto (`.failproofai-project/`), e di convenzione utente (`.failproofai-user/`). Vedi [Configuration → hint](/it/configuration#hint-cross-cutting) per i dettagli.
+</Tip>
+
+### Messaggi allow informativi
+
+`allow(message)` consente l'operazione **e** invia un messaggio informativo a Claude. Il messaggio viene consegnato come `additionalContext` nella risposta stdout del gestore hook — lo stesso meccanismo utilizzato da `instruct`, ma semanticamente diverso: è un aggiornamento di stato, non un avvertimento.
+
+| Funzione | Effetto | Usa quando |
+|----------|--------|----------|
+| `allow(message)` | Consenti e invia contesto a Claude | Conferma che un controllo è passato, o spiega perché un controllo è stato saltato |
+
+Casi di utilizzo:
+- **Conferme di stato:** `allow("All CI checks passed.")` — dice a Claude che tutto è verde
+- **Spiegazioni fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — dice a Claude perché un controllo è stato saltato in modo da avere il contesto completo
+- **Più messaggi si accumulano:** se diverse politiche restituiscono ciascuna `allow(message)`, tutti i messaggi vengono uniti con newline e consegnati insieme
+
+```js
+customPolicies.add({
+  name: "confirm-branch-status",
+  match: { events: ["Stop"] },
+  fn: async (ctx) => {
+    const cwd = ctx.session?.cwd;
+    if (!cwd) return allow("No working directory, skipping branch check.");
+
+    // ... check branch status ...
+    if (allPushed) {
+      return allow("Branch is up to date with remote.");
+    }
+    return deny("Unpushed changes detected.");
+  },
+});
+```
+
+### Campi `PolicyContext`
+
+| Campo | Tipo | Descrizione |
+|-------|------|-------------|
+| `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` |
+| `toolName` | `string \| undefined` | Lo strumento chiamato (ad es. `"Bash"`, `"Write"`, `"Read"`) |
+| `toolInput` | `Record<string, unknown> \| undefined` | I parametri di input dello strumento |
+| `payload` | `Record<string, unknown>` | Payload di evento grezzo completo da Claude Code |
+| `session` | `SessionMetadata \| undefined` | Contesto di sessione (vedi sotto) |
+
+### Campi `SessionMetadata`
+
+| Campo | Tipo | Descrizione |
+|-------|------|-------------|
+| `sessionId` | `string` | Identificatore di sessione Claude Code |
+| `cwd` | `string` | Directory di lavoro della sessione Claude Code |
+| `transcriptPath` | `string` | Percorso del file trascrizione JSONL della sessione |
+
+### Tipi di evento
+
+| Evento | Quando si attiva | Contenuti `toolInput` |
+|-------|--------------|----------------------|
+| `PreToolUse` | Prima che Claude esegua uno strumento | L'input dello strumento (ad es. `{ command: "..." }` per Bash) |
+| `PostToolUse` | Dopo il completamento di uno strumento | L'input dello strumento + `tool_result` (l'output) |
+| `Notification` | Quando Claude invia una notifica | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - gli hook devono sempre restituire `allow()`, non possono bloccare le notifiche |
+| `Stop` | Quando la sessione Claude termina | Vuoto |
+
+---
+
+## Ordine di valutazione
+
+Le politiche vengono valutate in questo ordine:
+
+1. Politiche incorporate (nell'ordine di definizione)
+2. Politiche personalizzate esplicite da `customPoliciesPath` (nell'ordine di `.add()`)
+3. Politiche di convenzione da `.failproofai/policies/` di progetto (file alfabetici, ordine di `.add()` all'interno)
+4. Politiche di convenzione da `~/.failproofai/policies/` utente (file alfabetici, ordine di `.add()` all'interno)
+
+<Note>
+Il primo `deny` interrompe tutte le politiche successive. Tutti i messaggi `instruct` vengono accumulati e consegnati insieme.
+</Note>
+
+---
+
+## Importazioni transitive
+
+I file di politica personalizzata possono importare moduli locali utilizzando percorsi relativi:
+
+```js
+// my-policies.js
+import { isBlockedPath } from "./utils.js";
+import { checkApproval } from "./approval-client.js";
+
+customPolicies.add({
+  name: "approval-gate",
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const approved = await checkApproval(ctx.toolInput?.command, ctx.session?.sessionId);
+    return approved ? allow() : deny("Approval required for this command");
+  },
+});
+```
+
+Tutti gli import relativi raggiungibili dal file di entry vengono risolti. Questo è implementato riscrivendo gli import `from "failproofai"` al percorso dist effettivo e creando file `.mjs` temporanei per garantire la compatibilità ESM.
+
+---
+
+## Filtraggio del tipo di evento
+
+Usa `match.events` per limitare quando una politica si attiva:
+
+```js
+customPolicies.add({
+  name: "require-summary-on-stop",
+  match: { events: ["Stop"] },
+  fn: async (ctx) => {
+    // Si attiva solo quando la sessione termina
+    // ctx.session.transcriptPath contiene il log di sessione completo
+    return allow();
+  },
+});
+```
+
+Ometti completamente `match` per attivare su ogni tipo di evento.
+
+---
+
+## Gestione degli errori e modalità di errore
+
+Le politiche personalizzate sono **fail-open**: gli errori non blocchiano mai le politiche incorporate o causano il crash del gestore hook.
+
+| Errore | Comportamento |
+|---------|----------|
+| `customPoliciesPath` non impostato | Nessuna politica personalizzata esplicita viene eseguita; le politiche di convenzione e incorporate continuano normalmente |
+| File non trovato | Avviso registrato in `~/.failproofai/hook.log`; le incorporate continuano |
+| Errore di sintassi/importazione (esplicito) | Errore registrato in `~/.failproofai/hook.log`; le politiche personalizzate esplicite saltate |
+| Errore di sintassi/importazione (convenzione) | Errore registrato; quel file saltato, altri file di convenzione ancora caricati |
+| `fn` butta a runtime | Errore registrato; quel hook trattato come `allow`; altri hook continuano |
+| `fn` impiega più di 10s | Timeout registrato; trattato come `allow` |
+| Directory di convenzione mancante | Nessuna politica di convenzione viene eseguita; nessun errore |
+
+<Tip>
+Per debuggare gli errori di politica personalizzata, guarda il file di log:
+
+```bash
+tail -f ~/.failproofai/hook.log
+```
+</Tip>
+
+---
+
+## Esempio completo: più politiche
+
+```js
+// my-policies.js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+
+// Impedisci all'agente di scrivere nella directory secrets/
+customPolicies.add({
+  name: "block-secrets-dir",
+  description: "Prevent agent from writing to secrets/ directory",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow();
+    const path = ctx.toolInput?.file_path ?? "";
+    if (path.includes("secrets/")) return deny("Writing to secrets/ is not permitted");
+    return allow();
+  },
+});
+
+// Mantieni l'agente in traccia: verifica i test prima di eseguire il commit
+customPolicies.add({
+  name: "remind-test-before-commit",
+  description: "Keep the agent on track: verify tests pass before committing",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = ctx.toolInput?.command ?? "";
+    if (/git\s+commit/.test(cmd)) {
+      return instruct("Verify all tests pass before committing. Run `bun test` if you haven't already.");
+    }
+    return allow();
+  },
+});
+
+// Impedisci i cambiamenti di dipendenza non pianificati durante il congelamento
+customPolicies.add({
+  name: "dependency-freeze",
+  description: "Prevent unplanned dependency changes during freeze period",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = ctx.toolInput?.command ?? "";
+    const isInstall = /^(npm install|yarn add|bun add|pnpm add)\s+\S/.test(cmd);
+    if (isInstall && process.env.DEPENDENCY_FREEZE === "1") {
+      return deny("Package installs are frozen. Unset DEPENDENCY_FREEZE to allow.");
+    }
+    return allow();
+  },
+});
+
+export { customPolicies };
+```
+
+---
+
+## Esempi
+
+La directory `examples/` contiene file di politica pronti all'uso:
+
+| File | Contenuti |
+|------|----------|
+| `examples/policies-basic.js` | Cinque politiche iniziali che coprono modalità di errore dell'agente comuni |
+| `examples/policies-advanced/index.js` | Pattern avanzati: importazioni transitive, chiamate asincrone, scrubbing dell'output, e hook di fine sessione |
+| `examples/convention-policies/security-policies.mjs` | Politiche di sicurezza basate su convenzione (blocca scritture .env, previeni la riscrittura della cronologia git) |
+| `examples/convention-policies/workflow-policies.mjs` | Politiche di flusso di lavoro basate su convenzione (promemoria dei test, file di audit writes) |
+
+### Utilizzo di esempi di file espliciti
+
+```bash
+failproofai policies --install --custom ./examples/policies-basic.js
+```
+
+### Utilizzo di esempi basati su convenzione
+
+```bash
+# Copia a livello di progetto
+mkdir -p .failproofai/policies
+cp examples/convention-policies/*.mjs .failproofai/policies/
+
+# O copia a livello di utente
+mkdir -p ~/.failproofai/policies
+cp examples/convention-policies/*.mjs ~/.failproofai/policies/
+```
+
+Nessun comando di installazione necessario — i file vengono raccolti automaticamente al prossimo evento hook.