Mettre à jour zn-gate

Que faire quand vous mettez à jour zn-gate : quand relancer zn hooks install, pourquoi Codex vous demande de faire de nouveau confiance aux hooks, que faire après une mise à jour ou un déplacement de Node.js avec nvm, comment vérifier avec zn-gate check et ce que demande chaque version depuis la 1.8.0.

Voir le .md

Lancez toutes les commandes de cette page dans votre propre terminal, pas par l’intermédiaire d’un agent IA : les hooks de zn refusent zn hooks install et quelques autres commandes quand un agent les démarre.

La version courte

Mettez le paquet à jour : npm install -g zn-gate (et pip install -U zn-gate si vous utilisez le paquet Python). Si vous ne lancez jamais que npx -y zn-gate ..., il n’y a rien à mettre à jour.
Cherchez votre ancienne et votre nouvelle version dans le tableau ci-dessous. La plupart des versions ne demandent rien de plus.
Lancez zn-gate check. Chaque agent configuré devrait afficher OK.

Si zn-gate check indique qu’un agent n’est pas protégé, il affiche aussi la commande qui le corrige.

Relancez `zn hooks install <agent>` quand une version change le hook

Les hooks de zn hooks install (Claude Code, Codex CLI, Cursor) sont écrits dans les réglages de l’agent lui-même : un nouveau zn-gate ne les réécrit donc pas tout seul. Quand une version ajoute ou change un hook, ses notes de version le disent et nomment l’agent. Relancez l’installation pour cet agent :

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

La relancer ne risque rien : elle met à jour les entrées de zn et laisse le reste de vos réglages en place. Depuis la 1.13.0, zn-gate check signale aussi quand les hooks de Claude Code qu’il trouve n’ont pas un hook que votre zn-gate possède.

Autres cas :

Le plugin zn-gate pour Claude Code se met à jour par le gestionnaire de plugins de Claude Code (/plugin dans Claude Code). Ouvrez ensuite une nouvelle session Claude Code. Le plugin installe la version de zn-gate à laquelle il est épinglé : vous ne lancez donc pas zn hooks install pour lui. Ne gardez pas à la fois le plugin et les hooks de zn hooks install claude-code : les deux s’exécuteraient. Retirez les hooks avec zn hooks uninstall claude-code.
OpenCode utilise un petit fichier de plugin qu’écrit zn-gate. Relancez zn hooks install opencode quand une version l’indique.
Les installations de projet (zn hooks install <agent> --project) écrivent des fichiers que vous pouvez versionner (.claude/settings.json, .codex/hooks.json, .cursor/hooks.json, .opencode/plugins/zn-gate.js). Ils appellent zn depuis votre PATH, donc ils suivent le zn-gate que vous avez installé. Relancez l’installation dans le projet quand une version change le hook, puis versionnez le fichier modifié.

Codex vous demande de faire de nouveau confiance aux hooks

Codex n’exécute un hook qu’après que vous lui avez fait confiance, et il redemande quand un hook est nouveau ou a changé. Après zn hooks install codex (la première fois et après toute version qui change le hook), ouvrez Codex et approuvez les hooks avec /hooks. Tant que vous ne l’avez pas fait, Codex n’exécute pas le hook nouveau ou modifié, et zn ne contrôle donc pas cette partie. zn-gate check n’affiche Codex comme protégé que lorsque le hook fonctionne.

Pour les automatisations qui vérifient déjà leurs propres hooks, codex exec --dangerously-bypass-hook-trust saute la question pour une exécution. Ne l’utilisez pas au quotidien.

Node.js a été mis à jour, déplacé ou supprimé (nvm, fnm, Homebrew)

Une installation utilisateur des hooks écrit les chemins du Node.js et des fichiers de zn-gate depuis lesquels elle a été lancée. Un paquet npm global appartient à une version de Node.js : nvm use, nvm uninstall, une mise à jour de Node.js par Homebrew ou une nouvelle installation de Node.js peuvent donc laisser le hook pointer vers quelque chose qui n’existe plus. Quand le hook ne peut pas démarrer :

Prompts : Claude Code 2.1.295 ou ultérieur, Cursor et OpenCode les bloquent au lieu de les laisser passer sans contrôle. Codex CLI les laisse passer.
Appels d’outils : dans Claude Code et Codex CLI, ils s’exécutent sans contrôle.

Pour corriger, avec le Node.js que vous voulez garder :

