Configurazione

​

Ambiti di configurazione

​

Regole di merge

project:  ["block-sudo"]
local:    ["block-rm-rf"]
global:   ["block-sudo", "sanitize-api-keys"]

resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← unione deduplicated

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

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

​

Formato del file di configurazione

{
  "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

​

policyParams

​

hint (multi-policy)

{
  "policyParams": {
    "block-force-push": {
      "hint": "Try creating a fresh branch instead."
    },
    "block-sudo": {
      "allowPatterns": ["sudo apt-get"],
      "hint": "Use apt-get directly without sudo."
    },
    "custom/my-policy": {
      "hint": "Ask the user for approval first."
    }
  }
}

​

customPoliciesPath

​

Policy basate su convenzione

​

llm

{
  "llm": {
    "model": "claude-sonnet-4-6",
    "apiKey": "sk-ant-..."
  }
}

​

Gestione della configurazione dalla CLI

• Impostazioni CLI agente — dice all’agente di chiamare failproofai --hook <event> su ogni tool use:
  • Claude Code: ~/.claude/settings.json (user), <cwd>/.claude/settings.json (project), <cwd>/.claude/settings.local.json (local)
  • OpenAI Codex: ~/.codex/hooks.json (user), <cwd>/.codex/hooks.json (project) — Codex non ha un ambito local
  • GitHub Copilot CLI (beta): ~/.copilot/hooks/failproofai.json (user), <cwd>/.github/hooks/failproofai.json (project) — Copilot non ha ambito local. Le voci di hook utilizzano i campi di comando bash/powershell con chiave OS di Copilot con timeoutSec; il file porta un marcatore di livello superiore version: 1. Il supporto di Copilot CLI è beta mentre verifichiamo lo schema di registrazione di events.jsonl (che i documenti pubblici non specificano) rispetto a più sessioni nel mondo reale.
  • Cursor Agent (beta): ~/.cursor/hooks.json (user), <cwd>/.cursor/hooks.json (project) — Cursor non ha ambito local. Le voci di hook utilizzano il modulo a forma di Claude {type, command, timeout} (nessuna divisione bash/powershell), ma memorizzate sotto chiavi di evento camelCase (preToolUse, beforeSubmitPrompt, …) in un array piatto per lo schema di hook di Cursor](https://cursor.com/docs/hooks); il file porta un marcatore di livello superiore version: 1. Il gestore canonicalizza camelCase → PascalCase tramite CURSOR_EVENT_MAP in modo che le policy builtin esistenti si attivino invariate. Il supporto di Cursor Agent è beta mentre verifichiamo il formato di trascrizione di Cursor su disco (non specificato nei documenti pubblici) rispetto a più installazioni nel mondo reale.
  • OpenCode (beta): ~/.config/opencode/opencode.json + ~/.config/opencode/plugins/failproofai.mjs (user), <cwd>/.opencode/opencode.json + <cwd>/.opencode/plugins/failproofai.mjs (project) — OpenCode non ha ambito local. A differenza degli altri sei CLI, OpenCode ha nessun sistema di hook di comando esterno: carica i 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 plugin shim generato che esegue in subprocess il binario failproofai e traduce la risposta JSON a forma di Claude del binario nella semantica del plugin: throw new Error() per il deny di evento tool (annulla la chiamata dello strumento), client.session.prompt(...) per instruct E per Stop / SubagentStop deny (invia il motivo di deny come il prossimo messaggio utente — l’unico canale di retry forzato poiché session.idle è solo notifica e il lancio 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 degli strumenti (camelCase → snake_case tramite OPENCODE_TOOL_INPUT_MAP per Read / Write / Edit, ad es. filePath → file_path, oldString → old_string) prima di inoltrarli al binario, quindi i builtin di controllo del percorso come block-read-outside-cwd, block-env-files, e block-secrets-write si attivano invariati sulle chiamate di tool di OpenCode. Le sessioni vivono nel database SQLite di opencode a ~/.local/share/opencode/opencode.db; il visualizzatore di sessioni del dashboard li legge tramite opencode db --format json e opencode export <id>. Il supporto di OpenCode è beta mentre verifichiamo il comportamento su versioni e rispetto a più sessioni nel mondo reale. Consulta la documentazione dei plugin OpenCode.
  • Pi (beta): ~/.pi/agent/settings.json (user), <cwd>/.pi/settings.json (project) — Pi non ha ambito local. Pi carica pacchetti di estensione TypeScript all’avvio; il file di impostazioni è un array di stringhe piatto {"packages": ["./relative/path", …]}. failproofai scrive una singola voce dell’array dei pacchetti che punta alla sua directory pi-extension/ in bundle. L’estensione internamente si iscrive agli eventi tool_call / user_bash / input / session_start di Pi e esegue il shelling in failproofai --hook <Event> --cli pi; il gestore canonicalizza underscore_lower_snake_case → PascalCase tramite PI_EVENT_MAP in modo che le policy builtin esistenti si attivino invariate. Gli argomenti di input degli strumenti vengono anche canonicalizzati tramite PI_TOOL_INPUT_MAP (Pi’s Read / Write / Edit forniscono path piuttosto che file_path; il mapping della chiave di livello superiore consente a block-env-files e block-secrets-write di attivarsi — block-read-outside-cwd aveva già un fallback path). Il supporto di Pi è beta mentre l’API di estensione di Pi e il layout del log di sessione si stabilizzano.
  • Gemini CLI (beta): ~/.gemini/settings.json (user), <cwd>/.gemini/settings.json (project) — Gemini non ha ambito local (documenta un ambito system a /etc/gemini-cli/settings.json che failproofai non espone). Le voci di hook utilizzano il modulo {type, command, timeout} di Claude racchiuso nello schema matcher {matcher, hooks: [...]} di Gemini con matcher: "*" per impostazione predefinita. Gli eventi sono PascalCase (SessionStart, BeforeAgent, AfterAgent, BeforeModel, AfterModel, BeforeToolSelection, BeforeTool, AfterTool, PreCompress, Notification, SessionEnd); il gestore mappa ai nomi canonici di Claude tramite GEMINI_EVENT_MAP. I nomi degli strumenti sono snake_case (run_shell_command, read_file, write_file, replace, …) — il gestore canonicalizza tramite GEMINI_TOOL_MAP in modo che i policy builtin esistenti si attivino invariati. L’evaluator di policy emette la forma piatta {decision: "deny", reason} di Gemini (preferita per il contratto exit-0 della regola d’oro di Gemini), {hookSpecificOutput: {hookEventName, additionalContext}} per l’iniezione di contesto su BeforeAgent / AfterTool / SessionStart, e {decision: "block", reason} su AfterAgent per la semantica di retry forzato. Il supporto di Gemini CLI è beta mentre aumentiamo la copertura nel mondo reale. Consulta la documentazione degli hook di Gemini CLI.
• policies-config.json — dice a failproofai quali policy valutare e con quali parametri (condiviso su tutti i CLI agente)

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 gemini --scope project
failproofai policies --install --cli claude codex copilot cursor opencode pi gemini

• Un CLI rilevato — seleziona automaticamente quel CLI senza richiedere conferma.
• Più CLI rilevati in un terminale interattivo — mostra un prompt single-select con freccia raggruppato in una sezione Detected (N) (con una riga aggregata Install for all N detected + ogni CLI rilevato singolarmente) e una sezione Not installed (M) · install hooks ahead of time che elenca ogni CLI supportato non rilevato come opzione di installazione anticipata (↑↓ per muoversi, Enter per selezionare, ^C per uscire). Il flusso di disinstallazione mostra solo la sezione Detected.
• Più CLI rilevati in un’esecuzione non interattiva (CI, no TTY) — installa per tutti i CLI rilevati senza richiedere conferma.
• Nessuno rilevato — ricade su claude, con un avviso che nessun binario agente è stato trovato in PATH; il comando hook viene comunque scritto in modo che si attivi non appena ne installi uno.

​

Esempio: configurazione a livello di progetto con impostazioni predefinite del team

{
  "enabledPolicies": [
    "block-sudo",
    "block-rm-rf",
    "block-push-master",
    "sanitize-api-keys",
    "block-env-files"
  ],
  "policyParams": {
    "block-push-master": {
      "protectedBranches": ["main", "release", "hotfix"]
    }
  }
}