Passer au contenu principal
Afficher en Markdown

Hooks

Les Hooks exécutent des commandes shell ou des requêtes d'agent automatiquement lorsque des événements précis se produisent dans votre session - l'agent modifie un fichier, invoque un outil ou termine une tâche. Vous définissez le déclencheur et l'action; Kiro se charge de l'exécution.

CapacitéIDECLIWebMobile
Hooks basés sur des événements✓✓✓—
Actions de commande shell✓✓✓—
Actions de requête d'agent✓✓✓—
Créer des Hooks en le demandant à l'agent dans le clavardage✓✓✓—

Ce que vous pouvez faire avec les Hooks

  • Appliquer des normes - exécutez des linters, des formateurs ou des vérifications de type automatiquement après les modifications de fichiers par l'agent
  • Encadrer les opérations dangereuses - bloquez l'exécution d'un outil à moins que les conditions préalables ne soient respectées (PreToolUse)
  • Générer des fichiers complémentaires - créez automatiquement des tests, de la documentation ou des traductions lorsque de nouveaux fichiers source apparaissent
  • Valider avant le commit - vérifiez la qualité du code avant que l'agent ne finalise les modifications
  • Injecter du contexte - fournissez à l'agent des instructions supplémentaires selon ce qu'il fait

Exemple rapide

Un Hook PostFileSave qui exécute ESLint chaque fois que l'agent enregistre ou modifie un fichier TypeScript :

json
{ "version": "v1", "hooks": [{ "name": "Lint on save", "trigger": "PostFileSave", "matcher": "\\.(ts|tsx)$", "action": { "type": "command", "command": "npx eslint --fix" } }] }

Ce fichier se trouve à .kiro/hooks/lint-on-save.json et s'active automatiquement - aucune requête manuelle n'est nécessaire. Le Hook reçoit le chemin du fichier enregistré et le contexte de la session via STDIN. Consultez Actions de Hook pour en savoir plus sur la façon dont les commandes reçoivent les données d'événement.

Comment fonctionnent les Hooks

Les configurations de Hooks de projet sont des fichiers JSON stockés dans .kiro/hooks/. Kiro CLI V3 charge aussi les Hooks globaux depuis ~/.kiro/hooks/, de sorte qu'un même Hook peut s'exécuter dans chaque espace de travail. Les Hooks globaux et ceux de l'espace de travail s'exécutent côte à côte. Chaque fichier définit un ou plusieurs Hooks avec un événement déclencheur, un motif de correspondance facultatif et une action.

Lorsque l'événement déclencheur se produit, Kiro vérifie le motif de correspondance. S'il correspond (ou si aucun motif n'est spécifié), l'action s'exécute :

  • Les actions de commande exécutent une commande shell à la racine de votre projet. La commande reçoit le contexte de la session en JSON sur STDIN.
  • Les actions d'agent injectent une requête dans la conversation en cours, orientant le comportement de l'agent.

Choisir un déclencheur

Utilisez Types de Hooks pour choisir le déclencheur adapté à votre tâche. C'est la liste de référence des déclencheurs; elle documente la disponibilité par surface et le comportement propre à chaque déclencheur.

Schéma de fichier de Hook

Chaque fichier de Hook est un fichier JSON autonome situé à .kiro/hooks/<id>.json. Le schéma complet :

json
{ "version": "v1", "hooks": [ { "name": "example-hook", "trigger": "PostFileSave", "matcher": "\\.(ts|tsx)$", "action": { "type": "command", "command": "npx eslint --fix" } } ] }

Référence des champs

ChampRequisDescription
versionOuiVersion du schéma - actuellement "v1"
hooksOuiTableau de définitions de Hook
hooks[].nameOuiIdentifiant lisible par un humain pour le Hook
hooks[].descriptionNonDocumentation seulement
hooks[].triggerOuiÉvénement qui déclenche le Hook (PascalCase - voir Types de Hooks)
hooks[].matcherNonFiltre les événements qui déclenchent ce Hook. Pour PreToolUse/PostToolUse, un sélecteur d'outil (ID d'outil, balise de catégorie, @mcp, @<server> ou caractère générique) ou une expression régulière appliquée à l'ID de l'outil; consultez Types de Hooks. Pour les événements de fichier, une expression régulière appliquée au chemin du fichier. Par défaut, le motif correspond à tous les événements.
hooks[].action.typeOui"command" (commande shell) ou "agent" (injecter une requête)
hooks[].action.commandCond.Commande shell à exécuter (requis lorsque type est "command")
hooks[].action.promptCond.Texte de la requête à injecter (requis lorsque type est "agent")
hooks[].timeoutNonDélai d'expiration en secondes pour les actions de commande (par défaut : 60). 0 désactive le délai d'expiration. Ignoré pour les actions d'agent.
hooks[].enabledNonRéglez à false pour ignorer le Hook sans le supprimer (par défaut : true)
hooks[].confirmNonDemander une confirmation avant qu'un Hook de commande Stop ne s'exécute. Voir Requêtes de confirmation.

