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 - un fichier est enregistré, un outil est invoqué ou une tâche est terminée. 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 à l'enregistrement d'un fichier
• Encadrer les opérations dangereuses - bloquez l'exécution d'un outil à moins que des conditions préalables ne soient respectées (PreToolUse)
• Générer des fichiers compagnons - créez automatiquement des tests, de la documentation ou des traductions lorsque de nouveaux fichiers source apparaissent
• Valider avant un 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 vous enregistrez 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 session par STDIN. Consultez Hook Actions pour plus de détails sur la façon dont les commandes reçoivent les données d'événement.

Les configurations de Hooks 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 session en JSON via STDIN.
• Les actions d'agent injectent une requête dans la conversation en cours, orientant le comportement de l'agent.

Consultez Hook Triggers 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, un label affiché sur le bouton, et un indicateur run qui contrôle 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 poser une question et laquelle, 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 en JSON :

• { "skip": true } supprime la requête et ignore le Hook pour ce tour
• { "question": "...", "options": [...] } remplace la question et les options statiques

{
  "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 question et options sont utilisées comme solution de repli. Cela est 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éclencheurs en PascalCase. Consultez What's new in 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 une conversion automatique, ou consultez CLI 3.0 Hooks migration pour la correspondance manuelle.

• Hook Triggers - Types de déclencheurs et leurs cas d'utilisation
• Hook Actions - Détails des actions de commande et d'agent
• Management - Organisez, modifiez et entretenez les Hooks
• Best Practices - Modèles pour une conception efficace des Hooks
• Examples - Modèles que vous pouvez utiliser
• Troubleshooting - Problèmes courants et solutions