Référence des mods

Référence complète des mods Claude Code : structure du module de hooks, événements, méthodes de l'API des mods, points de rendu, éléments par surface, limites et paramètres.

Consultez tout événement qu'un mod peut gérer, toute méthode de l'API des mods qu'il peut appeler, ou tout point de rendu dans lequel il peut dessiner. Les entrées couvrent la CLI Claude Code et l'application Desktop à partir de la v2.1.290, ainsi que l'extension VS Code à partir de la v2.1.299. Chaque entrée donne le nom et une description d'une ligne, avec un lien vers la section du guide qui l'explique lorsqu'elle existe.

[!NOTE]

La référence complète est constituée des déclarations TypeScript pour les mods de Claude Code, qui décrivent chaque événement, méthode et élément, avec des exemples. La copie sur GitHub peut être plus ancienne que la version de Claude Code que vous avez installée. En cas de divergence, fiez-vous à la copie que Claude Code écrit pour votre version.

Fichiers

Un mod est un répertoire de plugin contenant ces fichiers :

register reçoit on et options. options contient les valeurs des champs userConfig déclarés par le manifeste, avec les valeurs par défaut renseignées.

La fonction de hook

Un mod enregistre chacun de ses hooks, qui sont des gestionnaires d'événements, en appelant on à l'intérieur de register. on prend le nom de l'événement, un matcher facultatif, qui est un filtre sur les champs de l'événement, et le hook, comme dans on('tool.call', { tool: 'Bash' }, async ($, e, next) => next(e)). on renvoie un enregistrement doté d'une seule méthode, .catch(handler), qui définit le gestionnaire d'erreurs du hook.

Événements

Les événements sont regroupés selon ce qu'ils concernent, chacun avec le moment où il se déclenche et ce qu'un hook qui le gère peut renvoyer. Les hooks sur turn.step et process.spawn sont des générateurs asynchrones, et les autres hooks sont des fonctions asynchrones.

La dernière colonne de chaque tableau utilise une notation abrégée. next(e) transmet l'événement sans modification. next({ ...e, text }) transmet une copie dont le champ nommé est modifié, comme dans next({ ...e, text: e.text.trim() }). Un objet répond à l'événement sans appeler next, et un mot tel que reason désigne une chaîne que vous écrivez, comme dans { deny: 'Use the file tools.' }.

Outils

Les événements d'outils se déclenchent autour de chaque appel d'outil effectué par Claude, depuis la description que Claude lit jusqu'à la décision d'exécuter ou non l'appel :

Champs d'agent et d'organisation sur tool.check

Dans un hook tool.check, lisez ces champs pour distinguer l'appel d'un sous-agent de celui de la conversation principale, et pour savoir si votre organisation exige une approbation pour un outil de connecteur :

• e.agentId : défini lorsqu'un sous-agent ou un coéquipier en cours de processus effectue l'appel, et absent lorsque c'est la conversation principale qui l'effectue
• e.ceiling : ask pour un outil de connecteur que votre organisation a défini sur ask, dans les sessions où ce paramètre parvient à Claude Code

Sur tool.check, e.agentId et e.ceiling nécessitent Claude Code v2.1.290 ou une version ultérieure.

Le champ e.isReadOnly sur tool.check

Dans un hook tool.check, e.isReadOnly vaut true lorsque l'outil signale cet appel comme étant en lecture seule. Sinon, le champ est absent, et ne vaut pas false. La valeur correspond au propre signalement de l'outil : lisez donc Vérifier si un appel d'outil est en lecture seule avant d'approuver un appel sur la seule base de ce champ.

Sur tool.check, e.isReadOnly nécessite Claude Code v2.1.304 ou une version ultérieure.

Prompts et ce que Claude lit

Les événements de prompt couvrent le texte que l'utilisateur saisit et le texte que Claude Code envoie de lui-même à Claude, comme le prompt système et les rappels :

Champs de source et de frontmatter sur skill.prompt

Dans un hook skill.prompt, vous pouvez lire ces champs, en plus du nom du skill dans e.skill et du texte que Claude lit dans e.text :

