Trois hooks et un cliquet : Session Optimizer, suivi dans son code
Trois greffons se posent sur trois points d’une session Claude Code. L’un lit votre invite avant que le travail ne commence et demande que les mots vagues soient liés à de vrais artefacts. L’un surveille la taille de la conversation et l’arrête deux fois, une pour réfléchir, une pour passer la main. L’un met sur une ligne de terminal les chiffres qu’il faudrait sinon deviner. Ils ne partagent ni processus ni base de données, seulement quelques fichiers sous votre répertoire personnel, et rien de ce qu’ils calculent ne quitte la machine.6
Trois greffons, trois moments d’une session
Aucun de ces greffons n’est un programme qu’on lance. Chacun s’enregistre sur un point que l’hôte émet déjà, fait un travail borné, et s’efface. Le refine gate lit une invite avant qu’elle n’atteigne le modèle.1 La statusline se réinstalle au démarrage de session et c’est l’hôte qui la redessine à intervalle court.2 Le context guard tourne à la fin de chaque tour, et une fois de plus quand un sous-agent se termine.3
La règle commune aux trois est que échouer en silence vaut mieux qu’interférer. Le gate le dit explicitement : un gate capable de bloquer votre invite est pire que pas de gate du tout.4 Le guard sort en zéro sur toute erreur d’analyse ou d’entrée-sortie, parce qu’un hook Stop qui coince une session est pire qu’un checkpoint manqué.5 Ce ne sont pas des promesses de README : c’est la première chose que disent ces fichiers.
Ce que le refine gate entend, et ce qu’il répond
« Le correctif précédent est toujours cassé, refais-le marcher comme avant. » Chaque mot de cette phrase désigne quelque chose que le modèle ne voit pas. Le gate reconnaît la forme du problème plutôt que son sujet : sept expressions régulières couvrant cinq classes de référence non liée, tirées d’erreurs de liaison réellement survenues et non imaginées.8
Son deuxième étage est le plus intéressant, parce qu’il est structurel. Une invite qui se lit comme une demande de travail mais ne contient ni chemin, ni nom de fichier, ni empreinte de commit, ni référence de ligne est une invite dont personne ne pourra vérifier le résultat.9 Le raisonnement est écrit dans le fichier : aucun gate ne peut énumérer tous les vocabulaires métier, alors il teste l’ancrage, et une invite que vous avez ancrée vous-même est laissée tranquille.10 Sur correspondance il injecte des consignes ; sans correspondance il n’imprime rien, donc le cas courant ne coûte aucun contexte.11
Deux seuils, et un cliquet qui ne tourne que dans un sens
À la fin de chaque tour, le guard lit la queue de votre transcript plutôt que le fichier entier, en remontant par blocs de 64 Kio sous un plafond dur de 4 Mio. Cette taille n’est pas un pifomètre : le fichier consigne la mesure dont elle vient, un transcript de 24,5 Mo dont le dernier enregistrement d’usage était à 7 591 octets de la fin.15 De cet enregistrement il somme trois champs en un seul chiffre, les tokens d’entrée plus les deux champs de cache, et le compare aux seuils du modèle sur lequel vous êtes.1416
Ce qui suit mérite d’être compris avant l’installation. Les deux seuils rendent le même verdict à l’hôte : block.17 L’avertissement n’est pas un conseil qu’on ignore : c’est une interruption unique qui écrit un checkpoint et demande une pause de réflexion, après quoi la session continue.20 Le seuil dur interrompt une fois encore et vous demande d’effacer le contexte et de reprendre.21 Ni l’un ni l’autre ne peut se déclencher deux fois, car le plus haut niveau atteint est mémorisé par session.18
Trois mesures qu’il ne faut pas additionner
Un gros contexte courant et une grosse dépense cumulée sont deux faits différents. Le chiffre de contexte ne porte que sur le fil principal et exclut délibérément les enfants, parce que mêler leurs tokens déclencherait les checkpoints au mauvais moment ; la dépense des enfants est rapportée à côté.1425 L’agrégat qui la porte est indexé par identifiant d’agent, donc un événement répété met à jour une entrée au lieu de la doubler, et les transcripts frères sont balayés au cas où un événement aurait été manqué.26 Un étage plus bas, les tours d’assistant sont dédupliqués par identifiant de message, le plus grand usage l’emportant, parce que l’hôte réenregistre le même tour au fil des bifurcations et des reprises.27
La statusline applique ensuite une règle facile à énoncer et facile à rater : les comptes et les volumes de tokens viennent de l’agrégat, et chaque montant en dollars vient du seul registre, de sorte qu’une même dépense n’est jamais tarifée deux fois sur un même écran.313235 Quand le terminal est étroit, l’ajustement coupe par la queue et garde les segments de tête, car la charge de l’hôte ne porte aucun champ de largeur et la mise en page doit la deviner.2930
Ce que ces trois greffons ne prouvent pas
Le résultat de bout en bout est une demande mieux ancrée, des signaux de session visibles et un point de reprise écrit. Le code soutient ce flux ; il n’établit pas que les consignes ont été suivies, que l’implémentation qui a suivi était correcte, ni qu’un résumé a gardé tout ce qui comptait. Cela demande une relecture. Trois limites de plus méritent d’être connues : la reconnaissance est anglaise et syntaxique, ce n’est pas une compréhension de votre phrase8 ; les fichiers temporaires sont sous /tmp et ne survivent pas à un redémarrage25 ; et le coût d’un rendu complet de la statusline, en millisecondes, n’est mesuré nulle part dans les sources, qui ne documentent que les chemins évitant du travail.33 Un détail est un choix assumé et non un oubli : il n’y a aucun emoji, parce qu’un glyphe doit s’apprendre et que plusieurs cassent le budget de colonnes.34 Les lignes sont rendues avec l’identité en premier.28