zn-gate para o Copilot CLI

O suporte ao Copilot CLI é experimental. Trate-o como uma primeira camada: ele não consegue bloquear um segredo que você cola em um prompt, e o Copilot deixa uma chamada seguir em frente se um hook demorar demais (veja os Limites abaixo).

Você precisa do Node.js 18 ou mais recente. Cole cada linha em um terminal e pressione Enter depois de cada uma:

npm install -g zn-gate
zn hooks install copilot

No macOS e no Linux, se npm install -g falhar com EACCES, siga o guia do npm sobre como corrigir erros de permissão.

Corrija sem direitos de administrador:

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

Se usar bash, escreva em ~/.bashrc em vez de ~/.zshrc.

Depois, abra um novo terminal e execute npx -y zn-gate init. Um gerenciador de versões do Node.js, como o nvm, também evita o problema.

Depois, abra uma nova sessão do Copilot CLI. O zn grava seu próprio arquivo, zn-gate.json, em ~/.copilot/hooks/ (ou em $COPILOT_HOME/hooks/ se você definiu uma pasta personalizada do Copilot) e só altera o que gravou ali. Vai atualizar depois? Veja Atualizar o zn-gate.

Só para um projeto

Execute zn hooks install copilot --project dentro do projeto. Ele grava .github/hooks/zn-gate.json nesse projeto, e não na sua pasta pessoal. O hook executa o zn a partir do seu PATH, então todas as pessoas que abrirem o projeto no Copilot CLI precisam ter o zn-gate instalado; do contrário, o hook não consegue iniciar. O Copilot também pede a cada pessoa que confie na pasta antes de executar os hooks de um repositório.

O que você recebe

• O zn verifica cada chamada de ferramenta antes de ela rodar.
• Leituras e escritas de arquivos secretos, como arquivos .env com valores, são bloqueadas pelo caminho do arquivo.
• Comandos de shell que lidam com segredos são bloqueados. Para um comando que usa um marcador __ZN_<NAME>__, o zn o bloqueia e diz ao modelo a linha exata de zn run -- ... que deve usar no lugar.
• O agente não consegue editar os arquivos de hooks e de configuração do Copilot.
• Depois que uma ferramenta de leitura ou de shell roda, o zn substitui os valores secretos de um resultado bem-sucedido antes que o modelo o veja.
• Quando uma verificação precisa da sua decisão, o zn pede que você confirme. Onde ninguém pode responder, no agente em nuvem do Copilot e no piloto automático, o Copilot transforma essa pergunta em um bloqueio.
• O zn nunca aprova uma chamada por você. Quando ele não tem objeção, valem as regras de permissão do próprio Copilot.

Limites

• Um segredo colado em um prompt digitado não é impedido. O Copilot não deixa um hook bloquear um prompt digitado.
• O Copilot deixa a chamada seguir em frente quando um hook demora demais. O Copilot espera 30 segundos por padrão, e o zn define 15 segundos nos seus hooks. O zn também responde com um bloqueio quando sua própria verificação não terminou em 11 segundos.
• O registro próprio do Copilot guarda a saída original. O registro da sessão (events.jsonl) na sua máquina contém a saída da ferramenta antes de o zn substituir qualquer coisa. O zn limpa o que vai para o modelo, não esse arquivo.
• Hooks de política da máquina também rodam. O Copilot também carrega arquivos de hooks de /etc/github-copilot/policy.d, que o zn não consegue ver.
• Algumas ferramentas podem ficar sem verificação. O zn nem sempre reconhece uma ferramenta MCP, então suas chamadas podem não ser verificadas e sua saída não é limpa.
• Configurações podem desligar os hooks. "disableAllHooks": true no arquivo do zn, ou em .github/copilot/settings.json ou settings.local.json do repositório, os desliga. O zn-gate check avisa.
• Ele não foi testado no Windows.
• O zn foi verificado com o Copilot CLI 1.0.98 e um modelo simulado, não com todas as versões.

Confira se funciona

Em um novo terminal, execute zn-gate check. Ele deve mostrar OK para o Copilot CLI (experimental). O que significa a saída.

No PowerShell do Windows, se o npm disser "running scripts is disabled on this system", use npm.cmd e zn.cmd no lugar: veja Instalar.

Como remover

Execute zn hooks uninstall copilot no seu próprio terminal (acrescente --project para uma instalação de projeto).