Un hook peut transmettre un text ou un frontmatter modifié à next : les hooks qui le suivent lisent les deux, et Claude lit le text final. Un hook qui modifie tout autre champ échoue.

Sur skill.prompt, e.source, e.pluginName, e.path, e.frontmatter et e.frontmatterProblem nécessitent Claude Code v2.1.299 ou une version ultérieure.

Commandes et configuration

e.layers et e.source sur settings.read

• e.layers : un objet { source, settings } pour chaque source utilisée qui contient des paramètres, de la priorité la plus faible à la plus élevée. Consultez Ce que reçoit un hook settings.read.
• e.source : la source unique demandée par un mod, comme dans $.settings.read({ source: 'policy' }). Absent lors de la propre lecture de Claude Code et lors d'une lecture des paramètres fusionnés

Tours

Les événements de tour suivent une réponse du début à la fin, y compris chaque requête envoyée au modèle pendant celle-ci :

Session

Les événements de session marquent le démarrage, la fin et la compaction de la session, ainsi que l'échange de messages avec d'autres sessions :

Sous-agents

Les événements de sous-agent se déclenchent lorsqu'un type de sous-agent est proposé à Claude et lorsqu'un sous-agent ou un coéquipier d'une équipe d'agents est sur le point de démarrer :

Lorsque Claude reprend un sous-agent avec l'outil SendMessage, votre hook agent.spawn ne s'exécute pas à nouveau. Pour refuser les appels SendMessage qui reprennent un sous-agent, ciblez cet outil dans un hook tool.call.

Interface

Les événements d'interface se déclenchent lorsque Claude Code dessine un point de rendu et lorsque l'utilisateur utilise un contrôle dessiné par un mod. Dessiner dans l'interface montre ce que renvoie un hook ui.render :

Autres mods

Ces événements permettent à un mod d'agir sur d'autres mods au moment de leur chargement, pour en refuser un ou modifier l'API des mods qu'il reçoit :

Lorsque le hook d'un autre mod appelle une méthode sur un namespace que vous avez ajouté dans engine.create, les appels $ de votre méthode s'exécutent dans le contexte de ce hook jusqu'à ce que chaque hook sur cet événement ait renvoyé son résultat. Par exemple, un chemin relatif est résolu par rapport au répertoire de travail de ce hook, et $.prompt.submit est rejeté tant que le tour attend ce hook. Les appels que votre méthode effectue ensuite s'exécutent dans le contexte propre de votre mod.

Télémétrie

Les événements de télémétrie se déclenchent pour les enregistrements d'utilisation que Claude Code journalise :

Événements des hooks de paramètres

Chaque événement de hook de paramètres est un événement nommé classic.<Event>, tel que classic.Stop ou classic.PostToolUse. e est le JSON stdin du hook.

Appels à l'API des mods

Chaque méthode de l'API des mods est également un événement, nommé d'après son namespace et sa méthode, comme fs.read, model.complete ou ui.open. Un hook sur l'un d'eux intercepte les appels des mods qui s'exécutent après lui, et peut renvoyer next(e), { deny: reason } ou { value }.

Méthodes de l'API des mods

L'API des mods est l'argument $ que reçoit chaque hook. Ses méthodes sont regroupées en namespaces, comme $.ui. Ce tableau liste les méthodes de chaque namespace par nom : ainsi, open dans la ligne $.ui correspond à l'appel $.ui.open(...). Les guides montrent les plus courantes en action, et les types pour votre build documentent chaque méthode avec un exemple.

Points de rendu

Un point de rendu est un point d'extension de l'interface de Claude Code. Chaque ligne est une valeur de e.component dans un hook ui.render, avec les champs de e.props et les applications qui l'affichent. e.surface indique l'application qui dessine, par exemple terminal, desktop ou vscode. Modifier ce que Claude Code dessine déjà montre ce qu'un hook peut faire à un point de rendu, avec un exemple pour chaque option.

Le rendu dans l'extension VS Code nécessite la version 2.1.299 ou ultérieure de l'extension. Une session qui ne récupère pas les feature flags nécessite la version 2.1.304 ou ultérieure. Dessiner dans l'extension VS Code liste ce que l'extension dessine différemment.

