Passer au contenu principal
Afficher en Markdown

Référence de la CLI 2.x

Cette page documente le comportement de la CLI 2.x pour les utilisateurs qui n'ont pas encore migré vers V3. Pour le format actuel, consultez la documentation des Hooks.

Hooks

Dans la CLI 2.x, les Hooks étaient intégrés directement dans le fichier de configuration de l'agent plutôt que dans des fichiers autonomes.

Format

json
{ "hooks": { "agentSpawn": [{ "command": "echo 'starting'" }], "preToolUse": [{ "command": "npm run lint", "matcher": "fs_write" }] } }

Chaque nom de déclencheur correspond à un tableau de définitions de Hooks. Chaque définition comporte :

ChampDescription
commandCommande shell à exécuter
matcherSélecteur de nom d'outil pour preToolUse et postToolUse; noms exacts, alias et motifs génériques pris en charge

Déclencheurs disponibles

DéclencheurSe déclenche quandmatcher correspond à
agentSpawnL'agent est activéNon évalué
userPromptSubmitL'utilisateur envoie une requêteNon évalué
preToolUseAvant qu'un outil s'exécuteNom de l'outil
postToolUseAprès qu'un outil s'exécuteNom de l'outil
stopL'assistant termine sa réponseNon évalué

Communication des Hooks

Les Hooks reçoivent le contexte en JSON via STDIN et communiquent les résultats via des codes de sortie :

  • Code de sortie 0 : Le Hook a réussi. STDOUT est capturé.
  • Code de sortie 2 : (preToolUse seulement) Bloque l'exécution de l'outil. STDERR est renvoyé à l'agent.
  • Autres codes de sortie : Le Hook a échoué. STDERR est affiché comme avertissement.

Ce qui a changé dans V3

  • Les anciens Hooks en forme d'objet intégrés peuvent être mis à niveau vers les définitions actuelles en forme de tableau; utilisez des fichiers autonomes .kiro/hooks/*.json pour l'automatisation indépendante du profil
  • Les noms des déclencheurs sont passés en PascalCase (par exemple, agentSpawn → SessionStart)
  • CLI V3 prend en charge SessionStart, UserPromptSubmit, PreToolUse, PostToolUse et Stop, ainsi que des déclencheurs de fichiers pour les modifications faites par l'agent et des déclencheurs de tâches autour de l'exécution des specs
  • Les fichiers de Hooks autonomes utilisent le schéma versionné v1 et prennent en charge les actions de type commande ou agent
  • Les Hooks de commande Stop peuvent retourner {"decision": "block"} pour poursuivre la session

Pour le guide de migration complet, consultez Hooks migration.

Permissions et confiance des outils

Dans la CLI 2.x, les permissions des outils étaient gérées par des indicateurs de la CLI, des commandes slash et des paramètres par outil dans la configuration de l'agent. Dans V3, les paramètres par outil sont remplacés par des fichiers permissions.yaml structurés; les indicateurs et les commandes slash demeurent comme substitutions à la portée de la session.

Indicateurs de la CLI

bash
kiro-cli --trust-all-tools kiro-cli --trust-tools shell,write

Commandes slash

CommandeDescription
/toolsAffiche l'état de permission actuel pour tous les outils
/tools trust <tool>Accorde la confiance à un outil précis pour la session
/tools untrust <tool>Ramène un outil à la confirmation par requête
/tools trust-allAccorde la confiance à tous les outils (équivalent à /acceptall)
/tools resetRéinitialise toutes les permissions d'exécution aux valeurs par défaut

Paramètres par outil dans la configuration de l'agent (toolsSettings)

json
{ "toolsSettings": { "shell": { "allowedCommands": ["git *", "npm *"], "deniedCommands": ["rm -rf *", "sudo *"] }, "read": { "allowedPaths": ["src/**"], "deniedPaths": ["*.env"] } } }
ParamètreDescription
allowedCommandsMotifs d'expression régulière pour les commandes shell approuvées automatiquement
deniedCommandsMotifs d'expression régulière pour les commandes shell bloquées
allowedPathsMotifs glob de style gitignore pour les chemins de fichiers approuvés automatiquement
deniedPathsMotifs glob de style gitignore pour les chemins de fichiers bloqués
autoAllowReadonlyApprouve automatiquement les commandes shell en lecture seule (p. ex., git status)
denyByDefaultBloque tous les outils sauf ceux explicitement autorisés

Niveaux de confiance des commandes shell (interactif)