Requêtes de confirmation

Un Hook de commande sur le déclencheur Stop peut demander une confirmation avant de s'exécuter. Ajoutez un bloc confirm avec la question à poser et les options à présenter :

json
{ "version": "v1", "hooks": [ { "name": "Submit session results", "trigger": "Stop", "action": { "type": "command", "command": "./submit.sh" }, "confirm": { "question": "Submit this session's results?", "options": [ { "id": "submit", "label": "Yes, submit", "run": true }, { "id": "dismiss", "label": "Not this time", "run": false } ] } } ] }

Chaque option possède un id, une propriété label affichée sur le bouton et un indicateur run qui détermine si la commande du Hook s'exécute lorsque cette option est choisie.

Options de confirmation dynamiques avec confirmCommand

Pour décider au moment de l'exécution s'il faut demander une confirmation et quoi demander, ajoutez un confirmCommand facultatif au bloc confirm. La commande s'exécute avant l'affichage de la requête, et sa sortie standard contrôle la requête sous forme de JSON :

  • { "skip": true } supprime la requête et ignore le Hook pour ce tour
  • { "question": "...", "options": [...] } remplace la question statique et les options
json
{ "confirm": { "question": "Submit this session's results?", "confirmCommand": "./confirm-options.sh", "options": [ { "id": "submit", "label": "Yes, submit", "run": true }, { "id": "dismiss", "label": "Not this time", "run": false } ] } }

Si confirmCommand se termine avec un code non nul, expire ou affiche un JSON invalide, la question et les options statiques sont utilisées comme solution de repli. Cela le rend utile pour les requêtes qui ne devraient apparaître que sous certaines conditions - par exemple, une option « ne plus demander pour cette session » qui écrit un fichier marqueur et renvoie { "skip": true } lors des tours suivants.

Nom et emplacement des fichiers

  • Emplacement dans l'espace de travail : .kiro/hooks/ à la racine de votre projet
  • Emplacement global (CLI V3) : ~/.kiro/hooks/ pour les Hooks qui s'exécutent dans chaque espace de travail
  • Nommage : Tout nom de fichier .json fonctionne - utilisez des noms descriptifs en kebab-case (p. ex. lint-on-save.json, guard-writes.json)
  • Plusieurs Hooks par fichier : Un seul fichier peut définir plusieurs Hooks dans le tableau hooks
  • Activation : Les Hooks s'activent automatiquement au démarrage d'une session - aucun enregistrement manuel n'est nécessaire

Configuration des Hooks

Cliquez sur le bouton + dans la section Agent Hooks du panneau Kiro, puis sélectionnez Ask Kiro to create a hook. Décrivez ce que vous voulez en langage naturel - par exemple, « exécuter les tests après chaque enregistrement de fichier » - et Kiro génère la configuration du Hook au fil de la conversation.

Le Hook résultant est enregistré comme fichier JSON dans .kiro/hooks/.

Versions précédentes

Le format .kiro/hooks/*.json a été introduit dans IDE 1.0 et CLI V3. Si vous effectuez une mise à niveau à partir d'une version antérieure :

  • Depuis IDE 0.x - Les Hooks sont passés du format précédent à des fichiers JSON autonomes avec des noms de déclencheur en PascalCase. Consultez Quoi de neuf dans IDE 1.0 : Hooks pour la correspondance des déclencheurs.
  • Depuis CLI 2.x - Exécutez /upgrade-agent pour convertir les Hooks en forme d'objet en un tableau à la portée du profil. Déplacez les définitions qui doivent s'exécuter indépendamment d'un profil ou sur plusieurs surfaces dans des fichiers .kiro/hooks/*.json autonomes. Consultez Migration des Hooks CLI V3 pour les deux emplacements actuels et la correspondance des déclencheurs.

Prochaines étapes

Page mise à jour : 12 novembre 2026