Anatomie d'un Claw : 84 hooks comme couche d'orchestration

Le premier hook a pris quatre minutes à écrire. Il empêchait le modèle de suggérer des produits OpenAI dans un workflow exclusivement Anthropic. Deux mois plus tard, ce seul hook en était devenu 84. Les 84 hooks étaient connectés à 43 skills, 19 agents spécialisés et 30 modules de bibliothèque. À un moment donné, la collection a cessé d’être un ensemble de scripts pour devenir une couche d’orchestration.

Un « Claw » est une couche d’orchestration construite au-dessus d’un CLI d’agent IA, qui prend en charge la planification, la gestion du contexte, le routage des outils et le contrôle qualité. Elle grandit organiquement à force de résoudre des défaillances individuelles, plutôt que par une conception descendante. L’architecture correspond aux cinq fonctions identifiées par Karpathy, la séparation planification-exécution émergeant comme une propriété naturelle des systèmes fondés sur les hooks.

Je ne l’ai pas conçu ainsi. Personne ne s’assoit en disant « je vais construire 15 000 lignes d’infrastructure d’agents ». Vous résolvez un problème. Puis un autre. Puis vous résolvez le problème des interactions entre les problèmes. Au moment où vous remarquez l’architecture, elle existe déjà.

Andrej Karpathy l’a remarqué aussi. En février 2026, il a décrit les « Claws » comme une nouvelle couche computationnelle : orchestration, planification, gestion du contexte et routage des outils construits au-dessus des agents LLM, de la même manière que les agents sont construits au-dessus des LLM.¹ Cette conceptualisation a cristallisé quelque chose que les praticiens construisaient sans le nommer. Cet article est l’anatomie d’un tel système : ce qu’il contient, comment il a grandi, là où il fonctionne, et là où il échoue.

TL;DR

La couche « Claws » de Karpathy décrit les systèmes d’orchestration construits au-dessus des CLI d’agents. J’en ai construit un de manière organique en deux mois sur Claude Code : 84 hooks répartis sur 15 types d’événements, 43 skills, 19 agents et plus de 30 modules de bibliothèque. Le système correspond précisément à cinq fonctions Claws (orchestration, planification, gestion du contexte, routage des outils, contrôle qualité) avec une lacune notable (les définitions de workflows déclaratifs). Constat principal : la séparation planification-exécution a émergé comme une propriété naturelle de l’orchestration par hooks, et non comme un objectif de conception. L’observation de Lattner selon laquelle « le jugement et l’abstraction restent au cœur tandis que l’IA automatise l’implémentation » se transpose directement sur l’architecture de hooks : les hooks de gouvernance exercent le jugement, les hooks d’automatisation exécutent l’implémentation.

La taxonomie des Claws

La description de Karpathy identifie cinq fonctions qu’une couche Claws remplit. Chaque fonction a un analogue direct dans le système de hooks que j’ai construit sur Claude Code au cours des deux derniers mois.¹

La taxonomie est utile parce qu’elle sépare des préoccupations que les praticiens ont tendance à construire de manière enchevêtrée. Mes premiers hooks mélangeaient gestion du contexte et contrôle qualité. Le hook de suivi des coûts à la fois injectait le contexte budgétaire (gestion du contexte) et bloquait les opérations coûteuses (contrôle qualité). Séparer ceux-ci en hooks distincts a amélioré la fiabilité, car chaque hook pouvait échouer indépendamment sans compromettre l’autre fonction.

Le système complet

Les chiffres en février 2026 :

La distribution des hooks par type d’événement révèle où la complexité de l’orchestration se concentre :

UserPromptSubmit porte le plus de poids car il se déclenche à chaque message utilisateur. Le répartiteur (prompt-dispatcher.sh) exécute neuf hooks séquentiellement à chaque prompt : filtrage de sécurité, analytique, suivi d’utilisation, surveillance système, injection d’objectifs, blocage des estimations de temps, injection de contexte, injection de sujets mémoire et surveillance de la pression contextuelle.²

