zn-gate para Copilot CLI

La compatibilidad con Copilot CLI es experimental. Considérala una primera capa: no puede bloquear un secreto que pegues en un prompt, y Copilot deja que una llamada siga adelante si un hook tarda demasiado (mira los Límites más abajo).

Necesitas Node.js 18 o posterior. Pega cada línea en una terminal y pulsa Intro después de cada una:

npm install -g zn-gate
zn hooks install copilot

En macOS y Linux, si npm install -g falla con EACCES, sigue la guía de npm sobre cómo corregir errores de permisos.

Solucionarlo sin derechos de administrador:

mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc

Si usas bash, escribe en ~/.bashrc en lugar de ~/.zshrc.

Después, abre una terminal nueva y ejecuta npx -y zn-gate init. Un gestor de versiones de Node.js, como nvm, también evita el problema.

Después, abre una sesión nueva de Copilot CLI. zn escribe su propio archivo, zn-gate.json, en ~/.copilot/hooks/ (o en $COPILOT_HOME/hooks/ si has definido una carpeta de Copilot personalizada) y solo edita lo que escribió allí. ¿Vas a actualizar más adelante? Consulta Actualizar zn-gate.

Solo para un proyecto

Ejecuta zn hooks install copilot --project dentro del proyecto. Escribe .github/hooks/zn-gate.json en ese proyecto en lugar de en tu carpeta personal. El hook ejecuta zn desde tu PATH, así que todas las personas que abran el proyecto en Copilot CLI necesitan tener zn-gate instalado; de lo contrario, el hook no puede arrancar. Copilot también pide a cada persona que confíe en la carpeta antes de ejecutar los hooks de un repositorio.

Qué obtienes

• zn revisa cada llamada a una herramienta antes de que se ejecute.
• Se bloquean las lecturas y escrituras de archivos secretos, como los archivos .env con valores, según la ruta del archivo.
• Se bloquean los comandos de shell que manejan secretos. Para un comando que usa un marcador __ZN_<NAME>__, zn lo bloquea y le indica al modelo la línea exacta de zn run -- ... que debe usar en su lugar.
• El agente no puede editar los archivos de hooks y de ajustes de Copilot.
• Después de que se ejecuta una herramienta de lectura o de shell, zn sustituye los valores secretos de un resultado correcto antes de que lo vea el modelo.
• Cuando una comprobación necesita tu decisión, zn te pide confirmación. Donde nadie puede responder, en el agente en la nube de Copilot y en el piloto automático, Copilot convierte esa pregunta en un bloqueo.
• zn nunca aprueba una llamada por ti. Cuando no tiene objeciones, se aplican las reglas de permisos propias de Copilot.

Límites

• Un secreto pegado en un prompt escrito no se detiene. Copilot no deja que un hook bloquee un prompt escrito.
• Copilot deja que la llamada siga adelante cuando un hook tarda demasiado. Copilot espera 30 segundos por defecto, y zn fija 15 segundos en sus hooks. zn también responde con un bloqueo cuando su propia comprobación no ha terminado a los 11 segundos.
• El registro propio de Copilot conserva la salida original. El registro de la sesión (events.jsonl) en tu equipo contiene la salida de la herramienta antes de que zn sustituyera nada. zn limpia lo que va al modelo, no ese archivo.
• También se ejecutan los hooks de política del equipo. Copilot carga además archivos de hooks de /etc/github-copilot/policy.d, que zn no puede ver.
• Algunas herramientas pueden quedar sin revisar. zn no siempre reconoce una herramienta MCP, así que sus llamadas pueden no revisarse y su salida no se limpia.
• Los ajustes pueden desactivar los hooks. "disableAllHooks": true en el archivo de zn, o en .github/copilot/settings.json o settings.local.json del repositorio, los desactiva. zn-gate check lo detecta.
• No se ha probado en Windows.
• zn se comprobó con Copilot CLI 1.0.98 y un modelo simulado, no con todas las versiones.

Comprueba que funciona

En una terminal nueva, ejecuta zn-gate check. Debe mostrar OK para Copilot CLI (experimental). Qué significa la salida.

En PowerShell de Windows, si npm dice «running scripts is disabled on this system», usa npm.cmd y zn.cmd en lugar de npm y zn: mira Instalación.

Cómo quitarlo

Ejecuta zn hooks uninstall copilot en tu propia terminal (añade --project si lo instalaste en un proyecto).