docs: clearer Spanish + emphasize the PreToolUse hook

CHANGELOG.md

@@ -6,6 +6,14 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.9.2] - 2026-06-11
+
+### Changed
+- Docs: clearer Spanish in the Agent Safety guide — replaced the "gatear"
+  anglicism (which reads as "to crawl" in Spanish) with "controlar", and
+  promoted the PreToolUse **hook** as the definitive, un-bypassable block rather
+  than a footnote to the permission rules.
+
 ## [0.9.1] - 2026-06-11
 
 ### Fixed

docs/reference/vs-official-mcp.es.md

@@ -52,7 +52,7 @@ persona escribiendo comandos. El razonamiento está expuesto en el post
 - **La seguridad es aplicable.** `--dry-run` previsualiza la petición exacta en cualquier
   comando, `delete` pide confirmación, y un shell puede bloquear comandos destructivos con
   hooks — de modo que un agente autónomo *no puede* borrar aunque lo intente. Mira
-  [Seguridad para agentes](../user-guide/agent-safety.md) para el gateo por host (Claude
+  [Seguridad para agentes](../user-guide/agent-safety.md) para el control por host (Claude
   Code, Codex, OpenCode).
 - **Dos vías de entrada para agentes.** Un agente de código con acceso al shell usa la
   **skill** (aprende las reglas de oro y cuándo llamar a cada comando); un host del

docs/user-guide/agent-safety.es.md

@@ -3,7 +3,7 @@ title: Seguridad para agentes
 description: Evita que un agente de IA ejecute operaciones contables destructivas, con hooks y configuración por host para Claude Code, Codex y OpenCode.
 ---
 
-# Seguridad para agentes: gatear operaciones destructivas
+# Seguridad para agentes: controlar operaciones destructivas
 
 Dejar que un agente de IA toque tu contabilidad es útil pero riesgoso: puede
 crear facturas, registrar pagos, eliminar registros y emitir facturas
@@ -15,14 +15,23 @@ Ten claro qué hace cada capa:
 
 | Capa | Mecanismo | Qué hace | ¿Hace cumplir? |
 | --- | --- | --- | --- |
-| 1. Anotaciones de tools | `alegra mcp` marca cada tool como solo lectura o destructiva | Permite que un host que respete anotaciones gatee las escrituras solo | **Advisoria** — depende del host |
-| 2. Config del host | reglas deny / ask y hooks en el agente | Bloquea o pide aprobación antes de ejecutar un comando/tool | **Sí** — esta es la barrera real |
+| 1. Anotaciones de tools | `alegra mcp` marca cada tool como solo lectura o destructiva | Permite que un host que respete anotaciones controle las escrituras por su cuenta | **Advisoria** — depende del host |
+| 2. Config del host | reglas deny / ask **y un hook PreToolUse** | El hook inspecciona el comando real y no se esquiva con trucos del shell — el bloqueo definitivo | **Sí** — esta es la barrera real |
 | 3. Built-ins del CLI | `--dry-run`, confirmación de `delete` | Previsualización y confirmación manual en una terminal | Solo shell (no la superficie MCP) |
 
 El resumen honesto: **la capa 1 hace que los buenos hosts se porten bien por
 defecto, pero no es un límite de seguridad. La capa 2 es la que de verdad
 bloquea.** Usa ambas.
 
+!!! tip "El hook es la capa que no se puede esquivar"
+    Los globs de `deny`/`ask` son fáciles de leer, pero un comando de shell bien
+    armado puede esquivarlos (comillas, subshells, `&&`). Un **hook PreToolUse**
+    corre tu código contra el comando o tool *real* antes de ejecutarlo, así que
+    es la capa que **bloquea de forma definitiva** — en las superficies shell y
+    MCP. `alegra agent guard --host claude-code` te lo genera. (Los hooks son una
+    función de Claude Code; Codex bloquea con un sandbox de solo lectura,
+    OpenCode con reglas `deny`.)
+
 ## La vía rápida: `alegra agent guard`
 
 `alegra` te genera la config de la capa 2, con las operaciones destructivas
@@ -64,7 +73,7 @@ Lo que eso te da depende por completo del host:
 
 - Un host que respeta anotaciones (p. ej. **Codex**) pedirá aprobación para las
   tools destructivas y dejará correr las de solo lectura, automáticamente.
-- Un host que gatea por nombre de tool (p. ej. **Claude Code**) ignora la
+- Un host que controla por nombre de tool (p. ej. **Claude Code**) ignora la
   anotación para las decisiones de permiso — ahí configuras reglas (capa 2).
 
 Las anotaciones son advisorias según la spec de MCP: un host que las ignore
@@ -80,7 +89,7 @@ ejecuta todo. Nunca reemplazan la capa 2.
 
 ### Claude Code
 
-Claude Code gatea por **nombre de tool/comando**, y **`deny` siempre le gana a
+Claude Code controla por **nombre de tool/comando**, y **`deny` siempre le gana a
 `allow`**. Pon esto en el `.claude/settings.json` del proyecto (compartido con
 el equipo) o en `~/.claude/settings.json` (todos los proyectos).
 
@@ -106,9 +115,12 @@ Usa `"ask"` en vez de `"deny"` para pedir aprobación en lugar de bloquear de
 plano. Un comando denegado nunca corre; en una sesión headless/CI `ask` también
 falla cerrado (sin humano que apruebe → bloqueado).
 
-Los patrones glob se pueden esquivar con trucos del shell (comillas, subshells,
-`&&`). Para una barrera real, agrega un **hook PreToolUse** que inspeccione el
-comando real. Crea `.claude/hooks/block-alegra-writes.sh`:
+**El bloqueo definitivo es un hook PreToolUse.** Los globs de `deny` de arriba
+ayudan, pero un comando de shell bien armado puede esquivarlos (comillas,
+subshells, `&&`); un hook corre tu código contra el comando real antes de
+ejecutarlo, así que no se puede esquivar — y el mismo hook cubre también la
+superficie MCP. Esta es la pieza más importante en Claude Code. Crea
+`.claude/hooks/block-alegra-writes.sh`:
 
 ```bash
 #!/usr/bin/env bash
@@ -167,13 +179,13 @@ vez de intentar hacer allow-list de las lecturas:
 Los patrones de permiso MCP se evalúan como expresiones regulares, así que el
 `.*` y el grupo `(...)` funcionan tal cual; las tools de lectura (`..._list`,
 `..._get`, `..._export`) quedan intactas. Un hook PreToolUse también puede
-gatear tools MCP — pon `"matcher": "mcp__alegra__.*"` e inspecciona
+controlar tools MCP — pon `"matcher": "mcp__alegra__.*"` e inspecciona
 `.tool_name` en el script para semántica de allow-list (deniega cualquier cosa
 que no sea un verbo de lectura).
 
 ### Codex
 
-Codex gatea con dos ajustes en `config.toml` (`~/.codex/config.toml`):
+Codex controla con dos ajustes en `config.toml` (`~/.codex/config.toml`):
 `sandbox_mode` y `approval_policy`.
 
 **Superficie shell** — la barrera más fuerte y simple es quitar el acceso de
@@ -204,7 +216,7 @@ nada que aprobar.
 
 ### OpenCode
 
-OpenCode gatea con un bloque `permission` en `opencode.json`. Cada regla es
+OpenCode controla con un bloque `permission` en `opencode.json`. Cada regla es
 `"allow"`, `"ask"` o `"deny"`, y **gana el último patrón que coincide**, así que
 pon el comodín primero y las denegaciones específicas después.
 

docs/user-guide/agent-safety.md

@@ -16,12 +16,21 @@ Be clear about what each layer actually does:
 | Layer | Mechanism | What it does | Enforces? |
 | --- | --- | --- | --- |
 | 1. Tool annotations | `alegra mcp` marks each tool read-only or destructive | Lets an annotation-aware host gate writes on its own | **Advisory** — depends on the host |
-| 2. Host config | deny / ask rules and hooks in the agent | Blocks or prompts before a command/tool runs | **Yes** — this is the real gate |
+| 2. Host config | deny / ask rules **and a PreToolUse hook** | The hook inspects the real command and can't be dodged by shell tricks — the definitive block | **Yes** — this is the real gate |
 | 3. CLI built-ins | `--dry-run`, `delete` confirmation | Preview and a manual confirm in a terminal | Shell only (not the MCP surface) |
 
 The honest summary: **layer 1 makes good hosts behave well by default, but it is
 not a security boundary. Layer 2 is what actually blocks.** Use both.
 
+!!! tip "The hook is the layer that can't be bypassed"
+    Permission `deny`/`ask` globs are easy to read, but a crafted shell command
+    can dodge them (quoting, subshells, `&&`). A **PreToolUse hook** runs your
+    code against the *actual* command or tool before it executes, so it is the
+    layer that **definitively** blocks — on both the shell and MCP surfaces.
+    `alegra agent guard --host claude-code` generates it for you. (Hooks are a
+    Claude Code feature; Codex blocks with a read-only sandbox, OpenCode with
+    `deny` rules.)
+
 ## The quick way: `alegra agent guard`
 
 `alegra` generates the layer-2 config for you, with the destructive operations
@@ -103,9 +112,11 @@ Use `"ask"` instead of `"deny"` to require approval rather than hard-block. A
 denied command never runs; in a headless/CI session `ask` also fails closed
 (no human to approve → blocked).
 
-Glob patterns can be dodged with shell tricks (quoting, subshells, `&&`). For a
-real gate, add a **PreToolUse hook** that inspects the actual command. Create
-`.claude/hooks/block-alegra-writes.sh`:
+**The definitive block is a PreToolUse hook.** The `deny` globs above help, but
+a crafted shell command can dodge them (quoting, subshells, `&&`); a hook runs
+your code against the actual command before it executes, so it cannot be
+bypassed — and the same hook also covers the MCP surface. This is the most
+important piece on Claude Code. Create `.claude/hooks/block-alegra-writes.sh`:
 
 ```bash
 #!/usr/bin/env bash

docs/user-guide/mcp.es.md

@@ -66,6 +66,6 @@ en Alegra".
 ## Mantenlo seguro
 
 Cada tool expuesta está anotada como solo lectura o destructiva, así que un host
-que respete las anotaciones MCP gatea las escrituras por su cuenta. Para
+que respete las anotaciones MCP controla las escrituras por su cuenta. Para
 realmente bloquear las tools destructivas (`void`, `emit`, `delete`, …) del lado
 del agente, mira [Seguridad para agentes](agent-safety.md).