Les Agent Hooks prennent en charge divers types de déclencheurs, chacun étant conçu pour des scénarios d'automatisation précis. Comprendre ces types vous aide à choisir la bonne approche selon les besoins de votre flux de travail.
Cette page décrit les définitions de Hooks autonomes stockées dans .kiro/hooks/*.json. Les Hooks de profil intégrés ont des formes actuelle et héritée distinctes; consultez la référence de configuration d'agent.
Les déclencheurs de fichier et de tâche sont disponibles dans l'IDE et la CLI V3. Les sessions Kiro Web exécutent les déclencheurs Prompt Submit, Agent Stop, Session Start, Pre Tool Use et Post Tool Use. Le tableau ci-dessous montre ce qui est pris en charge, et où.
| Déclencheur | IDE | CLI | Web | Mobile |
|---|---|---|---|---|
| Prompt Submit | ✓ | ✓ | ✓ | — |
| Agent Stop | ✓ | ✓ | ✓ | — |
| Session Start | ✓ | V3 | ✓ | — |
| Agent Spawn | — | 2.x / alias V3 | — | — |
| Session End | — | V3 | — | — |
| Pre Compaction | ✓ | V3 (3.1.0+) | — | — |
| Post Compaction | ✓ | V3 (3.1.0+) | — | — |
| Pre Tool Use | ✓ | ✓ | ✓ | — |
| Permission Request | ✓ | V3 (3.4.0+) | — | — |
| Post Tool Use | ✓ | ✓ | ✓ | — |
| File Create | ✓ | V3 | — | — |
| File Save | ✓ | V3 | — | — |
| File Delete | ✓ | V3 | — | — |
| Pre Task Execution | ✓ | V3 | — | — |
| Post Task Execution | ✓ | V3 | — | — |
| Manual | — | Répertorié dans V3 | Peut être créé | — |
| Legacy Manual Hook | Legacy only | — | — | — |
Se déclenche lorsque l'utilisateur soumet une requête.
Lorsque vous utilisez l'action de commande shell, la requête de l'utilisateur peut être consultée via la variable d'environnement USER_PROMPT.
Cas d'utilisation :
- Fournir un contexte supplémentaire à l'agent en fonction de la requête
- Bloquer certaines requêtes selon leur contenu (IDE seulement; les Hooks Prompt Submit de la CLI ne peuvent pas bloquer)
- Consigner toutes les requêtes de l'utilisateur dans un emplacement central
Se déclenche lorsque l'agent a terminé son tour et fini de répondre à l'utilisateur.
Ceci est utile pour exécuter des tâches de post-traitement comme la compilation de code, les tests, le formatage ou le nettoyage après la réponse de l'agent.
Cas d'utilisation :
- Compiler le code et signaler tout échec à l'agent
- Formater ou réviser tout code généré par l'agent
- Réviser les modifications apportées par l'agent et fournir des instructions supplémentaires
Se déclenche lorsqu'une nouvelle session de clavardage commence dans l'IDE ou la CLI V3.
Cas d'utilisation :
- Injecter des instructions propres à l'espace de travail dans le contexte de l'agent
- Exécuter des vérifications d'environnement (vérifier les dépendances, valider les identifiants)
- Charger la configuration propre au projet au début de la session
La CLI 2.x utilisait agentSpawn lorsque l'agent était activé pour la première fois. La CLI V3 utilise SessionStart comme déclencheur canonique, mais accepte AgentSpawn et agentSpawn à des fins de compatibilité. L'événement ne fournit aucun contexte d'outil.
{ "hook_event_name": "agentSpawn", "cwd": "/current/working/directory", "session_id": "abc123-def456-789" }
Comportement du code de sortie :
- 0 : Le Hook a réussi, la sortie STDOUT est ajoutée au contexte de l'agent
- Autre : Afficher l'avertissement STDERR à l'utilisateur
Cas d'utilisation :
- Configurer le contexte d'environnement au début d'une session
- Charger la configuration propre au projet
- Initialiser des systèmes de journalisation ou d'audit
Le déclencheur SessionEnd se déclenche lorsqu'une session de la CLI V3 est démantelée.
Se déclenche avant que Kiro compacte une conversation. Dans Kiro IDE, la compaction est automatique, de sorte que le Hook s'exécute lorsque la session approche de la limite de contexte du modèle; consultez Compaction. Ce déclencheur n'accepte pas de matcher.
Dans Kiro IDE 1.4.121 ou une version ultérieure, choisissez Pre Compaction dans le groupe Compaction Hooks de la liste des déclencheurs de l'éditeur de Hooks.
Dans Kiro CLI 3.1.0 ou une version ultérieure, le déclencheur PreCompact se déclenche avant qu'une session de la CLI V3 compacte sa conversation. La compaction s'exécute lorsque vous exécutez /compact, lorsque le résumé automatique démarre, lorsque Kiro se rétablit après un dépassement de contexte et lorsque Kiro confie la session à un autre modèle.
Comportement du code de sortie :
- 0 : La compaction se poursuit. Dans l'IDE, Kiro fournit la sortie standard de la commande au générateur de résumé comme indication. Dans la CLI V3, la sortie STDOUT est ajoutée au contexte de l'agent, jusqu'à 3 000 caractères.
- 2 : Annuler la compaction. Dans l'IDE, Kiro signale STDERR comme raison, et le tour se poursuit sans compaction, sauf si le contexte est presque plein. Dans la CLI V3, la conversation reste telle quelle.
Cas d'utilisation :
- Enregistrer un instantané du travail en cours avant que l'historique plus ancien soit résumé
- Refuser la compaction tant qu'une tâche que vous suivez en dehors de Kiro est encore ouverte
Se déclenche après que Kiro a compacté une conversation et que le résumé a remplacé l'historique plus ancien. La sortie du Hook est ajoutée à la conversation, de sorte que l'agent conserve les détails que le résumé a laissés de côté. Ce déclencheur n'accepte pas de matcher.
Dans Kiro IDE 1.4.121 ou une version ultérieure, choisissez Post Compaction dans le groupe Compaction Hooks de la liste des déclencheurs de l'éditeur de Hooks.
Dans Kiro CLI 3.1.0 ou une version ultérieure, le déclencheur PostCompact se déclenche après qu'une session de la CLI V3 a compacté sa conversation. Le JSON de l'événement sur STDIN comprend summary, soit jusqu'à 3 000 caractères du texte du résumé, et summary_path, soit le fichier contenant le résumé complet. Le Hook ne peut ni annuler la compaction ni modifier le résumé.
Cas d'utilisation :
- Rétablir les indications propres à la tâche après la compaction
- Archiver chaque résumé pour révision
- Consigner le moment où une longue session a été compactée et ce que le résumé a conservé
Se déclenche lorsque l'agent est sur le point d'invoquer un outil. Peut valider et bloquer l'utilisation de l'outil.
Dans le champ Tool name pattern, fournissez un ID d'outil exact, une catégorie intégrée, un sélecteur de source ou une expression régulière. Vous pouvez spécifier plusieurs entrées. Les catégories intégrées suivantes sont prises en charge :
- read - tous les outils intégrés de lecture de fichiers
- write - tous les outils intégrés d'écriture de fichiers
- shell - tous les outils intégrés liés aux commandes shell
- web - tous les outils intégrés Web
- spec - tous les outils intégrés de Specs
Vous pouvez aussi utiliser des sélecteurs de source :
- @mcp - tous les outils MCP
- @powers - tous les outils Powers
- @builtin - tous les outils intégrés
@<server>- tous les outils d'un serveur MCP, par exemple@postgres@<server>/<tool>- un outil d'un serveur MCP, par exemple@postgres/query
L'éditeur vérifie chaque entrée comme une expression régulière comparée aux ID d'outils. Un nom simple comme read peut donc correspondre à tout ID d'outil contenant ce texte. Laissez le champ vide pour cibler tous les outils.
Les fichiers JSON de Hooks acceptent aussi des motifs à caractères génériques. Utilisez * pour correspondre à un nombre quelconque de caractères et ? pour correspondre à un seul caractère. Modifiez directement le fichier JSON du Hook pour utiliser ces motifs, car l'éditeur de l'IDE les rejette comme expressions régulières non valides.
Vous pouvez demander à Kiro les noms des outils disponibles.
Un Hook Run Command peut retourner hookSpecificOutput.updatedInput pour remplacer l'objet d'entrée complet de l'outil. Copiez chaque argument, modifiez les valeurs voulues et retournez l'objet complet. Kiro valide le remplacement et conserve les vérifications d'autorisation normales. Si Kiro vous demande d'approuver l'appel d'outil, il affiche les arguments finaux.
Cas d'utilisation :
- Bloquer certaines invocations d'outils
- Valider les entrées de l'outil avant l'exécution
- Réécrire les entrées d'un appel d'outil avant son exécution (Kiro IDE 1.4.236 ou une version ultérieure, ou Kiro CLI 3.4.0 ou une version ultérieure)
- Fournir des instructions supplémentaires à l'agent avant qu'il invoque un outil
Dans Kiro IDE 1.4.236 ou une version ultérieure et Kiro CLI 3.4.0 ou une version ultérieure, le déclencheur PermissionRequest s'exécute après que Kiro a évalué sa politique d'autorisation et immédiatement avant qu'un appel d'outil ne vous affiche une invite. Un script peut répondre aux invites courantes dans une session que personne ne surveille. Le déclencheur ne s'exécute pas lorsque la politique autorise ou refuse déjà l'appel, ni lorsqu'un Hook Pre Tool Use l'a déjà autorisé. Kiro CLI 2.x n'a aucun équivalent. L'alias en camelCase permissionRequest est aussi accepté.
Dans l'éditeur de Hooks, sélectionnez Permission Request sous Tool Hooks, puis choisissez Run Command.
Seules les actions de commande s'exécutent sur ce déclencheur. Le champ matcher fonctionne comme pour Pre Tool Use.
Événement de Hook :
{ "hook_event_name": "PermissionRequest", "cwd": "/current/working/directory", "session_id": "abc123-def456-789", "tool_name": "read_file", "tool_input": { "path": "/home/user/notes/todo.md" }, "permission": { "capability": "fs_read", "paths": ["/home/user/notes/todo.md"] } }
tool_input est l'entrée effective, après toute réécriture par Pre Tool Use. L'objet permission contient ceux des champs capability, resource, command et paths qui s'appliquent à l'appel.
Retournez la réponse en JSON sur STDOUT, sous l'une de ces deux formes :
{"hookSpecificOutput": {"decision": {"behavior": "allow"}}}
{"hookSpecificOutput": {"decision": {"behavior": "deny", "message": "Reads outside the workspace need a person."}}}
Comportement du code de sortie :
- 0 avec une décision
allow: L'appel d'outil s'exécute sans invite. - 0 avec une décision
deny: L'appel d'outil est bloqué etmessageest retourné à l'agent. - 2 : Refuser l'appel d'outil.
- 0 sans décision valide, ou Autre : Kiro affiche l'invite comme d'habitude.
decision.behavior accepte uniquement allow et deny. Tout autre hookSpecificOutput, y compris les champs permissionDecision et permissionDecisionReason de Pre Tool Use, ne constitue pas une décision et conserve l'invite. Lorsque plusieurs Hooks s'exécutent, deny ou le code de sortie 2 de n'importe quel Hook l'emporte sur allow.
Pour confirmer que le Hook répond, enregistrez un Hook PermissionRequest avec le matcher ^read_file$ dont la commande affiche la forme allow, puis demandez à Kiro, dans une session V3 sans règle allow pour read_file, de lire un fichier hors de l'espace de travail. La lecture s'exécute sans invite et la carte du Hook affiche la décision.
Cas d'utilisation :
- Approuver les invites courantes à partir d'un script dans des sessions sans surveillance
- Refuser un appel qui échoue à une vérification d'équipe, avec un message sur lequel l'agent peut agir
- Consigner chaque invite qu'une session aurait affichée
Un Hook PermissionRequest peut autoriser ou refuser, à partir d'un script, l'invite habituelle qu'un appel d'outil afficherait autrement, de sorte que l'appel se poursuit dans une session que personne ne surveille. Chaque réponse s'applique à cet appel d'outil seulement. Kiro ne l'enregistre pas comme règle.
Le Hook ne peut ni passer outre un deny de politique, ni modifier l'entrée de l'outil, ni répondre à une invite de chemin protégé, d'organisation ou d'administration, ni à toute autre invite qui requiert une personne. Ces invites continuent de vous attendre.
Pour empêcher un Hook de répondre, désactivez ou supprimez sa définition. Pour limiter les appels auxquels il répond, restreignez son matcher. Les règles de politique allow, ask et deny sont décrites sous Autorisations.
Se déclenche après que l'agent a invoqué un outil, avec accès aux résultats de l'outil.
Pour plus de détails sur le champ Tool name, consultez la section Pre Tool Use ci-dessus.
Cas d'utilisation :
- Consigner les invocations d'outils à des fins d'audit
- Formater ou réviser tout fichier mis à jour après un appel d'outil « write »
- Fournir des instructions supplémentaires à l'agent en plus de la réponse de l'outil
Se déclenche lorsque l'agent crée de nouveaux fichiers correspondant à des motifs précis dans votre espace de travail.
Cas d'utilisation :
- Générer du code passe-partout pour de nouveaux composants
- Ajouter des en-têtes de licence aux nouveaux fichiers
- Configurer des fichiers de test lors de la création de fichiers d'implémentation
Se déclenche lorsque l'agent enregistre ou modifie des fichiers correspondant à des motifs précis.
Cas d'utilisation :
- Exécuter le linting et le formatage
- Mettre à jour les fichiers connexes
- Générer de la documentation
- Exécuter les tests pour les fichiers modifiés
Se déclenche lorsque l'agent supprime des fichiers correspondant à des motifs précis.
Cas d'utilisation :
- Nettoyer les fichiers connexes
- Mettre à jour les références d'importation dans d'autres fichiers
- Maintenir l'intégrité du projet
Se déclenche avant qu'une tâche de Spec commence son exécution.
Cas d'utilisation :
- Exécuter des scripts de configuration ou de préparation de l'environnement avant l'exécution de la tâche
- Valider que les conditions préalables sont respectées avant le début d'une tâche
- Consigner les événements de début de tâche pour le suivi
Se déclenche après qu'une tâche de Spec a terminé son exécution.
Cas d'utilisation :
- Exécuter des tests après la fin d'une tâche pour en vérifier l'exactitude
- Exécuter le linting ou le formatage sur les fichiers modifiés
- Générer de la documentation pour le travail terminé
- Notifier les systèmes externes de l'achèvement de la tâche
La CLI V3 reconnaît et répertorie les définitions de Hooks Manual, mais /hooks n'offre pas d'action pour les invoquer.
Dans Kiro Web, vous pouvez choisir Manual comme déclencheur lorsque vous créez un Hook sous Agent Config > Hooks.
Les Hooks manuels créés dans l'IDE 0.x continuent d'apparaître dans le panneau des Agent Hooks avec une étiquette legacy. Les Hooks manuels legacy activés restent exécutables à l'aide du bouton de lecture à côté du nom du Hook ou de Start Hook dans la vue du Hook.
Les Hooks userTriggered de l'IDE 0.x n'ont pas d'équivalent de déclencheur v1 dans l'IDE, et vous ne pouvez pas créer un nouveau Hook à déclenchement manuel dans l'IDE. Pour un nouveau flux de travail à la demande dans l'IDE, créez un fichier Steering à inclusion manuelle; il s'exécute comme une commande à barre oblique /<filename>.
Pour les outils MCP, les événements de Hook V3 utilisent l'ID d'outil interne nettoyé mcp_<server>_<tool>, et non le nom d'affichage @server/tool :
{ "hook_event_name": "PreToolUse", "cwd": "/current/working/directory", "session_id": "abc123-def456-789", "tool_name": "mcp_postgres_query", "tool_input": { "sql": "SELECT * FROM orders LIMIT 10;" } }
Ceci s'applique aux Hooks Pre Tool Use, Permission Request et Post Tool Use lorsqu'ils ciblent des outils de serveur MCP. Dans le matcher du Hook, utilisez le sélecteur @<server> ou @<server>/<tool>, ou une expression régulière comparée à l'ID interne.
Types de Hooks