> ## Documentation Index > Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt > Use this file to discover all available pages before exploring further. # Politiche personalizzate > Crea, testa e distribuisci politiche JavaScript o TypeScript per errori specifici dei tuoi agenti. Le politiche personalizzate trasformano un modello di errore dalle tue tracce o audit in una decisione che viene eseguita mentre un agente lavora. Una politica può consentire un'azione, fornire orientamento all'agente o negare l'azione prima che causi un altro incidente. Utilizza una politica personalizzata quando il comportamento dipende dai tuoi strumenti, percorsi, comandi, ambienti o regole operative. Controlla prima il [catalogo delle politiche integrate](/it/policies/builtin-catalog) per non ricreare un controllo già esistente. ## Crea una politica personalizzata 1. Vai a **Admin → policy editor**, seleziona **New policy** e descrivi l'errore che vuoi prevenire. 2. Aggiungi il codice della politica, quindi testa i match previsti e i match non sicuri nell'editor. Risolvi ogni errore di validazione. 3. Salva la bozza e seleziona **Publish version** per creare una versione immutabile. 4. Vai a **Admin → enforcement**, distribuisci la versione su una macchina di test in modalità **observe** e verifica le sue decisioni in **Observe → policy** prima di applicarla. L'editor di politica utilizzato per creare e pubblicare una politica personalizzata. 1. Crea `.failproofai/policies/checkout-policies.ts`. Il nome del file deve terminare in `policies.js`, `policies.mjs` o `policies.ts`. 2. Registra una o più politiche con `customPolicies.add()`. 3. Valida e installa il file con `failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project`. 4. Attiva un'azione corrispondente e un'azione sicura. Esegui `failproofai policies`, quindi ispeziona le decisioni attribuite in **Observe → policy**. ## Inizia con una regola ristretta Questa politica blocca i comandi Kubernetes distruttivi solo quando il comando ha come target la produzione. Tutto ciò che non rientra in quel modello di errore esatto restituisce `allow()`. ```ts theme={null} import { customPolicies, allow, deny } from "failproofai"; const DESTRUCTIVE_KUBECTL = /\bkubectl\s+(delete|replace)\b/i; const PRODUCTION_TARGET = /(?:--context|--namespace|-n)\s+(prod|production)\b/i; customPolicies.add({ name: "block-destructive-production-kubectl", description: "Block destructive Kubernetes commands against production", match: { events: ["PreToolUse"] }, fn: async ({ toolName, toolInput }) => { if (toolName !== "Bash") return allow(); const command = String(toolInput?.command ?? ""); if (!DESTRUCTIVE_KUBECTL.test(command)) return allow(); if (!PRODUCTION_TARGET.test(command)) return allow(); return deny( "Destructive production Kubernetes commands require the approved deployment workflow.", ); }, }); ``` Le buone politiche sono abbastanza ristrette da spiegare in una frase. Adatta l'azione osservabile, non l'intenzione che speri avesse l'agente, e restituisci `allow()` non appena la regola non si applica. ## Scegli una decisione | Helper | Risultato | Usalo quando | | ------------------ | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | `allow(reason?)` | L'operazione continua. | La politica non si applica o l'azione è sicura. | | `instruct(reason)` | L'operazione continua con orientamento dove supportato dall'harness. | Vuoi guidare l'agente verso un approccio migliore senza applicare un invariante. | | `deny(reason)` | L'operazione è bloccata quando l'evento e l'harness supportano il blocco. | L'azione non deve procedere. | Scrivi il motivo per l'agente che deve recuperare. Spiega cosa è stato rilevato e cosa dovrebbe fare invece. Non utilizzare `instruct()` per un confine di sicurezza. La consegna della guida varia a seconda dell'harness dell'agente. Utilizza `deny()` quando l'azione deve essere prevenuta. ## Oggetto policy ```ts theme={null} customPolicies.add({ name: "policy-name", description: "What this policy prevents", match: { events: ["PreToolUse"] }, fn: async (ctx) => allow(), }); ``` | Campo | Obbligatorio | Descrizione | | -------------- | ------------ | ------------------------------------------------------------------------------------------------ | | `name` | Sì | Identificatore stabile per la politica. Mantieni i nomi unici tra i file. | | `description` | No | Scopo leggibile mostrato negli elenchi di politiche e nelle decisioni. | | `match.events` | No | Tipi di evento che invocano la politica. Omettere `match` la invoca per ogni evento disponibile. | | `fn` | Sì | Funzione sincrona o asincrona che restituisce un risultato `allow`, `instruct` o `deny`. | Filtra gli strumenti dentro `fn`. `match.toolNames` non fa parte del tipo di politica personalizzata pubblico. ## Contesto della politica Ogni politica riceve un `PolicyContext`. | Campo | Tipo | Cosa contiene | | ----------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `eventType` | `HookEventType` | Evento normalizzato attualmente in valutazione. | | `toolName` | `string \| undefined` | Nome dello strumento canonico come `Bash`, `Read`, `Write` o `Edit`. | | `toolInput` | `Record \| undefined` | Input canonico per la chiamata dello strumento corrente. | | `payload` | `Record` | Payload dell'evento normalizzato completo. | | `session` | `SessionMetadata \| undefined` | ID sessione, directory di lavoro, percorso della trascrizione, modalità di autorizzazione e metadati dell'harness se disponibili. | | `cli` | `string \| undefined` | Harness agente di origine, come `claude`, `codex` o `cursor`. | | `params` | `Record` | Parametri delle politiche integrate. Le politiche personalizzate ricevono attualmente un oggetto vuoto. | Tratta ogni valore opzionale come genuinamente opzionale. Le versioni dell'agente e i tipi di evento non forniscono tutti gli stessi campi. ### Input comuni degli strumenti Failproof AI normalizza i comuni strumenti tra gli harness supportati in modo che una politica possa di solito utilizzare una sola forma di input. | Strumento | Campi comuni | | --------- | --------------------------------------- | | `Bash` | `command` | | `Read` | `file_path` | | `Write` | `file_path`, `content` | | `Edit` | `file_path`, `old_string`, `new_string` | | `Grep` | `pattern`, `path` | Utilizza la coercizione difensiva perché i valori dell'input dello strumento sono tipizzati come `unknown`: ```ts theme={null} const command = String(ctx.toolInput?.command ?? ""); const filePath = String(ctx.toolInput?.file_path ?? ""); ``` ## Scegli l'evento | Evento | Quando viene eseguito | Uso tipico | | ----------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `PreToolUse` | Prima dell'esecuzione di uno strumento. | Blocca o guida comandi, scritture, letture e azioni esterne. | | `PostToolUse` | Dopo che uno strumento restituisce. | Ispeziona i risultati prima che raggiungano l'agente. Un deny blocca l'intero risultato; non redige campi selezionati. | | `PermissionRequest` | Quando l'agente richiede un'autorizzazione. | Applica regole di autorizzazione specifiche dell'organizzazione. | | `UserPromptSubmit` | Prima che un prompt inviato continui. | Rifiuta istruzioni proibite o aggiungi orientamento del flusso di lavoro. | | `Stop` | Quando l'agente tenta di terminare. | Richiedi una condizione di completamento raggiungibile, come un passo di verifica locale. | | `SubagentStop` | Quando un sub-agente tenta di terminare. | Controlla il lavoro delegato prima che torni al padre. | | `SessionStart` / `SessionEnd` | Ai confini della sessione. | Registra o controlla lo stato a livello di sessione. | La disponibilità dell'evento e il comportamento di blocco dipendono dall'harness dell'agente. Vedi [Agent harnesses](/it/reference/harnesses) prima di fare affidamento su un evento su una flotta mista. `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `PreToolUse`, `PermissionRequest`, `PermissionDenied`, `PostToolUse`, `PostToolUseFailure`, `Notification`, `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `Stop`, `StopFailure`, `TeammateIdle`, `InstructionsLoaded`, `ConfigChange`, `CwdChanged`, `FileChanged`, `WorktreeCreate`, `WorktreeRemove`, `PreCompact`, `PostCompact`, `Elicitation`, `ElicitationResult`, `UserPromptExpansion`, `PostToolBatch` e `Setup`. ## Crea modelli di politica comuni ### Blocca le scritture nei percorsi protetti ```ts theme={null} import { customPolicies, allow, deny } from "failproofai"; customPolicies.add({ name: "block-generated-file-edits", description: "Require generated files to be changed through their generator", match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow(); const filePath = String(ctx.toolInput?.file_path ?? ""); if (!/(^|\/)(dist|generated)\//.test(filePath)) return allow(); return deny("Edit the source and run the generator instead of changing generated output."); }, }); ``` ### Fornisci orientamento senza blocco ```ts theme={null} import { customPolicies, allow, instruct } from "failproofai"; customPolicies.add({ name: "prefer-reviewed-deploy-command", description: "Guide agents toward the reviewed deployment wrapper", match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); const command = String(ctx.toolInput?.command ?? ""); if (!/^kubectl\s+apply\b/.test(command.trim())) return allow(); return instruct("Use ./scripts/deploy-reviewed instead of invoking kubectl directly."); }, }); ``` ### Controlla il completamento della sessione ```ts theme={null} import { execFileSync } from "node:child_process"; import { customPolicies, allow, deny } from "failproofai"; customPolicies.add({ name: "require-clean-typecheck", description: "Require the project typecheck to pass before the agent finishes", match: { events: ["Stop"] }, fn: async (ctx) => { const cwd = ctx.session?.cwd; if (!cwd) return allow(); try { execFileSync("bunx", ["tsc", "--noEmit"], { cwd, stdio: "ignore", timeout: 8_000, }); return allow(); } catch { return deny("Fix the typecheck errors before finishing the task."); } }, }); ``` Un evento `Stop` negato può far ritentare l'agente. Controlla solo una condizione che l'agente può soddisfare nell'ambiente corrente e delimita ogni subprocess o chiamata di rete. ## Carica i file di politica ### File di convenzione I file di convenzione si caricano automaticamente: ```text theme={null} /.failproofai/policies/security-policies.ts ~/.failproofai/policies/personal-policies.mjs ``` * Le directory delle politiche di progetto e utente vengono caricate entrambe. * I file si caricano alfabeticamente all'interno di ogni directory. * Un file deve terminare in `policies.js`, `policies.mjs` o `policies.ts`. * Sono supportate più chiamate a `customPolicies.add()` in un file. * Sono supportati gli import relativi da moduli locali. * Le politiche di progetto possono essere commesse in modo che le stesse regole seguano il repository. ### File espliciti Utilizza percorsi espliciti quando la validazione o la configurazione deve nominare direttamente il file di entry: ```bash theme={null} failproofai policies --install \ --custom ./security.policies.ts \ --custom ./workflow.policies.ts \ --scope project ``` I file espliciti si caricano per primi, seguiti dai file di convenzione del progetto e quindi dai file di convenzione dell'utente. Un file scoperto attraverso entrambi i percorsi viene caricato una volta. ## Valida e testa La validazione esegue il modulo attraverso il loader di produzione e conferma che registra almeno una politica. ```bash theme={null} failproofai policies --install \ --custom ./.failproofai/policies/checkout-policies.ts \ --scope project failproofai policies ``` La validazione rileva file mancanti, errori di sintassi, import non risolti, eccezioni di primo livello e timeout di caricamento del modulo. Non prova che la tua logica di corrispondenza sia corretta. Testa almeno questi casi: * Un'azione che deve corrispondere e produrre il motivo della politica previsto. * Un'azione vicina ma sicura che deve restituire `allow()`. * Campi dello strumento mancanti o malformati. * Sintassi alternativi del comando, percorsi, quotazione, maiuscole/minuscole e spazi vuoti. * Una dipendenza subprocess o di rete non disponibile. Attribuisci il risultato alla tua politica personalizzata in **Observe → policy**. Un test bloccato non è sufficiente se una politica integrata diversa ha preso la decisione. ## Comportamento a runtime * Le politiche integrate vengono valutate prima delle politiche personalizzate. * Il primo `deny` interrompe l'ulteriore valutazione della politica. * Più risultati di `instruct` possono essere combinati quando nessuna politica nega l'evento. * Una funzione di politica ha una scadenza di esecuzione di 10 secondi. * Un'eccezione lanciata o un timeout viene registrato e trattato come `allow()`. * Un file di convenzione che non riesce a caricarsi viene saltato; altri file personalizzati e le politiche integrate continuano. * Il caricamento del modulo di primo livello ha anche una scadenza di 10 secondi. * La modalità di osservazione cloud esegue la politica ma registra una decisione non-allow senza applicarla. Mantieni i moduli di politica deterministici e veloci. Evita le chiamate di rete di primo livello o l'avvio del server. Delimita il lavoro all'interno di `fn`, cattura gli errori di dipendenza e scegli deliberatamente se quell'errore deve consentire o negare l'operazione. ## Export dell'API | Export | Scopo | | ---------------------------- | ------------------------------------------------------------------------ | | `customPolicies.add(policy)` | Registra una politica personalizzata al caricamento del modulo. | | `allow(reason?)` | Permetti l'operazione. | | `instruct(reason)` | Permetti l'operazione e fornisci orientamento dove supportato. | | `deny(reason)` | Blocca l'operazione dove supportato. | | `getCustomHooks()` | Restituisci le politiche attualmente registrate nel registro del modulo. | | `clearCustomHooks()` | Cancella quel registro, principalmente per test e loader. | TypeScript export `PolicyContext`, `PolicyResult`, `CustomHook`, `PolicyDecision` e `PolicyFunction`. Pubblica una versione, distribuiscila in modalità observe, verifica le decisioni e passa all'enforcement.