Chaque hook ajoute de la latence. Neuf hooks séquentiels ajoutent un total mesuré de 200 ms par prompt. Le répartiteur les exécute séquentiellement (pas en parallèle) car les écritures concurrentes de hooks dans des fichiers d’état JSON partagés causaient une corruption de données lors des premiers tests. Deux hooks écrivant simultanément dans jiro.state.json produisaient du JSON tronqué qui cassait tous les hooks en aval. L’exécution séquentielle est plus lente mais sûre. La surcharge de 200 ms est invisible pour les utilisateurs car la vitesse de frappe humaine est le goulot d’étranglement, pas la latence des hooks.

Comment le système a grandi

La croissance n’a pas été linéaire. Elle a suivi un schéma de cycles problème-solution-intégration.

Phase 1 : hooks à usage unique (Semaines 1-2). Chaque hook résolvait un seul problème. enforce-opus-model.sh bloquait les requêtes de modèles non-Opus. no-time-estimates.sh supprimait les estimations d’effort des réponses. filter-sensitive.sh interceptait les identifiants dans les appels d’outils. Ces hooks fonctionnaient indépendamment. Aucun hook ne connaissait l’existence d’un autre hook.

Phase 2 : problèmes de coordination (Semaines 3-4). Les hooks ont commencé à interférer les uns avec les autres. Le filtre d’identifiants bloquait des appels API légitimes. L’imposeur de modèle entrait en conflit avec le spawning de sous-agents. La solution : les répartiteurs. Un point d’entrée unique (prompt-dispatcher.sh) a remplacé sept hooks UserPromptSubmit individuels, contrôlant l’ordre d’exécution et partageant l’état via un pipe stdin mis en cache.

Phase 3 : capacités composées (Semaines 5-8). Les hooks individuels se sont composés en systèmes. La boucle qualité a connecté les hooks pre-tool (détection des problèmes avant qu’ils ne surviennent) avec les hooks post-tool (vérification des résultats après leur survenue) via un fichier d’état partagé (jiro.state.json). Le système de délibération utilisait des gardes de récursion, des budgets de spawn et des protocoles de consensus pour coordonner plusieurs agents sans boucles infinies. Ralph (la boucle de développement autonome) connectait les fichiers PRD au spawning de Claude, à la vérification des tests et à la revue de code dans un seul pipeline orchestré.

Phase 4 : conscience de soi (Semaine 9+). Le système est devenu suffisamment grand pour nécessiter des outils permettant de se comprendre lui-même. La recherche sémantique à travers le système de hooks (skill /find) permettait aux agents de découvrir les hooks par objectif plutôt que par nom de fichier. La surveillance des performances (skill /perf) suivait si la surcharge propre au système dégradait la machine. Un moniteur de pression contextuelle avertissait lorsque le contexte injecté par la couche d’orchestration consommait trop de la fenêtre de contexte du modèle.

La progression de hooks à usage unique vers une infrastructure auto-surveillée reflète un schéma que Chris Lattner a identifié dans sa revue du projet Claude C Compiler : « Un bon logiciel dépend du jugement, de la communication et d’une abstraction claire. L’IA a amplifié cela. »³ L’architecture du système de hooks révèle la même vérité. Les hooks les plus précieux ne sont pas ceux qui automatisent des tâches. Les hooks les plus précieux sont ceux qui encodent le jugement sur quand et comment les tâches doivent être automatisées.

Hooks de jugement vs. hooks d’automatisation

La revue du Claude C Compiler par Lattner distinguait entre ce que l’IA automatise bien (l’implémentation) et ce qui reste fondamentalement humain (le jugement et l’abstraction).³ Cette distinction se transpose directement sur le système de hooks.

Les hooks de jugement décident si quelque chose doit se produire. Ils encodent une politique, pas une procédure.

Les hooks d’automatisation exécutent des actions prédéterminées. Ils encodent une procédure, pas une politique.

Les hooks de jugement sont plus difficiles à écrire, plus difficiles à tester et plus précieux. quality-gate.sh a nécessité sept modes d’échec nommés, six critères de preuves et un détecteur de langage évasif. inject-context.sh a nécessité cinq lignes de bash. Mais les deux sont nécessaires. Les hooks d’automatisation fournissent les données que les hooks de jugement évaluent. sysmon-snapshot.sh (automatisation) alimente en données le moniteur de performances qui décide s’il faut recommander de réduire le nombre d’agents (jugement).

