Nouveau avec Kiro CLI V3? Cette page couvre la migration des Hooks de CLI 2.x. Pour la référence actuelle du format autonome, consultez Hooks →.
Conseil : Exécutez d'abord
/upgrade-agent. Il convertit les Hooks en forme d'objet en un tableau en ligne à la portée du profil et signale tout déclencheur ou matcher qu'il n'a pas pu convertir en toute sécurité.
CLI V3 prend en charge deux emplacements actuels. Les profils d'agent peuvent conserver des Hooks à la portée du profil dans un tableau hooks plat. Pour l'automatisation qui doit fonctionner indépendamment d'un profil particulier ou à la fois dans l'IDE et la CLI, placez les mêmes définitions de Hooks dans des fichiers autonomes .kiro/hooks/*.json. L'ancienne forme d'objet reste acceptée en entrée à des fins de compatibilité, mais utilisez la forme de tableau actuelle lorsque vous révisez des définitions migrées.
Les Hooks de CLI 2.x utilisaient un objet dont les clés étaient des noms de déclencheurs en camelCase :
{ "hooks": { "agentSpawn": [{ "command": "echo 'starting'" }], "preToolUse": [{ "command": "npm run lint", "matcher": "fs_read" }] } }
/upgrade-agent aplatit l'ancien objet en un tableau dans le profil d'agent. Il donne un nom à chaque Hook et conserve l'alias de déclencheur camelCase compatible :
{ "hooks": [ { "name": "agentSpawn-0", "trigger": "agentSpawn", "action": { "type": "command", "command": "echo 'starting'" }, "timeout": 10 }, { "name": "preToolUse-0", "trigger": "preToolUse", "matcher": "read", "action": { "type": "command", "command": "npm run lint" }, "timeout": 10 } ] }
Le convertisseur préserve les Hooks en forme de tableau. Il abandonne un Hook que V3 ne peut pas représenter et signale un avertissement au lieu d'écrire un profil invalide.
Un fichier autonome .kiro/hooks/*.json enveloppe les mêmes définitions de Hooks dans un document versionné. Utilisez des noms de déclencheurs en PascalCase lorsque vous créez ou révisez un Hook autonome :
{ "version": "v1", "hooks": [ { "name": "lint-before-read", "trigger": "PreToolUse", "matcher": "read", "action": { "type": "command", "command": "npm run lint" }, "timeout": 30, "enabled": true } ] }
Dans l'interface utilisateur du terminal V2, les harnais V2 et V3 peuvent tous deux faire correspondre un nom d'outil exact ou un groupe d'outils partagé. Le tableau utilise les noms V2 de chaque outil :
| Matcher | Outils dans le groupe V2 |
|---|---|
read | fs_read, grep, glob, code, introspect, tool_search |
write | fs_write, code |
shell | execute_bash |
web | web_fetch, web_search |
subagent | use_subagent |
Le harnais V1 traite read, write, shell et subagent comme des alias d'un seul outil. Il ne prend pas en charge le matcher @mcp ni les globs de balises.
/upgrade-agent réécrit les noms connus de CLI 2.x en groupes partagés. Par exemple, fs_read devient read, et execute_cmd devient shell. Il avertit lorsqu'un groupe couvre plus d'outils que l'ancien nom. La réécriture de fs_read correspond aussi à grep, glob, code, introspect et tool_search.
Les matchers en forme de tableau qui sont des ID d'outils V3 valides restent tels qu'ils ont été rédigés. Kiro signale les matchers qu'un seul harnais peut évaluer.
Les Hooks d'outils qui s'exécutent par le harnais V2 reçoivent tool_tags avec tool_name et tool_input. Utilisez les balises lorsqu'un script doit traiter chaque outil d'un groupe de la même façon :
{ "tool_name": "fs_read", "tool_tags": ["read", "@builtin"], "tool_input": {} }
Les harnais V1 et V3 n'envoient pas tool_tags.
Les déclencheurs que CLI V3 prend en charge, ce que chacun fait correspondre et ceux qui peuvent bloquer sont documentés une seule fois dans Types de Hooks.
SessionEnd est un déclencheur propre à V3. Dans Kiro CLI 3.1.0 ou une version ultérieure, PreCompact et PostCompact sont aussi propres à V3 et n'ont aucun équivalent dans CLI 2.x.
Dans Kiro CLI 3.4.0 ou une version ultérieure, PermissionRequest est aussi propre à V3, exécute uniquement des actions de commande et n'a aucun équivalent dans CLI 2.x. Un fichier autonome contenant "trigger": "permissionRequest" se charge sous /hooks dans une session V3 sans erreur de validation.
Les Hooks en forme d'objet de CLI 2.x se rattachent aux déclencheurs partagés comme suit.
| Déclencheur CLI 2.x | Déclencheur V3 |
|---|---|
agentSpawn | SessionStart |
userPromptSubmit | UserPromptSubmit |
preToolUse | PreToolUse |
postToolUse | PostToolUse |
stop | Stop |
Stockez les Hooks d'espace de travail dans .kiro/hooks/. Pour exécuter le même Hook V3 dans chaque espace de travail, placez-le dans ~/.kiro/hooks/. Les Hooks globaux et d'espace de travail s'exécutent côte à côte. Consultez la référence complète des Hooks → pour les détails du schéma, les emplacements et les types d'action.
Migration des Hooks