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.

• 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

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

{
  "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.

Les configurations de Hook sont des fichiers JSON stockés dans .kiro/hooks/. 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.

Consultez Déclencheurs de Hook pour des descriptions détaillées, des motifs de correspondance et des cas d'utilisation pour chaque type de déclencheur.

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

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

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 :

{
  "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 a un id, une 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.

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

{
  "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.

• Emplacement : .kiro/hooks/ à la racine de votre projet
• 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

Le format .kiro/hooks/*.json a été introduit dans IDE 1.0 et CLI 3.0. 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 - Les Hooks sont passés de champs intégrés dans la configuration de l'agent à des fichiers autonomes. Exécutez kiro-cli agent migrate pour effectuer la conversion automatique, ou consultez Migration des Hooks CLI 3.0 pour la correspondance manuelle.

• Déclencheurs de Hook - Types de déclencheurs et leurs cas d'utilisation
• Actions de Hook - Détails sur les actions de commande et d'agent
• Gestion - Organisez, modifiez et maintenez les Hooks
• Bonnes pratiques - Modèles pour une conception efficace des Hooks
• Exemples - Modèles que vous pouvez utiliser
• Dépannage - Problèmes courants et solutions