Atualizar o zn-gate

O que fazer ao atualizar o zn-gate: quando rodar zn hooks install de novo, por que o Codex pede para confiar nos hooks outra vez, o que fazer depois de atualizar ou mover o Node.js com nvm, como conferir com zn-gate check e o que cada versão pede desde a 1.8.0.

Ver .md

Rode todos os comandos desta página no seu próprio terminal, não por meio de um agente de IA: os hooks do zn recusam zn hooks install e alguns outros comandos quando um agente os inicia.

A versão curta

Atualize o pacote: npm install -g zn-gate (e pip install -U zn-gate se você usa o pacote Python). Se você só roda npx -y zn-gate ..., não há nada para atualizar.
Procure sua versão antiga e a nova na tabela abaixo. A maioria das versões não pede mais nada.
Rode zn-gate check. Cada agente configurado deve mostrar OK.

Se o zn-gate check disser que um agente não está protegido, ele também mostra o comando que corrige.

Rode `zn hooks install <agent>` de novo quando uma versão mudar o hook

Os hooks do zn hooks install (Claude Code, Codex CLI, Cursor) são gravados nas configurações do próprio agente, então um zn-gate novo não os reescreve sozinho. Quando uma versão adiciona ou muda um hook, as notas da versão dizem isso e nomeiam o agente. Rode a instalação de novo para esse agente:

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

Rodar de novo é seguro: ele atualiza as entradas do zn e deixa o resto das suas configurações como está. Desde a 1.13.0, o zn-gate check também avisa quando os hooks do Claude Code que ele encontra não têm um hook que o seu zn-gate tem.

Outros casos:

O plugin zn-gate para o Claude Code é atualizado pelo gerenciador de plugins do Claude Code (/plugin dentro do Claude Code). Depois, abra uma nova sessão do Claude Code. O plugin instala a versão do zn-gate à qual está fixado, então você não roda zn hooks install para ele. Não mantenha ao mesmo tempo o plugin e os hooks de zn hooks install claude-code: os dois rodariam. Remova os hooks com zn hooks uninstall claude-code.
O OpenCode usa um pequeno arquivo de plugin que o zn-gate grava. Rode zn hooks install opencode de novo quando uma versão indicar.
Instalações de projeto (zn hooks install <agent> --project) gravam arquivos que você pode versionar (.claude/settings.json, .codex/hooks.json, .cursor/hooks.json, .opencode/plugins/zn-gate.js). Eles chamam o zn a partir do seu PATH, então seguem o zn-gate que você tem instalado. Rode a instalação de novo no projeto quando uma versão mudar o hook e versione o arquivo alterado.

O Codex pede para confiar nos hooks outra vez

O Codex só roda um hook depois que você confia nele, e pergunta de novo quando um hook é novo ou mudou. Depois de zn hooks install codex (na primeira vez e após qualquer versão que mude o hook), abra o Codex e aprove os hooks com /hooks. Até você fazer isso, o Codex não roda o hook novo ou alterado, e o zn não verifica essa parte. O zn-gate check mostra o Codex como protegido só quando o hook funciona.

Para automações que já verificam seus próprios hooks, codex exec --dangerously-bypass-hook-trust pula a pergunta em uma execução. Não use no dia a dia.

O Node.js foi atualizado, movido ou removido (nvm, fnm, Homebrew)

Uma instalação de usuário dos hooks grava os caminhos do Node.js e dos arquivos do zn-gate a partir dos quais ela foi executada. Um pacote global do npm pertence a uma versão do Node.js, então nvm use, nvm uninstall, uma atualização do Node.js pelo Homebrew ou uma nova instalação do Node.js podem deixar o hook apontando para algo que não existe mais. Quando o hook não consegue iniciar:

Prompts: Claude Code 2.1.295 ou posterior, Cursor e OpenCode os bloqueiam em vez de deixá-los passar sem verificação. O Codex CLI os deixa passar.
Chamadas de ferramentas: no Claude Code e no Codex CLI elas seguem sem verificação.

Para corrigir, com o Node.js que você quer manter:

