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.
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.
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é.
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.
Un Hook comporte trois parties :
- Déclencheur — quand Crew doit-il l'exécuter?
- 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.
- Action — exécuter une commande shell, ou charger les Skills sélectionnés dans le contexte.
| Déclencheur | Se déclenche quand |
|---|---|
AgentSpawn | Une nouvelle session d'agent commence |
UserPromptSubmit | Un message est envoyé à l'agent |
PreToolUse | Avant le démarrage d'un outil |
PostToolUse | Après la fin d'un outil |
Stop | Un tour de l'agent se termine |
| Type d'événement | Sujet de la correspondance | Modes |
|---|---|---|
PreToolUse, PostToolUse | Nom de l'outil | Glob : nom exact, prefix*, *suffix, *text* ou * |
AgentSpawn, UserPromptSubmit, Stop | Texte du message ou de la réponse finale | Glob, 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.
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éclencheur | Moment prévu | État de la ligne |
|---|---|---|
PreTaskExecution | Avant le début d'une tâche de Spec | not fired yet |
PostTaskExecution | Après la fin d'une tâche de Spec | not fired yet |
FileCreated | Après la création d'un fichier par Kiro Agent | never fires |
FileEdited | Après l'enregistrement d'un fichier par Kiro Agent | never fires |
FileDeleted | Après la suppression d'un fichier par Kiro Agent | never fires |
UserTriggered | Lorsque vous exécutez le Hook à la main | never fires |
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 :
0autorisePreToolUse. PourAgentSpawnetUserPromptSubmit, la sortie standard entre dans le contexte du modèle.2refuse un appelPreToolUseet 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.
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.
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.
Utilisez UserPromptSubmit, choisissez contient et définissez une correspondance comme deploy|release. Sélectionnez les Skills à charger et laissez la commande vide.
- Ouvrez Agent Capabilities → Hooks.
- Sélectionnez New Hook, nommez-le et choisissez un événement.
- Pour un événement d'outil, ajoutez une correspondance glob. Pour un événement de message, choisissez glob, expression régulière ou contient.
- Ajoutez une commande, ou laissez-la vide et sélectionnez des Skills pour
AgentSpawnouUserPromptSubmit. - 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.
- 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.
Hooks