Fonctionnement des hooks

Le superviseur de hooks est la partie de Pathrule qui donne l'impression, pendant une session d'IA, que l'assistant connaissait déjà les conventions de votre équipe. Il s'exécute localement, lit un cache, fournit les mémoires et règles pertinentes, et propose les skills par leur nom avant que l'assistant n'effectue sa première action. Les instructions d'un skill arrivent lorsque vous l'invoquez.

Cette page présente le mécanisme du point de vue de l'utilisateur. Elle n'entre pas dans le détail du fonctionnement interne du runtime.

Qu'est-ce qu'un hook

Un hook est un petit script que votre client IA invoque à des moments bien définis d'un tour. Pathrule utilise les événements de fourniture de contexte et d'application des règles que chaque client expose réellement.

• SessionStart indique à l'assistant l'espace de travail dans lequel il se trouve, le protocole Pathrule et le contexte de votre équipe, une fois par session.
• UserPromptSubmit cadre le tour à venir sur les clients dont l'événement de prompt accepte du contexte.
• PreToolUse fournit du contexte ou une décision de règle stricte avant une action, lorsque le client l'accepte.
• PostToolUse enregistre les résultats et compense avec du contexte lié au chemin sur les clients dont l'événement de pré-outil accepte des décisions mais pas de contexte.
• Les événements Stop et de fin de session clôturent le tour. Sur Claude Code et Codex, une vérification obligatoire approuvée par une personne peut maintenir le tour ouvert à ce stade jusqu'à ce que sa commande ait réussi.

pathrule setup et pathrule sync, ou l'extension VS Code, enregistrent ces hooks pour Claude Code, Codex, Cursor et GitHub Copilot. Windsurf n'a pas de hooks Pathrule : son fichier de règles généré assure l'amorçage de la session et le serveur MCP local fournit à la demande un contexte plus approfondi.

Profils de fourniture par client

Une règle stricte est une règle qui porte un motif de blocage approuvé par une personne. Consultez Les règles comme garde-fous pour savoir ce qui bloque et ce qui se contente d'informer.

Ce que fait le hook

Le superviseur de hooks effectue quatre opérations, dans cet ordre.

1. Résoudre le chemin. Il associe le répertoire de travail à un nœud de l'espace de travail.
2. Lire le cache. Le cache local contient un index précalculé des mémoires, règles et skills pour ce chemin.
3. Façonner la tranche. Il choisit une profondeur adaptée à l'intention. Une retouche d'interface reçoit une charge minimale. Une correction de bug ou une refactorisation reçoit une charge ciblée. Les prompts d'exploration en débloquent une plus profonde.
4. Renvoyer la charge. Le texte revient au client comme contexte système pour l'action à venir.

En mode local, tout le processus s'exécute sur votre machine. Sur un espace de travail Cloud, le hook de prompt envoie aussi le début de votre prompt (environ les 1 000 premiers caractères) à Pathrule Cloud afin de prioriser les connaissances selon leur sens. Si cet appel est lent ou échoue, le hook se rabat sur une correspondance avec l'index local : un problème réseau ne prive donc pas le tour de contexte.

Ce que vous voyez

La zone de contexte de l'assistant (celle que votre éditeur expose) gagne une section Pathrule. Elle indique :

• Le chemin résolu par le hook, ainsi que les chemins où le travail se situe le plus probablement, un parcours que l'assistant doit ouvrir avant de lancer une recherche. Pathrule enregistre s'il l'a fait.
• Les règles correspondantes, avec leur priorité.
• Les mémoires les plus pertinentes pour votre prompt, fournies dans leur intégralité pour que l'assistant puisse s'en servir directement. Les correspondances moins sûres apparaissent tout de même sous forme de titres avec leurs identifiants, que vous pouvez lire en entier si vous le souhaitez.
• Les skills adaptés à ce périmètre, par leur nom, prêts à être invoqués avec ::skill-name.

Si le hook n'a rien de nouveau ni de pertinent pour le chemin courant, il n'ajoute rien : un tour sans apport ne consomme pas de contexte.

Deux canaux de fourniture

Les connaissances parviennent à l'assistant par deux canaux de hooks aux rôles distincts.

• Le canal par prompt s'exécute une fois à la soumission d'un prompt, sur les clients dotés d'un hook de soumission de prompt (Claude Code et Codex). C'est là que se trouve la profondeur : les règles adaptées au prompt, les mémoires les plus pertinentes dans leur intégralité pour que l'assistant puisse s'en servir directement, et les skills qui semblent pertinents, proposés par leur nom. Un skill est une procédure : il n'est donc jamais imposé comme une instruction, et son corps complet arrive lorsque vous l'invoquez avec ::skill-name.
• Le canal par appel d'outil s'exécute avant ou après chaque action sur un fichier ou dans le shell, de nombreuses fois par tour. Il reste volontairement léger : les noms et les résumés d'une ligne des règles et mémoires qui s'appliquent au chemin concerné, pour que l'assistant sache ce qui existe à cet endroit et puisse lire un contenu complet en un seul appel si nécessaire.

