Capability-based permissions

The capability-based permissions system replaces the 0.x trust model — trustedCommands with prefix matching and a separate command denylist with substring matching — with fine-grained, declarative control over what the agent can do. You define rules per capability, with match patterns and explicit effects. One rule can target an entire class of operations across all tools: a deny on fs_read blocks every tool that reads files, without enumerating them individually.

The Autopilot and Supervised autonomy modes remain (Settings → Agent → Agent Autonomy, settings key kiroAgent.agentAutonomy). They control whether file changes apply immediately or wait for review; the capability-based permissions layer applies after the autonomy mode determines whether to proceed. Together they give you coarse-grained control plus fine-grained rules.

Permissions are defined in YAML files. There are two scopes:

Workspace-scoped (~/.kiro/workspace-roots/<hash>/permissions.yaml, stored per-user outside the repository) — use deny to block dangerous operations in a specific project:

rules:
  - capability: fs_write
    match: ["*.env", "*.pem", "*.key"]
    effect: deny
  - capability: shell
    match: ["rm -rf *", "sudo *"]
    effect: deny

User-scoped (~/.kiro/settings/permissions.yaml) — use allow to pre-approve trusted operations across all workspaces:

rules:
  - capability: shell
    match: ["git *", "npm *", "npx *"]
    effect: allow
  - capability: fs_write
    match: ["src/**", "tests/**"]
    effect: allow
  - capability: mcp
    match: ["my-server/*"]
    effect: allow

In 0.x, trust was configured per-tool: a single intent like "deny reads to .env" had to be set separately for every tool that could read files, and missing one left a gap. In 1.0, express the intent once at the capability level.

• If you used trusted commands, translate each prefix into a shell allow rule (git *, npm *) in your user-scoped permissions.yaml.
• If you relied on the command denylist, translate each entry into a shell deny rule. Deny rules win over allow rules in every scope.
• No configuration is required up front. Without any rules, the agent can read workspace files and run read-only git commands; everything else prompts, and you can persist decisions from the prompt as "always allow" or "always deny" rules.

For the full reference (capabilities, pattern syntax, the interactive approval flow, and configuration examples), see Permissions.