Comment les hooks interceptent les outils

Tokenade fonctionne grâce aux hooks : de petites commandes que votre agent exécute avant et après chaque appel d'outil. Avant l'exécution, un hook peut réécrire l'appel (une commande shell passe par tokenade wrap) ; après, un hook peut remplacer le résultat par une version compacte. Vous n'avez rien à appeler : une fois les hooks écrits par tokenade install, chaque session s'en sert.

Pourquoi les hooks passent en premier

Un hook agit avant même que le résultat d'un outil soit envoyé au modèle : la sortie brute n'est donc jamais facturée. C'est pourquoi Tokenade privilégie les hooks à tout autre canal :

1. les hooks, ou un plugin passerelle pour les agents qui chargent des plugins ;
2. l'enveloppe shell (tokenade wrap, et les alias de shell-init) ;
3. le proxy MCP (mcp-wrap) ;
4. le proxy LLM, qui ne peut alléger que les tours suivants.

Chaque agent reçoit le meilleur canal qu'il prend en charge. Voir agents pris en charge pour savoir lequel utilise le vôtre.

Les hooks de Claude Code

tokenade install écrit ces entrées dans ~/.claude/settings.json. Chacune porte un _tag qui commence par tokenade, ce qui permet à uninstall de les retrouver.

tokenade hooks status liste ce qui est installé sur votre machine et tokenade hooks tail montre l'activité récente.

Ce qui arrive à chaque outil

Commandes shell

Bash(git log) devient Bash(tokenade wrap 'git log') avant de s'exécuter ; les commandes PowerShell reçoivent tokenade wrap --shell powershell '…'. L'agent voit la sortie compactée et le code de sortie de la commande d'origine. Les commandes qui ont besoin d'un terminal ou qui suivent un flux continu ne sont pas touchées, pas plus que celles visées par l'une de vos propres règles de permission deny ou ask. Voir Compaction des sorties.

Lectures de fichiers

Avant une lecture, le hook peut :

• servir un court renvoi quand le fichier n'a pas changé depuis la dernière lecture de l'agent dans la session ;
• retirer ce dont le modèle n'a pas besoin et masquer les secrets ;
• transformer les documents (PDF, Office, EPUB…) en texte et décrire les fichiers média au lieu de renvoyer des octets, comme tokenade read ;
• fournir une copie réduite d'une grande image (grand côté au-delà de 1024 px par défaut ; TOKENADE_IMAGE_MAX_EDGE=0 garde la taille d'origine), et refuser une image identique déjà vue par l'agent.

Grep et Glob

Les résultats de Grep et de Glob sont repliés. TOKENADE_NO_GREP=1 et TOKENADE_NO_GLOB=1 désactivent ces traitements.

Web

WebSearch s'exécute localement sur plusieurs moteurs et remplace le résultat natif ; si les moteurs échouent ou sont trop lents, l'outil natif prend le relais. WebFetch n'est intercepté que pour les PDF, les autres binaires et les très grosses pages. TOKENADE_NO_WEBSEARCH=1 et TOKENADE_NO_WEBFETCH=1 les désactivent. Voir web et search.

Outils MCP et sous-agents

Les résultats MCP sont repliés après l'appel (TOKENADE_NO_MCP_HOOK=1 le désactive). Quand l'agent lance un sous-agent via Task ou Agent, le hook ajoute les consignes de Tokenade au prompt du sous-agent.

Les autres agents

Les détails propres à chaque agent sont dans la section Agents.

Les hooks ne bloquent jamais votre agent

• Chaque commande de hook sort en 0, même si Tokenade lui-même échoue ; l'échec est journalisé et l'appel d'outil se poursuit comme si Tokenade n'était pas là.
• Un hook qui reçoit un événement trop gros ne rend aucune décision plutôt que de deviner.
• Sans licence active, les commandes shell ne sont pas réécrites. Le masquage des secrets continue quel que soit l'état de la licence.

Désactiver les hooks

Si vous contournez souvent, un rappel d'une ligne suggère tokenade expand-ref à la place.

Journaux

L'activité des hooks est écrite dans ~/.tokenade/debug.log (rotation à 16 Mio). tokenade hooks tail [N] affiche les N derniers enregistrements (20 par défaut). tokenade install --no-debug-log désactive ce journal.

Pièges

• Claude Code n'exécute aucun hook en session interactive dans un dossier dont vous n'avez pas accepté l'invite de confiance. tokenade health vous le signale.
• Les hooks prennent effet à la session suivante de l'agent, pas dans celle déjà ouverte.
• Si vous remplacez à la main une entrée de hook de Tokenade, tokenade healthcheck le signale et tokenade install la rétablit.

Voir aussi

• Compaction des sorties et stash
• Agents pris en charge et compatibilité
• wrap, raw et filter
• Commandes de maintenance
• Article : Les hooks de Claude Code expliqués