Rode npx -y zn-gate check. Ele mostra cada agente que não está protegido e o comando que corrige.
Normalmente é npm install -g zn-gate e depois zn hooks install <agent>. Se você usa o Codex, confie nos hooks alterados em /hooks.
Com o plugin zn-gate para o Claude Code, corrija o Node.js (o plugin precisa da 20.12 ou posterior) e abra uma nova sessão do Claude Code.
Se você precisa do agente agora, desative o zn para ele até corrigir: npx -y zn-gate hooks uninstall <agent> (o comando zn pode ter sumido com o Node.js antigo), ou claude plugin disable zn-gate@usezn para o plugin. Reative com zn hooks install <agent> ou claude plugin enable zn-gate@usezn e rode zn-gate check de novo.

Confira se funciona

zn-gate check

Ele cria uma pasta temporária com um arquivo .env que tem uma chave falsa e um arquivo comum, pede ao hook instalado de cada agente que leia os dois e só conta um agente como protegido quando o arquivo .env é bloqueado e o arquivo comum é permitido. Nada é enviado e nenhuma configuração muda. O que significa a saída.

O que cada versão pede

Versões a partir da 1.8.0. "Nenhuma ação" significa que atualizar o pacote basta. Para a lista completa de mudanças, veja o changelog.

Versão	Data	O que fazer
1.13.1	2026-10-20	Só se você usa as integrações Python com LangChain ou LlamaIndex: atualize com `pip install -U zn-gate`. Um prompt, uma chamada de ferramenta ou uma saída de ferramenta bloqueados agora interrompem a execução do LangChain, e com `mask_secrets=True` uma saída de ferramenta que contém um segredo também a interrompe. `ZnGuardCallbackHandler(on_block="return")` agora gera `ValueError`: em vez disso, envolva a ferramenta com `guard_langchain_tool(tool, on_block="return")` (veja LangChain, CrewAI e LlamaIndex). O pacote npm não muda. Se você envolve seus tools com `guard_langchain_tool`, crie o handler com `mask_secrets=False`.
1.13.0	2026-10-19	Se você instalou os hooks do Claude Code com `zn hooks install claude-code`, rode de novo para adicionar o hook que verifica no que uma skill ou um comando digitado se expande (o `zn-gate check` avisa; o plugin já tem). Com um Node.js anterior à 20.12, o `zn-gate init` configura os hooks no lugar do plugin; se você tem o plugin lá, o `check` indica a saída. Em um workflow do GitHub que usa a Action sem `version`, defina `version` para escolher o que roda: a Action da 1.12.0 usava a 1.10.0 por padrão.
1.12.0	2026-10-18	Nenhuma ação. Se você verifica as assinaturas das versões, o workflow assinante agora é `build-release.yml` (veja verificar uma versão).
1.11.0	2026-10-17	Nenhuma ação. Um job de CI que falha quando o `zn-gate scan` encontra segredos pode passar a falhar com tokens dos novos tipos (por exemplo tokens do Square, Discord, Grafana ou Notion): examine cada achado e troque qualquer token real.
1.10.0	2026-10-16	Se um script roda `zn unlock` com o chaveiro do sistema, agora ele precisa de um terminal interativo (`--passphrase-stdin` com o backend de senha continua funcionando a partir de um pipe).
1.9.1	2026-10-16	Nenhuma ação. Um job de CI que falha com os achados do `zn-gate scan` pode passar a falhar com mais tipos de segredos. Com Node.js anterior ao 18, os comandos `zn-gate` e `zn` param com uma mensagem que diz como instalar o Node.js 18 ou posterior.
1.9.0	2026-10-16	Se um script roda `zn-gate init` sem opções para envolver servidores MCP, mude para `zn-gate init --wrap-mcp`: o `init` sozinho agora é uma configuração guiada que só roda no seu próprio terminal.
1.8.2	2026-10-15	Nenhuma ação.
1.8.1	2026-10-15	Atualize se você usa os hooks de agente; nenhum outro passo.
1.8.0	2026-10-15	Rode `zn unlock` uma vez depois de atualizar: um cofre ainda em execução de uma versão mais antiga mantém os segredos como marcadores e tokens nos hooks até reiniciar. Python 3.8 e 3.9 não são mais suportados (o pip neles continua instalando a 1.7.1). Em uma organização zn Team com regras de aviso (Warn), não volte para a 1.7.1.

Se você está atualizando de uma versão anterior à 1.8.0, passe pelas linhas de todas as versões intermediárias. As versões mais antigas estão no changelog.