failproofai 1.0.1-beta.0 → 1.0.1

package/.next/standalone/docs-old/es/built-in-policies.mdx

@@ -0,0 +1,853 @@
+---
+title: Políticas Integradas
+description: "Las 39 políticas integradas que detectan los modos de fallo más comunes de los agentes"
+icon: shield
+---
+
+failproofai incluye 39 políticas integradas que detectan los modos de fallo más comunes de los agentes. Cada política se activa en un tipo de evento de hook específico y un nombre de herramienta determinado. Diecinueve políticas aceptan parámetros que permiten ajustar su comportamiento sin necesidad de escribir código. Cinco políticas de flujo de trabajo imponen una secuencia commit → push → PR → CI antes de que Claude se detenga.
+
+---
+
+## Descripción general
+
+Las políticas están agrupadas por categorías:
+
+| Categoría | Políticas | Tipo de hook |
+|----------|----------|-----------|
+| [Comandos peligrosos](#dangerous-commands) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands, block-self-pause | PreToolUse |
+| [Comandos de infraestructura](#infra-commands) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse |
+| [Secretos (sanitizadores)](#secrets-sanitizers) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse |
+| [Entorno](#environment) | block-env-files, protect-env-vars | PreToolUse |
+| [Acceso a archivos](#file-access) | block-read-outside-cwd, block-secrets-write | PreToolUse |
+| [Git](#git) | block-push-master, block-work-on-main, block-force-push, warn-git-amend, warn-git-stash-drop, warn-all-files-staged | PreToolUse |
+| [Base de datos](#database) | warn-destructive-sql, warn-schema-alteration | PreToolUse |
+| [Advertencias](#warnings) | warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install | PreToolUse |
+| [Gestores de paquetes](#package-managers) | prefer-package-manager | PreToolUse |
+| [Flujo de trabajo](#workflow) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop |
+
+- **`block-`** — impide que el agente continúe.
+- **`warn-`** — proporciona contexto adicional al agente para que pueda corregirse.
+- **`sanitize-`** — elimina datos sensibles de la salida de la herramienta antes de que el agente la vea.
+
+### Espacios de nombres
+
+Cada política ocupa un espacio `<namespace>/<name>`. Las políticas integradas pertenecen al espacio de nombres **`failproofai/`** — por ejemplo, `failproofai/sanitize-jwt`. El espacio de nombres evita colisiones cuando también se cargan políticas personalizadas o de terceros con nombres cortos similares.
+
+En tu configuración puedes hacer referencia a una política integrada tanto por su nombre corto como por su nombre completo; ambas formas se resuelven a la misma política:
+
+```json
+{
+  "enabledPolicies": [
+    "sanitize-jwt",
+    "failproofai/block-rm-rf"
+  ]
+}
+```
+
+Si un nombre no contiene `/`, failproofai lo trata como perteneciente al espacio de nombres predeterminado `failproofai`. Los nombres que ya contienen `/` (p. ej. `myorg/foo`, `custom/my-hook`) se mantienen tal cual.
+- **`require-`** — bloquea el evento Stop hasta que se cumplan las condiciones.
+
+---
+
+<Tip>
+Toda política admite un campo opcional `hint` en `policyParams`. El hint se añade al mensaje de deny o instruct que ve Claude, proporcionando orientación accionable sin modificar el código de la política. Funciona con políticas integradas, personalizadas y de convención. Consulta [Configuración → hint](/es/configuration#hint-cross-cutting) para más detalles.
+</Tip>
+
+---
+
+## Comandos peligrosos
+
+Evita que los agentes ejecuten operaciones difíciles de deshacer o que podrían dañar el sistema anfitrión.
+
+### `block-sudo`
+
+**Evento:** PreToolUse (Bash)  
+**Por defecto:** Deniega cualquier comando `sudo` o `doas`.
+
+Bloquea un comando que ejecuta un binario de elevación de privilegios **en posición de comando**. La coincidencia es estructural, no textual: el comando se divide en segmentos tal como lo haría un shell, se eliminan las asignaciones de prefijo (`FOO=bar`), las redirecciones y los ejecutores con sus flags (`env`, `nohup`, `timeout`, `xargs`, `sh -c`, …), y el binario resultante se compara por **nombre base**. Así, `/usr/bin/sudo`, `env sudo`, `timeout 5 sudo`, `"sudo"`, `\sudo` y `bash -c "sudo …"` son todos denegados, y `doas` se trata como la misma capacidad bajo un nombre distinto.
+
+Al anclar en la posición del comando en lugar de en la aparición de la palabra en cualquier parte, **no** se activa en comandos que simplemente la mencionan: `grep -r sudo /etc`, `cat /etc/sudoers`, `git commit -m "fix sudo handling"`, o una alternancia de `grep` que contiene la palabra se ejecutan normalmente.
+
+<Warning>
+Esto detiene el intento obvio; no cierra la clase completa. Un agente capaz de ejecutar shell arbitrario puede seguir alcanzando la elevación de forma indirecta — mediante una variable (`S=sudo; $S …`), una tubería decodificada en base64, o un script envolvente en disco — porque ninguna inspección de una sola cadena de comandos puede seguir esas vías. Trátalo como una barrera contra errores y escalada casual, no como un límite de seguridad frente a un agente con intenciones deliberadas. Una barrera real debe aplicarse por debajo del shell.
+</Warning>
+
+**Parámetros:**
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | Prefijos de comandos exactos que están permitidos. Cada entrada se compara con los tokens argv analizados. |
+
+**Ejemplo:**
+
+```json
+{
+  "policyParams": {
+    "block-sudo": {
+      "allowPatterns": ["sudo systemctl status", "sudo journalctl"]
+    }
+  }
+}
+```
+
+Con esta configuración, `sudo systemctl status nginx` está permitido, pero `sudo rm /etc/hosts` es denegado.
+
+<Note>
+Los patrones se comparan con los tokens analizados, no con la cadena de comandos sin procesar. Esto evita la evasión mediante operadores de shell añadidos (p. ej. `sudo systemctl status x; rm -rf /` no coincide con `sudo systemctl status *`).
+</Note>
+
+---
+
+### `block-rm-rf`
+
+**Evento:** PreToolUse (Bash)  
+**Por defecto:** Deniega `rm -rf`, `rm -fr` y formas similares de eliminación recursiva.
+
+**Parámetros:**
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-------|------|---------|-------------|
+| `allowPaths` | `string[]` | `[]` | Rutas donde es seguro realizar una eliminación recursiva (p. ej. `/tmp`). |
+
+**Ejemplo:**
+
+```json
+{
+  "policyParams": {
+    "block-rm-rf": {
+      "allowPaths": ["/tmp", "/var/cache"]
+    }
+  }
+}
+```
+
+---
+
+### `block-curl-pipe-sh`
+
+**Evento:** PreToolUse (Bash)  
+**Por defecto:** Deniega `curl <url> | bash`, `curl <url> | sh`, `wget <url> | bash` y patrones similares.
+
+Sin parámetros.
+
+---
+
+### `block-failproofai-commands`
+
+**Evento:** PreToolUse (Bash)  
+**Por defecto:** Deniega comandos que desinstalarían o deshabilitarían failproofai (p. ej. `npm uninstall failproofai`, `failproofai policies --uninstall`).
+
+Sin parámetros.
+
+---
+
+### `block-self-pause`
+
+**Evento:** PreToolUse (Bash)  
+**Por defecto:** Deniega `failproofai config --pause`, que suspende la aplicación de políticas durante una sesión. Pausar es una decisión humana — un agente capaz de ejecutarlo podría desactivar todas las demás políticas con un solo comando.
+
+Es intencionalmente más específico que [`block-failproofai-commands`](#block-failproofai-commands) y no está cubierto por él: esa política ancla en el límite de un comando, por lo que `npx -y failproofai config --pause` no la activa; y al ser más amplia, a menudo se desactiva para que los agentes puedan ejecutar `failproofai audit`. `--resume` y `--status` están permitidos — ninguno elimina la aplicación de políticas.
+
+Esto detiene el intento directo, no la clase completa: un agente aún puede alcanzar el mismo estado mediante un alias o un script envolvente. Cerrar completamente esa vía requiere que la pausa sea inaccesible desde una llamada de herramienta.
+
+Sin parámetros.
+
+---
+
+## Comandos de infraestructura
+
+Evita que los agentes de codificación ejecuten CLIs de infraestructura o activen pipelines de CI/CD. Todas las políticas de esta categoría son **opt-in** (`defaultEnabled: false`) — los agentes que legítimamente necesiten llamar a `kubectl`, `terraform`, etc. no se verán afectados a menos que habilites la política. Una vez habilitada, toda invocación del CLI correspondiente es denegada salvo que el comando coincida con una entrada en `allowPatterns`.
+
+La gramática de patrones es la misma que en [`block-sudo`](#block-sudo): los tokens se comparan con los argv analizados, `*` actúa como comodín para un token, y cualquier comando que contenga un operador de shell independiente (`&&`, `||`, `|`, `;`) o un token con metacaracteres de shell embebidos es rechazado antes de la comprobación de la lista de permitidos, para evitar inyecciones.
+
+### `block-kubectl`
+
+**Evento:** PreToolUse (Bash)  
+**Por defecto:** Deniega cualquier invocación de `kubectl`.
+
+**Parámetros:**
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | Prefijos de comandos kubectl que están permitidos. |
+
+**Ejemplo:**
+
+```json
+{
+  "policyParams": {
+    "block-kubectl": {
+      "allowPatterns": ["kubectl get *", "kubectl describe *", "kubectl logs *"]
+    }
+  }
+}
+```
+
+Con esta configuración, `kubectl get pods` está permitido pero `kubectl apply -f deploy.yaml` es denegado.
+
+---
+
+### `block-terraform`
+
+**Evento:** PreToolUse (Bash)  
+**Por defecto:** Deniega cualquier invocación de `terraform` o `tofu` (OpenTofu).
+
+**Parámetros:**
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | Prefijos de comandos terraform/tofu que están permitidos. |
+
+**Ejemplo:**
+
+```json
+{
+  "policyParams": {
+    "block-terraform": {
+      "allowPatterns": ["terraform plan", "terraform validate", "terraform show *"]
+    }
+  }
+}
+```
+
+---
+
+### `block-aws-cli`
+
+**Evento:** PreToolUse (Bash)  
+**Por defecto:** Deniega cualquier invocación del CLI `aws`.
+
+**Parámetros:**
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | Prefijos de comandos del CLI aws que están permitidos. |
+
+**Ejemplo:**
+
+```json
+{
+  "policyParams": {
+    "block-aws-cli": {
+      "allowPatterns": ["aws s3 ls *", "aws sts get-caller-identity"]
+    }
+  }
+}
+```
+
+---
+
+### `block-gcloud`
+
+**Evento:** PreToolUse (Bash)  
+**Por defecto:** Deniega cualquier invocación del CLI `gcloud` (Google Cloud).
+
+**Parámetros:**
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | Prefijos de comandos gcloud que están permitidos. |
+
+**Ejemplo:**
+
+```json
+{
+  "policyParams": {
+    "block-gcloud": {
+      "allowPatterns": ["gcloud auth list", "gcloud config list"]
+    }
+  }
+}
+```
+
+---
+
+### `block-az-cli`
+
+**Evento:** PreToolUse (Bash)  
+**Por defecto:** Deniega cualquier invocación del CLI `az` (Azure).
+
+**Parámetros:**
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | Prefijos de comandos del CLI az que están permitidos. |
+
+**Ejemplo:**
+
+```json
+{
+  "policyParams": {
+    "block-az-cli": {
+      "allowPatterns": ["az account show", "az group list"]
+    }
+  }
+}
+```
+
+---
+
+### `block-helm`
+
+**Evento:** PreToolUse (Bash)  
+**Por defecto:** Deniega cualquier invocación de `helm`.
+
+**Parámetros:**
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | Prefijos de comandos helm que están permitidos. |
+
+**Ejemplo:**
+
+```json
+{
+  "policyParams": {
+    "block-helm": {
+      "allowPatterns": ["helm list", "helm status *"]
+    }
+  }
+}
+```
+
+---
+
+### `block-gh-pipeline`
+
+**Evento:** PreToolUse (Bash)  
+**Por defecto:** Deniega los siguientes subcomandos del CLI `gh` que mutan estado o activan pipelines:
+
+- `gh workflow run`, `gh workflow enable`, `gh workflow disable`
+- `gh run rerun`, `gh run cancel`
+- `gh pr merge`
+- `gh release create`, `gh release delete`
+- `gh cache delete`
+- `gh secret set`, `gh secret delete`
+
+Los subcomandos de `gh` de solo lectura como `gh pr view`, `gh pr list`, `gh run list`, `gh release view` y `gh api repos/.../...` **no** son detectados por esta política — se necesitan habitualmente para comprobaciones de flujo de trabajo (incluida la propia `require-ci-green-before-stop` de failproofai).
+
+**Parámetros:**
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | Invocaciones específicas que se permiten aunque de otro modo serían denegadas. |
+
+**Ejemplo:**
+
+```json
+{
+  "policyParams": {
+    "block-gh-pipeline": {
+      "allowPatterns": ["gh run rerun *"]
+    }
+  }
+}
+```
+
+---
+
+## Secretos (sanitizadores)
+
+Evita que los agentes filtren credenciales en su contexto o salida. Las políticas de sanitización se activan en eventos **PostToolUse**. Cuando Claude ejecuta un comando Bash, lee un archivo o llama a cualquier herramienta, estas políticas inspeccionan la salida antes de que se devuelva a Claude. Si se detecta un patrón de secreto, la política devuelve una decisión de deny que impide que la salida sea devuelta.
+
+### `sanitize-jwt`
+
+**Evento:** PostToolUse (todas las herramientas)  
+**Por defecto:** Redacta tokens JWT (tres segmentos base64url separados por `.`).
+
+Sin parámetros.
+
+---
+
+### `sanitize-api-keys`
+
+**Evento:** PostToolUse (todas las herramientas)  
+**Por defecto:** Redacta formatos comunes de claves de API: Anthropic (`sk-ant-`), OpenAI (`sk-`), PATs de GitHub (`ghp_`), claves de acceso AWS (`AKIA`), claves Stripe (`sk_live_`, `sk_test_`) y claves de API de Google (`AIza`).
+
+**Parámetros:**
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-------|------|---------|-------------|
+| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | Patrones regex adicionales para tratar como secretos. |
+
+**Ejemplo:**
+
+```json
+{
+  "policyParams": {
+    "sanitize-api-keys": {
+      "additionalPatterns": [
+        { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo internal API key" },
+        { "regex": "pat_[0-9a-f]{40}", "label": "Internal PAT" }
+      ]
+    }
+  }
+}
+```
+
+---
+
+### `sanitize-connection-strings`
+
+**Evento:** PostToolUse (todas las herramientas)  
+**Por defecto:** Redacta cadenas de conexión a bases de datos que contengan credenciales embebidas (p. ej. `postgresql://user:password@host/db`).
+
+Sin parámetros.
+
+---
+
+### `sanitize-private-key-content`
+
+**Evento:** PostToolUse (todas las herramientas)  
+**Por defecto:** Redacta bloques PEM (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, etc.).
+
+Sin parámetros.
+
+---
+
+### `sanitize-bearer-tokens`
+
+**Evento:** PostToolUse (todas las herramientas)  
+**Por defecto:** Redacta cabeceras `Authorization: Bearer <token>` donde el token tiene 20 o más caracteres.
+
+Sin parámetros.
+
+---
+
+## Entorno
+
+Protege la configuración de entorno sensible para que los agentes no puedan leerla ni exponerla.
+
+### `block-env-files`
+
+**Evento:** PreToolUse (Bash, Read)  
+**Por defecto:** Deniega la lectura de archivos `.env` mediante `cat .env`, llamadas a la herramienta `Read` con `.env` como ruta de archivo, etc.
+
+No bloquea `.envrc` ni otros archivos relacionados con el entorno: solo archivos con el nombre exacto `.env`.
+
+Sin parámetros.
+
+---
+
+### `protect-env-vars`
+
+**Evento:** PreToolUse (Bash)  
+**Por defecto:** Deniega comandos que imprimen variables de entorno: `printenv`, `env`, `echo $VAR`.
+
+Sin parámetros.
+
+---
+
+## Acceso a archivos
+
+Mantén a los agentes trabajando dentro de los límites del proyecto y alejados de archivos sensibles.
+
+### `block-read-outside-cwd`
+
+**Evento:** PreToolUse (Read, Bash)  
+**Por defecto:** Deniega la lectura de archivos fuera de la raíz del proyecto. El límite es `CLAUDE_PROJECT_DIR` (establecido una vez por sesión por Claude Code), con un fallback al directorio de trabajo actual de la sesión cuando esa variable no está definida. Al usar la raíz del proyecto en lugar del `cwd` activo, el límite se mantiene estable incluso cuando Claude hace `cd` a un subdirectorio.
+
+**Parámetros:**
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-------|------|---------|-------------|
+| `allowPaths` | `string[]` | `[]` | Prefijos de rutas absolutas que están permitidos aunque estén fuera de la raíz del proyecto. |
+
+**Ejemplo:**
+
+```json
+{
+  "policyParams": {
+    "block-read-outside-cwd": {
+      "allowPaths": ["/shared/data", "/opt/company/config"]
+    }
+  }
+}
+```
+
+---
+
+### `block-secrets-write`
+
+**Evento:** PreToolUse (Write, Edit)  
+**Por defecto:** Deniega escrituras en archivos habitualmente usados para claves privadas y certificados: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`.
+
+**Parámetros:**
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-------|------|---------|-------------|
+| `additionalPatterns` | `string[]` | `[]` | Patrones de nombre de archivo adicionales (estilo glob) que se bloquean. |
+
+**Ejemplo:**
+
+```json
+{
+  "policyParams": {
+    "block-secrets-write": {
+      "additionalPatterns": [".token", ".secret"]
+    }
+  }
+}
+```
+
+---
+
+## Git
+
+Evita pushes accidentales, force-pushes y errores de rama difíciles de deshacer.
+
+### `block-push-master`
+
+**Evento:** PreToolUse (Bash)  
+**Por defecto:** Deniega `git push origin main` y `git push origin master`.
+
+**Parámetros:**
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-------|------|---------|-------------|
+| `protectedBranches` | `string[]` | `["main", "master"]` | Nombres de ramas a las que no se puede hacer push directamente. |
+
+**Ejemplo:**
+
+```json
+{
+  "policyParams": {
+    "block-push-master": {
+      "protectedBranches": ["main", "master", "release", "prod"]
+    }
+  }
+}
+```
+
+<Tip>
+Para permitir el push a todas las ramas (desactivando efectivamente esta política sin eliminarla de `enabledPolicies`), establece `protectedBranches: []`.
+</Tip>
+
+---
+
+### `block-work-on-main`
+
+**Evento:** PreToolUse (Bash)  
+**Por defecto:** Deniega `git commit`, `git merge`, `git rebase` y `git cherry-pick` cuando el árbol de trabajo está en `main` o `master`. La creación y el cambio de ramas (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) no se ven afectados.
+
+**Parámetros:**
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-------|------|---------|-------------|
+| `protectedBranches` | `string[]` | `["main", "master"]` | Nombres de ramas en las que se deniega commit/merge/rebase/cherry-pick. |
+
+---
+
+### `block-force-push`
+
+**Evento:** PreToolUse (Bash)  
+**Por defecto:** Deniega `git push --force` y `git push -f`.
+
+Sin parámetros específicos de la política. Usa el campo transversal [`hint`](/es/configuration#hint-cross-cutting) para sugerir alternativas:
+
+```json
+{
+  "policyParams": {
+    "block-force-push": {
+      "hint": "Create a new branch from your current HEAD (e.g. `git checkout -b <new-branch>`) and push that instead."
+    }
+  }
+}
+```
+
+---
+
+### `warn-git-amend`
+
+**Evento:** PreToolUse (Bash)  
+**Por defecto:** Instruye a Claude para que proceda con cuidado al ejecutar `git commit --amend`. No bloquea el comando.
+
+Sin parámetros.
+
+---
+
+### `warn-git-stash-drop`
+
+**Evento:** PreToolUse (Bash)  
+**Por defecto:** Instruye a Claude para que confirme antes de ejecutar `git stash drop`. No bloquea el comando.
+
+Sin parámetros.
+
+---
+
+### `warn-all-files-staged`
+
+**Evento:** PreToolUse (Bash)  
+**Por defecto:** Instruye a Claude para que revise lo que está preparando cuando ejecuta `git add -A` o `git add .`. No bloquea el comando.
+
+Sin parámetros.
+
+---
+
+## Base de datos
+
+Detecta operaciones SQL destructivas antes de que se ejecuten contra tu base de datos.
+
+### `warn-destructive-sql`
+
+**Evento:** PreToolUse (Bash)  
+**Por defecto:** Instruye a Claude para que confirme antes de ejecutar SQL que contenga `DROP TABLE`, `DROP DATABASE`, o `DELETE` sin una cláusula `WHERE`.
+
+Sin parámetros.
+
+---
+
+### `warn-schema-alteration`
+
+**Evento:** PreToolUse (Bash)  
+**Por defecto:** Instruye a Claude para que confirme antes de ejecutar sentencias `ALTER TABLE`.
+
+Sin parámetros.
+
+---
+
+## Advertencias
+
+Proporciona contexto adicional a los agentes antes de operaciones potencialmente arriesgadas pero no destructivas.
+
+### `warn-large-file-write`
+
+**Evento:** PreToolUse (Write)  
+**Por defecto:** Instruye a Claude para que confirme antes de escribir archivos de más de 1024 KB.
+
+**Parámetros:**
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-------|------|---------|-------------|
+| `thresholdKb` | `number` | `1024` | Umbral de tamaño de archivo en kilobytes a partir del cual se emite una advertencia. |
+
+**Ejemplo:**
+
+```json
+{
+  "policyParams": {
+    "warn-large-file-write": {
+      "thresholdKb": 256
+    }
+  }
+}
+```
+
+<Note>
+El manejador de hooks impone un límite de 1 MB en stdin para los payloads. Para probar esta política con contenido pequeño, establece `thresholdKb` a un valor bastante inferior a 1024.
+</Note>
+
+---
+
+### `warn-package-publish`
+
+**Evento:** PreToolUse (Bash)  
+**Por defecto:** Instruye a Claude para que confirme antes de ejecutar `npm publish`.
+
+Sin parámetros.
+
+---
+
+### `warn-background-process`
+
+**Evento:** PreToolUse (Bash)  
+**Por defecto:** Instruye a Claude para que sea cuidadoso al lanzar procesos en segundo plano mediante `nohup`, `&`, `disown` o `screen`.
+
+Sin parámetros.
+
+---
+
+### `warn-global-package-install`
+
+**Evento:** PreToolUse (Bash)  
+**Por defecto:** Instruye a Claude para que confirme antes de ejecutar `npm install -g`, `yarn global add` o `pip install` sin un entorno virtual.
+
+Sin parámetros.
+
+---
+
+## Gestores de paquetes
+
+Define qué gestores de paquetes puede usar el agente.
+
+### `prefer-package-manager`
+
+**Evento:** PreToolUse (Bash)  
+**Por defecto:** Deshabilitado. Cuando se habilita, bloquea cualquier comando de gestor de paquetes que no esté en la lista `allowed` e indica a Claude que reescriba el comando usando un gestor permitido.
+
+Detecta: pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo.
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-----------|------|---------|-------------|
+| `allowed` | string[] | `[]` | Nombres de gestores de paquetes permitidos. Cualquier gestor detectado que no esté en esta lista es bloqueado. Si está vacío, la política no tiene efecto. |
+| `blocked` | string[] | `[]` | Nombres de gestores adicionales a bloquear más allá de la lista integrada (p. ej. `['pdm', 'pipx']`). |
+
+La lista de bloqueo integrada incluye: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Usa `blocked` para añadir gestores que no estén en esta lista.
+
+**Ejemplo de configuración:**
+
+```json
+{
+  "enabledPolicies": ["prefer-package-manager"],
+  "policyParams": {
+    "prefer-package-manager": {
+      "allowed": ["uv", "bun"],
+      "blocked": ["pdm", "pipx"]
+    }
+  }
+}
+```
+
+Con esta configuración, `pip install flask` y `pdm install flask` son denegados con un mensaje que indica a Claude que use `uv` o `bun` en su lugar. Comandos como `uv pip install flask` están permitidos porque `uv` está en la lista de permitidos y se comprueba primero.
+
+---
+
+## Comportamiento de IA
+
+Detecta cuando los agentes se quedan atascados o se comportan de forma inesperada.
+
+### `warn-repeated-tool-calls`
+
+**Evento:** PreToolUse (todas las herramientas)  
+**Por defecto:** Instruye a Claude para que reconsidere cuando se llama a la misma herramienta 3 o más veces con parámetros idénticos — una señal habitual de que el agente está atrapado en un bucle.
+
+Sin parámetros.
+
+---
+
+## Flujo de trabajo
+
+Impone un flujo de trabajo disciplinado al final de la sesión. Estas políticas se activan en el evento **Stop** y deniegan al agente la posibilidad de detenerse hasta que se cumpla cada condición. Siguen una cadena de dependencias natural: commit → push → PR → CI. Si una política deniega, las políticas posteriores de la cadena se omiten (la denegación provoca un cortocircuito).
+
+Todas las políticas de flujo de trabajo son **fail-open**: si la herramienta requerida no está disponible (p. ej. `gh` no instalado, sin remote de git), la política permite con un mensaje informativo explicando por qué se omitió la comprobación.
+
+### Semántica de Stop por CLI
+
+La aplicación de Stop se ve ligeramente diferente según cada uno de los seis CLIs compatibles, ya que cada uno expone un contrato de hook de «agente finalizado» distinto. El **resultado** es el mismo — el agente no puede detenerse mientras una compuerta de flujo de trabajo esté fallando — pero los **mecanismos** difieren. La tabla siguiente lo resume; solo Pi tiene una particularidad visible para el usuario que conviene entender antes de habilitar una política `require-*-before-stop`.
+
+| CLI | Cuándo se activa la compuerta | Qué ves |
+|---|---|---|
+| Claude Code | En el mismo bucle del agente, inmediatamente | Claude continúa trabajando — resuelve el problema y vuelve a intentar finalizar. Sin interrupción visible para ti. |
+| Codex | En el mismo bucle del agente, inmediatamente | Igual que Claude. |
+| GitHub Copilot CLI | En el mismo bucle del agente, inmediatamente | Igual que Claude (usa el canal de reintento `{decision:"block", reason}` de Copilot — verificado empíricamente contra Copilot CLI 1.0.41). |
+| Cursor Agent | En el mismo bucle del agente, inmediatamente | Igual que Claude (usa el canal `{followup_message}` de Cursor — limitado a `loop_limit`, por defecto 5 reintentos). |
+| OpenCode | En el mismo bucle del agente, inmediatamente | Igual que Claude (usa la llamada SDK `client.session.prompt(...)` de OpenCode enrutada a través de `hookSpecificOutput.additionalContext`). |
+| **Pi (pi-coding-agent)** | **Siguiente turno del usuario** | **Pi se detiene visiblemente** cuando se activa la compuerta — su bucle de agente termina y se te devuelve al prompt. La compuerta se activa la próxima vez que envíes un prompt: failproofai antepone una directiva `MANDATORY ACTION REQUIRED` al prompt de sistema de ese turno, instruyendo al LLM para que complete el paso del flujo de trabajo (commit, push, etc.) antes de hacer lo que pediste. |
+
+<Note>
+**Limitación de Pi.** El `AgentEndEvent` de Pi (el equivalente upstream al hook `Stop` de Claude) no tiene tipo Result — cuando se activa, el bucle del agente de Pi ya ha terminado. Pi no puede ser forzado a reintentar el mismo bucle como Claude / Copilot / Cursor / OpenCode. failproofai traslada la compuerta al evento `before_agent_start` de Pi (que se activa tras el siguiente prompt del usuario) para que la comprobación del flujo de trabajo siga aplicándose, aunque en el turno siguiente en lugar del actual.
+
+**Lo que esto significa en la práctica:**
+
+- Cuando Pi se detiene, la razón de denegación se captura en memoria, indexada por el ID de sesión de Pi. El siguiente prompt que envíes en el mismo proceso de Pi la consume: el LLM ve la directiva `MANDATORY ACTION REQUIRED` al comienzo de su prompt de sistema, realiza el commit (o push / abre el PR / espera a CI) y solo entonces continúa con tu solicitud. La razón capturada es de un solo uso — una vez consumida, la compuerta queda libre.
+- La compuerta está limitada por la vida útil del proceso de Pi. Si haces `Ctrl+C` en Pi o sales entre turnos, la entrada en memoria se descarta junto con el proceso y la compuerta se pierde. Claude, Copilot, Cursor y OpenCode tienen el mismo límite (matar el agente hace que se pierda la compuerta) — Pi simplemente lo hace más visible porque el agente termina visiblemente antes de que se active la compuerta.
+- Una denegación pendiente también se borra en `session_shutdown` por cualquier razón (`new` / `resume` / `fork` / `quit`), por lo que una compuerta obsoleta de una sesión anterior no puede filtrarse en una sesión nueva iniciada en el mismo proceso de Pi.
+
+Si necesitas el comportamiento de reintento en el mismo bucle al estilo Claude, ejecuta tus políticas `Stop` bajo cualquiera de los otros cinco CLIs compatibles. Estamos siguiendo el upstream de Pi para un futuro tipo Result en `AgentEndEvent` que nos permitiría cerrar esta brecha.
+</Note>
+
+### `require-commit-before-stop`
+
+**Evento:** Stop  
+**Por defecto:** Deniega la detención cuando hay cambios sin confirmar (archivos modificados, preparados o sin seguimiento). Devuelve un mensaje informativo cuando el directorio de trabajo está limpio.
+
+Sin parámetros.
+
+---
+
+### `require-push-before-stop`
+
+**Evento:** Stop  
+**Por defecto:** Deniega la detención cuando hay commits sin publicar o cuando la rama actual no tiene una rama de seguimiento remota. Sugiere `git push -u` para crear una rama de seguimiento si es necesario. Fail-open si no hay ningún remote configurado.
+
+**Parámetros:**
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-------|------|---------|-------------|
+| `remote` | `string` | `"origin"` | Nombre del remote al que hacer push. |
+
+**Ejemplo:**
+
+```json
+{
+  "policyParams": {
+    "require-push-before-stop": {
+      "remote": "upstream"
+    }
+  }
+}
+```
+
+---
+
+### `require-pr-before-stop`
+
+**Evento:** Stop  
+**Por defecto:** Deniega la detención cuando no existe ningún pull request para la rama actual, o cuando el PR existente está cerrado sin fusionar. Instruye a Claude para que cree un PR con `gh pr create`. Cuando el PR está **fusionado**, la política permite (el trabajo ha sido publicado) y el mensaje sugiere cambiar de rama (`git checkout main && git pull`).
+
+Sin parámetros.
+
+<Note>
+Esta política requiere que [GitHub CLI](https://cli.github.com/) (`gh`) esté instalado y autenticado.
+Ejecuta `gh auth login` con un token de acceso personal que tenga el ámbito `repo` para acceso de lectura a
+pull requests. Si `gh` no está instalado o no está autenticado, la política aplica fail-open e informa a Claude del motivo.
+</Note>
+
+---
+
+### `require-no-conflicts-before-stop`
+
+**Evento:** Stop  
+**Por defecto:** Deniega la detención cuando la rama actual no puede fusionarse limpiamente en la rama base. La política primero confirma que existe un PR `OPEN` en GitHub para la rama — sin él, no hay destino de fusión que aplicar, por lo que toda la política aplica cortocircuito hacia allow. Una vez confirmado un PR `OPEN`, se ejecutan dos sondeos independientes:
+
+1. **Local** — `git merge-tree --write-tree --name-only origin/<baseBranch> HEAD`. En caso de conflicto, el mensaje de denegación nombra los archivos en conflicto para que Claude sepa exactamente qué resolver.
+2. **GitHub** — reutiliza el resultado de `gh pr view --json mergeable,state` ya obtenido en la precomprobación. Detecta conflictos que un `origin/<baseBranch>` local desactualizado pasaría por alto (p. ej. alguien publicó un PR conflictivo en `main` desde la última sincronización). Un resultado `CONFLICTING` deniega. Un resultado `UNKNOWN` también deniega e instruye a Claude para que espere ~10 segundos y vuelva a comprobar antes de intentar detenerse de nuevo — esto evita falsos negativos mientras GitHub recalcula.
+
+Se omite completamente (allow) cuando: `gh` no está instalado, no existe ningún PR para la rama, el estado del PR no es `OPEN` (p. ej. `MERGED`, `CLOSED`), o `gh pr view` devuelve una salida no analizable. También fail-open cuando `origin/<baseBranch>` falta localmente o cuando no hay commits por delante de la base — esos fallbacks de Capa 1 aún consultan la fusionabilidad del PR en caché antes de permitir.
+
+**Parámetros:**
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-------|------|---------|-------------|
+| `baseBranch` | `string` | `"main"` | Rama base contra la que se comprueban los conflictos. |
+
+<Note>
+Esta política requiere GitHub CLI (`gh`). Usa `gh pr view` para confirmar
+que existe un PR `OPEN` antes de ejecutar cualquier sondeo de conflictos — sin `gh`, la política
+aplica cortocircuito hacia allow. Ejecuta `gh auth login` con un token de acceso personal que tenga
+el ámbito `repo` para acceso de lectura a pull requests.
+</Note>
+
+---
+
+### `require-ci-green-before-stop`
+
+**Evento:** Stop  
+**Por defecto:** Deniega la detención cuando las comprobaciones de CI están fallando o aún en ejecución en la rama actual. Comprueba tanto las ejecuciones de flujo de trabajo de GitHub Actions como las comprobaciones de bots de terceros (p. ej. CodeRabbit, SonarCloud, Codecov). Trata las conclusiones `skipped`, `cancelled` y `neutral` como no fallidas (esta última cubre, por ejemplo, alertas de Socket Security en PRs de contribuidores externos, donde la aplicación intencionalmente informa neutral en lugar de éxito/fallo). Devuelve un mensaje informativo cuando todas las comprobaciones pasan.
+
+Sin parámetros.
+
+<Note>
+Esta política requiere que [GitHub CLI](https://cli.github.com/) (`gh`) esté instalado y autenticado.
+Ejecuta `gh auth login` con un token de acceso personal que tenga el ámbito `repo` para acceso de lectura a
+ejecuciones de flujo de trabajo de Actions y a la API de Checks. Si `gh` no está instalado o no está autenticado, la política aplica fail-open e informa a Claude del motivo.
+</Note>
+
+---
+
+---
+
+## Deshabilitar políticas individuales
+
+Elimina una política específica de `enabledPolicies` en tu configuración, o desactívala en la pestaña Políticas del panel de control.
+
+```json
+{
+  "enabledPolicies": [
+    "block-rm-rf",
+    "sanitize-api-keys"
+  ]
+}
+```
+
+Las políticas que no aparecen en `enabledPolicies` no se ejecutan, aunque existan entradas en `policyParams` para ellas.