Actualizar zn-gate

Qué hacer al actualizar zn-gate: cuándo ejecutar de nuevo zn hooks install, por qué Codex te pide volver a confiar en los hooks, qué hacer tras actualizar o mover Node.js con nvm, cómo comprobarlo con zn-gate check y qué pide cada versión desde la 1.8.0.

Ver .md

Ejecuta todos los comandos de esta página en tu propio terminal, no a través de un agente de IA: los hooks de zn rechazan zn hooks install y algunos otros comandos cuando los lanza un agente.

La versión corta

Actualiza el paquete: npm install -g zn-gate (y pip install -U zn-gate si usas el paquete de Python). Si solo ejecutas npx -y zn-gate ..., no hay nada que actualizar.
Busca tu versión anterior y la nueva en la tabla de abajo. La mayoría de las versiones no piden nada más.
Ejecuta zn-gate check. Cada agente configurado debería decir OK.

Si zn-gate check dice que un agente no está protegido, también imprime el comando que lo arregla.

Ejecuta de nuevo `zn hooks install <agent>` cuando una versión cambia el hook

Los hooks de zn hooks install (Claude Code, Codex CLI, Cursor) se escriben en los ajustes del propio agente, así que un zn-gate nuevo no los reescribe por sí solo. Cuando una versión añade o cambia un hook, sus notas de versión lo dicen y nombran el agente. Ejecuta de nuevo la instalación para ese agente:

zn hooks install claude-code   # o codex, cursor, opencode

Repetirlo es seguro: actualiza las entradas de zn y no toca el resto de tus ajustes. Desde la 1.13.0, zn-gate check también avisa cuando a los hooks de Claude Code que encuentra les falta un hook que tu zn-gate sí tiene.

Otros casos:

El plugin zn-gate para Claude Code se actualiza con el gestor de plugins de Claude Code (/plugin dentro de Claude Code). Después abre una sesión nueva de Claude Code. El plugin instala la versión de zn-gate a la que está fijado, así que no ejecutas zn hooks install para él. No mantengas a la vez el plugin y los hooks de zn hooks install claude-code: se ejecutarían los dos. Quita los hooks con zn hooks uninstall claude-code.
OpenCode usa un pequeño archivo de plugin que escribe zn-gate. Ejecuta de nuevo zn hooks install opencode cuando una versión lo indique.
Instalaciones de proyecto (zn hooks install <agent> --project) escriben archivos que puedes subir al repositorio (.claude/settings.json, .codex/hooks.json, .cursor/hooks.json, .opencode/plugins/zn-gate.js). Llaman a zn desde tu PATH, así que siguen al zn-gate que tienes instalado. Ejecuta de nuevo la instalación en el proyecto cuando una versión cambie el hook y sube el archivo modificado.

Codex te pide volver a confiar en los hooks

Codex ejecuta un hook solo después de que confíes en él, y vuelve a preguntar cuando un hook es nuevo o ha cambiado. Tras zn hooks install codex (la primera vez y después de cualquier versión que cambie el hook), abre Codex y aprueba los hooks con /hooks. Hasta que lo hagas, Codex no ejecuta el hook nuevo o modificado, así que zn no revisa esa parte. zn-gate check muestra Codex como protegido solo cuando el hook funciona.

Para automatizaciones que ya verifican sus propios hooks, codex exec --dangerously-bypass-hook-trust se salta la pregunta en una ejecución. No lo uses en el trabajo diario.

Node.js se actualizó, se movió o se quitó (nvm, fnm, Homebrew)

Una instalación de usuario de los hooks escribe las rutas del Node.js y de los archivos de zn-gate desde los que se ejecutó. Un paquete global de npm pertenece a una versión de Node.js, así que nvm use, nvm uninstall, una actualización de Node.js con Homebrew o una instalación nueva de Node.js pueden dejar el hook apuntando a algo que ya no existe. Cuando el hook no puede arrancar:

Prompts: Claude Code 2.1.295 o posterior, Cursor y OpenCode los bloquean en lugar de dejarlos pasar sin revisar. Codex CLI los deja pasar.
Llamadas a herramientas: en Claude Code y Codex CLI se ejecutan sin revisar.

Para arreglarlo, con el Node.js que quieras conservar:

