> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://code.claude.com/docs/fr/plugins/mods/overview.md) 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](https://github.com/anthropics/claude-code/blob/main/mods/types/claude-code.d.ts) 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](https://code.claude.com/docs/fr/plugins/mods/create.md#get-the-types-for-your-build).

## Fichiers

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

| Fichier | Requis | Contenu |
| :- | :- | :- |
| `.claude-plugin/plugin.json` | Oui | Le [manifeste](https://code.claude.com/docs/fr/plugins/manifest-reference.md) du plugin. Les mods n'ajoutent aucun champ requis. |
| `hooks/hooks.json` | Oui | `modules` : un tableau contenant un chemin, relatif à ce fichier, vers le module de hooks, comme dans `"modules": ["./register.js"]`. Peut aussi contenir des [hooks de paramètres](https://code.claude.com/docs/fr/hooks.md) sous `hooks`. |
| Le module de hooks, tel que [`hooks/register.js`](https://code.claude.com/docs/fr/plugins/mods/create#write-a-mod-yourself) | Oui | Le point d'entrée du mod. Exporte `register(on, options)`. Nommé `.js`, `.mjs`, `.cjs`, `.jsx`, `.ts`, `.mts`, `.cts` ou `.tsx`. Un module ES. |
| [`types/index.d.ts`](https://code.claude.com/docs/fr/plugins/mods/interface#declare-the-values), sauf si `types` dans le manifeste désigne un autre chemin | Lorsque le mod utilise `$.state` ou ajoute un namespace à l'API des mods | Déclare les valeurs `PluginState` et tout namespace ajouté par le mod. Pour omettre `types` du manifeste, vous avez besoin de la v2.1.299 ou d'une version ultérieure. |
| Fichiers dont le nom se termine par `.test.ts` ou `.test.tsx` | Non | Tests exécutés par [`claude plugin test`](https://code.claude.com/docs/fr/plugins/mods/test#write-a-test) |

`register` reçoit `on` et `options`. `options` contient les valeurs des champs [`userConfig`](https://code.claude.com/docs/fr/plugins/components#user-configuration) 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](https://code.claude.com/docs/fr/plugins/mods/events.md#filter-which-events-a-hook-handles) 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](https://code.claude.com/docs/fr/plugins/mods/events.md#handle-a-hook-that-fails) du hook.

| Argument | Ce que c'est |
| :- | :- |
| [`$`](https://code.claude.com/docs/fr/plugins/mods/events#how-a-hook-handles-an-event) | L'API des mods : chaque méthode de [Méthodes de l'API des mods](#mods-api-methods). Écrivez chaque appel en entier, namespace puis méthode, comme dans `$.fs.read('notes.md')`. |
| [`e`](https://code.claude.com/docs/fr/plugins/mods/events#how-a-hook-handles-an-event) | L'entrée de l'événement, sous forme de données simples profondément figées. Pour la modifier, passez une copie à `next`. |
| [`next(e)`](https://code.claude.com/docs/fr/plugins/mods/events#how-a-hook-handles-an-event) | Le gestionnaire suivant, comme dans un middleware. Exécute les hooks qui suivent celui-ci, puis le comportement de Claude Code. Se résout avec le résultat de l'événement. |
| [`next.signal`](https://code.claude.com/docs/fr/plugins/mods/api#stop-background-work) | Un `AbortSignal` qui s'interrompt lorsque l'événement est abandonné |
| `next.origin` | `{ plugin, tier }` de l'émetteur de l'événement. Claude Code lui-même est `{ plugin: 'engine', tier: 'core' }`. Le `tier` d'un mod est son groupe de priorité dans [l'ordre d'exécution des mods](https://code.claude.com/docs/fr/plugins/mods/events.md#the-order-mods-run-in) : `prepend`, `user`, `append` ou `builtin`. |
| `next.budget` | La limite de temps du hook en millisecondes : `next.budget.ms` est la limite totale, et `next.budget.remainingMs` est ce qui reste à cet instant |
| `next.to(e, tier)` | Passe directement à un tier ultérieur, qui est `append`, `builtin` ou `core`. `next.to(e, 'append')` ignore les mods installés par un utilisateur. Seul un mod présent dans `prependPlugins` ou `appendPlugins` peut l'appeler. |
| `next.error` | Dans un gestionnaire `.catch` uniquement. `kind` vaut `throw` ou `timeout`, et `message` est le texte de l'erreur. |
| `next.called` | Dans un gestionnaire `.catch` uniquement. `true` lorsque le hook avait appelé `next`. |

## É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 :

| Événement | Se déclenche lorsque | Un hook peut renvoyer |
| :- | :- | :- |
| [`tool.call`](https://code.claude.com/docs/fr/plugins/mods/events#guard-or-change-a-tool-call) | Un outil est sur le point de s'exécuter | `next(e)`, `{ deny: reason }` ou `{ result }` |
| [`tool.check`](https://code.claude.com/docs/fr/plugins/mods/events#where-settings-hooks-run-in-the-order) | Claude Code décide si un appel d'outil peut s'exécuter, après les hooks `tool.call` et `PreToolUse`. `next(e)` se résout avec la décision à laquelle ont abouti les règles, le mode de permission et ces hooks. | `next(e)` ou `{ decision }`, avec `decision` défini sur `allow`, `ask` ou `deny` et un `reason` facultatif |
| `tool.describe` | Une fois pour chaque outil, lorsque sa description est envoyée à Claude pour la première fois. Une seconde fois pour un outil MCP lorsque Claude le charge via la [recherche d'outils](https://code.claude.com/docs/fr/mcp.md#scale-with-mcp-tool-search), avec `e.description` défini sur le texte que Claude lit pour l'outil chargé. | `{ description }`, avec éventuellement `isDeferred` défini sur `true` pour placer l'outil derrière la recherche d'outils ou sur `false` pour le charger dès le départ. Ajoutez [`breakPromptCache: true`](#break-prompt-cache) pour envoyer une description modifiée au tour suivant. |

#### 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](https://code.claude.com/docs/fr/sub-agents.md) ou un [coéquipier en cours de processus](https://code.claude.com/docs/fr/agent-teams.md#choose-a-display-mode) 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](https://code.claude.com/docs/fr/mcp.md#organization-controls-on-connector-tools)

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](https://code.claude.com/docs/fr/plugins/mods/events.md#check-whether-a-tool-call-is-read-only) 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 :

| Événement | Se déclenche lorsque | Un hook peut renvoyer |
| :- | :- | :- |
| [`prompt.submit`](https://code.claude.com/docs/fr/plugins/mods/events#rewrite-or-add-to-a-prompt) | Un prompt est soumis | `next({ ...e, text })`, `next({ ...e, context })` ou `{ drop: reason }` |
| `prompt.fill`, `prompt.suggest` | Du texte est sur le point d'être placé dans la zone de prompt en tant que brouillon, ou en tant que suggestion estompée | `next(e)` avec le texte modifié |
| `prompt.edit` | L'utilisateur modifie la zone de prompt | `next(e)` |
| `prompt.autocomplete` | L'utilisateur saisit du texte dans la zone de prompt et un mot se termine au niveau du curseur. `e.token` est ce mot. Claude Code n'attend pas le hook : ses propres lignes d'autocomplétion s'affichent en premier. | `{ suggestions }`, une liste de lignes `{ text, label, description }` affichées sous celles de Claude Code. Choisir une ligne remplace le mot par son `text`. |
| `prompt.compose` | Claude Code génère un prompt système | `{ sections }`, une liste de `{ id, text, scope }` dans l'ordre d'envoi |
| [`prompt.section`](https://code.claude.com/docs/fr/plugins/mods/events#rewrite-or-add-to-a-prompt) | Une fois pour chaque section nommée du prompt système. `e.name` est l'`id` de la section dans `prompt.compose`. | `{ text }`, ou `{ text: null }` pour omettre la section. Ajoutez [`breakPromptCache: true`](#break-prompt-cache) pour envoyer une section modifiée au tour suivant. |
| [`prompt.context`](https://code.claude.com/docs/fr/plugins/mods/events#rewrite-or-add-to-a-prompt) | Une fois pour chaque conversation, pour le contexte envoyé avec le premier message | `{ blocks }` |
| `prompt.attachment` | Claude Code ajoute un message de sa propre initiative pour Claude, tel qu'un rappel. `e.type` nomme le type, et pour les types que déclarent les déclarations de types, `e.detail` contient les informations à partir desquelles le texte a été rédigé. | `{ text }`, ou `{ text: null }` pour l'omettre |
| `prompt.mention` | Claude Code est sur le point de lire un fichier qu'un prompt mentionne avec @. Nécessite Claude Code v2.1.290 ou une version ultérieure. | `next({ ...e, path })` pour lire un autre fichier, ou `{ deny: reason }` |
| [`skill.prompt`](https://code.claude.com/docs/fr/plugins/mods/events#rewrite-or-add-to-a-prompt) | Le texte d'un skill est développé pour Claude | `{ text }` |
| `attribution.text` | Claude Code compose le texte d'attribution d'un commit ou d'une pull request | `{ text }` |

#### 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` :

| Champ | Type | Contenu |
| :- | :- | :- |
| `e.source` | string | Qui fournit le skill : `policySettings`, `userSettings` ou `projectSettings` pour un skill situé respectivement à l'[emplacement](https://code.claude.com/docs/fr/skills.md#where-skills-live) entreprise, personnel ou projet. Les autres sources donnent un mot tel que `plugin`, `mcp`, `syncedSkills` ou `built-in`. |
| `e.pluginName` | string | Le nom du plugin, pour un skill dont `e.source` vaut `plugin` |
| `e.path` | string | Le chemin absolu du fichier `SKILL.md` du skill, ou de son fichier `.md` pour un skill écrit sous forme de [fichier de commande](https://code.claude.com/docs/fr/skills.md#where-skills-live). Absent lorsque le skill n'a aucun fichier sur cette machine, comme c'est le cas pour un skill intégré. |
| `e.frontmatter` | object | Le frontmatter du fichier du skill, sous forme de données simples |
| `e.frontmatterProblem` | string | La raison pour laquelle il manque à `e.frontmatter` le frontmatter du fichier ou l'une de ses clés, comme dans `is a list or a single value, not a table`. Absent lorsque `e.frontmatter` contient l'intégralité du frontmatter ou que le skill n'en a pas. |

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](https://code.claude.com/docs/fr/plugins/mods/events.md#handle-a-hook-that-fails).

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.

#### Envoyer une section de prompt système ou une description d'outil modifiée avec `breakPromptCache`

Pour modifier une section ou une description d'outil dans une conversation en cours, appelez `$.ui.invalidate('prompt.section')` ou `$.ui.invalidate('tool.describe')` afin que votre hook s'exécute à nouveau. Renvoyez `{ text, breakPromptCache: true }` ou `{ description, breakPromptCache: true }` depuis celui-ci. Sans ce champ, Claude continue de lire le texte [enregistré avec la conversation](https://code.claude.com/docs/fr/cli-reference.md#system-prompt-flags-in-resumed-conversations) pour une section ou un outil chargé dès le départ, jusqu'à une nouvelle conversation ou une [compaction](https://code.claude.com/docs/fr/prompt-caching.md#compacting-the-conversation).

Le texte modifié parvient à Claude au tour suivant, et le [cache de prompts](https://code.claude.com/docs/fr/prompt-caching.md) repart de zéro : ce tour est donc plus lent et plus coûteux. Le champ nécessite Claude Code v2.1.321 ou une version ultérieure. De la v2.1.299 jusqu'à la v2.1.321, une conversation en cours recevait le texte modifié au tour suivant.

### Commandes et configuration

| Événement | Se déclenche lorsque | Un hook peut renvoyer |
| :- | :- | :- |
| [`command.run`](https://code.claude.com/docs/fr/plugins/mods/api#add-a-command) | Une commande est sur le point de s'exécuter | `{ text }`, `{}` ou `next(e)` |
| `command.describe` | Une fois pour chaque commande, pour la liste des commandes | `{ description, argumentHint, isHidden }` |
| `config.set` | Une ligne de `/config` est sur le point de changer | `next({ ...e, value })` ou `{ deny: reason }` |
| `config.describe` | Une fois pour chaque ligne de `/config` | `{ label, description, isHidden }` |
| [`settings.read`](https://code.claude.com/docs/fr/plugins/mods/events#settings-read-hook) | Un mod appelle [`$.settings.read`](https://code.claude.com/docs/fr/plugins/mods/api#reach-files-processes-and-the-network), ou Claude Code construit les paramètres fusionnés de la session. Nécessite Claude Code v2.1.304 ou une version ultérieure pour la propre lecture de Claude Code et pour `e.layers` | `next(e)`, `{ value }` ou `{ deny: reason }` |

#### `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é](https://code.claude.com/docs/fr/settings.md#settings-precedence) la plus faible à la plus élevée. Consultez [Ce que reçoit un hook `settings.read`](https://code.claude.com/docs/fr/plugins/mods/events#settings-read-receives).
* **`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 :

| Événement | Se déclenche lorsque | Un hook peut renvoyer |
| :- | :- | :- |
| [`turn.start`](https://code.claude.com/docs/fr/plugins/mods/events#follow-a-turn) | Un tour commence | `next(e)` |
| [`turn.step`](https://code.claude.com/docs/fr/plugins/mods/events#follow-a-turn) | Une requête est sur le point d'être envoyée au modèle | `yield* next(e)`, ou `next({ ...e, model })`, `next({ ...e, effort })` |
| [`turn.complete`](https://code.claude.com/docs/fr/plugins/mods/events#follow-a-turn) | Un tour s'est terminé | `next(e)`, ou `{ text }` pour afficher une ligne sous la réponse |

### 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 :

| Événement | Se déclenche lorsque | Un hook peut renvoyer |
| :- | :- | :- |
| [`session.start`](https://code.claude.com/docs/fr/plugins/mods/api#add-a-command-or-a-tool) | Une fois pour chaque mod chargé, avant le premier prompt, puis à nouveau après un rechargement de ce mod. Pas après `/clear`, `/resume` ou `/branch`. | `next(e)` |
| `session.end` | La session se termine, ou `/clear`, `/resume` ou `/branch` s'exécute. `e.reason` vaut `clear`, `resume`, `logout`, `prompt_input_exit` ou `other`. `/branch` signale `resume`. | `next(e)` |
| `session.compact` | La conversation est sur le point d'être compactée | `{ skip: reason }` |
| [`session.receive`](https://code.claude.com/docs/fr/plugins/mods/api#send-and-receive-messages-between-sessions), [`session.send`](https://code.claude.com/docs/fr/plugins/mods/api#send-and-receive-messages-between-sessions) | Un message arrive d'un autre agent ou d'une autre session, ou est sur le point d'y être envoyé. Consultez [Envoyer et recevoir des messages entre sessions](https://code.claude.com/docs/fr/plugins/mods/api.md#send-and-receive-messages-between-sessions). | `{ consumed: reason }` pour `receive`, `{ isDelivered: false, reason }` pour `send` |
| `session.append` | Une fois pour chaque ligne conservée par la conversation, telle qu'un prompt, un bloc de réponse, un résultat d'outil ou une notification, avant son stockage | `next({ ...e, message })` avec un `message.content` modifié, pour réécrire les blocs de texte de la ligne ou le `content` d'un bloc `tool_result` qu'elle contient |
| `session.attach`, `session.detach` | Une autre application se connecte à la session ou s'en déconnecte | `next(e)` |
| `session.measure` | Après chaque tour, et lorsque le pourcentage utilisé d'une limite de forfait change | `next(e)` |

### 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 :

| Événement | Se déclenche lorsque | Un hook peut renvoyer |
| :- | :- | :- |
| `agent.offer` | Un type de sous-agent est proposé à Claude | `{ isOffered: false }` pour le retenir |
| `agent.spawn` | Un sous-agent ou un coéquipier d'une [équipe d'agents](https://code.claude.com/docs/fr/agent-teams.md) est sur le point de démarrer, ou un sous-agent qui s'est terminé ou a été arrêté est sur le point de s'exécuter à nouveau. Pour un coéquipier, `e.isTeammate` vaut `true`. Pour une exécution reprise, `e.resume` est défini. | `next({ ...e, model })` pour choisir le modèle de celui qui démarre, ou `{ deny: reason }` |

Votre hook `agent.spawn` s'exécute également lorsqu'un sous-agent qui s'est terminé ou a été arrêté est sur le point de s'exécuter à nouveau, par exemple lorsque Claude lui envoie un message avec l'outil [`SendMessage`](https://code.claude.com/docs/fr/sub-agents#resume-subagents). Sur cet événement, `e.resume` vaut `{ agentId }`. Si votre hook compte les sous-agents, ignorez les événements où `e.resume` est défini, afin qu'un sous-agent repris ne soit pas compté à nouveau.

Renvoyez `{ deny: reason }` pour refuser une exécution reprise. L'exécution ne démarre pas, et le sous-agent reste dans l'état où il était. Lorsqu'un appel `SendMessage` a demandé l'exécution, Claude lit `a plugin declined the resume:` suivi de votre raison comme résultat de cet appel. Si vous transmettez un événement modifié à `next` pour une exécution reprise, par exemple un `model` différent, Claude Code ignore la modification.

> [!NOTE]
>
> L'événement pour une exécution reprise nécessite Claude Code v2.1.299 ou une version ultérieure. Avant la v2.1.299, votre hook `agent.spawn` ne s'exécutait pas lorsqu'un sous-agent reprenait. Sur ces versions, pour refuser les appels `SendMessage` qui reprennent un sous-agent, ciblez cet outil dans un hook [`tool.call`](https://code.claude.com/docs/fr/plugins/mods/events#guard-or-change-a-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](https://code.claude.com/docs/fr/plugins/mods/interface.md) montre ce que renvoie un hook `ui.render` :

| Événement | Se déclenche lorsque |
| :- | :- |
| [`ui.render`](https://code.claude.com/docs/fr/plugins/mods/interface#pick-where-to-draw) | Un [point de rendu](#render-sites) est sur le point d'être dessiné |
| `ui.resolve` | Les mods se chargent, une fois pour chaque application, point de rendu et mod. Le résultat est la table d'éléments que lit `$.ui.resolve(e)`. |
| [`ui.press`](https://code.claude.com/docs/fr/plugins/mods/interface#respond-to-presses-and-typing), [`ui.input`](https://code.claude.com/docs/fr/plugins/mods/interface#respond-to-presses-and-typing), [`ui.select`](https://code.claude.com/docs/fr/plugins/mods/interface#respond-to-presses-and-typing) | Un `Button`, un `Input` ou un `Select` dessiné par un mod est utilisé |
| `ui.focus`, `ui.scroll` | Le contrôle ayant le focus ou la position de défilement d'un volet ou du bandeau est sur le point de changer |
| `ui.close` | Un volet est sur le point de se fermer. `e.id` est le volet et `e.origin.kind` vaut `plugin`, `person` ou `unload`. |
| [`ui.message`](https://code.claude.com/docs/fr/plugins/mods/interface#build-a-tree-from-elements) | Un élément `Client` envoie des données à son mod |
| [`ui.fault`](https://code.claude.com/docs/fr/plugins/mods/interface#redraw-when-something-changes) | Un élément `Client` dessiné par votre mod n'a pas pu se charger, se dessiner ou s'exécuter. `e.phase` vaut `load`, `render` ou `run`, et `e.reason` est le message d'erreur. Nécessite Claude Code v2.1.289 ou une version ultérieure. |

### 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 :

| Événement | Se déclenche lorsque | Un hook peut renvoyer |
| :- | :- | :- |
| [`plugin.register`](https://code.claude.com/docs/fr/plugins/mods/admin#enforce-a-policy-with-a-mod-of-your-own) | Un module de hooks est sur le point de se charger. `e.uses` liste ses événements, ses appels à l'API des mods, ses variables d'environnement et son état, tels que `claude plugin validate` les affiche. Chaque appel est écrit sans le préfixe `$.`, comme `fs.read`. | `{ refuse: reason }` |
| `engine.create` | L'API des mods est en cours de construction pour ce mod | Une API des mods modifiée, pour ajouter un namespace. Un mod en dehors du [niveau](#the-hook-function) `user` peut également en retenir un. |

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énement | Se déclenche lorsque | Un hook peut renvoyer |
| :- | :- | :- |
| `telemetry.log`, `telemetry.mark` | Un enregistrement de télémétrie est sur le point d'être journalisé, ou une utilisation d'une fonctionnalité est marquée. Dans un mod que vous installez, donnez à un hook de télémétrie le filtre `{ to: 'collector' }`, comme dans `on('telemetry.log', { to: 'collector' }, hook)`. Sans ce filtre, le mod échoue à `claude plugin validate`. `*` ne correspond pas à ces événements. | `next(e)`, ou `{ deny: reason }` |

### Événements des hooks de paramètres

Chaque [événement de hook de paramètres](https://code.claude.com/docs/fr/hooks.md#hook-events) 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](#mods-api-methods) 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 peut renvoyer `next(e)`, `{ deny: reason }` ou `{ value }`.

Certains de ces événements se déclenchent également pour les propres actions de Claude Code : vérifiez donc si `next.origin.plugin` vaut `engine` avant d'en refuser un.

#### Champs des propres requêtes `http.fetch` de Claude Code

Dans un hook `http.fetch`, un [`next.origin`](#the-hook-function) valant `{ plugin: 'engine', tier: 'core' }` signale l'une des propres requêtes de Claude Code, comme une requête au modèle, et non un appel `$.http.fetch` d'un mod. Là où le [garde-fou intégré](https://code.claude.com/docs/fr/plugins/mods/admin.md#know-what-happens-by-default) est chargé, votre hook ne reçoit pas ces événements, sauf si votre mod [compte comme un mod de votre organisation](https://code.claude.com/docs/fr/plugins/mods/admin.md#install-your-organizations-mods).

Sur ces événements, `e.init` et la `value` avec laquelle `next(e)` se résout peuvent contenir ces champs, entre autres :

| Champ | Signification |
| :- | :- |
| `e.init.compress` | Défini lorsque Claude Code compresse le corps après votre hook. `e.init.body` contient le corps non compressé. Pour envoyer le corps sans compression, appelez `next({ ...e, init: { ...e.init, compress: undefined } })`. |
| `value.isStreaming` | Défini sur `true` car Claude Code lit lui-même le corps de la réponse, de sorte que `value.text` est vide. Lisez plutôt `value.status` et `value.headers`. Pour répondre avec votre propre `text`, renvoyez une `value` sans `isStreaming`. |

Ces événements et ces champs nécessitent Claude Code v2.1.321 ou une version ultérieure.

## 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](https://code.claude.com/docs/fr/plugins/mods/create.md#get-the-types-for-your-build) documentent chaque méthode avec un exemple.

| Namespace | Méthodes |
| :- | :- |
| `$.plugin` | `name`, `root` : le nom et le répertoire de ce plugin |
| [`$.ui`](https://code.claude.com/docs/fr/plugins/mods/interface#pick-where-to-draw) | `resolve`, `invalidate`, `open`, `close`, `panes`, [`place`](https://code.claude.com/docs/fr/plugins/mods/interface#place-a-row-in-the-transcript), `focus`, `scroll`, `toast`, `notify`, `status`, `log`, `notice`, `ask`, `copy`, `selection`, `blit`, `view`. `view` nécessite Claude Code v2.1.300 ou une version ultérieure et `place` v2.1.314 ou une version ultérieure. |
| [`$.theme`](https://code.claude.com/docs/fr/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `set`, `clear` : définir un arrière-plan que l'application Desktop ou mobile dessine, et retirer cet arrière-plan. Nécessite Claude Code v2.1.319 ou une version ultérieure. |
| [`$.command`](https://code.claude.com/docs/fr/plugins/mods/api#add-a-command) | `register`, `run`, `list` |
| [`$.tool`](https://code.claude.com/docs/fr/plugins/mods/api#add-a-tool) | `register`, `call`, `check`, `list`. Lorsqu'un `call` nécessite l'approbation d'une personne, par exemple un appel auquel un hook ou votre organisation répond par `ask`, il se résout avec `{ deny: "<tool> wasn't run: this call needs a person's approval, and a mod's own call can't ask for it." }`, où `<tool>` est le nom de l'outil. |
| `$.agent` | `register`, `spawn`, `list`. `list()` renvoie les sous-agents et coéquipiers de cette session, chacun avec un `status` parmi `pending`, `running`, `waiting`, `idle`, `completed`, `failed` ou `killed`, où `idle` et `waiting` nécessitent Claude Code v2.1.289 ou une version ultérieure. |
| [`$.model`](https://code.claude.com/docs/fr/plugins/mods/api#call-a-model) | `complete`, `fork`, `classify` |
| [`$.prompt`](https://code.claude.com/docs/fr/plugins/mods/api#start-a-turn-from-a-background-job) | `submit`, `read`, `fill`, `suggest`, `compose`. Claude lit le texte de `submit({ text })` après une phrase qui désigne votre mod comme expéditeur. `submit({ text, asUser: true })` envoie le texte comme s'il s'agissait des propres mots de l'utilisateur, sans cette phrase. |
| `$.turn` | `abort` |
| [`$.session`](https://code.claude.com/docs/fr/plugins/mods/api#send-and-receive-messages-between-sessions) | `messages`, `cwd`, `root`, `model`, `turns`, `id`, `repo`, `surfaces`, `usage`, `version`, `compact`, `send`, `append`, `authorize`. `usage()` renvoie `{ startedAt, context, rateLimits, cost }` : `context` contient `tokens`, `window` et `percent`, et `rateLimits` est une liste de `{ kind, percentUsed, resetsAt }`. |
| `$.config` | `list`, `set` |
| [`$.settings`](https://code.claude.com/docs/fr/plugins/mods/api#reach-files-processes-and-the-network) | `read` |
| [`$.env`](https://code.claude.com/docs/fr/plugins/mods/api#reach-files-processes-and-the-network) | `get`, `set` |
| [`$.fs`](https://code.claude.com/docs/fr/plugins/mods/api#reach-files-processes-and-the-network) | `read`, `write`, `list`, `exists`, `stat`, `ancestors`. `write` n'est pas atomique : il remplace le contenu du fichier sur place, de sorte qu'un autre processus peut lire un fichier partiellement écrit. Conservez dans `$.store` les données que plusieurs sessions modifient. |
| [`$.store`](https://code.claude.com/docs/fr/plugins/mods/interface#keep-state) | `get`, `set`, `delete`, `keys`. Un magasin clé-valeur partagé par toutes les sessions de la machine. Consultez [Enregistrer depuis plusieurs sessions](https://code.claude.com/docs/fr/plugins/mods/interface.md#save-from-more-than-one-session). |
| [`$.state`](https://code.claude.com/docs/fr/plugins/mods/interface#keep-a-value-in-\$-state) | État réactif : `get`, `set`, avec les helpers `atom`, `read`, `update`, `derive` et `memberOf` importés depuis `claude-code` |
| [`$.clock`](https://code.claude.com/docs/fr/plugins/mods/api#run-work-in-the-background) | `now`, `sleep`, `after`, `every` |
| [`$.http`](https://code.claude.com/docs/fr/plugins/mods/api#reach-files-processes-and-the-network) | `fetch` |
| [`$.process`](https://code.claude.com/docs/fr/plugins/mods/api#reach-files-processes-and-the-network) | `run`, `spawn` |
| [`$.mcp`](https://code.claude.com/docs/fr/plugins/mods/api#reach-files-processes-and-the-network) | `call`, `connect`. `connect(server)` connecte un serveur MCP listé par le manifeste de votre propre plugin. |
| `$.audio` | `play`, `speak` |
| `$.telemetry` | `log`, `mark`. Un enregistrement n'est envoyé que lorsque l'appel est effectué par Claude Code ou par un mod intégré. |

## 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à](https://code.claude.com/docs/fr/plugins/mods/interface.md#change-what-claude-code-already-draws) 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](https://code.claude.com/docs/fr/env-vars.md#features-that-need-feature-flag-fetching) nécessite la version 2.1.304 ou ultérieure. [Dessiner dans l'extension VS Code](https://code.claude.com/docs/fr/plugins/mods/interface.md#draw-in-the-vs-code-extension) liste ce que l'extension dessine différemment.

| Point de rendu | `e.props` | `e.requestId` | Affiché dans |
| :- | :- | :- | :- |
| [`Pane`](https://code.claude.com/docs/fr/plugins/mods/interface#pick-where-to-draw) | `title`, `isFocused`, `bodyColumns`, `placement`, `scroll`, `view` | L'`id` du volet | Terminal, Desktop, VS Code |
| [`AbovePrompt`](https://code.claude.com/docs/fr/plugins/mods/interface#pick-where-to-draw) | `hasSurvey`, [`isCollapsed`](https://code.claude.com/docs/fr/plugins/mods/interface#when-the-user-collapses-the-band), `isWorking`, `maxRows`, `bodyColumns`, `scroll`, `view` | Une seule instance | Terminal, Desktop |
| `AbovePromptList`, la pile des lignes `AbovePrompt` | `rows`, une liste contenant un `{ plugin, tree }` pour la ligne de chaque mod, ainsi que les props de `AbovePrompt` | Une seule instance | Terminal, Desktop. Nécessite Claude Code v2.1.323 ou ultérieure. |
| [`Placed`](https://code.claude.com/docs/fr/plugins/mods/interface#place-a-row-in-the-transcript) | `id`, `plugin`, `onScreen` | Le `requestId` renvoyé par `$.ui.place` | Terminal |
| [`Backdrop`](https://code.claude.com/docs/fr/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `scene`, `plugin`, `glass`, `overrideColorScheme`. Avant la v2.1.323, `scene` s'appelait `id` et `overrideColorScheme` s'appelait `colorScheme`. | `backdrop` | Surfaces `desktop` et `mobile`. Votre hook s'exécute lorsque l'application Desktop ou mobile demande à dessiner un arrière-plan. |
| `UserMessage` | `text`, `origin`, `isExpanded`, et `task` ou `from` selon l'origine | L'id de la ligne dessinée | Terminal, Desktop, VS Code |
| `AssistantMessage` | Le texte de la réponse | L'id de la ligne dessinée | Terminal, Desktop, VS Code |
| `ToolUse`, `ToolResult`, `ToolGroup` | Le nom, l'entrée et le résultat de l'outil | L'id de l'appel d'outil | Terminal, Desktop, VS Code |
| `CommandOutput` | `command`, `text` | L'id de la ligne dessinée | Terminal, Desktop |
| [`AskUserQuestion`](https://code.claude.com/docs/fr/plugins/mods/interface#change-what-claude-code-already-draws) | La question et les options | L'id de l'appel d'outil | Terminal, Desktop, VS Code |
| `ToolProgress` | `kind` | L'id de l'appel d'outil | Terminal |
| [`Spinner`](https://code.claude.com/docs/fr/plugins/mods/interface#change-what-claude-code-already-draws) | `word`, `message`, `suffix`, `mode` | L'id de l'agent | Terminal, Desktop, VS Code |
| `TurnDuration` | `word`, `durationMs` | L'id de la ligne dessinée | Terminal |
| `InfoNotice` | `text`, `command` | Le `text` de la notification, préfixé par `notice:` | Terminal |
| `SessionMode` | `modes` | Une seule instance | Terminal, Desktop |
| `PromptHint` | `isDraft`, `isWorking`, `hint` | Une seule instance | Terminal, Desktop |

`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`](https://code.claude.com/docs/fr/plugins/mods/interface#open-a-pane-at-the-right-time) 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](https://code.claude.com/docs/fr/plugins/mods/interface.md#build-a-tree-from-elements) présente les plus courants avec leur rendu dans le terminal, et la [galerie d'interface](https://code.claude.com/docs/fr/plugins/mods/gallery.md) contient des captures d'écran de la plupart d'entre eux. Une coche signifie que l'application peut dessiner l'élément.

| Élément | Props principales | Terminal | Desktop | VS Code |
| :- | :- | :-: | :-: | :-: |
| [`Box`](https://code.claude.com/docs/fr/plugins/mods/interface#build-a-tree-from-elements) | `key`, disposition flex, [`gap`, `padding`, `margin`](#box-spacing-steps), `width`, `height`, `minWidth`, `minHeight`, [`borderStyle`](#box-border-styles), `borderColor`, `borderDimColor`, `backgroundColor`, `position`, `top`, `left`, `right`, `bottom`, `overflow`, `display`, `hover` | ✓ | ✓ | ✓ |
| [`Text`](https://code.claude.com/docs/fr/plugins/mods/interface#build-a-tree-from-elements) | `color`, `backgroundColor`, [`bold`](#text-bold), `italic`, `underline`, `strikethrough`, `dimColor`, `inverse`, `wrap`, [`size`, `weight`, `mono`, `tabular`](#text-typography), `hover` | ✓ | ✓ | ✓ |
| [`Button`](https://code.claude.com/docs/fr/plugins/mods/interface#respond-to-presses-and-typing) | `key`, `label`, `children`, `onPress`, `hotkey`, `plain`, `dimColor`, `autoFocus`, `action`, `variant`, `role`, `hover` | ✓ | ✓ | ✓ |
| [`Link`](https://code.claude.com/docs/fr/plugins/mods/interface#link-in-the-desktop-app) | `href`, `label`. Consultez [Limites](#limits). | ✓ | ✓ | ✓ |
| [`Code`](https://code.claude.com/docs/fr/plugins/mods/gallery#show-code-and-changes) | `source`, `language`, `path`, `startLine`, `format`, `wrap` | ✓ | ✓ | ✓ |
| `Markdown` | `text`, `key`, `dimColor`, `onLinkPress`, `pressableLinks` | ✓ | ✓ | ✓ |
| [`Input`](https://code.claude.com/docs/fr/plugins/mods/interface#take-typed-input-and-draw-a-row-for-each-item) | `key`, `label`, `placeholder`, `value`, `submitLabel`, [`rows`](https://code.claude.com/docs/fr/plugins/mods/gallery#input), `onSubmit`, `onInput`, `autoFocus` | ✓ | ✓ | ✓ |
| `Select` | `key`, `label`, `options`, `value`, `onSelect`, `autoFocus` | ✓ | ✓ | ✓ |
| `Svg` | Une `source` de balisage SVG jusqu'à 131 072 caractères, un texte `alt`, `width`, `height` et `isInteractive` | | ✓ | ✓ |
| [`Client`](https://code.claude.com/docs/fr/plugins/mods/interface#build-a-tree-from-elements) | `module`, `key`, `props`, `width`, `height`, `flexGrow` | ✓ | ✓ | |
| [`Raster`](https://code.claude.com/docs/fr/plugins/mods/interface#draw-a-grid-of-colored-cells) | `key`, `columns` jusqu'à 512, `rows` jusqu'à 256, `cells`. Consultez [Dessiner une grille de cellules colorées](https://code.claude.com/docs/fr/plugins/mods/interface.md#draw-a-grid-of-colored-cells). | ✓ | | |
| `Image` | `key`, une `source` telle que des octets PNG ou RGBA jusqu'à 2 Mio, ou un chemin de fichier, `columns` et `rows` jusqu'à 255, et un texte `alt`. Consultez [les terminaux qui le dessinent](https://code.claude.com/docs/fr/plugins/mods/gallery.md#image-and-client). | ✓ | | |

Autres règles pour `Button` :

* **`action`** : nomme l'une des propres [actions de raccourci clavier](https://code.claude.com/docs/fr/keybindings.md) 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](https://code.claude.com/docs/fr/plugins/mods/interface.md#when-the-user-collapses-the-band), ni un raccourci `action` ni un hotkey ne presse un bouton qu'il contient
* **Deux boutons sur un même hotkey** : lorsque deux de vos boutons d'un même dessin désignent le même `hotkey`, c'est le dernier qui l'obtient. Pour le bouton d'un autre mod sur la même touche, consultez [Les hotkeys ne font rien](https://code.claude.com/docs/fr/plugins/mods/troubleshoot.md#hotkeys-do-nothing).
* **`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.

| `borderStyle` | Ce que dessine le terminal | Bord supérieur |
| :- | :- | :- |
| `'single'` | Traits fins avec des coins carrés | `┌──┐` |
| `'double'` | Traits doubles | `╔══╗` |
| `'round'` | Traits fins avec des coins arrondis | `╭──╮` |
| `'bold'` | Traits épais | `┏━━┓` |
| `'singleDouble'` | Traits fins en haut et en bas, traits doubles sur les côtés | `╓──╖` |
| `'doubleSingle'` | Traits doubles en haut et en bas, traits fins sur les côtés | `╒══╕` |
| `'classic'` | Les caractères ASCII `+`, `-` et `\|` | `+--+` |
| `'arrow'` | Des flèches qui pointent vers l'intérieur de la `Box` | `↘↓↓↙` |
| `'dashed'` | Traits en pointillés avec des coins vides | `╌╌` |
| `'quote'` | Une barre, `▎`, le long du côté gauche et des cellules vides sur les trois autres côtés | Vide |

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 :

| Pas | Cellules en largeur | Cellules en hauteur |
| :- | :- | :- |
| `'xs'` | 1 | 0 |
| `'sm'` | 1 | 0 |
| `'md'` | 2 | 1 |
| `'lg'` | 3 | 1 |
| `'xl'` | 4 | 2 |

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.

| Prop | Valeurs | Dans le terminal | Dans l'extension VS Code |
| :- | :- | :- | :- |
| `size` | `'caption'`, `'footnote'`, `'body'`, `'heading'` ou `'title'` | Ignorée : le terminal n'a qu'une seule taille de texte | Ignorée |
| `weight` | `'regular'`, `'medium'`, `'semibold'` ou `'bold'` | `semibold` et `bold` sont dessinées en gras | `semibold` et `bold` sont dessinées en gras |
| `mono` | `true` pour demander la police à chasse fixe de l'application | Ignorée : le terminal est toujours à chasse fixe | Ignorée, le texte conserve donc la police propre à l'extension |
| `tabular` | `true` pour demander des chiffres de largeur égale, afin qu'un nombre mis à jour sur place ou une colonne de nombres reste aligné | Ignorée : les chiffres du terminal occupent déjà une cellule chacun | Ignorée |

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é](https://code.claude.com/docs/fr/plugins/mods/troubleshoot.md#a-pane-or-band-is-empty).

| Limite | Valeur |
| :- | :- |
| Le temps d'exécution propre d'un hook pour un événement, sans compter le temps passé dans `next` ou dans un appel à l'API des mods autre que `$.clock.sleep` | 10 secondes, ou 50 millisecondes pour un hook `prompt.edit` |
| Le temps d'exécution d'un gestionnaire `.catch` | 1 seconde |
| L'ensemble des hooks `session.end` | Aussi longtemps que le [budget du hook SessionEnd](https://code.claude.com/docs/fr/hooks.md#sessionend-input), soit 1,5 seconde sauf si vous le modifiez, compté à partir du moment où les hooks `SessionEnd` de vos paramètres se terminent |
| Délai d'expiration de `$.process.run` | 30 secondes par défaut, 10 minutes au maximum |
| `stdout` et `stderr` de `$.process.run` | 4 Mio chacun. `isStdoutTruncated` ou `isStderrTruncated` vaut `true` lorsque l'un d'eux a été tronqué. |
| `maxTokens` de `$.model.complete` | 1024 par défaut, jusqu'à 64 000 ou la limite de sortie du modèle |
| `$.fs.read` et `$.fs.write` | 4 Mio pour un fichier |
| Le corps de la requête d'un `$.http.fetch` | 4 Mio, comptés en caractères. Un appel avec un corps plus volumineux est rejeté. |
| Le corps de la réponse d'un `$.http.fetch` | 4 Mio. `text` contient les 4 premiers Mio et le reste n'est pas lu. Lorsque l'en-tête `Content-Length` déclare davantage, l'appel est rejeté à la place, avec une raison qui se termine par `is over the 4194304-byte limit`, sauf lorsque la dernière requête après d'éventuelles redirections utilise la méthode `HEAD`. L'exemption `HEAD` nécessite Claude Code v2.1.296 ou une version ultérieure. |
| Un appel `$.http.fetch`, redirections et corps compris | 30 secondes |
| Redirections suivies par un appel `$.http.fetch` | 5 |
| La raison `drop` d'un hook ou la raison `deny` de `config.set` | 4 096 caractères. La fin d'une raison plus longue est tronquée, et le drop ou le deny s'applique quand même. La troncature nécessite Claude Code v2.1.292 ou une version ultérieure ; sur les versions antérieures, le hook [échoue](https://code.claude.com/docs/fr/plugins/mods/events.md#handle-a-hook-that-fails) à la place. |
| Texte dans un arbre | Les 100 000 premiers caractères sont dessinés |
| Le `language` ou le `path` d'un `Code`, la `value` d'une option `Select`, ou le `module` d'un `Client` | 10 000 caractères. Si l'un d'eux est plus long, le hook `ui.render` qui l'a renvoyé [échoue](https://code.claude.com/docs/fr/plugins/mods/events.md#handle-a-hook-that-fails). |
| Le `href` d'un `Link` | 2 048 caractères. S'il est plus long, le hook `ui.render` qui l'a renvoyé [échoue](https://code.claude.com/docs/fr/plugins/mods/events.md#handle-a-hook-that-fails). |
| Profondeur d'imbrication d'un arbre | 32 niveaux sous l'élément racine |
| Éléments et enfants texte dans un arbre | 20 000 |
| Cellules `Raster` dans un arbre, soit les `columns` de chaque `Raster` multipliées par ses `rows` | 262 144 |
| Les lignes au-dessus du prompt, empilées | Les éléments, les cellules `Raster` et les octets `Image` s'additionnent sur l'ensemble des lignes, par rapport aux limites d'un arbre |
| Octets PNG ou RGBA de l'ensemble des `Image` d'un arbre | 2 Mio |
| `$.store` | 4 Mio de JSON au total |
| `$.session.messages()` | Les 4 096 entrées les plus récentes |
| Redessins `$.ui.invalidate('ui.render')` | Limités à 10 par seconde, ou 30 dans le terminal pour le volet visible, le bandeau déployé et la ligne d'indication sous le prompt. Les appels plus rapprochés sont regroupés. |
| `$.ui.toast` | Affiché pendant 4 secondes sauf si vous passez `{ timeoutMs }`. Dans le [moteur de rendu classique](https://code.claude.com/docs/fr/fullscreen.md#enable-fullscreen-rendering), un toast plus récent d'un mod peut [prendre la place de son toast plus ancien](https://code.claude.com/docs/fr/plugins/mods/troubleshoot.md#a-toast-doesn’t-appear) en cours d'affichage ou en attente d'affichage. |
| Un volet ouvert sans que l'utilisateur l'ait demandé | Placé à partir de 144 colonnes de terminal, 110 une fois que l'utilisateur l'a ouvert une fois |
| Lignes issues de `$.ui.place` qu'un même mod possède dans une conversation à un instant donné | 500. À la limite, un appel avec un nouvel `id` se résout en `{ isPlaced: false, reason: 'a plugin holds at most 500 placed rows' }`. |
| Profondeur d'imbrication des arguments d'un appel à l'API des mods | 28 000 niveaux. Au-delà, l'appel est rejeté avec un message se terminant par `nesting deeper than 28000 levels is not supported`. Nécessite Claude Code v2.1.299 ou une version ultérieure. |
| Profondeur d'imbrication d'un événement modifié passé à `next`, en dehors des [hooks générateurs asynchrones](#events) tels qu'un hook sur `turn.step` | 28 000 niveaux. Au-delà, `next` est rejeté avec un message se terminant par `nesting deeper than 28000 levels is not supported`. Nécessite Claude Code v2.1.299 ou une version ultérieure. |
| Profondeur d'imbrication de la valeur de retour d'un hook, en dehors de `ui.render`, `ui.resolve` et des hooks générateurs asynchrones | 28 000 niveaux. Au-delà, le résultat du hook est refusé, et [l'avis qui le signale](https://code.claude.com/docs/fr/plugins/mods/troubleshoot.md#find-out-why-a-mod-does-nothing) inclut `nesting deeper than 28000 levels is not supported`. Nécessite Claude Code v2.1.299 ou une version ultérieure. |
| Portées, telles que les fonctions, les blocs et les boucles, imbriquées les unes dans les autres dans un même fichier d'un module de hooks | 2 000 |
| Noms de commandes, d'outils, de types de sous-agents et de volets, l'`id` d'une ligne placée et la `scene` d'un arrière-plan | Lettres, chiffres, `_` et `-`, jusqu'à 64 caractères |
| Un test `claude plugin test` | 5 secondes sauf si le test définit `timeoutMs` |

## 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 :

| Nom | Emplacement | Effet |
| :- | :- | :- |
| `CLAUDE_CODE_PLUGIN_DIRS` | Environnement, ou `env` dans `~/.claude/settings.json` | Répertoires de plugins à charger comme le fait `--plugin-dir`, pour les applications auxquelles vous ne pouvez pas passer de flag. Chemins absolus séparés par `:`, ou `;` sous Windows. |
| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | Environnement | Détermine si les mods se rechargent à l'enregistrement. Consultez la [référence des variables d'environnement](https://code.claude.com/docs/fr/env-vars.md) pour les valeurs par défaut et les valeurs possibles |
| `prependPlugins`, `appendPlugins` | Paramètres gérés. Paramètres utilisateur uniquement sur une machine sans paramètres gérés ni fichier [`managed-mcp.json`](https://code.claude.com/docs/fr/managed-mcp#deploy-managed-mcp-json), dans une session dont les identifiants ne proviennent pas d'un `/login` Team ou Enterprise. | Listes d'identifiants de plugins, comme `acme-guard@acme-tools`. Les mods de `prependPlugins` s'exécutent avant tout mod installé par un utilisateur, et ceux de `appendPlugins` après, dans l'ordre indiqué. Consultez [L'ordre d'exécution des mods](https://code.claude.com/docs/fr/plugins/mods/events.md#the-order-mods-run-in). |
| `allowManagedModsOnly` | Paramètres gérés, en tant qu'[option du garde-fou intégré](https://code.claude.com/docs/fr/plugins/mods/admin.md#set-options-on-the-built-in-guard) | Seuls les mods qui [relèvent de votre organisation](https://code.claude.com/docs/fr/plugins/mods/admin.md#install-your-organizations-mods) et les mods intégrés à Claude Code exécutent leurs hooks. Les hooks de paramètres des utilisateurs continuent de s'exécuter. |
| `allowModsToOverrideDenyRules` | Paramètres gérés, en tant qu'[option du garde-fou intégré](https://code.claude.com/docs/fr/plugins/mods/admin.md#set-options-on-the-built-in-guard) | Permet à un mod installé par un utilisateur d'approuver un appel d'outil en passant outre la plupart des [résultats qui restent en place par défaut](https://code.claude.com/docs/fr/permissions.md#precedence-among-rules-hooks-and-mods), y compris une règle `deny` |
| `allowManagedHooksOnly` | Paramètres gérés | Bloque les hooks et les mods installés qui n'appartiennent pas à votre organisation. Consultez [ce qui continue de s'exécuter](https://code.claude.com/docs/fr/settings-reference.md#what-runs-under-allowmanagedhooksonly). |
| `disableAllHooks` | Tout fichier de paramètres | Dans les paramètres gérés, aucun mod ni hook provenant d'un plugin installé ne s'exécute. Dans vos propres paramètres, ce que gère votre organisation continue de s'exécuter. Consultez [`disableAllHooks`](https://code.claude.com/docs/fr/settings-reference#disableallhooks). |
| `disableSideloadFlags` | Paramètres gérés | Rejette `--plugin-dir` et `--plugin-url` au démarrage |
| `pluginConfigs` | Paramètres utilisateur ou gérés | Contient les valeurs `userConfig` d'un mod, indexées par l'identifiant du plugin, comme `acme-guard@acme-tools`, ou par son nom suivi de `@inline`, comme `first-mod@inline`, pour un mod chargé avec `--plugin-dir` |

`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. [Là où il se charge](https://code.claude.com/docs/fr/plugins/mods/admin.md#know-what-happens-by-default), il s'exécute avant tout mod installé par une personne. 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](https://github.com/anthropics/claude-code/tree/main/mods/sec-default).

## 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.

| Commande | Effet |
| :- | :- |
| [`/plugin`](https://code.claude.com/docs/fr/plugins/mods/overview#see-which-mods-a-session-loaded) | Affiche une ligne telle que `1 mod active · first-mod` sous ses onglets lorsqu'un mod non intégré a été chargé |
| [`claude plugin validate <directory>`](https://code.claude.com/docs/fr/plugins/mods/create#check-what-claude-code-reads-from-your-mod) | Lit le manifeste et le module de hooks d'un plugin et signale les erreurs, les événements qu'il gère et les appels à l'API des mods qu'il effectue. `--strict` traite les avertissements comme des erreurs et `--json` affiche un rapport lisible par une machine. |
| [`claude plugin test [directory]`](https://code.claude.com/docs/fr/plugins/mods/test#write-a-test) | Exécute chaque fichier du répertoire, ou du répertoire courant si vous n'en indiquez aucun, dont le nom se termine par `.test.ts` ou `.test.tsx`. Se termine avec le statut 1 lorsqu'un test échoue. |
| [`claude --plugin-dir <directory>`](https://code.claude.com/docs/fr/plugins/mods/create#write-a-mod-yourself) | Charge un répertoire de plugin pour une session et recharge son module de hooks lorsque vous enregistrez. Répétez le flag pour en charger plusieurs. |
| `/reload-plugins` | Recharge les plugins lorsque vous l'exécutez |