e.viewport contient columns, rows et isFullscreen. Dans le terminal et l'application Desktop, il est absent tant que l'application n'a pas mesuré sa fenêtre. Dans ces applications, son rows correspond à la hauteur de la fenêtre entière, et non à celle de votre volet. Dans l'extension VS Code, il est toujours présent.

Pour adapter un arbre à son point de rendu, lisez ces props dans le hook :

• Largeur d'un Pane ou du bandeau : dessinez selon e.props.bodyColumns
• Hauteur d'un Pane à côté de la transcription : lorsque e.props.placement vaut 'dock', e.props.scroll.bodyRows est le nombre de lignes dont dispose le volet pour votre arbre
• Hauteur d'un Pane au-dessus du prompt : lorsque e.props.placement vaut 'inline', le volet s'agrandit avec votre arbre jusqu'à une limite, et bodyRows correspond à cette limite. Le champ rows de $.ui.open permet de demander une limite différente.

Un arbre plus haut que le volet défile d'un seul bloc.

Éléments

Les éléments sont les briques de l'arbre que renvoie un hook ui.render, et vous les obtenez à partir de $.ui.resolve(e). Construire un arbre à partir d'éléments présente les plus courants avec leur rendu dans le terminal, et la galerie d'interface contient des captures d'écran de la plupart d'entre eux. Une coche signifie que l'application peut dessiner l'élément.

Autres règles pour Button :

• action : nomme l'une des propres actions de raccourci clavier de Claude Code, et le raccourci de l'utilisateur pour cette action presse le bouton lorsque ce raccourci est une combinaison de touches ou une touche avec modificateur
• Hotkeys numériques dans le bandeau : un hotkey numérique sur un bouton du bandeau se déclenche aussi lorsque l'utilisateur tape ce seul chiffre dans un prompt vide puis marque une pause
• Un bandeau réduit : tant que le bandeau est réduit, ni un raccourci action ni un hotkey ne presse un bouton qu'il contient
• Deux boutons sur un même hotkey : lorsque deux boutons d'un même dessin désignent le même hotkey, c'est le dernier qui l'obtient
• variant : primary ou secondary, toute autre valeur lève une exception. Dans le terminal, un bouton primary est dessiné dans la couleur d'accentuation, sauf s'il est plain.
• role : dismiss marque un bouton de fermeture, toute autre valeur lève une exception. Effectuez la fermeture dans votre onPress. Dans un bandeau qui contient du texte et une rangée de boutons, l'application Desktop peut dessiner le premier bouton dismiss de la rangée comme son propre contrôle de fermeture. Le terminal dessine le bouton comme il le ferait sans role.

Un Button peut contenir des children à la place d'un label :

• Ce que peuvent être les enfants : des chaînes et des éléments Text, comme un nom suivi d'un détail atténué ou d'une pastille colorée. Claude Code refuse tout autre élément à l'intérieur d'un Button.
• Nommer le bouton : le label nomme le bouton et prend par défaut le texte de ses enfants. Donnez une key ou un label à un bouton dont les enfants ne se limitent pas à une seule chaîne.
• Dans le terminal : les enfants sont dessinés à l'emplacement du label, et un appui n'importe où sur eux compte comme un seul appui : vous pouvez donc faire de chaque ligne d'une liste un bouton unique
• Dans l'application Desktop et l'extension VS Code : le bouton dessine son label

[!NOTE]

Un Button dont les enfants ne se limitent pas à une seule chaîne nécessite Claude Code v2.1.295 ou une version ultérieure.

autoFocus n'accepte que true sur tout contrôle : omettez donc la prop pour le désactiver.

L'extension VS Code ignore certaines props d'éléments et dessine l'élément comme si vous les aviez omises :

