Configuración

​

Ámbitos de configuración

​

Reglas de combinación

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

resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← unión sin duplicados

project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }

resolved: { allowPatterns: ["sudo apt-get update"] }   ← project gana, global se ignora

project:  (sin entrada para block-sudo)
local:    (sin entrada para block-sudo)
global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }

resolved: { allowPatterns: ["sudo systemctl status"] }  ← se aplica global como respaldo

​

Formato del archivo de configuración

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

​

Referencia de campos

​

enabledPolicies

​

policyParams

​

hint (transversal)

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

​

Políticas basadas en convenciones

​

llm

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

​

Gestión de la configuración desde la CLI

• Configuración de la CLI del agente — indica al agente que llame a failproofai --hook <event> en cada uso de herramienta:
  • Claude Code: ~/.claude/settings.json (usuario), <cwd>/.claude/settings.json (proyecto), <cwd>/.claude/settings.local.json (local)
  • OpenAI Codex: ~/.codex/hooks.json (usuario), <cwd>/.codex/hooks.json (proyecto) — Codex no tiene ámbito local
  • GitHub Copilot CLI (beta): ~/.copilot/hooks/failproofai.json (usuario), <cwd>/.github/hooks/failproofai.json (proyecto) — Copilot no tiene ámbito local. Las entradas de hook usan los campos de comando bash/powershell de Copilot según el sistema operativo con timeoutSec; el archivo lleva un marcador version: 1 de nivel superior. El soporte de Copilot CLI está en beta mientras verificamos el esquema de registros events.jsonl (que la documentación pública no especifica) con más sesiones reales.
  • Cursor Agent (beta): ~/.cursor/hooks.json (usuario), <cwd>/.cursor/hooks.json (proyecto) — Cursor no tiene ámbito local. Las entradas de hook usan la forma de Claude {type, command, timeout} (sin división bash/powershell), pero almacenadas bajo claves de evento en camelCase (preToolUse, beforeSubmitPrompt, …) en un array plano según el esquema de hooks de Cursor; el archivo lleva un marcador version: 1 de nivel superior. El manejador canonicaliza camelCase → PascalCase mediante CURSOR_EVENT_MAP, de modo que las políticas integradas existentes se activan sin cambios. El soporte de Cursor Agent está en beta mientras verificamos el formato en disco de la transcripción de Cursor (no especificado en la documentación pública) con más instalaciones reales.
  • OpenCode (beta): ~/.config/opencode/opencode.json + ~/.config/opencode/plugins/failproofai.mjs (usuario), <cwd>/.opencode/opencode.json + <cwd>/.opencode/plugins/failproofai.mjs (proyecto) — OpenCode no tiene ámbito local. A diferencia de las otras cinco CLIs, OpenCode no tiene un sistema de hooks de comandos externos: carga plugins JS/TS en proceso registrados explícitamente mediante el array plugin: [] en opencode.json (el autodescubrimiento desde .opencode/plugins/ no es cómo se cargan los plugins en opencode v1.14.33). La instalación coloca un pequeño shim de plugin generado que llama al binario failproofai como subproceso y traduce la respuesta JSON de forma Claude del binario de vuelta a la semántica del plugin: throw new Error() para denegar eventos de herramienta (cancela la llamada a la herramienta), client.session.prompt(...) para instruct Y para Stop / SubagentStop deny (envía el motivo de denegación como el siguiente mensaje del usuario — el único canal de reintento forzado, ya que session.idle es solo notificación y lanzar desde él es un no-op), y no-op para allow. El shim canonicaliza tanto los nombres de herramientas (minúsculas → PascalCase mediante OPENCODE_TOOL_MAP) como las claves de argumentos de entrada de herramientas (camelCase → snake_case mediante OPENCODE_TOOL_INPUT_MAP para Read / Write / Edit, p. ej. filePath → file_path, oldString → old_string) antes de reenviar al binario, de modo que las políticas integradas de verificación de rutas como block-read-outside-cwd, block-env-files y block-secrets-write se activan sin cambios en las llamadas a herramientas de OpenCode. Las sesiones viven en la base de datos SQLite de opencode en ~/.local/share/opencode/opencode.db; el visor de sesiones del panel las lee mediante opencode db --format json y opencode export <id>. El soporte de OpenCode está en beta mientras verificamos el comportamiento en distintas versiones y con más sesiones reales. Consulta la documentación de plugins de OpenCode.
  • Pi (beta): ~/.pi/agent/settings.json (usuario), <cwd>/.pi/settings.json (proyecto) — Pi no tiene ámbito local. Pi carga paquetes de extensiones TypeScript al inicio; el archivo de configuración es un array de cadenas plano {"packages": ["./relative/path", …]}. failproofai escribe una única entrada en el array de packages apuntando a su directorio pi-extension/ integrado. La extensión se suscribe internamente a los eventos tool_call / user_bash / input / session_start de Pi y ejecuta failproofai --hook <Event> --cli pi como proceso hijo; el manejador canonicaliza eventos de snake_case en minúsculas → PascalCase mediante PI_EVENT_MAP para que las políticas integradas existentes se activen sin cambios. Los argumentos de entrada de herramientas también se canonizan mediante PI_TOOL_INPUT_MAP (Pi’s Read / Write / Edit entregan path en lugar de file_path; mapear la clave de nivel superior permite que block-env-files y block-secrets-write se activen — block-read-outside-cwd ya tenía un respaldo con path). El soporte de Pi está en beta mientras la API de extensiones de Pi y el diseño del registro de sesiones se estabilizan.
  • Hermes (hermes-agent): ~/.hermes/config.yaml (solo ámbito de usuario — Hermes no tiene configuración de proyecto/local). Hermes es una pasarela de Slack/Telegram, por lo que una instalación intercepta las llamadas a herramientas de todas las plataformas (Slack/Telegram/cli/cron) y de los subagentes internos. Las entradas de hook son un par {command, timeout} (tiempo de espera en segundos) bajo un mapa hooks: indexado por los eventos snake_case de Hermes (pre_tool_call / post_tool_call / on_session_start / on_session_end / subagent_stop); el manejador canonicaliza los eventos mediante HERMES_EVENT_MAP y los nombres de herramientas mediante HERMES_TOOL_MAP para que las políticas integradas se activen sin cambios. La configuración se edita mediante un round-trip YAML Document que preserva los comentarios, de modo que los demás ajustes del operador sobreviven, y la instalación establece hooks_auto_accept: true para que la pasarela sin cabeza (sin TTY) ejecute los hooks sin solicitud de consentimiento. El evaluador emite el contrato stdout {"decision":"block","reason"} de Hermes (Hermes ignora los códigos de salida). Limitaciones: Hermes no tiene un evento Stop de fin de turno, por lo que las políticas integradas require-*-before-stop nunca se activan para él (no aplicable, no roto); instruct degrada a allow con nota registrada (sin canal de contexto adicional); y la redacción de secretos en la salida (sanitize-*) no puede reescribir la salida de herramientas a través del contrato de hook de shell. Hermes es también una fuente de auditoría sin conexión — el panel lee sus sesiones de pasarela directamente desde ~/.hermes/state.db.
• policies-config.json — indica a failproofai qué políticas evaluar y con qué parámetros (compartido entre todas las CLIs de agentes)

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 claude codex copilot cursor opencode pi

• Una CLI detectada — la selecciona automáticamente sin solicitar confirmación.
• Múltiples CLIs detectadas en un terminal interactivo — muestra un prompt de selección única con teclas de flecha, agrupado en una sección Detected (N) (con una fila agregada Install for all N detected + cada CLI detectada individualmente) y una sección Not installed (M) · install hooks ahead of time que lista cada CLI compatible no detectada como opción de instalación anticipada (↑↓ para moverse, Enter para seleccionar, ^C para salir). El flujo de desinstalación muestra solo la sección Detected.
• Múltiples CLIs detectadas en una ejecución no interactiva (CI, sin TTY) — instala para todas las CLIs detectadas sin solicitar confirmación.
• Ninguna detectada — recurre a claude, con una advertencia de que no se encontró ningún binario de agente en el PATH; el comando de hook se escribe de todas formas para que se active en cuanto instales uno.

​

Ejemplo: configuración a nivel de proyecto con valores predeterminados del equipo

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