Lancez npx -y zn-gate check. Il nomme chaque agent qui n’est pas protégé et la commande qui le corrige.
En général, c’est npm install -g zn-gate, puis zn hooks install <agent>. Si vous utilisez Codex, faites confiance aux hooks modifiés dans /hooks.
Avec le plugin zn-gate pour Claude Code, corrigez Node.js (le plugin demande la 20.12 ou ultérieure) et ouvrez une nouvelle session Claude Code.
Si vous avez besoin de votre agent tout de suite, désactivez zn pour lui le temps de corriger : npx -y zn-gate hooks uninstall <agent> (la commande zn a pu disparaître avec l’ancien Node.js), ou claude plugin disable zn-gate@usezn pour le plugin. Réactivez-le avec zn hooks install <agent> ou claude plugin enable zn-gate@usezn, puis relancez zn-gate check.

Vérifiez que ça fonctionne

zn-gate check

Il crée un dossier temporaire avec un fichier .env qui contient une fausse clé et un fichier ordinaire, demande au hook installé de chaque agent de lire les deux, et ne compte un agent comme protégé que lorsque le fichier .env est bloqué et le fichier ordinaire autorisé. Rien n’est envoyé et aucun réglage ne change. Ce que signifie la sortie.

Ce que demande chaque version

Versions depuis la 1.8.0. « Rien à faire » signifie que la mise à jour du paquet suffit. Pour la liste complète des changements, voir le changelog.

Version	Date	Que faire
1.13.1	2026-10-20	Seulement si vous utilisez les intégrations Python LangChain ou LlamaIndex : mettez à jour avec `pip install -U zn-gate`. Un prompt, un appel d’outil ou une sortie d’outil bloqués arrêtent désormais l’exécution LangChain, et avec `mask_secrets=True` une sortie d’outil qui contient un secret l’arrête aussi. `ZnGuardCallbackHandler(on_block="return")` lève désormais `ValueError` : enveloppez plutôt l’outil avec `guard_langchain_tool(tool, on_block="return")` (voir LangChain, CrewAI et LlamaIndex). Le paquet npm ne change pas. Si vous enveloppez vos tools avec `guard_langchain_tool`, créez le handler avec `mask_secrets=False`.
1.13.0	2026-10-19	Si vous avez installé les hooks de Claude Code avec `zn hooks install claude-code`, relancez-le pour ajouter le hook qui contrôle ce que devient une skill ou une commande saisie (`zn-gate check` vous le dit ; le plugin l’a déjà). Avec un Node.js antérieur à 20.12, `zn-gate init` configure les hooks à la place du plugin ; si vous avez le plugin là, `check` indique la sortie. Dans un workflow GitHub qui utilise l’Action sans `version`, fixez `version` pour choisir ce qui s’exécute : l’Action de la 1.12.0 prenait la 1.10.0 par défaut.
1.12.0	2026-10-18	Rien à faire. Si vous vérifiez les signatures des versions, le workflow signataire est désormais `build-release.yml` (voir vérifier une version).
1.11.0	2026-10-17	Rien à faire. Un job CI qui échoue quand `zn-gate scan` trouve des secrets peut se mettre à échouer sur des jetons des nouveaux types (par exemple Square, Discord, Grafana ou Notion) : examinez chaque résultat et renouvelez tout jeton réel.
1.10.0	2026-10-16	Si un script lance `zn unlock` avec le trousseau du système, il lui faut désormais un terminal interactif (`--passphrase-stdin` avec le backend à phrase secrète fonctionne toujours depuis un tube).
1.9.1	2026-10-16	Rien à faire. Un job CI qui échoue sur les résultats de `zn-gate scan` peut se mettre à échouer sur davantage de types de secrets. Avec un Node.js antérieur à 18, les commandes `zn-gate` et `zn` s’arrêtent avec un message qui explique comment installer Node.js 18 ou ultérieur.
1.9.0	2026-10-16	Si un script lance `zn-gate init` sans option pour envelopper des serveurs MCP, remplacez par `zn-gate init --wrap-mcp` : `init` seul est désormais une configuration guidée qui ne s’exécute que dans votre propre terminal.
1.8.2	2026-10-15	Rien à faire.
1.8.1	2026-10-15	Mettez à jour si vous utilisez les hooks d’agent ; aucune autre étape.
1.8.0	2026-10-15	Lancez `zn unlock` une fois après la mise à jour : un coffre encore actif d’une version plus ancienne garde les secrets sous forme de marqueurs et de jetons dans les hooks jusqu’à son redémarrage. Python 3.8 et 3.9 ne sont plus pris en charge (pip y continue d’installer la 1.7.1). Dans une organisation zn Team avec des règles d’avertissement (Warn), ne revenez pas à la 1.7.1.

Si vous mettez à jour depuis une version antérieure à la 1.8.0, parcourez les lignes de toutes les versions intermédiaires. Les versions plus anciennes sont dans le changelog.