• Box : position avec ses top, left, right et bottom, alignSelf, borderDimColor et hover
• Text : size, mono, tabular et hover
• Button : hotkey, plain, autoFocus, action et hover ; l'utilisateur y presse donc un bouton d'un clic, ou avec Entrée une fois que le bouton a le focus. L'extension ignore également variant et role.
• Code : language, path, startLine, format et wrap ; le code est donc dessiné sans couleurs ni numéros de ligne, et un bloc format: 'diff' affiche le texte brut du diff
• Input et Select : autoFocus, ainsi que rows sur un Input
• Svg : isInteractive

Styles de bordure de Box

Pour dessiner une bordure autour d'une Box, définissez sa prop borderStyle sur l'un de ces noms, comme dans borderStyle: 'round'. Chaque ligne indique ce que le terminal dessine pour ce nom et montre le bord supérieur de la bordure.

Une Box dont la prop borderStyle désigne tout autre nom, comme 'rounded', est dessinée sans bordure.

Pas d'espacement de Box

Les props d'espacement de Box sont gap, columnGap, rowGap, padding, margin, ainsi que les formes de padding et margin portant sur un seul côté ou un seul axe, comme paddingX et marginTop. Chacune accepte un nombre de cellules du terminal, comme gap: 1, ou un nom de pas, comme gap: 'md'. Dans le terminal et l'extension VS Code, chaque pas correspond au nombre de cellules suivant :

Si vous définissez gap, padding ou margin sur un pas, celui-ci s'applique à la fois en largeur et en hauteur. Par exemple, dans le terminal et l'extension VS Code, padding: 'md' correspond à deux cellules de chaque côté et à une ligne au-dessus et en dessous.

Les noms de pas nécessitent Claude Code v2.1.299 ou une version ultérieure. Sur une version antérieure, un arbre qui utilise un nom de pas n'est pas dessiné.

Props typographiques de Text

Définissez size, weight, mono ou tabular sur un Text pour demander à l'application qui dessine votre arbre une taille de texte, une graisse, une police à chasse fixe ou des chiffres de largeur égale. Avant de vous appuyer sur une prop, vérifiez ce qu'en font le terminal et l'extension VS Code. Si une application ignore une prop que vous avez définie, votre arbre y est tout de même dessiné, avec le texte tel qu'il serait si vous aviez omis cette prop.

Ces quatre props nécessitent Claude Code v2.1.299 ou une version ultérieure. Sur une version antérieure, un arbre qui définit size, weight, mono ou tabular n'est pas dessiné.

Remplacer bold par weight

bold sur un Text est déprécié au profit de weight et fonctionne toujours. Pour le remplacer sur un Text sans weight, changez bold: true en weight: 'semibold' pour obtenir le même résultat sur Claude Code v2.1.299 ou une version ultérieure.

Sur une version antérieure à v2.1.299, un arbre qui définit weight n'est pas dessiné. Si vous définissez à la fois bold et weight sur un Text, bold n'a aucun effet.

Limites

Les hooks et les appels à l'API des mods s'exécutent sous des limites de temps et de taille. Claude Code ignore un hook qui dépasse une limite de temps. Un arbre qui dépasse la limite d'imbrication, d'éléments, de cellules Raster ou d'octets Image n'est pas dessiné.

Paramètres et variables d'environnement

Voici les paramètres et variables d'environnement qui affectent les mods. La colonne Emplacement indique le fichier de paramètres ou l'environnement à partir duquel chacun est lu :

sec-default@builtin est un garde-fou intégré à Claude Code, listé sous le nom cc-plugin-sec-default dans /plugin et dans le log de débogage. Il se charge avant tout mod installé par une personne sur une machine dotée de paramètres gérés, ou dans une session dont les identifiants proviennent d'un /login Team ou Enterprise. Si prependPlugins est défini dans les paramètres gérés, le garde-fou ne se charge que lorsque cette liste le nomme, à la position indiquée.

Son code source se trouve dans le répertoire mods/sec-default du dépôt Claude Code.

Commandes

Ces commandes et flags permettent de charger, d'inspecter et de tester un mod. Les commandes claude s'exécutent dans votre shell et les commandes / dans le prompt de Claude Code. Dans le tableau, <directory> désigne un chemin que vous saisissez, comme dans claude plugin validate ./first-mod. Les crochets indiquent un argument facultatif.