CLI 2.x reference

This page documents CLI 2.x behavior for users who haven't yet migrated to 3.0. For the current format, see the Features documentation.

In CLI 2.x, hooks were embedded directly in the agent configuration file rather than in standalone files.

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

Each trigger name maps to an array of hook definitions. Each definition has:

Hooks receive context as JSON via STDIN and communicate results through exit codes:

• Exit code 0: Hook succeeded. STDOUT is captured.
• Exit code 2: (preToolUse only) Block tool execution. STDERR is returned to the agent.
• Other exit codes: Hook failed. STDERR is shown as a warning.

• Hooks moved from embedded agent config to standalone .kiro/hooks/*.json files
• Trigger names changed to PascalCase (e.g., agentSpawn → SessionStart)
• New version: "v1" schema with name, description, enabled, and timeout fields
• New triggers added: PreTaskExec, PostTaskExec, PostFileDelete, Manual
• {{filePath}} template variable available for file-related triggers
• stop hook gained Block Decision support (return {"decision": "block"} to continue the session)

For the full migration guide, see Hooks migration.

In CLI 2.x, tool permissions were managed through CLI flags, slash commands, and per-tool settings in agent config. In 3.0, this is replaced by structured permissions.yaml files.

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"]
    }
  }
}

When the agent requested a shell command, a tiered picker appeared:

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

Trusted patterns persisted for the session and were stored as regex in allowedCommands.

When the agent needed to access a file outside the working directory:

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

• toolsSettings replaced by permissions.yaml with capability/match/effect rules
• --trust-all-tools still works as a session-scope override but permissions.yaml is preferred
• Regex patterns replaced by glob patterns (.* → *, \.ts$ → *.ts)
• Separate per-tool deny was independent; now deny-always-wins across all scopes
• autoAllowReadonly removed — explicitly list allowed commands
• denyByDefault removed — use exclude patterns instead
• Interactive trust levels and /tools commands still available for session-level management

For the full migration guide, see Permissions migration.

In CLI 2.x, compaction behavior was the same as 3.0:

• /compact for manual trigger
• Automatic trigger when context window overflows
• Creates a new session with compacted context; resume original via /chat resume
• Configurable via compaction.excludeMessages and compaction.excludeContextWindowPercent

No changes in 3.0 for this feature.

In CLI 2.x, agent configs were JSON-only with embedded toolsSettings and hooks.

.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?"
}

• Markdown format added (.md files with YAML frontmatter + body as system prompt)
• toolsSettings removed — replaced by permissions field with capability-based rules
• hooks moved to standalone .kiro/hooks/*.json files
• New fields: excludedTools, includeMcpJson, includePowers, permissions, welcomeMessage
• Tags system — tool names simplified to short categories (read, write, shell, web, @mcp, @builtin, *)
• resources field now supports skill:// URIs in addition to file://

For the current format reference, see Custom agents.