Le ratio compte. Dans une couche d’orchestration saine, les hooks de jugement devraient être plus nombreux que les hooks d’automatisation. Si la plupart des hooks ne font qu’injecter des données ou enregistrer des métriques, le système automatise bien mais gouverne mal. Un décompte vérifié du système actuel : 35 hooks de jugement, 44 hooks d’automatisation, soit environ 4:5. L’automatisation mène encore. Le ratio a commencé à environ 1:6 (presque exclusivement des hooks d’injection et de journalisation) et s’est déplacé vers le jugement sur deux mois, à mesure que des contraintes de gouvernance ont été ajoutées après avoir rencontré des échecs que la pure automatisation ne pouvait pas prévenir. Le ratio n’a pas encore atteint la parité, ce qui est en soi un signal utile : ce système gouverne encore moins qu’il n’automatise.

Séparation planification-exécution

L’article de Boris Tane « How I use Claude Code » a attiré 936 points sur Hacker News en décrivant un schéma de workflow : séparer la planification de l’exécution.⁴ Planifier avec une session Claude (rechercher, esquisser, concevoir), puis exécuter avec une session fraîche qui reçoit le plan en entrée structurée. Le schéma a résonné parce qu’il résout un vrai problème : la planification et l’exécution rivalisent pour l’espace de la fenêtre de contexte.

Le système de hooks est arrivé à la même séparation par un chemin différent. Le système de délibération engendre des agents spécialisés pour rechercher et débattre des approches. Le résultat est un PRD structuré (Product Requirements Document) avec des stories, des critères d’acceptation et des types de vérification. La boucle Ralph lit le PRD et engendre des instances Claude fraîches pour implémenter chaque story. Les agents de planification n’implémentent jamais. Les agents d’implémentation ne planifient jamais.

Cette séparation n’était pas un objectif de conception. Elle a émergé de deux contraintes indépendantes :

1. Pression de la fenêtre de contexte. La planification nécessite de lire de nombreux fichiers et d’explorer des options. L’implémentation nécessite un contexte focalisé sur la tâche en cours. Mettre les deux dans la même fenêtre de contexte signifie qu’aucun des deux n’obtient assez d’espace. Des sessions séparées donnent à chaque phase un contexte complet.

2. Indépendance de la vérification qualité. Si le même agent planifie et implémente, il ne peut pas vérifier objectivement sa propre implémentation par rapport au plan. Un agent frais disposant uniquement du plan et du code fournit une vérification indépendante. La boucle Ralph impose cela : les agents d’implémentation exécutent les tests, mais trois agents de revue distincts (correction, sécurité, conventions) vérifient les résultats.

La convergence entre le workflow manuel de Tane et le système automatisé de hooks suggère que la séparation planification-exécution est une propriété naturelle des systèmes agentiques, et pas seulement une préférence de praticien. Tout système qui gère des fenêtres de contexte et vérifie des sorties finira par séparer la planification de l’exécution, car l’alternative (faire les deux dans un seul contexte) produit de moins bons résultats dans les deux phases.

Là où le système de hooks échoue

L’architecture présente trois faiblesses significatives qu’un framework d’orchestration dédié résoudrait.

Pas de définitions de workflows déclaratifs. Chaque workflow est encodé de manière impérative dans des scripts bash. La boucle Ralph fait 1 320 lignes de bash qui encodent une séquence spécifique : lire le PRD, sélectionner la story, rassembler le contexte, engendrer Claude, exécuter les tests, lancer les revues, gérer les échecs, mettre à jour l’état. Modifier le workflow signifie éditer du bash. Un système déclaratif définirait les workflows comme des données (YAML, JSON) qu’un interpréteur exécute. Les workflows déclaratifs sont plus faciles à modifier, composer et visualiser. Les scripts impératifs sont plus faciles à écrire initialement mais plus difficiles à maintenir à mesure qu’ils grandissent.

