Permissions

Kiro uses a capability-based permissions system that gives you fine-grained, declarative control over what the agent can do. You define rules per capability with match patterns and explicit effects, replacing older binary trust models.

The permissions system is built around three core concepts:

Additional rule properties:

Permissions are defined in YAML files at two levels:

User-scoped (~/.kiro/settings/permissions.yaml) - applies across all projects. Use to pre-approve trusted operations:

rules:
  - capability: shell
    match: ["git *", "npm *", "npx *"]
    effect: allow

  - capability: fs_write
    match: ["src/**", "tests/**"]
    effect: allow

  - capability: fs_read
    effect: allow

  - capability: mcp
    match: ["my-server/*"]
    effect: allow

Workspace-scoped (~/.kiro/workspace-roots/<hash>/permissions.yaml) - applies only to a specific project. Use to scope rules to one codebase:

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

  - capability: shell
    match: ["rm -rf *", "sudo *"]
    effect: deny

Both scopes support all effects (deny, ask, allow).

Rules support an exclude field for "allow everything except" patterns:

rules:
  - capability: mcp
    match: ["my-server/*"]
    exclude: ["my-server/dangerous-tool"]
    effect: allow

Rules use glob patterns. The syntax differs by capability type:

Filesystem patterns (fs_read, fs_write):

• * matches within a single path component
• ** matches across path separators
• {a,b} brace expansion and [abc] character classes are supported
• Patterns without wildcards implicitly match children: ~/temp matches ~/temp/child

Shell, web, and MCP patterns:

• * matches any sequence of characters
• **, ?, and character classes are not supported

rules:
  # Allow npm commands except npm publish
  - capability: shell
    effect: allow
    match:
      - "npm *"
    exclude:
      - "npm publish*"

  # Deny reads to secrets at any depth
  - capability: fs_read
    effect: deny
    match:
      - "**/.env"
      - "**/.env.*"
      - "secrets/**"
      - "**/*.pem"

Shell commands are parsed before pattern matching. Compound commands (using ;, &&, ||, |) are split and each sub-command is evaluated independently. This prevents a rule for npm test * from accidentally matching npm test ; curl attacker.com.

Permissions are evaluated across multiple scopes. The most restrictive effect wins regardless of which scope it came from.

Rules are evaluated using a deny-overrides algorithm: deny > ask > allow. There is no precedence between scopes - the most restrictive effect wins regardless of which scope it came from.

Without any permissions.yaml configured, the default agent policy allows:

• fs_read on ./** - read any workspace file silently
• shell for common git read-only commands - git status, git log, git diff, git branch, and similar
• shell for system info commands - pwd, whoami, uname, and similar
• Utility tools (diagnostics, knowledge, and similar)

The Kiro scope (hardcoded, cannot be overridden) enforces:

• Always denied: writes to ~/.kiro/settings/, .kiro/settings/, and ~/.kiro/workspace-roots/ (prevents the agent from modifying its own permission files)
• Always asks: writes to .git/**, .kiro/agents/**, .kiro/hooks/**, .kiroignore

Everything else prompts for approval. Creating a permissions.yaml adds to these defaults; it does not replace them.

Here are common patterns for configuring permissions:

If you're upgrading from CLI 2.x or IDE 0.x, see the reference pages for how permissions worked previously and what changed:

• CLI 2.x reference - Permissions
• IDE 0.x reference - Permissions
• What's new in CLI 3.0 - Permissions migration