Ejecuta npx -y zn-gate check. Nombra cada agente que no está protegido y el comando que lo arregla.
Normalmente es npm install -g zn-gate y después zn hooks install <agent>. Si usas Codex, confía en los hooks modificados en /hooks.
Con el plugin zn-gate para Claude Code, arregla Node.js (el plugin necesita la 20.12 o posterior) y abre una sesión nueva de Claude Code.
Si necesitas tu agente ya, desactiva zn para él hasta arreglarlo: npx -y zn-gate hooks uninstall <agent> (el comando zn puede haberse ido con el Node.js anterior), o claude plugin disable zn-gate@usezn para el plugin. Vuelve a activarlo con zn hooks install <agent> o claude plugin enable zn-gate@usezn y ejecuta otra vez zn-gate check.

Comprueba que funciona

zn-gate check

Crea una carpeta temporal con un archivo .env que contiene una clave falsa y un archivo normal, pide al hook instalado de cada agente que lea ambos y cuenta un agente como protegido solo cuando el archivo .env se bloquea y el normal se permite. No se envía nada y no cambia ningún ajuste. Qué significa la salida.

Qué pide cada versión

Versiones desde la 1.8.0. "Sin acción" significa que basta con actualizar el paquete. Para la lista completa de cambios, consulta el changelog.

Versión	Fecha	Qué hacer
1.13.1	2026-10-20	Solo si usas las integraciones de Python con LangChain o LlamaIndex: actualiza con `pip install -U zn-gate`. Un prompt, una llamada a herramienta o una salida de herramienta bloqueados ahora detienen la ejecución de LangChain, y con `mask_secrets=True` también la detiene una salida de herramienta que contiene un secreto. `ZnGuardCallbackHandler(on_block="return")` ahora lanza `ValueError`: envuelve la herramienta con `guard_langchain_tool(tool, on_block="return")` en su lugar (consulta LangChain, CrewAI y LlamaIndex). El paquete de npm no cambia. Si envuelves tus tools con `guard_langchain_tool`, crea el handler con `mask_secrets=False`.
1.13.0	2026-10-19	Si instalaste los hooks de Claude Code con `zn hooks install claude-code`, ejecútalo de nuevo para añadir el hook que revisa en qué se expande una skill o un comando escrito (`zn-gate check` te lo dice; el plugin ya lo tiene). Con un Node.js anterior a 20.12, `zn-gate init` configura los hooks en lugar del plugin; si tienes el plugin ahí, `check` indica la salida. En un workflow de GitHub que usa la Action sin `version`, fija `version` para elegir qué se ejecuta: la Action de la 1.12.0 usaba por defecto la 1.10.0.
1.12.0	2026-10-18	Sin acción. Si verificas las firmas de las versiones, el workflow firmante ahora es `build-release.yml` (consulta verificar una versión).
1.11.0	2026-10-17	Sin acción. Un trabajo de CI que falla cuando `zn-gate scan` encuentra secretos puede empezar a fallar con tokens de los tipos nuevos (por ejemplo tokens de Square, Discord, Grafana o Notion): revisa cada hallazgo y rota los tokens reales.
1.10.0	2026-10-16	Si un script ejecuta `zn unlock` con el llavero del sistema, ahora necesita un terminal interactivo (`--passphrase-stdin` con el backend de frase de paso sigue funcionando desde una tubería).
1.9.1	2026-10-16	Sin acción. Un trabajo de CI que falla con los hallazgos de `zn-gate scan` puede empezar a fallar con más tipos de secretos. Con Node.js anterior a 18, los comandos `zn-gate` y `zn` se detienen con un mensaje que explica cómo instalar Node.js 18 o posterior.
1.9.0	2026-10-16	Si un script ejecuta `zn-gate init` sin opciones para envolver servidores MCP, cámbialo a `zn-gate init --wrap-mcp`: `init` a secas ahora es una configuración guiada que solo se ejecuta en tu propio terminal.
1.8.2	2026-10-15	Sin acción.
1.8.1	2026-10-15	Actualiza si usas los hooks de agente; ningún otro paso.
1.8.0	2026-10-15	Ejecuta `zn unlock` una vez tras actualizar: un almacén que sigue en marcha desde una versión anterior mantiene los secretos como marcadores y tokens en los hooks hasta que se reinicia. Python 3.8 y 3.9 ya no se admiten (pip ahí sigue instalando la 1.7.1). En una organización de zn Team con reglas de aviso (Warn), no vuelvas a la 1.7.1.

Si actualizas desde una versión anterior a la 1.8.0, repasa las filas de todas las versiones intermedias. Las versiones anteriores están en el changelog.