L’ordonnancement des hooks est fragile. Le répartiteur de prompts exécute les hooks dans une séquence codée en dur. Déplacer memory-capsule-inject.sh avant inject-context.sh casserait l’injection de capsule car elle dépend de l’ID de session que inject-context.sh résout. Ces dépendances sont implicites (encodées dans l’ordonnancement du répartiteur) plutôt qu’explicites (déclarées comme dépendances entre hooks). Un système dédié exprimerait les dépendances des hooks sous forme de DAG et trierait topologiquement l’ordre d’exécution.

Pas de visualisation des workflows. Avec 84 hooks, comprendre le chemin d’exécution complet de toute action utilisateur nécessite de lire le code du répartiteur et de tracer les chaînes de hooks manuellement. Il n’existe aucun outil qui montre « quand l’utilisateur tape un message, ces 9 hooks se déclenchent dans cet ordre, et le hook 3 appelle la fonction de bibliothèque X qui écrit dans le fichier d’état Y ». Le système est observable via les logs mais pas via la structure. Un framework d’orchestration dédié fournirait un graphe visuel des dépendances de hooks, des flux de données et des chemins d’exécution.

Ces faiblesses partagent une cause commune : le système a grandi de manière organique en résolvant des problèmes individuels plutôt que d’être conçu comme une couche d’orchestration cohérente. La croissance organique produit des systèmes qui fonctionnent (les 84 hooks fonctionnent correctement en production) mais qui sont difficiles à appréhender dans leur ensemble. Le compromis est réel : concevoir la couche d’orchestration en amont aurait produit une meilleure structure mais de moins bonnes capacités, car de nombreuses capacités (capsules mémoire, listes blanches de sorties, budgets de spawn) ont été inventées en réponse à des échecs qui n’auraient pas pu être prédits avant qu’ils ne se produisent.

Le harness se généralise

Trois semaines après que Karpathy a nommé la couche, le concept a un second nom et une communauté qui grandit.

Geoffrey Huntley a proposé une définition formelle : « Agent Harness : la couche d’orchestration autour d’un modèle de langage qui le transforme d’outil en coéquipier. »⁵ La formulation est précise. Le harness n’est pas le modèle. Ce ne sont pas les outils que le modèle appelle. C’est le système qui décide quels outils appeler, quand les appeler et comment évaluer si l’appel a réussi. Tout système d’agents en production construit cette couche. La plupart la construisent implicitement, à l’intérieur d’un code applicatif qui mêle logique d’orchestration et logique métier. La nommer rend l’architecture visible.

Les signaux de la communauté confirment que le schéma se répand. Pieter Levels a annoncé être passé définitivement à l’exécution de Claude Code sur un serveur, en le traitant comme une infrastructure plutôt que comme un outil local.⁶ Anthropic a livré Remote Control, qui permet de lancer des tâches depuis le terminal et de les reprendre depuis Claude.ai.⁷ Ben Cherny a annoncé /simplify et /batch comme skills natives.⁸ Chacun de ces éléments est une fonctionnalité de harness : exécution persistante, orchestration à distance et modules de capacités intégrés. Le CLI se transforme peu à peu en harness.

Pendant ce temps, les praticiens construisent leurs propres composants de harness. Un développeur a publié 22 commandes Obsidian + Claude Code personnalisées pour un système d’exploitation personnel.⁹ Un autre a créé une skill d’agent « Visual Explainer » accompagnée de slash commands complémentaires.¹⁰ Les schémas se recoupent : répartiteurs, skills, état partagé, hooks événementiels. Personne ne lit un guide de framework avant de construire ces systèmes. Ils résolvent un problème, puis un autre, puis les problèmes des interactions entre les problèmes.

Deux projets récents montrent à quel point les composants de harness construits par la communauté sont devenus sophistiqués. nah est un garde-fou de permissions sensible au contexte qui s’enregistre comme hook PreToolUse.¹⁴ Il classe 20 types d’actions distincts (écritures de fichiers, requêtes réseau, création de processus, etc.) et applique des politiques par type. L’outil détecte les attaques par décomposition en pipes, où un agent enchaîne des commandes anodines pour parvenir à une opération bloquée. L’architecture reflète filter-sensitive.sh et recursion-guard.sh décrits dans cet article, atteinte indépendamment par un autre praticien confronté aux mêmes problèmes de gouvernance.

