Upgrading agent configs

CLI V3 agent profiles use tag-based tools and unified permissions. If you have agents created before this format was introduced, the /upgrade-agent command converts them in place. It adds the new permission fields alongside your existing configuration and backs up originals before writing.

Run /upgrade-agent whenever you spot older fields like toolsSettings or allowedTools, or after you change V2 trust settings in an upgraded agent. Kiro records the generated V3 state in a kiroUpgrade marker in each upgraded file, so a later run can tell which agents need a first upgrade, a refresh, or your review.

# Scan agents and open the selection menu
/upgrade-agent

# Same as above (explicit subcommand)
/upgrade-agent run

# Review previously upgraded agents and any conversion warnings
/upgrade-agent diagnostics

Use the CLI command when agent files live in a central directory or you want a non-interactive preview:

# Preview changes and warnings without writing files
kiro-cli agent upgrade <directory> --dry-run

# Upgrade the files and keep backups
kiro-cli agent upgrade <directory>

The command checks top-level *.json files in the directory. It does not search subdirectories. By default, each changed file gets a .bak backup. Add --no-backup only when another recovery copy already exists.

A dry run reports what would change and includes conversion warnings. On macOS and Linux, it also reports files the real run could not write. It leaves every file unchanged. The command skips non-agent JSON, externally managed agents, non-regular files, out-of-sync universal configs, duplicate paths to the same file, and symlinks whose target is outside the selected directory.

Exit code 0 means every file was upgraded, unchanged, or skipped. Exit code 1 means at least one file failed. Exit code 2 means the path is missing, unreadable, or not a directory.

By default, the run subcommand scans .kiro/agents/ in your workspace and ~/.kiro/agents/ globally. If those directories don't exist, Kiro checks .amazonq/cli-agents/ in the workspace and ~/.aws/amazonq/cli-agents/ globally. When KIRO_AGENT_CONFIG_DIR is set, Kiro uses that directory for the global scan and skips the workspace scan. The selection menu groups results by scope, and only agents that need upgrading appear.

When you select a group of agents to upgrade:

1. Each original file is copied to <filename>.json.bak as a backup
2. New-format permission fields are added alongside your existing configuration
3. Your original settings (tool names, allowed commands, path restrictions) are preserved with equivalent rules in the new format
4. A confirmation alert shows how many agents were upgraded

If a backup file already exists, numbered suffixes are used (.bak.1, .bak.2, etc.). When an agent config is a symlink, Kiro writes the upgraded content to the linked file and leaves the symlink in place.

Kiro refreshes the generated V3 permissions, tools, and Hooks when they no longer match the V2 trust settings in the same file, or when the migration itself has been revised. If you haven't edited those generated fields, the agent appears in the selection menu again and the upgrade replaces them with freshly generated values.

If you edit generated V3 fields by hand, Kiro stops refreshing them automatically. The agent appears under Universal · Out of Sync in the selection menu. Selecting that group rebuilds V3 from the V2 settings and overwrites your manual V3 edits. Kiro saves the previous file as a .bak backup.

If you want to undo the upgrade, rename the .json.bak file back to .json:

mv .kiro/agents/my-agent.json.bak .kiro/agents/my-agent.json

The upgrade translates your existing permission settings into the v3 format:

• Tool names: Old names (like fs_read, execute_bash) are mapped to v3 capability tags (like read, shell). Both are preserved for compatibility.
• toolsSettings: Per-tool allow/deny rules become permissions.rules entries with capability, match pattern, and effect.
• allowedTools: Trusted-tool entries become capability-level allow rules.
• Regex patterns: Regex patterns are translated to simple wildcard globs where possible. Complex patterns that can't be safely converted generate a warning.
• autoAllowReadonly: Converts to a read-only-shell policy.
• Object-form hooks: Converted to the array format the v3 schema requires.
• Workspace reads: Migrated configs allow fs_read for ./**, so the agent can read workspace files without asking. Deny rules still take precedence.
• Skill trust: If the V2 config trusts all built-in tools, or both includes a read tool and trusts fs_read, the migration also trusts skill loading. When V2 read restrictions (deniedPaths) could reach skill files, skills ask for approval in V3 instead, and diagnostics reports skill-read-restrictions.

All other fields (name, description, model, prompt, resources, mcpServers, welcomeMessage) pass through unchanged.

Here's a typical first run. You have 3 workspace agents and 1 global agent in older formats:

/upgrade-agent

Selection menu:

V2 or earlier upgrade [3 agents]    Workspace    Upgrade or refresh the universal (V2 + V3) config
V2 or earlier upgrade [1 agent]     Global       Upgrade or refresh the universal (V2 + V3) config

Select "V2 or earlier upgrade [3 agents] - Workspace" to upgrade all 3 workspace-level agents. A universal (V2 + V3) config keeps your original fields for backward compatibility while adding newer permission rules.

Post-upgrade alert:

Upgraded 3 agents (backed up to .json.bak)

Run diagnostics to check for conversion warnings, patterns that couldn't be perfectly translated:

/upgrade-agent diagnostics

2 Universal agents

  my-agent     Workspace   ⚠ regex-shell-pattern: ^git\s
  strict-dev   Global      ⚠ deny-by-default-readonly

The following are excluded from the scan:

• Backup files (.bak) are excluded from the scan
• Files that aren't valid agent configs (JSON files without prompt, tools, hooks, or permission fields) are ignored

All your agents are already in the latest format. Run /upgrade-agent diagnostics to review their current state.

Some patterns can't be perfectly translated from regex to glob format. Run /upgrade-agent diagnostics, review the flagged agents, and manually edit the permissions.rules in the upgraded config if needed.

Verify the file is valid JSON and contains at least a prompt, tools, or hooks field. Files that don't look like agent configurations are ignored.

• Agent config for the v3 agent config format reference
• Permissions for the capability-based permission rules
• Custom agents for creating and managing agents