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 la version 3.0. Pour le format actuel, consultez la documentation des Features.

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.

{
  "hooks": {
    "agentSpawn": [{"command": "echo 'starting'", "matcher": ".*"}],
    "preToolUse": [{"command": "npm run lint", "matcher": "Write|Edit"}],
    "fileEdited": [{"command": "prettier --write", "matcher": "\\.ts$"}]
  }
}

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

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.

• Les Hooks sont passés d'une configuration d'agent intégrée à des fichiers autonomes .kiro/hooks/*.json
• Les noms des déclencheurs sont passés en PascalCase (p. ex., agentSpawn → SessionStart)
• Nouveau schéma version: "v1" avec les champs name, description, enabled et timeout
• Nouveaux déclencheurs ajoutés : PreTaskExec, PostTaskExec, PostFileDelete, Manual
• Variable de gabarit {{filePath}} disponible pour les déclencheurs liés aux fichiers
• Le Hook stop a obtenu la prise en charge de la décision de blocage (retournez {"decision": "block"} pour poursuivre la session)

Pour le guide de migration complet, consultez Hooks migration.

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 la version 3.0, ceci est remplacé par des fichiers permissions.yaml structurés.

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

{
  "toolsSettings": {
    "shell": {
      "allowedCommands": ["git *", "npm *"],
      "deniedCommands": ["rm -rf *", "sudo *"]
    },
    "read": {
      "allowedPaths": ["src/**"],
      "deniedPaths": ["*.env"]
    }
  }
}

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.

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          → *

• 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é
• Motifs d'expression régulière remplacés par des motifs glob (.* → *, \.ts$ → *.ts)
• Le refus distinct par outil était indépendant; maintenant, le refus prévaut toujours dans toutes les portées
• autoAllowReadonly supprimé — indiquez explicitement les commandes autorisées
• denyByDefault supprimé — utilisez plutôt des motifs exclude
• Les niveaux de confiance interactifs et les commandes /tools sont toujours disponibles pour la gestion au niveau de la session

Pour le guide de migration complet, consultez Permissions migration.

Dans la CLI 2.x, le comportement du compactage était le même que dans la version 3.0 :

• /compact pour un déclenchement manuel
• Déclenchement automatique lorsque la fenêtre contextuelle débordait
• Crée une nouvelle session avec le contexte compacté; reprenez la session originale via /chat resume
• Configurable via compaction.excludeMessages et compaction.excludeContextWindowPercent

Aucun changement dans la version 3.0 pour cette fonctionnalité.

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

.kiro/agents/my-agent.json :

{
  "name": "my-agent",
  "description": "A development agent",
  "prompt": "file://resources/MY_PROMPT.md",
  "model": "claude-sonnet-4",
  "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?"
}

• 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
• hooks déplacés vers des fichiers autonomes .kiro/hooks/*.json
• 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.