Rudel fournit des analyses de session en injectant les données de session de Claude Code dans ClickHouse.¹⁵ L’analyse de 1 573 sessions a révélé que seuls 4 % des utilisateurs invoquent des skills et que 26 % des sessions sont abandonnées en moins de 60 secondes. Ces chiffres confirment ce que l’architecture de harness implique : la plupart des utilisateurs n’interagissent avec les CLI d’agents qu’en surface. La couche d’orchestration décrite dans cet article représente le grand bain d’une distribution d’usage dont l’immense majorité ne quitte jamais le petit bain. L’écart entre ce que l’outil peut faire et ce que la plupart des utilisateurs lui demandent est précisément l’espace que comble l’infrastructure de harness.

Autoresearch : le harness comme boucle de recherche

Le projet autoresearch de Karpathy lui-même illustre le schéma du harness dans un autre domaine.¹¹ Le système braque un modèle de langage sur un script d’entraînement (train.py), lance une expérience de cinq minutes, évalue le résultat selon une métrique fixe (bits par octet en validation), puis conserve les améliorations ou écarte les régressions. En deux jours, le système a mené environ 700 expériences et trouvé environ 20 améliorations réelles, réduisant de 11 % le temps d’entraînement de GPT-2.

L’architecture est identique au système de hooks décrit plus haut. Un harness d’évaluation fixe (prepare.py) équivaut aux hooks de jugement : il décide si une expérience a réussi. Le script d’entraînement (train.py) équivaut aux hooks d’automatisation : il exécute les modifications de l’agent. La gestion des branches git (conserver en cas d’amélioration, réinitialiser en cas de régression) équivaut à la gestion d’état de la boucle Ralph. Le journal results.tsv équivaut à la télémétrie de session.

Le schéma se transpose parce que le harness résout un problème indépendant du domaine. Que l’agent écrive du code, optimise une boucle d’entraînement ou pilote un pipeline de contenu, il lui faut : un moyen d’évaluer les résultats par rapport à des critères, un moyen de conserver ou d’écarter les changements, un moyen de maintenir l’état d’une itération à l’autre, et un moyen de fonctionner de façon autonome sans intervention humaine. Ces quatre exigences produisent la même architecture, quelle que soit la tâche réellement confiée à l’agent.

Tobi Lütke, PDG de Shopify, a adapté autoresearch en interne. Son petit modèle optimisé par agent a surpassé un modèle plus grand configuré manuellement, ce qui valide l’idée qu’une itération autonome pilotée par le harness découvre des configurations que les humains ne pensent pas à essayer.¹²

La faille de sécurité du harness

Le harness résout l’orchestration. Il ne résout pas automatiquement la sûreté.

Une étude sur le raffinement itératif de code piloté par LLM a constaté que 43,7 % des chaînes d’itérations contenaient plus de vulnérabilités après dix tours de modifications par l’agent que le code de départ.¹³ La cause profonde était la dérive de spécification : à mesure que l’agent optimisait la correction fonctionnelle, il retirait progressivement la logique défensive et affaiblissait la gestion des exceptions. Pire, ajouter des outils d’analyse statique de sécurité (portes SAST) à la boucle d’itération a en réalité fait passer la dégradation latente de 12,5 % à 20,8 %. Les scanners ont créé un faux sentiment de sécurité qui a rendu l’agent moins prudent, et non plus prudent.

Ce constat de dégradation concerne directement la conception des harness. Les hooks de jugement décrits dans cet article (quality-gate.sh, filter-sensitive.sh, recursion-guard.sh) traitent les dimensions de qualité et de sûreté que l’automatisation seule dégrade. Le framework SCAFFOLD-CEGIS, qui s’est attaqué au problème de dégradation, utilisait quatre couches de vérification sous porte, atteignant un taux de dégradation latente de 2,1 % avec une monotonie de sûreté de 100 %.¹³ L’architecture fait écho au système de hooks : des couches d’évaluation séparées, chacune vérifiant une propriété différente, avec des portes explicites entre les phases.