Lorsque l'agent demandait une commande shell, un sélecteur à paliers apparaissait :

Press (↑↓) to navigate (⏎) to select scope > Full command → git pull --rebase Partial command → git pull * Base command → git * Entire Tool → *

Les motifs de confiance persistaient pendant la session et étaient stockés comme expressions régulières dans allowedCommands.

Niveaux de confiance des chemins de lecture et d'écriture (interactif)

Lorsque l'agent devait accéder à un fichier hors du répertoire de travail :

Press (↑↓) to navigate (⏎) to select scope > Specific paths → ~/.config/app/settings.json Complete directory → ~/.config/app Entire Tool → *

Ce qui a changé dans V3

  • toolsSettings remplacé par permissions.yaml avec des règles capability/match/effect
  • --trust-all-tools fonctionne toujours comme substitution à l'échelle de la session, mais permissions.yaml est privilégié
  • Les expressions régulières des commandes shell passent aux globs de permissions; les règles de chemins de fichiers existantes restent des motifs glob de style gitignore
  • Le refus distinct par outil était indépendant; maintenant, le refus prévaut toujours dans toutes les portées
  • autoAllowReadonly est converti par /upgrade-agent en une politique read-only-shell, sauf si denyByDefault s'applique aussi; examinez les règles générées
  • denyByDefault supprimé — utilisez plutôt des motifs exclude
  • Le panneau /tools, /tools trust-all et le sélecteur d'approbation demeurent disponibles pour la gestion au niveau de la session

Pour le guide de migration complet, consultez Permissions migration.

Compactage

Le compactage de la CLI 2.x crée une nouvelle session dérivée qui contient le contexte compacté :

  • Exécutez /compact manuellement, ou laissez le compactage se déclencher lorsque la fenêtre contextuelle déborde.
  • Reprenez la session CLI 2.x originale avec /chat resume au besoin.
  • Configurez la rétention avec compaction.excludeMessages et compaction.excludeContextWindowPercent.

CLI V3 enregistre plutôt le résumé du compactage comme marqueur de point de contrôle dans la même session. Au rechargement, V3 charge ce résumé au lieu de rejouer l'historique antérieur complet ou de créer une session distincte. Consultez Compactage.

Configuration d'agent personnalisée

Dans la CLI 2.x, les configurations d'agent étaient uniquement en JSON, avec toolsSettings et hooks intégrés.

Noms intégrés

Les configurations d'agent personnalisé de la CLI 2.x peuvent utiliser des noms intégrés comme kiro_default ou kiro_planner. Le chargeur V2 ne rejette pas ces configurations comme des conflits de noms réservés. Pour les agents intégrés actuels et leurs rôles, consultez Agents intégrés.

Format

.kiro/agents/my-agent.json :

json
{ "name": "my-agent", "description": "A development agent", "prompt": "file://resources/MY_PROMPT.md", "model": "claude-sonnet-4.6", "tools": ["fs_read", "fs_write", "execute_bash", "grep", "glob", "code"], "toolsSettings": { "execute_bash": { "allowedCommands": ["^git status$", "^cargo build[^&;]*$"], "deniedCommands": ["^rm -rf"], "denyByDefault": false }, "fs_read": { "allowedPaths": ["src/**", "docs/**"], "deniedPaths": [".env", "secrets/**"] }, "fs_write": { "allowedPaths": ["src/**"], "deniedPaths": ["*.lock"] } }, "resources": ["file://AGENTS.md"], "hooks": { "agentSpawn": [{ "command": "git status", "description": "Add git context" }] }, "welcomeMessage": "Hello! How can I help?" }

Ce qui a changé dans V3

  • Format Markdown ajouté (fichiers .md avec en-tête YAML + corps comme requête système)
  • toolsSettings supprimé — remplacé par le champ permissions avec des règles fondées sur les capacités
  • Forme de hooks modifiée — /upgrade-agent convertit la forme d'objet en un tableau à la portée du profil. Utilisez des fichiers autonomes .kiro/hooks/*.json pour l'automatisation indépendante du profil ou commune à plusieurs surfaces.
  • Nouveaux champs : excludedTools, includeMcpJson, includePowers, permissions, welcomeMessage
  • Système d'étiquettes — les noms d'outils simplifiés en courtes catégories (read, write, shell, web, @mcp, @builtin, *)
  • Le champ resources prend maintenant en charge les URI skill:// en plus de file://

Pour la référence du format actuel, consultez Custom agents.

Page mise à jour : 3 novembre 2026