failproofai 1.0.1-beta.0 → 1.0.1

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

@@ -0,0 +1,271 @@
+---
+title: Configuración
+description: "Formato del archivo de configuración, sistema de tres ámbitos y reglas de combinación"
+icon: gear
+---
+
+failproofai utiliza archivos de configuración JSON para controlar qué políticas están activas, cómo se comportan y desde dónde se cargan las políticas personalizadas. La configuración está diseñada para compartirse fácilmente con tu equipo: confírmala en tu repositorio y cada desarrollador tendrá la misma red de seguridad para el agente.
+
+---
+
+## Ámbitos de configuración
+
+Existen tres ámbitos de configuración, evaluados en orden de prioridad:
+
+| Ámbito | Ruta del archivo | Propósito |
+|--------|-----------------|-----------|
+| **project** | `.failproofai/policies-config.json` | Configuración por repositorio, confirmada en control de versiones |
+| **local** | `.failproofai/policies-config.local.json` | Anulaciones personales por repositorio, ignoradas por git |
+| **global** | `~/.failproofai/policies-config.json` | Valores predeterminados del usuario para todos los proyectos |
+
+Cuando failproofai recibe un evento de hook, carga y combina los tres archivos que existen para el directorio de trabajo actual.
+
+### Reglas de combinación
+
+**`enabledPolicies`** — la unión de los tres ámbitos. Una política habilitada en cualquier nivel está activa.
+
+```text
+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
+```
+
+**`policyParams`** — el primer ámbito que defina los parámetros para una política dada prevalece por completo. No se realiza una combinación profunda de los valores dentro de los parámetros de una política.
+
+```text
+project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
+global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
+
+resolved: { allowPatterns: ["sudo apt-get update"] }   ← project prevalece, global se ignora
+```
+
+```text
+project:  (sin entrada block-sudo)
+local:    (sin entrada block-sudo)
+global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
+
+resolved: { allowPatterns: ["sudo systemctl status"] }  ← cae al global
+```
+
+**`customPoliciesPaths` / `customPoliciesPath`** — el primer ámbito que defina cualquiera de las dos formas prevalece.
+
+**`disabledCustomPolicies`** — unión de todos los ámbitos. El panel escribe un
+ID cualificado por fuente aquí cuando desactivas una política individual desde un
+archivo de políticas explícito o de convención. Las políticas no listadas permanecen habilitadas
+de forma predeterminada; los IDs incluyen el archivo fuente para que las políticas con el mismo nombre en múltiples archivos
+puedan controlarse de forma independiente.
+
+**`llm`** — el primer ámbito que lo defina prevalece.
+
+---
+
+## Formato del archivo de configuración
+
+```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"
+}
+```
+
+---
+
+## Referencia de campos
+
+### `enabledPolicies`
+
+Tipo: `string[]`
+
+Lista de nombres de políticas a habilitar. Los nombres deben coincidir exactamente con los identificadores de política mostrados por `failproofai policies`. Consulta [Políticas integradas](/es/built-in-policies) para ver la lista completa.
+
+Las políticas que no están en `enabledPolicies` están inactivas, incluso si tienen entradas en `policyParams`.
+
+### `policyParams`
+
+Tipo: `Record<string, Record<string, unknown>>`
+
+Anulaciones de parámetros por política. La clave exterior es el nombre de la política; las claves interiores son específicas de cada política. Cada política documenta sus parámetros disponibles en [Políticas integradas](/es/built-in-policies).
+
+Si una política tiene parámetros pero no los especificas, se utilizan los valores predeterminados integrados de la política. Los usuarios que no configuran `policyParams` en absoluto obtienen un comportamiento idéntico al de versiones anteriores.
+
+Las claves desconocidas dentro del bloque de parámetros de una política se ignoran silenciosamente en el momento de dispararse el hook, pero se marcan como advertencias cuando ejecutas `failproofai policies`.
+
+#### `hint` (transversal)
+
+Tipo: `string` (opcional)
+
+Un mensaje que se añade al motivo cuando una política devuelve `deny` o `instruct`. Úsalo para dar a Claude orientación práctica sin modificar la política en sí.
+
+Funciona con cualquier tipo de política: integrada, personalizada (`custom/`), convención de proyecto (`.failproofai-project/`) o convención de usuario (`.failproofai-user/`).
+
+```json
+{
+  "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."
+    }
+  }
+}
+```
+
+Cuando `block-force-push` deniega, Claude ve: *"Force-pushing is blocked. Try creating a fresh branch instead."*
+
+Los valores que no son cadenas de texto y las cadenas vacías se ignoran silenciosamente. Si `hint` no está definido, el comportamiento no cambia (compatible con versiones anteriores).
+
+### `customPoliciesPath`
+
+Tipo: `string` (ruta absoluta)
+
+Ruta a un archivo JavaScript que contiene políticas de hook personalizadas. Este valor lo establece automáticamente `failproofai policies --install --custom <path>` (la ruta se resuelve a absoluta antes de almacenarse).
+
+El archivo se carga de nuevo en cada evento de hook; no hay caché. Consulta [Políticas personalizadas](/es/custom-policies) para más detalles sobre cómo crearlas.
+
+### Políticas basadas en convención
+
+Además del `customPoliciesPath` explícito, failproofai descubre y carga automáticamente archivos de políticas desde los directorios `.failproofai/policies/`:
+
+| Nivel | Directorio | Ámbito |
+|-------|-----------|--------|
+| Proyecto | `.failproofai/policies/` | Compartido con el equipo mediante control de versiones |
+| Usuario | `~/.failproofai/policies/custom-policies/` | Personal, se aplica a todos los proyectos |
+
+<Note>
+  El directorio de nivel de usuario se movió un nivel más abajo en la
+  reorganización del directorio home. Los archivos que quedaron en la antigua ruta `~/.failproofai/policies/` se mueven
+  automáticamente a `custom-policies/` la primera vez que ejecutas cualquier comando `failproofai`
+  después de actualizar, y el comando te indica qué archivos movió.
+</Note>
+
+**Coincidencia de archivos:** Solo se cargan los archivos que coincidan con `*policies.{js,mjs,ts}` (por ejemplo, `security-policies.mjs`, `workflow-policies.js`). Los demás archivos del directorio se ignoran.
+
+**Sin configuración necesaria:** Las políticas de convención no requieren ninguna entrada en `policies-config.json`. Solo coloca los archivos en el directorio y se detectarán en el siguiente evento de hook.
+
+**Carga por unión:** Se analizan tanto el directorio de convención del proyecto como el del usuario. Se cargan todos los archivos coincidentes de ambos niveles (a diferencia de `customPoliciesPath`, que usa el principio de primer ámbito ganador).
+
+Consulta [Políticas personalizadas](/es/custom-policies) para más detalles y ejemplos.
+
+### `llm`
+
+Tipo: `object` (opcional)
+
+Configuración del cliente LLM para políticas que realizan llamadas a IA. No es necesario en la mayoría de los casos.
+
+```json
+{
+  "llm": {
+    "model": "claude-sonnet-4-6",
+    "apiKey": "sk-ant-..."
+  }
+}
+```
+
+---
+
+## Gestión de la configuración desde la CLI
+
+Los comandos `policies --install` y `policies --uninstall` escriben en el archivo de configuración de hooks de tu CLI de agente (los puntos de entrada del hook), mientras que `policies-config.json` es el archivo que gestionas directamente. Los dos son independientes:
+
+- **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` con clave de SO de Copilot con `timeoutSec`; el archivo lleva un marcador de nivel superior `version: 1`. La compatibilidad con Copilot CLI es **beta** mientras verificamos el esquema de registros `events.jsonl` (que la documentación pública no especifica) con más sesiones del mundo real. **El modo de agente de VS Code Copilot Chat (Preview)** lee las configuraciones de hook desde `.github/hooks/*.json`, `~/.copilot/hooks/*.json` y `~/.claude/settings.json` (gobernado por la configuración `chat.hookFilesLocations`) usando el mismo contrato Claude `{hookSpecificOutput:{permissionDecision:"deny",…}}` — exactamente las rutas que esta integración `copilot` y la integración `claude` (`~/.claude/settings.json`) ya escriben, por lo que `failproofai policies --install --cli copilot` (o `--cli claude`) **ya aplica en el modo de agente de VS Code** sin necesidad de una integración `vscode` separada (confirmado en vivo desde los registros de descubrimiento de VS Code).
+  - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (usuario), `<cwd>/.cursor/hooks.json` (proyecto) — Cursor no tiene ámbito `local`. Las entradas de hook usan la forma Claude `{type, command, timeout}` (sin división `bash`/`powershell`), pero almacenadas bajo claves de eventos en camelCase (`preToolUse`, `beforeSubmitPrompt`, …) en un array plano según el [esquema de hooks de Cursor](https://cursor.com/docs/hooks); el archivo lleva un marcador de nivel superior `version: 1`. El manejador canonicaliza camelCase → PascalCase mediante `CURSOR_EVENT_MAP` para que las políticas integradas existentes se disparen sin cambios. La compatibilidad con Cursor Agent es **beta** mientras verificamos el formato de transcripción en disco de Cursor (no especificado en la documentación pública) con más instalaciones del mundo real.
+  - **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 sistema de hooks de comandos externos**: carga plugins JS/TS en proceso registrados explícitamente mediante el array `plugin: []` en `opencode.json` (la autodescubrimiento desde `.opencode/plugins/` **no** es como cargan los plugins en opencode v1.14.33). La instalación coloca un pequeño shim de plugin generado que llama al binario de failproofai como subproceso y traduce la respuesta JSON con forma Claude del binario de vuelta a semántica de plugins: `throw new Error()` para denegación de evento de herramienta (cancela la llamada a la herramienta), `client.session.prompt(...)` para instruct Y para denegación de `Stop` / `SubagentStop` (envía el motivo de denegación como el siguiente mensaje de usuario — el único canal de reintento forzado ya que `session.idle` es solo de notificación y lanzar una excepción desde él no tiene efecto), y no-op para allow. El shim canonicaliza tanto los nombres de herramientas (minúsculas → PascalCase mediante `OPENCODE_TOOL_MAP`) como las claves de argumento de entrada de herramientas (camelCase → snake_case mediante `OPENCODE_TOOL_INPUT_MAP` para `Read` / `Write` / `Edit`, por ejemplo `filePath` → `file_path`, `oldString` → `old_string`) antes de reenviar al binario, por lo que las políticas integradas de comprobación de rutas como `block-read-outside-cwd`, `block-env-files` y `block-secrets-write` se disparan 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>`. La compatibilidad con OpenCode es **beta** mientras verificamos el comportamiento en distintas versiones y con más sesiones del mundo real. Consulta la [documentación de plugins de OpenCode](https://opencode.ai/docs/plugins/).
+  - **Pi _(beta)_**: `~/.pi/agent/settings.json` (usuario), `<cwd>/.pi/settings.json` (proyecto) — Pi no tiene ámbito `local`. Pi carga paquetes de extensión TypeScript al inicio; el archivo de configuración es un array plano de cadenas `{"packages": ["./relative/path", …]}`. failproofai escribe una única entrada en el array de paquetes que apunta a su directorio `pi-extension/` incluido. La extensión se suscribe internamente a los eventos `tool_call` / `user_bash` / `input` / `session_start` de Pi y llama a `failproofai --hook <Event> --cli pi`; el manejador canonicaliza underscore_lower_snake_case → PascalCase mediante `PI_EVENT_MAP` para que las políticas integradas existentes se disparen sin cambios. Los argumentos de entrada de herramientas también se canonicalizan mediante `PI_TOOL_INPUT_MAP` (los eventos Read / Write / Edit de Pi entregan `path` en lugar de `file_path`; mapear la clave de nivel superior permite que se disparen `block-env-files` y `block-secrets-write` — `block-read-outside-cwd` ya tenía un fallback para `path`). La compatibilidad con Pi es **beta** mientras la API de extensión de Pi y el esquema de 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 sola instalación intercepta las llamadas a herramientas de cada plataforma (Slack/Telegram/cli/cron) **y** subagentes internos. Las entradas de hook son un par `{command, timeout}` (tiempo de espera en **segundos**) bajo un mapa `hooks:` con clave de 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 disparen sin cambios. La configuración se edita mediante una ida y vuelta de `Document` YAML que preserva los comentarios para que las otras configuraciones del operador sobrevivan, y la instalación establece `hooks_auto_accept: true` para que la pasarela sin cabeza (sin TTY) ejecute los hooks sin un aviso de consentimiento. El evaluador emite el contrato stdout `{"decision":"block","reason"}` de Hermes (Hermes ignora los códigos de salida). **Limitaciones:** Hermes no tiene evento `Stop` al final del turno, por lo que las políticas integradas `require-*-before-stop` nunca se disparan para él (no aplicable, no es un error); `instruct` degrada a permitir con nota registrada (sin canal de contexto adicional); y la redacción de secretos en la salida (`sanitize-*`) no puede reescribir la salida de la herramienta 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`.
+  - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json` (**solo ámbito de usuario** — OpenClaw no tiene configuración de proyecto/local). Al igual que Hermes, OpenClaw es una **pasarela** multicanal autoalojada, por lo que una sola instalación intercepta las llamadas a herramientas de cada canal y sus subagentes internos. La aplicación se ejecuta a través de los **hooks de plugin en proceso** de OpenClaw (sus hooks internos basados en archivos son solo de observación y no pueden bloquear), por lo que — al igual que OpenCode/Pi — failproofai incluye un paquete estático `openclaw-plugin/` que genera el binario de failproofai de forma asíncrona y traduce el veredicto. La instalación registra el directorio de plugin incluido en `plugins.load.paths[]` de `openclaw.json` y lo habilita bajo `plugins.entries.failproofai` (con `hooks.allowConversationAccess: true`, necesario para los hooks de conversación sin procesar). El evaluador emite un veredicto plano `{permission, reason}` y el shim lo mapea a la forma de retorno nativa de cada hook: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**), y `before_agent_finalize → {action:"revise", reason}` (**Stop** — una compuerta real al final del turno, por lo que las políticas integradas `require-*-before-stop` **se aplican** en OpenClaw, a diferencia de Hermes). Los eventos y los nombres de herramientas se canonicalizan en el lado del binario mediante `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` (`exec→Bash`, `read→Read`, …) para que las políticas integradas se disparen sin cambios; el shim falla de forma abierta ante cualquier error de ejecución/análisis/tiempo de espera. OpenClaw es **también** una fuente de **auditoría** sin conexión — el panel lee sus sesiones JSONL en `~/.openclaw/agents/<agentId>/sessions/<uuid>.jsonl`.
+  - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (usuario), `<cwd>/.factory/hooks.json` (proyecto) — Factory no tiene ámbito `local`. droid incluye un sistema de hooks de comandos externos al estilo Claude, pero con dos particularidades verificadas en vivo con droid v0.171.0: (1) los nombres de eventos se encuentran en el **nivel superior** de `hooks.json` — **no hay envoltorio `"hooks"`** (droid lo rechaza); los eventos de herramientas (`PreToolUse`/`PostToolUse`) llevan `"matcher": "*"`, los eventos que no son de herramientas lo omiten. (2) La denegación se controla por el **código de salida 2 + stderr** del hook, no por una decisión JSON — la rama `factory` del evaluador devuelve salida 2 para eventos de herramienta/prompt y `{decision:"block", reason}` solo en el evento `Stop` al final del turno (el único canal de reintento forzado de droid). Los eventos ya están en PascalCase (sin mapa de eventos) y el payload es snake_case de Claude; solo los nombres de herramientas se canonicalizan mediante `FACTORY_TOOL_MAP` (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …). Factory es **también** una fuente de **auditoría** sin conexión — el panel lee sus sesiones JSONL en disco en `~/.factory/sessions/<encoded-cwd>/<sessionId>.jsonl`.
+  - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (usuario), `<cwd>/.devin/config.json` (proyecto) — Devin no tiene ámbito `local`. Devin es un **clon puro de Claude** verificado en vivo con devin v3000.1.27: usa el esquema estándar de envoltorio `"hooks"` de Claude (las escrituras preservan la combinación para que las otras claves del archivo de configuración — `org_id`, `theme_mode`, … — sobrevivan), nombres de eventos ya en PascalCase (sin mapa de eventos, sin rama del manejador) y un payload stdin en snake_case de Claude (sin normalización). La rama `devin` del evaluador deniega con JSON `{"decision":"block","reason"}` en stdout con salida 0 para **cada** evento (verificado — el bloqueo anuló `--permission-mode dangerous`); en el evento `Stop` al final del turno, el motivo lleva el texto de reintento forzado MANDATORY-ACTION para que las políticas integradas `require-*-before-stop` se apliquen. Solo los nombres de herramientas se canonicalizan mediante `DEVIN_TOOL_MAP` (`exec→Bash`; `tool_input.command` ya es canónico). Devin es **también** una fuente de **auditoría** sin conexión — el panel lee sus sesiones SQLite en `~/.local/share/devin/cli/sessions.db` (cada fila de `sessions` lleva un `working_directory` real, por lo que las sesiones se agrupan por cwd del proyecto como Claude).
+  - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (usuario), `<cwd>/.agents/hooks.json` (proyecto) — Antigravity no tiene ámbito `local`. A diferencia de Factory/Devin, Antigravity tiene su **propio** contrato (no es un clon de Claude), verificado en vivo con agy v1.1.2. `hooks.json` usa un esquema de **hook con nombre**: la clave de nivel superior es un *nombre* de hook (`"failproofai"`) cuyo valor es un mapa evento→manejadores — los eventos de herramientas (`PreToolUse`/`PostToolUse`) envuelven los manejadores en `{matcher:"*", hooks:[…]}`, mientras que `PreInvocation`/`Stop` son arrays de manejadores **planos** (otros hooks con nombre se preservan). El payload stdin es **protojson en camelCase** (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) — failproofai lo normaliza a snake_case antes de ejecutar las políticas, y mapea los args en PascalCase de `run_command` (`CommandLine`/`Cwd`) mediante `ANTIGRAVITY_TOOL_INPUT_MAP`. La rama `antigravity` del evaluador usa las **propias** formas de respuesta de Antigravity: `{decision:"deny", reason}` bloquea una herramienta/prompt (salida 0), `{decision:"continue", reason}` en el evento `Stop` al final del turno vuelve a entrar en el bucle (por lo que las políticas integradas `require-*-before-stop` se aplican), y `{injectSteps:[{ephemeralMessage}]}` inyecta una instrucción en `PreInvocation` (→ `UserPromptSubmit`). Los nombres de herramientas se canonicalizan mediante `ANTIGRAVITY_TOOL_MAP` (`run_command→Bash`, `view_file→Read`, …). Antigravity es **también** una fuente de **auditoría** sin conexión — el panel lee sus transcripciones JSONL planas en `~/.gemini/antigravity-cli/brain/<conversationId>/.system_generated/logs/transcript_full.jsonl` (índice de conversaciones en `conversation_summaries.db`).
+  - **Goose (nombre en clave goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (usuario), `<cwd>/.agents/plugins/failproofai/hooks/hooks.json` (proyecto) — Goose no tiene ámbito `local`. La aplicación usa el sistema de **hooks** de Goose, la especificación transversal de agentes **Open Plugins**: el instalador simplemente coloca el directorio del plugin `failproofai` y Goose lo autodescubre al inicio (registrándolo automáticamente en `~/.config/goose/config.yaml`). El `hooks.json` usa un esquema de Open Plugins **con** un envoltorio `"hooks"` de nivel superior, y el matcher se **omite** en cada evento — un `"*"` simple es una expresión regular inválida que no coincide con nada (verificado en vivo con goose v1.43.0). Los nombres de eventos ya están en PascalCase (sin mapa de eventos); el payload stdin usa `event`/`working_dir`, que el manejador normaliza a `hook_event_name`/`cwd`. La rama `goose` del evaluador deniega con JSON `{"decision":"block","reason"}` en stdout con salida 0, respetado en el evento **`PreToolUse`** únicamente (incluido en goose ≥ v1.37.0) — que se dispara para la herramienta de shell **y dentro de subagentes delegados**, por lo que es el único punto de denegación suficiente; cualquier otro error de hook falla de forma **abierta**. Goose **no tiene evento `Stop`**, por lo que las políticas integradas `require-*-before-stop` no aplican (como con Hermes). Los nombres de herramientas se canonicalizan mediante `GOOSE_TOOL_MAP` (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) y las claves de ruta mediante `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`). Goose es **también** una fuente de **auditoría** sin conexión — el panel lee sus sesiones SQLite en `~/.local/share/goose/sessions/sessions.db` (cada fila de `sessions` lleva un `working_dir` real, por lo que las sesiones se agrupan por cwd del proyecto como Devin; las ejecuciones rápidas con `--no-session` se filtran).
+- **`policies-config.json`** — indica a failproofai qué políticas evaluar y con qué parámetros (compartido entre todas las CLIs de agente)
+
+Pasa `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` para apuntar a un agente específico (separados por espacios o repetidos para cualquier subconjunto):
+
+```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
+```
+
+Cuando se omite `--cli`, `failproofai` detecta qué CLIs de agente están instaladas (`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`):
+
+- **Una CLI detectada** — la selecciona automáticamente sin preguntar.
+- **Varias CLIs detectadas** en una terminal interactiva — 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 solo muestra la sección Detected.
+- **Varias CLIs detectadas** en una ejecución no interactiva (CI, sin TTY) — instala para todas las CLIs detectadas sin preguntar.
+- **Ninguna detectada** — recurre a `claude`, con una advertencia de que no se encontró ningún binario de agente en PATH; el comando de hook se escribe igualmente para que se active en cuanto instales uno.
+
+Puedes editar `policies-config.json` directamente en cualquier momento; los cambios surten efecto inmediatamente en el siguiente evento de hook sin necesidad de reiniciar.
+
+---
+
+## Ejemplo: configuración a nivel de proyecto con valores predeterminados del equipo
+
+Confirma `.failproofai/policies-config.json` en tu repositorio:
+
+```json
+{
+  "enabledPolicies": [
+    "block-sudo",
+    "block-rm-rf",
+    "block-push-master",
+    "sanitize-api-keys",
+    "block-env-files"
+  ],
+  "policyParams": {
+    "block-push-master": {
+      "protectedBranches": ["main", "release", "hotfix"]
+    }
+  }
+}
+```
+
+Cada desarrollador puede entonces crear `.failproofai/policies-config.local.json` (ignorado por git) para sus anulaciones personales sin afectar a sus compañeros de equipo.

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

@@ -0,0 +1,358 @@
+---
+title: Políticas Personalizadas
+description: "Escribe tus propias políticas en JavaScript: aplica convenciones del proyecto, previene la deriva, detecta fallos e integra con sistemas externos"
+icon: code
+---
+
+Las políticas personalizadas te permiten escribir reglas para cualquier comportamiento del agente: aplicar convenciones del proyecto, prevenir la deriva, bloquear operaciones destructivas, detectar agentes bloqueados o integrarte con Slack, flujos de aprobación y más. Utilizan el mismo sistema de eventos de hooks y las decisiones `allow`, `deny`, `instruct` que las políticas integradas.
+
+---
+
+## Ejemplo rápido
+
+```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();
+  },
+});
+```
+
+Instálala:
+
+```bash
+failproofai policies --install --custom ./my-policies.js
+```
+
+---
+
+## Dos formas de cargar políticas personalizadas
+
+### Opción 1: Por convención (recomendada)
+
+Coloca archivos `*policies.{js,mjs,ts}` en `.failproofai/policies/` y se cargarán automáticamente, sin necesidad de flags ni cambios de configuración. Funciona como los git hooks: deposita el archivo y listo.
+
+```
+# A nivel de proyecto — incluido en git, compartido con el equipo
+.failproofai/policies/security-policies.mjs
+.failproofai/policies/workflow-policies.mjs
+
+# A nivel de usuario — personal, aplica a todos los proyectos
+~/.failproofai/policies/my-policies.mjs
+```
+
+**Cómo funciona:**
+- Se analizan tanto el directorio del proyecto como el del usuario (unión; no gana el primero en el ámbito)
+- Los archivos se cargan en orden alfabético dentro de cada directorio. Usa el prefijo `01-`, `02-` para controlar el orden
+- Solo se cargan los archivos que coincidan con `*policies.{js,mjs,ts}`; los demás se ignoran
+- Cada archivo se carga de forma independiente (fail-open por archivo)
+- Funciona junto con `--custom` explícito y las políticas integradas
+
+<Tip>
+Las políticas por convención son la forma más sencilla de establecer un estándar de calidad para tu organización. Incluye `.failproofai/policies/` en git y cada miembro del equipo obtendrá las mismas reglas automáticamente, sin configuración individual. A medida que el equipo descubra nuevos modos de fallo, añade una política y envíala. Con el tiempo, estas se convierten en un estándar de calidad vivo que mejora con cada contribución.
+</Tip>
+
+### Opción 2: Ruta de archivo explícita
+
+```bash
+# Instalar con un archivo de políticas personalizado
+failproofai policies --install --custom ./my-policies.js
+
+# Reemplazar las rutas de políticas personalizadas
+failproofai policies --install --custom ./new-policies.js
+
+# Configurar múltiples archivos explícitos (cargados en el orden de los flags)
+failproofai policies --install --custom ./security.js --custom ./workflow.js
+
+# Eliminar todas las rutas de políticas personalizadas explícitas de la configuración
+failproofai policies --uninstall --custom
+```
+
+Las rutas absolutas resueltas se almacenan en `policies-config.json` como `customPoliciesPaths`. Repite `--custom` para configurar múltiples archivos. Las configuraciones existentes que usen el campo heredado `customPoliciesPath` siguen funcionando. Los archivos se cargan de nuevo en cada evento de hook; no hay caché entre eventos.
+
+Cada política registrada aparece con su propio interruptor en el panel. Desactivar una política registra su ID calificado por fuente en `disabledCustomPolicies`; el archivo y sus demás políticas continúan cargándose, mientras que la política desactivada se excluye antes de la coincidencia de eventos. Los nombres de políticas duplicados entre archivos tienen interruptores independientes.
+
+### Usar ambas a la vez
+
+Las políticas por convención y los archivos `--custom` explícitos pueden coexistir. Orden de carga:
+
+1. Archivos `customPoliciesPaths` explícitos (en el orden configurado)
+2. Archivos de convención del proyecto (`{cwd}/.failproofai/policies/`, orden alfabético)
+3. Archivos de convención del usuario (`~/.failproofai/policies/`, orden alfabético)
+
+---
+
+## API
+
+### Importación
+
+```js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+```
+
+### `customPolicies.add(hook)`
+
+Registra una política. Llámalo tantas veces como sea necesario para múltiples políticas en el mismo archivo.
+
+```ts
+customPolicies.add({
+  name: string;                         // requerido - identificador único
+  description?: string;                 // se muestra en la salida de `failproofai policies`
+  match?: { events?: HookEventType[] }; // filtrar por tipo de evento; omitir para coincidir con todos
+  fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
+});
+```
+
+### Helpers de decisión
+
+| Función | Efecto | Úsalo cuando |
+|----------|--------|----------|
+| `allow()` | Permite la operación en silencio | La acción es segura y no se necesita mensaje |
+| `deny(message)` | Bloquea la operación | El agente no debería realizar esta acción |
+| `instruct(message)` | Añade contexto sin bloquear | Proporciona contexto adicional al agente para que no se desvíe |
+
+`deny(message)` — el mensaje aparece para Claude con el prefijo `"Blocked by failproofai:"`. Un único `deny` cortocircuita toda evaluación posterior.
+
+`instruct(message)` — el mensaje se añade al contexto de Claude para la llamada de herramienta actual. Todos los mensajes `instruct` se acumulan y se entregan juntos.
+
+<Tip>
+Puedes añadir orientación adicional a cualquier mensaje `deny` o `instruct` incluyendo un campo `hint` en `policyParams`, sin necesidad de cambiar el código. Esto funciona también para políticas personalizadas (`custom/`), de convención del proyecto (`.failproofai-project/`) y de convención del usuario (`.failproofai-user/`). Consulta [Configuración → hint](/es/configuration#hint-cross-cutting) para más detalles.
+</Tip>
+
+### Mensajes allow informativos
+
+`allow(message)` permite la operación **y** envía un mensaje informativo a Claude. El mensaje se entrega como `additionalContext` en la respuesta stdout del handler del hook, el mismo mecanismo que usa `instruct`, aunque semánticamente diferente: es una actualización de estado, no una advertencia.
+
+| Función | Efecto | Úsalo cuando |
+|----------|--------|----------|
+| `allow(message)` | Permite y envía contexto a Claude | Confirmar que una comprobación pasó o explicar por qué se omitió |
+
+Casos de uso:
+- **Confirmaciones de estado:** `allow("All CI checks passed.")` — indica a Claude que todo está en orden
+- **Explicaciones de fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — indica a Claude por qué se omitió una comprobación para que tenga contexto completo
+- **Acumulación de múltiples mensajes:** si varias políticas devuelven `allow(message)`, todos los mensajes se unen con saltos de línea y se entregan juntos
+
+```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.");
+  },
+});
+```
+
+### Campos de `PolicyContext`
+
+| Campo | Tipo | Descripción |
+|-------|------|-------------|
+| `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` |
+| `toolName` | `string \| undefined` | La herramienta que se está invocando (p. ej., `"Bash"`, `"Write"`, `"Read"`) |
+| `toolInput` | `Record<string, unknown> \| undefined` | Los parámetros de entrada de la herramienta |
+| `payload` | `Record<string, unknown>` | Payload completo del evento sin procesar de Claude Code |
+| `session` | `SessionMetadata \| undefined` | Contexto de sesión (ver más abajo) |
+
+### Campos de `SessionMetadata`
+
+| Campo | Tipo | Descripción |
+|-------|------|-------------|
+| `sessionId` | `string` | Identificador de sesión de Claude Code |
+| `cwd` | `string` | Directorio de trabajo de la sesión de Claude Code |
+| `transcriptPath` | `string` | Ruta al archivo de transcripción JSONL de la sesión |
+
+### Tipos de eventos
+
+| Evento | Cuándo se activa | Contenido de `toolInput` |
+|-------|--------------|----------------------|
+| `PreToolUse` | Antes de que Claude ejecute una herramienta | La entrada de la herramienta (p. ej., `{ command: "..." }` para Bash) |
+| `PostToolUse` | Tras completarse una herramienta | La entrada de la herramienta + `tool_result` (la salida) |
+| `Notification` | Cuando Claude envía una notificación | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` — los hooks siempre deben devolver `allow()`, no pueden bloquear notificaciones |
+| `Stop` | Cuando finaliza la sesión de Claude | Vacío |
+
+---
+
+## Orden de evaluación
+
+Las políticas se evalúan en este orden:
+
+1. Políticas integradas (en orden de definición)
+2. Políticas personalizadas explícitas de `customPoliciesPath` (en orden de `.add()`)
+3. Políticas de convención del proyecto en `.failproofai/policies/` (archivos en orden alfabético, orden de `.add()` dentro de cada uno)
+4. Políticas de convención del usuario en `~/.failproofai/policies/` (archivos en orden alfabético, orden de `.add()` dentro de cada uno)
+
+<Note>
+El primer `deny` cortocircuita todas las políticas siguientes. Todos los mensajes `instruct` se acumulan y se entregan juntos.
+</Note>
+
+---
+
+## Importaciones transitivas
+
+Los archivos de políticas personalizadas pueden importar módulos locales mediante rutas relativas:
+
+```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");
+  },
+});
+```
+
+Se resuelven todas las importaciones relativas accesibles desde el archivo de entrada. Esto se implementa reescribiendo las importaciones `from "failproofai"` a la ruta real de dist y creando archivos `.mjs` temporales para garantizar la compatibilidad con ESM.
+
+---
+
+## Filtrado por tipo de evento
+
+Usa `match.events` para limitar cuándo se activa una política:
+
+```js
+customPolicies.add({
+  name: "require-summary-on-stop",
+  match: { events: ["Stop"] },
+  fn: async (ctx) => {
+    // Solo se activa cuando finaliza la sesión
+    // ctx.session.transcriptPath contiene el registro completo de la sesión
+    return allow();
+  },
+});
+```
+
+Omite `match` por completo para activarla en todos los tipos de eventos.
+
+---
+
+## Manejo de errores y modos de fallo
+
+Las políticas personalizadas son **fail-open**: los errores nunca bloquean las políticas integradas ni detienen el handler del hook.
+
+| Fallo | Comportamiento |
+|---------|----------|
+| `customPoliciesPath` no configurado | No se ejecutan políticas personalizadas explícitas; las políticas de convención y las integradas continúan con normalidad |
+| Archivo no encontrado | Se registra una advertencia en `~/.failproofai/hook.log`; las integradas continúan |
+| Error de sintaxis/importación (explícito) | Se registra el error en `~/.failproofai/hook.log`; se omiten las políticas personalizadas explícitas |
+| Error de sintaxis/importación (por convención) | Se registra el error; ese archivo se omite, los demás archivos de convención continúan cargándose |
+| `fn` lanza un error en tiempo de ejecución | Se registra el error; ese hook se trata como `allow`; los demás hooks continúan |
+| `fn` tarda más de 10 s | Se registra el tiempo de espera; se trata como `allow` |
+| Directorio de convención no existe | No se ejecutan políticas de convención; sin error |
+
+<Tip>
+Para depurar errores en políticas personalizadas, monitorea el archivo de log:
+
+```bash
+tail -f ~/.failproofai/hook.log
+```
+</Tip>
+
+---
+
+## Ejemplo completo: múltiples políticas
+
+```js
+// my-policies.js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+
+// Evitar que el agente escriba en el directorio 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();
+  },
+});
+
+// Mantener al agente en curso: verificar los tests antes de hacer 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();
+  },
+});
+
+// Prevenir cambios de dependencias no planificados durante el periodo de congelamiento
+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 };
+```
+
+---
+
+## Ejemplos
+
+El directorio `examples/` contiene archivos de políticas listos para usar:
+
+| Archivo | Contenido |
+|------|----------|
+| `examples/policies-basic.js` | Cinco políticas básicas que cubren los modos de fallo más comunes del agente |
+| `examples/policies-advanced/index.js` | Patrones avanzados: importaciones transitivas, llamadas asíncronas, limpieza de salida y hooks de fin de sesión |
+| `examples/convention-policies/security-policies.mjs` | Políticas de seguridad basadas en convención (bloquear escrituras en .env, prevenir la reescritura del historial de git) |
+| `examples/convention-policies/workflow-policies.mjs` | Políticas de flujo de trabajo basadas en convención (recordatorios de tests, auditoría de escrituras de archivos) |
+
+### Usar los ejemplos de archivo explícito
+
+```bash
+failproofai policies --install --custom ./examples/policies-basic.js
+```
+
+### Usar los ejemplos basados en convención
+
+```bash
+# Copiar a nivel de proyecto
+mkdir -p .failproofai/policies
+cp examples/convention-policies/*.mjs .failproofai/policies/
+
+# O copiar a nivel de usuario
+mkdir -p ~/.failproofai/policies
+cp examples/convention-policies/*.mjs ~/.failproofai/policies/
+```
+
+No se necesita ningún comando de instalación: los archivos se detectan automáticamente en el siguiente evento de hook.