Un travail distinct corrobore ce modèle de menace du côté de la production. La réponse de Perplexity au NIST sur la sécurité des agents IA cartographie la surface d’attaque des systèmes agentiques opérant à grande échelle.¹⁶ Les vecteurs principaux : l’injection de prompt indirecte via les canaux de données (pages web, e-mails, sorties d’outils), les violations de la triade CIA propres aux agents (exfiltration de données par appels d’outils, manipulation d’actions par empoisonnement du contexte, épuisement des ressources par création récursive de processus) et des CVE réelles issues de systèmes adjacents aux agents. L’architecture de défense qu’ils recommandent (filtrage au niveau des entrées, alignement au niveau du modèle et application déterministe par bac à sable et listes d’autorisation) reflète le schéma en trois couches qui a émergé organiquement dans le système de hooks décrit ici. Les hooks d’automatisation filtrent les entrées. Le modèle exerce le jugement. Les hooks de gouvernance imposent des contraintes déterministes que le modèle ne peut pas outrepasser.

La leçon pour les praticiens : si votre harness se contente d’automatiser et d’orchestrer sans gouverner, l’exécution itérative des agents introduira des régressions de sécurité que l’outillage standard ne sait pas détecter. Les hooks de jugement ne sont pas une surcharge. Ils sont la raison pour laquelle le système ne se dégrade pas.

Mise à jour, 3 septembre : le mode de défaillance dans la nature

La faille que cet article décrit dans « La faille de sécurité du harness » a désormais une victime documentée. Le 19 juillet 2026, Claude Code v2.1.204 vidait un cache sur l’ordinateur d’Udaya Kumar P L, directeur honoraire du Bengaluru Inscriptions 3D Digital Conservation Project de la Mythic Society, lorsque, selon son récit, « une erreur de guillemets dans une commande générée par l’IA a transformé l’instruction en “tout supprimer” ». Ce qui importe pour la conception des harness, c’est la suite : « Lorsqu’il a compris et a tenté de tuer le processus, son système de sûreté a bloqué l’arrêt. Deux fois […] La couche de sûreté a permis la destruction. » Il a éteint la machine au bout de quatre minutes. Perdus : quatre ou cinq programmes et des photographies originales d’inscriptions, de pierres héroïques, de temples et de pièces de monnaie rassemblées sur une décennie, soit environ 15 % des archives du projet, dont une pierre portant une forme ancienne du nom Hebbal (750 apr. J.-C.). La copie sur NAS a survécu ; le disque, non. La Society dépense 15 lakh de roupies pour un second NAS et une sauvegarde sur bande hors site, et des bénévoles vont renumériser environ 120 sites. Plus d’un mois après, il n’avait eu de nouvelles de personne chez Anthropic.¹⁷

Trois éléments de ce récit rejoignent l’argumentation ci-dessus. L’étape destructrice n’était pas une décision du modèle mais une défaillance de guillemets shell dans une commande générée, exactement la catégorie qu’un hook de jugement PreToolUse existe pour intercepter. L’article ne nomme aucun mode de permission, donc rien de first-party n’est officiellement attesté comme ayant relu cette commande ; même en mode auto, le classifieur ne relit par défaut que les commandes shell correspondant à des motifs d’exécution de code arbitraire. Il dit aussi que l’agent a franchi un bac à sable ; l’article ne donne aucun détail sur sa nature. Anthropic avait déjà livré une protection pour le cas voisin : la v2.1.205, publiée le 8 juillet, fait demander confirmation au mode auto avant d’exécuter rm -rf sur une variable qu’il ne parvient pas à résoudre depuis le contexte. La machine était en v2.1.204.¹⁹ La couche de sûreté a ensuite fait son travail dans le mauvais sens : elle a traité la remédiation de l’agent lui-même comme l’action dangereuse. Et ce qui a survécu a survécu grâce au seul contrôle qui se situe entièrement en dehors du harness, une sauvegarde ; le reste sera renumérisé à la main. Il existe désormais au moins un registre non officiel pour cette catégorie d’événements ; il faisait remarquer qu’aucun registre officiel n’existe. I Have Been Clawed, une archive d’incidents d’agents et de chatbots reliée à ses sources, avec une leçon attachée à chacun, 58 entrées au moment où ces lignes sont écrites, dont sept concernant Claude Code, avec l’avertissement honnête affiché sur sa propre page d’accueil : les entrées sont auto-sélectionnées et pondérées par la viralité, si bien que les décomptes par outil mesurent la culture du signalement, pas la sûreté. Elle contenait déjà trois entrées Claude Code de la même forme avant celle-ci : une commande récursive qui a supprimé des fichiers appartenant à l’utilisateur dans un répertoire personnel WSL (21 octobre 2025), un répertoire tilde littéral qui a exposé le répertoire personnel à la suppression (28 novembre 2025) et une commande de nettoyage se terminant par le chemin du répertoire personnel qui a effacé un Mac (7 décembre 2025). Dans la nature, c’est un schéma, pas une anecdote.¹⁸