Sur Claude Code et Codex, le canal de prompt et le canal de pré-outil atteignent tous deux l'assistant. Cursor et GitHub Copilot n'acceptent pas de contexte sur leur événement de prompt : le hook de début de session porte donc l'amorçage et le hook post-outil porte les noms liés au chemin.

Aucun des deux canaux ne se répète. Un contenu déjà fourni pendant la session n'est pas renvoyé, et un contenu modifié revient la prochaine fois qu'il est pertinent.

Ce qui reste sur disque

Un client dont le hook Pathrule est installé reçoit le protocole et le contexte d'équipe par le hook de début de session plutôt que par son fichier d'instructions. Sur Claude Code, le contexte de début de session rejoint le prompt système et survit donc à la compaction de la conversation. Le fichier d'instructions (CLAUDE.md, AGENTS.md, la règle Cursor ou les instructions Copilot) ne conserve qu'une courte note Pathrule, et Pathrule supprime les copies du protocole et les fichiers de connaissances par répertoire qu'il écrivait dans les versions précédentes. Votre propre contenu dans ces fichiers est conservé.

Deux cas conservent les fichiers compilés :

• Un client sans hook Pathrule, comme Windsurf, ou un client dont le hook n'est pas installé, conserve le protocole complet et les fichiers de connaissances par chemin, car rien d'autre ne les fournirait.
• Si une version antérieure de Pathrule a déplacé votre propre fichier d'instructions dans une sauvegarde qui n'a pas encore été restaurée, Pathrule conserve le fichier complet tant que cette sauvegarde n'a pas été traitée, afin que vous ne vous retrouviez jamais face à une courte note pendant que vos propres instructions se trouvent ailleurs.

Pour conserver les fichiers compilés même lorsque le hook est installé, définissez PATHRULE_SIGNATURE_MODE=off dans l'environnement du runtime Pathrule.

Quand le hook ne suffit pas

Les hooks sont conçus pour le cas courant. L'assistant peut toujours recourir aux outils MCP lorsqu'il a besoin de davantage.

• Pour les prompts d'exploration (« liste tout ce que nous savons sur la facturation »), l'assistant appelle directement pathrule_get_context.
• Pour le contenu complet d'une mémoire, l'assistant appelle pathrule_read_memory avec l'identifiant fourni par le hook.
• Pour les écritures (l'utilisateur demande d'enregistrer une convention ou une règle), l'assistant utilise l'outil d'écriture correspondant.

Le hook est la voie rapide. MCP est la voie approfondie. Les deux partagent la même source de vérité.

Le périmètre du chemin limite la taille

Le hook renvoie une tranche façonnée par le répertoire de travail.

• Une modification dans apps/web/dashboard n'entraîne pas les règles sur les migrations de base de données.
• Une modification dans services/billing/webhooks entraîne les règles de facturation et le skill de rejeu des webhooks, pas les conventions du site marketing.
• Un prompt d'exploration à la racine du dépôt entraîne une vue d'ensemble de l'espace de travail, pas l'intégralité des contenus.

C'est le périmètre du chemin qui maintient le contexte fourni à une taille réduite, comparé à un fichier d'instructions global unique que chaque session charge en entier.

Quand rien n'apparaît

Si vous ouvrez une session et que la section Pathrule est vide, lancez le diagnostic.

pathrule doctor

Il fonctionne en lecture seule et vérifie :

• Votre connexion, votre organisation et votre espace de travail.
• Si le dossier courant est rattaché à un espace de travail.
• Si l'entrée MCP Pathrule est installée pour chaque client IA.
• Quels fichiers gérés par Pathrule se trouvent dans le dossier, et quelle surface et quelle version de Pathrule les ont écrits.

La sortie se termine par la prochaine commande à lancer lorsqu'un point demande votre attention. Ajoutez --json pour obtenir le rapport complet, qui couvre aussi la version de Node et signale toute entrée MCP pointant vers un runtime qui n'existe plus.

Pour remettre en place les éléments locaux, lancez :

pathrule repair

La réparation réécrit les entrées MCP obsolètes, réinstalle le script de hook et l'enregistrement des hooks de chaque client, resynchronise les fichiers compagnons et le cache local que lit le hook, puis relance le diagnostic.

Si vous voulez un jour désactiver tous les hooks Pathrule d'un coup, créez ~/.pathrule/kill-hooks. L'appel de hook suivant passe directement sans rien faire ; supprimez le fichier pour réactiver les hooks.

Pour aller plus loin

• Présentation du MCP pour les outils qui sous-tendent la voie approfondie.
• Concepts clés pour le modèle de données que lit le hook.
• Installation du CLI pour installer le runtime qui héberge le superviseur de hooks.