CLI 2.x reference

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

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

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

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.

• Legacy embedded object Hooks can be upgraded to current array definitions; use standalone .kiro/hooks/*.json files for profile-independent automation
• Trigger names changed to PascalCase (for example, agentSpawn → SessionStart)
• CLI V3 supports SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, and Stop, plus file triggers for agent-made changes and task triggers around spec execution
• Standalone Hook files use the versioned v1 schema and support command or agent actions
• Stop command Hooks can 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 V3, per-tool settings are replaced by structured permissions.yaml files; the flags and slash commands remain as session-scoped overrides.

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
• Shell-command regexes move to permission globs; existing file-path rules remain gitignore-style glob patterns
• Separate per-tool deny was independent; now deny-always-wins across all scopes
• autoAllowReadonly converts through /upgrade-agent to a read-only-shell policy unless denyByDefault also applies; review the generated rules
• denyByDefault removed — use exclude patterns instead
• The /tools panel, /tools trust-all, and the approval picker remain available for session-level management

For the full migration guide, see Permissions migration.

CLI 2.x compaction forks a new session that contains the compacted context:

• Run /compact manually, or let compaction trigger when the context window overflows.
• Resume the original CLI 2.x session with /chat resume when needed.
• Configure retention with compaction.excludeMessages and compaction.excludeContextWindowPercent.

CLI V3 instead records the compaction summary as a checkpoint marker within the same session. On reload, V3 loads that summary rather than replaying the full earlier history or creating a separate session. See Compaction.

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

CLI 2.x custom agent configs can use built-in names such as kiro_default or kiro_planner. The V2 loader does not reject these configs as reserved-name conflicts. For current built-in agents and their roles, see Built-in agents.

.kiro/agents/my-agent.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?"
}

• Markdown format added (.md files with YAML frontmatter + body as system prompt)
• toolsSettings removed — replaced by permissions field with capability-based rules
• hooks shape changed — /upgrade-agent converts the object form to a profile-scoped array. Use standalone .kiro/hooks/*.json files for profile-independent or cross-surface automation.
• 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.