Ce que les praticiens devraient retenir

Si vous construisez une couche d’orchestration au-dessus d’un CLI d’agent, que vous partiez du guide Claude Code ou de zéro, trois schémas de ce système sont directement transposables.

Commencez par les répartiteurs, pas par les hooks individuels. L’amélioration architecturale la plus significative a été de remplacer sept hooks UserPromptSubmit individuels par un seul répartiteur qui les exécute séquentiellement. Si vous anticipez plus de trois hooks sur un type d’événement donné, construisez d’abord le répartiteur. Les 30 minutes passées à écrire un répartiteur économisent des heures de débogage de bugs d’interaction entre hooks par la suite. Le schéma minimal :

#!/bin/bash
# dispatcher.sh — sequential hook execution with shared stdin
HANDLERS=("inject-context.sh" "track-usage.sh" "quality-gate.sh")
HOOK_DIR="$(dirname "$0")/handlers"
INPUT=$(cat)  # Cache stdin once (each handler gets the same input)

for handler in "${HANDLERS[@]}"; do
    [ -x "$HOOK_DIR/$handler" ] && echo "$INPUT" | "$HOOK_DIR/$handler"
done

Enregistrez ce répartiteur unique comme point d’entrée de vos hooks. Ajoutez les gestionnaires au tableau à mesure que vous les construisez. Chaque gestionnaire lit le même stdin mis en cache (la charge utile de l’événement hook) et écrit sur stdout indépendamment.

Séparez le jugement de l’automatisation dès le début. Lorsque vous écrivez un nouveau hook, demandez-vous : « Ce hook décide-t-il si quelque chose doit se produire, ou exécute-t-il une action prédéterminée ? » Les hooks de jugement nécessitent plus de tests, plus de gestion de cas limites et plus d’itérations. Les hooks d’automatisation nécessitent fiabilité et performance. Les traiter de la même manière conduit à des hooks de jugement sous-testés et des hooks d’automatisation sur-ingéniérés.

Laissez la séparation planification-exécution émerger. Ne forcez pas la séparation dès le premier jour. Construisez la chose la plus simple qui fonctionne. Quand vous remarquez que la fenêtre de contexte de votre agent est trop pleine pour la planification et l’implémentation à la fois, séparez-les. Quand vous remarquez que votre agent ne peut pas vérifier objectivement son propre travail, ajoutez des agents de revue indépendants. La séparation semblera évidente quand les contraintes l’exigeront.

Le harness se généralise parce que le schéma est inévitable. Que vous appeliez cette couche Claws, Agent Harness ou simplement « mon dossier de hooks », tout système qui coordonne des agents vers des objectifs convergera vers la même architecture : des répartiteurs pour l’ordonnancement, des hooks de jugement pour la gouvernance, des hooks d’automatisation pour l’exécution et des fichiers d’état pour la continuité. La fuite du code source de Claude Code a confirmé que l’architecture interne d’Anthropic suit ces mêmes schémas : le mode coordinateur est implémenté entièrement sous forme d’instructions de prompt système, et non d’orchestration au niveau du code. L’approche par hooks a un avantage par rapport aux frameworks d’orchestration dédiés : zéro engagement. Chaque hook est indépendant. Vous pouvez adopter un hook, dix hooks ou quatre-vingt-quatre hooks. Vous pouvez supprimer n’importe quel hook sans casser les autres (à condition de maintenir le répartiteur). Il n’y a pas de framework à apprendre, pas de dépendance à gérer, pas de runtime à opérer. La couche d’orchestration n’est que des fichiers.

