Passer au contenu principal
Afficher en Markdown

Hooks

Les Hooks vous permettent d'automatiser les événements pris en charge dans Crew. Un Hook peut exécuter un script, injecter du contexte ou filtrer un appel d'outil lorsqu'un événement de clavardage de la passerelle se déclenche. Vous pouvez aussi enregistrer les noms d'événements de tâche, de fichier et manuels de Kiro Agent pour des essais à la demande.

Gestion des Hooks

À partir du tableau de bord

Ouvrez Agent Capabilities → Hooks. Vous pouvez consulter, créer, modifier et supprimer des Hooks depuis le navigateur. Chaque Hook affiche son déclencheur, son action et son modèle de correspondance facultatif.

À partir du système de fichiers

Les Hooks sont stockés dans ~/.kiro/crew/hooks.json. Les Hooks appartenant à un fournisseur apparaissent en lecture seule dans le tableau de bord et restent dans la configuration de leur fournisseur.

Dans Kiro Crew 0.12.0 ou une version ultérieure, les scripts de Hook exécutables de votre propre dossier ~/.kiro/hooks s'exécutent aussi lors des tours Kiro Agent, comme ils le font sur le harnais Kiro CLI. Un script que vous avez désactivé dans la page Hooks reste désactivé.

Sur les canaux de messagerie

Dans Kiro Crew 0.12.0 ou une version ultérieure, les Hooks UserPromptSubmit et Stop que vous avez enregistrés dans la page Hooks s'exécutent aussi lors d'un tour sur un canal de messagerie. Les Hooks AgentSpawn, PreToolUse et PostToolUse ne s'y exécutent pas. La sortie standard d'un Hook terminé avec le code 0 et la ligne BLOCKED: d'un Hook terminé avec le code 2 parviennent à la requête comme contexte de Hook; un Hook Stop ne peut pas y demander un autre tour. Les hooks propres à un agent restent avec le harnais qui les exécute.

Structure d'un Hook

Un Hook comporte trois parties :

  1. Déclencheur — quand Crew doit-il l'exécuter?
  2. Correspondance (facultative) — filtre les événements qui exécutent le Hook. Les événements d'outil correspondent au nom de l'outil, et les événements de message correspondent au texte du message. Consultez Faire correspondre les événements automatiques.
  3. Action — exécuter une commande shell, ou charger les Skills sélectionnés dans le contexte.

Déclencheurs

Événements qui se déclenchent automatiquement

DéclencheurSe déclenche quand
AgentSpawnUne nouvelle session d'agent commence
UserPromptSubmitUn message est envoyé à l'agent
PreToolUseAvant le démarrage d'un outil
PostToolUseAprès la fin d'un outil
StopUn tour de l'agent se termine

Faire correspondre les événements automatiques

Type d'événementSujet de la correspondanceModes
PreToolUse, PostToolUseNom de l'outilGlob : nom exact, prefix*, *suffix, *text* ou *
AgentSpawn, UserPromptSubmit, StopTexte du message ou de la réponse finaleGlob, expression régulière insensible à la casse, ou termes « contient » séparés par des barres verticales

Les six événements KAS ci-dessous n'acceptent aucune correspondance.

Événements Kiro Agent enregistrés pour les essais

L'éditeur de Hooks peut enregistrer six noms d'événements supplémentaires provenant du backend KAS. Aucun ne se déclenche automatiquement dans Crew 0.8. Tester est la seule façon d'exécuter ces Hooks, et chacun est enregistré désactivé.

DéclencheurMoment prévuÉtat de la ligne
PreTaskExecutionAvant le début d'une tâche de Specnot fired yet
PostTaskExecutionAprès la fin d'une tâche de Specnot fired yet
FileCreatedAprès la création d'un fichier par Kiro Agentnever fires
FileEditedAprès l'enregistrement d'un fichier par Kiro Agentnever fires
FileDeletedAprès la suppression d'un fichier par Kiro Agentnever fires
UserTriggeredLorsque vous exécutez le Hook à la mainnever fires

Actions

Action de commande

Une action de commande exécute une commande shell. Elle reçoit KIROCREW_HOOK_EVENT et KIROCREW_HOOK_CONTEXT dans son environnement, ainsi que le JSON de l'événement sur l'entrée standard. Les Hooks utilisent /bin/sh sur POSIX et %ComSpec% sur Windows; écrivez donc des commandes propres à la plateforme au besoin.

Un Hook n'hérite pas de l'environnement complet de la passerelle. Il reçoit PATH, les répertoires personnel et temporaire, les paramètres régionaux, la confiance TLS et KIROCREW_HOME. Définissez des valeurs comme AWS_PROFILE ou VIRTUAL_ENV dans la commande, ou utilisez des chemins absolus.

Les codes de sortie ont de l'importance :

  • 0 autorise PreToolUse. Pour AgentSpawn et UserPromptSubmit, la sortie standard entre dans le contexte du modèle.
  • 2 refuse un appel PreToolUse et envoie la sortie d'erreur au modèle.
  • Toute autre sortie, expiration ou plantage bloque aussi PreToolUse. Le filtre se ferme en cas d'échec.
  • Pour tout autre événement, une sortie non nulle consigne un avertissement et le tour continue.

Un Hook Stop peut demander un autre tour. Terminez avec le code 0 et la sortie standard {"decision": "block", "reason": "<text>"} pour injecter la raison et faire continuer l'agent. Toute autre sortie standard est ignorée.

Un Hook PreToolUse ne peut bloquer que lorsque la passerelle contrôle l'approbation. Si Kiro CLI a déjà approuvé l'appel, le Hook signale l'événement mais ne peut pas l'arrêter.

Action Skills

Laissez la commande vide et sélectionnez des Skills pour les charger dans le contexte sans démarrer de sous-processus. Cela fonctionne uniquement avec AgentSpawn ou UserPromptSubmit. Les autres combinaisons de déclencheur et d'action sont refusées plutôt qu'enregistrées sans effet.

Modèles courants

Filtrer les appels d'outils avec une commande

Utilisez PreToolUse avec la correspondance * pour faire passer chaque appel d'outil approuvé par la passerelle par un seul script de politique. Terminez avec 0 pour autoriser l'appel, ou avec 2 et un message utile sur la sortie d'erreur pour le refuser.

Charger des Skills pour les requêtes correspondantes

Utilisez UserPromptSubmit, choisissez contient et définissez une correspondance comme deploy|release. Sélectionnez les Skills à charger et laissez la commande vide.

Créer un Hook à partir du tableau de bord

  1. Ouvrez Agent Capabilities → Hooks.
  2. Sélectionnez New Hook, nommez-le et choisissez un événement.
  3. Pour un événement d'outil, ajoutez une correspondance glob. Pour un événement de message, choisissez glob, expression régulière ou contient.
  4. Ajoutez une commande, ou laissez-la vide et sélectionnez des Skills pour AgentSpawn ou UserPromptSubmit.
  5. Enregistrez le Hook. Les Hooks d'événements automatiques sont activés dès l'enregistrement; les Hooks des six événements KAS sont enregistrés désactivés.
  6. Utilisez Tester pour exécuter le Hook enregistré et inspecter son code de sortie, sa sortie standard et sa sortie d'erreur.

Un nouveau Hook automatique peut se déclencher avant que vous l'ayez testé. Désactivez d'abord un Hook PreToolUse lorsque sa commande n'est pas prête à filtrer des appels réels. Aucun redémarrage de la passerelle n'est nécessaire.

Page mise à jour : 11 novembre 2026