FAQ

Qu’est-ce qu’un agent harness ou une couche « Claws » ?

Une couche Claws (nommée ainsi par Andrej Karpathy en février 2026) est le système d’orchestration construit au-dessus d’un CLI d’agent, qui le transforme d’outil en coéquipier.¹ Elle remplit cinq fonctions : l’orchestration (coordonner plusieurs agents), la planification (déterminer quand les tâches s’exécutent), la gestion du contexte (maintenir les informations pertinentes entre les tours), le routage des outils (diriger les appels d’outils vers les gestionnaires appropriés) et le contrôle qualité (vérifier que les sorties respectent les standards). Geoffrey Huntley a formalisé la définition comme « la couche d’orchestration autour d’un modèle de langage ».⁵

Comment fonctionnent les hooks PreToolUse dans Claude Code ?

Les hooks PreToolUse se déclenchent avant chaque appel d’outil (commandes Bash, écritures de fichiers, éditions de fichiers, créations de sous-agents) et reçoivent la charge utile de l’appel d’outil sous forme de JSON sur stdin. Le script du hook évalue cette charge utile et renvoie une décision : autoriser, refuser ou modifier. Le modèle ne peut ni contourner, ni outrepasser les hooks, ni négocier avec eux, car ils s’exécutent au niveau de l’infrastructure, pas au niveau du prompt.² Un schéma de répartiteur exécute plusieurs hooks séquentiellement à chaque événement, avec un pipe stdin mis en cache pour que chaque gestionnaire reçoive la même entrée.

Quelle est la différence entre les hooks de jugement et les hooks d’automatisation ?

Les hooks de jugement décident si quelque chose doit se produire (la politique), tandis que les hooks d’automatisation exécutent des actions prédéterminées (la procédure). Les hooks de jugement comprennent les portes qualité, les filtres d’identifiants, les gardes de récursion et les portes de coût. Les hooks d’automatisation comprennent l’injection de contexte, le suivi d’utilisation, la surveillance système et les battements de cœur.³ Le ratio compte : un système composé majoritairement de hooks d’automatisation automatise bien mais gouverne mal. Le système actuel compte 35 hooks de jugement pour 44 hooks d’automatisation, et se déplace vers la gouvernance à mesure que les échecs révèlent ce que la pure automatisation ne peut pas prévenir.

Pourquoi la séparation planification-exécution émerge-t-elle naturellement dans les systèmes d’agents ?

Deux contraintes indépendantes imposent la séparation. D’abord, la planification nécessite de lire de nombreux fichiers et d’explorer des options tandis que l’implémentation nécessite un contexte focalisé sur la tâche en cours, et mettre les deux dans la même fenêtre de contexte signifie qu’aucune des deux n’obtient assez d’espace. Ensuite, si le même agent planifie et implémente, il ne peut pas vérifier objectivement son propre travail par rapport au plan.⁴ Tout système qui gère des fenêtres de contexte et vérifie des sorties finira par séparer la planification de l’exécution, car l’alternative produit de moins bons résultats dans les deux phases.

Comment commencer à construire mon propre système de hooks ?

Commencez par les répartiteurs, pas par les hooks individuels. Si vous anticipez plus de trois hooks sur un type d’événement donné, construisez un répartiteur unique qui exécute les gestionnaires séquentiellement à partir d’un tableau. Les 30 minutes passées à écrire un répartiteur économisent des heures de débogage de bugs d’interaction entre hooks par la suite. Séparez le jugement de l’automatisation dès le début en vous demandant : « ce hook décide-t-il si quelque chose doit se produire, ou exécute-t-il une action prédéterminée ? » Commencez par le tutoriel sur les hooks de Claude Code et ajoutez des hooks à mesure que de vraies défaillances l’exigent, plutôt que de concevoir le système complet d’emblée.

Sources